ti/runtime/netapi/netapi_sec.h

   1 /******************************************************************************
   2  * FILE PURPOSE:  Netapi Security configuration header file
   3  ******************************************************************************
   4  * FILE NAME:   netapi_sec.h
   5  *
   6  * DESCRIPTION: netapi security  header file for user space transport library
   7  *
   8  * REVISION HISTORY:
   9  *
  10  *  Copyright (c) Texas Instruments Incorporated 2013
  11  *
  12  *  Redistribution and use in source and binary forms, with or without
  13  *  modification, are permitted provided that the following conditions
  14  *  are met:
  15  *
  16  *    Redistributions of source code must retain the above copyright
  17  *    notice, this list of conditions and the following disclaimer.
  18  *
  19  *    Redistributions in binary form must reproduce the above copyright
  20  *    notice, this list of conditions and the following disclaimer in the
  21  *    documentation and/or other materials provided with the
  22  *    distribution.
  23  *
  24  *    Neither the name of Texas Instruments Incorporated nor the names of
  25  *    its contributors may be used to endorse or promote products derived
  26  *    from this software without specific prior written permission.
  27  *
  28  *  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
  29  *  "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
  30  *  LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
  31  *  A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
  32  *  OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  33  *  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
  34  *  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
  35  *  DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
  36  *  THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
  37  *  (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
  38  *  OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  39  *
  40  */
  41 /* ============================================================= */
  42
  43
  44 /**
  45  *   @file netapi_sec.h
  46  *   @brief netapi security header file for user space transport library
  47  */
  48
  49 #ifndef __NETAPI_SEC__H
  50 #define __NETAPI_SEC__H
  51 #include "netapi.h"
  52 #include "ti/drv/nwal/nwal.h"
  53 #include <ti/drv/sa/salld.h>
  54
  55
  56
  57
  58 /**
  59  *  @ingroup cfg_security_structures
  60  *  @brief NETAPI SA Statistics
  61  *
  62  *  @details Pointer to this structure is passed in the call to netapi_getSaStats API. It will be popluated with the requested statistics.
  63  */
  64 typedef struct NETAPI_SA_STATS_Tag
  65 {
  66 /**
  67  * Bit map indicating the IPSec SA Inflow/Side band data mode stats validity
  68  * <br>
  69  * The validParams field indicates to the caller which stats being returned by calling the @ref netapi_getSaStats are valid.
  70  *      @ref NETAPI_IPSEC_STAT_VALID, @ref NETAPI_SIDEBAND_DATA_MODE_STAT_VALID
  71  */
  72     uint16_t            validParams;            /**< Bit map indicating the IPSec SA Inflow/Side band data mode stats validity */
  73
  74 /**
  75  * @def NETAPI_IPSEC_STAT_VALID
  76  * @ingroup security_constants
  77  *      Indicates to user application that IPSEC stats are valid for INFLOW mode
  78  */
  79 #define NETAPI_IPSEC_STAT_VALID                 0x0001
  80
  81 /**
  82  * @def NETAPI_SIDEBAND_DATA_MODE_STAT_VALID
  83  * @ingroup security_constants
  84  *      Indicates to user application that IPSEC stats are valid for SIDEBAND mode
  85  */
  86 #define NETAPI_SIDEBAND_DATA_MODE_STAT_VALID    0x0002
  87
  88     Sa_IpsecStats_t     saIpsecStats;           /**<  Structure containing IPSEC stats for INFLOW MODE*/
  89     Sa_DataModeStats_t  dataModeStats;          /**<  Structure containing Data Mode stats for SIDEBAND MODE */
  90 } NETAPI_SA_STATS_T;
  91
  92
  93 /**
  94  *  @ingroup cfg_security_structures
  95  *  @brief NETAPI security SA information
  96  *
  97  *  @details This structure contains the information necessary to create a security association (for either for inflow mode or sideband mode)
  98  */
  99 typedef struct NETAPI_SEC_SA_INFO_tag
 100 {
 101     nwal_SaDir          dir;            /**< Direction for the channel. Inbound or Outbound */
 102     uint32_t            spi;            /**< IPSec Security Parameter index */
 103     nwal_IpSecProto     proto;          /**< IpSec Proto (ESP/AH) */
 104     nwal_saMode         saMode;         /**< Tunnel/ Transport mode (sideband RX/TX) */
 105     nwal_IpType         ipType;         /**< IPV4 or V6 (sideband RX/TX) */
 106     nwalIpAddr_t        src;            /**< Source IP Address (remote) (sideband RX) */
 107     nwalIpAddr_t        dst;            /**< DST IP Address (local) (sideband RX) */
 108     uint32_t            replayWindow;   /**< Replay Window Size (sideband RX) */
 109     nwal_saAALG         authMode;       /**< Authentication Algorithm */
 110     nwal_saEALG         cipherMode;     /**< Encryption Algorithm */
 111     uint32_t            esnLo;          /**< Initial Value of Extended Sequence Number LSB (sideband TX) */
 112     uint32_t            esnHi;          /**< Initial Value of Extended Sequence Number MSB (sideband TX) */
 113 } NETAPI_SEC_SA_INFO_T;
 114
 115
 116
 117 /**
 118  * @brief This defines the SA mode of operation to be INFLOW. This means that IPSEC will be applied
 119  *        as the packet is being received or just before it is transmitted. This is a more efficient
 120  *        way to use SA and saves host cycles.
 121  * @ingroup security_constants
 122  */
 123 #define NETAPI_SEC_SA_INFLOW   0x2
 124
 125 /**
 126  * @brief This defines the SA mode of operation to be SIDEBAND. This means that Security Acclerator is
 127  *        to be used a traditional accelerator where for RX, the packet will first be received on host
 128  *        and then sent back to SA for crypto.  For TX the packet will first be sent to SA for crypto,
 129  *        returned to host and then sent to NETCP for transmit.
 130  * @ingroup security_constants
 131  */
 132 #define NETAPI_SEC_SA_SIDEBAND 0x1
 133
 134 /**
 135  *  @ingroup cfg_security_functions
 136  *  @brief netapi_secAddSA  API to add an IPSEC SA.
 137  *
 138  *  @details API to add an IPSec SA. SAs are IPSec security contexts and define a uni-directional
 139  *           secure path (tunnel or transport). SAs are attached to MAC interfaces that have already
 140  *           been created. API allows SA to be configured as either inflow or sideband mode. This API is used for both receive and transmit SAs.
 141  *  @param[in]  h            The NETAPI handle, @ref NETAPI_T
 142  *  @param[in]  iface_no     Interface to attach SA to.
 143  *  @param[in]  sa_info      Information on the SA being added, @ref NETAPI_SEC_SA_INFO_T
 144  *  @param[in]  key_params   Security key information for the SA.
 145  *  @param[in]  mode         SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
 146  *  @param[in]  route        Optional: @ref NETCP_CFG_ROUTE_HANDLE_T
 147  *  @param[in]  data_mode_handle     Returned data mode handle for PKTIO (in the case of sideband SAs)
 148  *  @param[in]  inflow_mode_handle   Returned inflow mode handle for PKTIO (in the case of TX inflow SAs)
 149  *  @param[in]  user_data     Optional: pointer to user provided data associated with SA, optional
 150  *  @param[out]  perr        Pointer to error code.
 151  *  @retval     Application id associated with created SA @ref NETCP_CFG_SA_T.
 152  *              This ID is used when referencing this SA in subsequent APIs (eg. to delete it).
 153  *              Also in the case of Receive Inflow,  packets will be tagged with this ID so that s/w will know
 154  *              that the packet has already been decrypted, authenticated and window-replay checked.
 155  *              (note: if a RX policy is matched also then the ID associated with the policy will be tagged instead).
 156  *  @pre        @ref netapi_init
 157  */
 158 NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T                     h,
 159                                 int iface_no,
 160                                 NETAPI_SEC_SA_INFO_T*       sa_info,
 161                                 nwalSecKeyParams_t*         key_params,
 162                                 int                         mode,
 163                                 NETCP_CFG_ROUTE_HANDLE_T    route,
 164                                 void**                      data_mode_handle,
 165                                 void**                      inflow_mode_handle,
 166                                 void*                       user_data,
 167                                 int*                        perr);
 168 /**
 169  *  @ingroup cfg_security_functions
 170  *  @brief  netapi_secDelSA: API to delete an IPSEC SA.
 171  *
 172  *  @details API to delete an IPSEC SA
 173  *  @param[in]  h       The NETAPI handle, @ref NETAPI_T
 174  *  @param[in] iface_no Interface to attach SA to.
 175  *  @param[in] sa_app_id Application id returned from call to @ref netapi_secAddSA
 176  *  @param[out] perr Pointer to error code.
 177  *  @retval     none
 178  *  @pre        @ref netapi_init @ref netapi_secAddSA
 179 */
 180 void netapi_secDelSA(NETAPI_T       h,
 181                      int            iface_no,
 182                      NETCP_CFG_SA_T sa_app_id,
 183                      int*           perr);
 184
 185 /**
 186  *  @ingroup cfg_security_functions
 187  *  @brief netapi_secAddRxPolicy: API to add a receive security policy
 188  *
 189  *  @details API to add a receive security policy
 190  *  @param[in]  h       The NETAPI handle @ref NETAPI_T
 191  *  @param[in] sa       Application id returned from call to @ref netapi_secAddSA.
 192  *                      This SA must have beeen configured for (a) RX and (b) Inflow mode.
 193  *  @param[in] ipType   IPV4 or IPV6
 194  *  @param[in] src_ip_addr  source IP for policy check
 195  *  @param[in] dst_ip_addr  destination IP for policy check
 196  *  @param[in] ip_qualifiers  IP qualifiers for policy check
 197  *  @param[in] route    Optional: @ref NETCP_CFG_ROUTE_HANDLE_T
 198  *  @param[in]  user_data   Optional: pointer to user provided data associated with policy
 199  *  @param[out] perr    Pointer to error code.
 200  *  @retval    Aplication id associated with created receive security policy @ref NETCP_CFG_IPSEC_POLICY_T.  This is used to refer to the policy in the @ref netapi_secDelRxPolicy call.  Also, packets that match this policy but do not pass any further lookups in NETCP will be tagged with this ID
 201  *  @pre        @ref netapi_init @ref netapi_secAddSA
 202 */
 203 NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T                     h,
 204                                                NETCP_CFG_SA_T               sa,
 205                                                nwal_IpType                  ipType,
 206                                                nwalIpAddr_t*                src_ip_addr,
 207                                                nwalIpAddr_t*                dst_ip_addr,
 208                                                nwalIpOpt_t*                 ip_qualifiers,
 209                                                NETCP_CFG_ROUTE_HANDLE_T     route,
 210                                                void*                        user_data,
 211                                                int*                         perr);
 212
 213 /**
 214  *  @ingroup cfg_security_functions
 215  *  @brief netapi_secDelRxPolicy: API to add a receive security policy
 216  *
 217  *  @details API to add a receive security policy
 218  *  @param[in]  h               The NETAPI handle, @ref NETAPI_T
 219  *  @param[in] policy_app_id    Application id returned from call to @ref netapi_secAddRxPolicy
 220  *  @param[out] perr            Pointer to error code.
 221  *  @retval     none
 222  *  @pre        @ref netapi_init, @ref netapi_secAddRxPolicy
 223 */
 224 void netapi_secDelRxPolicy(NETAPI_T                 h,
 225                            NETCP_CFG_IPSEC_POLICY_T policy_app_id,
 226                            int*                     perr);
 227
 228
 229 /**
 230  *  @ingroup cfg_security_functions
 231  *  @brief netapi_getSaStats: API to retrieve SA statistics via NWAL.
 232  *
 233  *  @details API to retrieve SA statistics via NWAL.
 234  *  @param[in]  h   The NETAPI handle, @ref NETAPI_T
 235  *  @param[in]  handle @ref NETCP_CFG_SA_T
 236  *  @param[out] pSaStats Pointer to SA stats which will get populated by this API call @ref NETAPI_SA_STATS_T
 237  *  @retval     none
 238  *  @pre        @ref netapi_init, @ref netapi_secAddSA
 239 */
 240 void  netapi_getSaStats (NETAPI_T                   h,
 241                          NETCP_CFG_SA_T             handle,
 242                          NETAPI_SA_STATS_T*         pSaStats);
 243
 244 #endif