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 2010-2011
  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/runtime/pktlib/pktlib.h"
  53 #include "ti/drv/nwal/nwal.h"
  54 #include <ti/drv/sa/salld.h>
  55
  56
  57
  58
  59 /**
  60  *  @ingroup netapi_structures
  61  *  @brief NETAPI SA Statistics
  62  *
  63  *  @details Pointer to this strucutre is passed in the call to netapi_getSaStats API.
  64  */
  65
  66
  67 typedef struct NETAPI_SA_STATS_Tag
  68 {
  69 #define NETAPI_IPSEC_STAT_VALID                                 0x0001
  70 #define NETAPI_SIDEBAND_DATA_MODE_STAT_VALID    0x0002
  71     uint16_t            validParams; /** < Bit map indicating the IPSec SA Inflow/Side band data mode stats validity */
  72     Sa_IpsecStats_t     saIpsecStats;           /**<  Structure containing IPSEC stats in INFLOW MODE*/
  73     Sa_DataModeStats_t  dataModeStats;     /**<  Structure containing IPSEC stats in SIDEBAND MODE */
  74 } NETAPI_SA_STATS_T;
  75
  76
  77 /**
  78  *  @ingroup netapi_structures
  79  *  @brief NETAPI security SA information
  80  *
  81  *  @details This structure contains SA information
  82  */
  83 typedef struct NETAPI_SEC_SA_INFO_tag
  84 {
  85     nwal_SaDir          dir;            /**< Direction for the channel. Inbound or Outbound */
  86     uint32_t            spi;              /**< IPSec Security Parameter index */
  87     nwal_IpSecProto     proto;              /**< IpSec Proto (ESP/AH) */
  88     nwal_saMode         saMode;         /**< Tunnel/ Transport mode */
  89     nwal_IpType         ipType;             /**< IPV4 or V6 */
  90     nwalIpAddr_t        src;            /**< Source IP Address (remote) */
  91     nwalIpAddr_t        dst;           /**< DST IP Address (local) */
  92     uint32_t            replayWindow;   /**< Replay Window Size */
  93     nwal_saAALG         authMode;       /**< Authentication Algorithm */
  94     nwal_saEALG         cipherMode;       /**< Encryption Algorithm */
  95     uint32_t            esnLo;          /**< Initial Value of Extended Sequence Number LSB */
  96     uint32_t            esnHi;          /**< Initial Value of Extended Sequence Number MSB */
  97 } NETAPI_SEC_SA_INFO_T;
  98
  99
 100 /**
 101  * @brief This defines the SA mode of operation to be INFLOW
 102  */
 103 #define NETAPI_SEC_SA_INFLOW   0x2
 104
 105 /**
 106  * @brief This defines the SA mode of operation to be SIDEBAND
 107  */
 108 #define NETAPI_SEC_SA_SIDEBAND 0x1
 109
 110 /**
 111  *  @ingroup netapi_cfg_sec_functions
 112  *  @brief netapi_secAddSA: API to configure an IPSEC SA.
 113  *
 114  *  @details  API to configure an  IPSec SA. SAs are IPSec security contexts and define a uni-directional
 115  * secure path (tunnel or transport). SAs are attached to Mac interfaces that have already
 116  * been created. API allows SA to be configured as either inflow or sideband mode
 117  *  @param[in]  @ref NETAPI_T: the NETAPI handle
 118  *  @param[in] iface_no:interface to attach SA to.
 119  *  @param[in] sa_info: @ref NETAPI_SEC_SA_INFO_T: information on the SA being added
 120  *  @param[in]  key_params: @ref nwalSecKeyParams_t: security key information for the SA.
 121  *  @param[in] mode: SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
 122  *  @param[in] route: @ref NETCP_CFG_ROUTE_HANDLE_T
 123  *  @param[in] data_mode_handle: returned data mode handle for PKTIO
 124  *  @param[in] inflow_mode_handle: returned inflow mode handle for PKTIO
 125  *  @param[out] perr: error codem, zero on sucess, non-zero on failure
 126  *  @retval     Aplication id associated with created SA, @ref NETCP_CFG_SA_T
 127  *  @pre        @ref netapi_init
 128  */
 129 NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h,
 130                                 int iface_no,
 131                                 NETAPI_SEC_SA_INFO_T *sa_info   ,
 132                                 nwalSecKeyParams_t *key_params,
 133                                 int mode,
 134                                 NETCP_CFG_ROUTE_HANDLE_T  route,
 135                                 void ** data_mode_handle,
 136                                 void ** inflow_mode_handle,
 137                                 int * perr);
 138
 139 /**
 140  *  @ingroup netapi_cfg_sec_functions
 141  *  @brief netapi_secDelSA: API to delete an IPSEC SA.
 142  *
 143  *  @details  API to delete an IPSEC SA
 144  *  @param[in]  h   the NETAPI handle, @ref NETAPI_T
 145  *  @param[in] iface_no:interface to attach SA to.
 146  *  @param[in] sa_app_id: Application id returned from call to @ref netapi_secAddSA
 147  *  @param[out] perr: zero on sucess, non-zero on failure
 148  *  @retval     none
 149  *  @pre        @ref netapi_init @ref netapi_secAddSA
 150 */
 151 void netapi_secDelSA(NETAPI_T h,int iface_no, NETCP_CFG_SA_T  sa_app_id,  int *perr);
 152
 153 /**
 154  *  @ingroup netapi_cfg_sec_functions
 155  *  @brief netapi_secAddRxPolicy: API to add a recieve security policy
 156  *
 157  *  @details  API to add a recieve security policy
 158  *  @param[in]  h   the NETAPI handle, @ref NETAPI_T
 159  *  @param[in] sa: Application id returned from call to @ref netapi_secAddSA
 160  *  @param[in] ipType, @ref nwal_IpType
 161  *  @param[in] src_ip_addr, @ref nwalIpAddr_t
 162  *  @param[in] dst_ip_addr, @ref nwalIpAddr_t
 163  *  @param[in] ip_qualifiers @ref nwalIpOpt_t
 164  *  @param[in] route: optional route, @ref NETCP_CFG_ROUTE_HANDLE_T
 165  *  @param[out] perr: zero on sucess, non-zero on failure
 166  *  @retval    Aplication id associated with created receive security policy , @ref NETCP_CFG_IPSEC_POLICY_T
 167  *  @pre        @ref netapi_init @ref netapi_secAddSA
 168 */
 169 NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h, //the  netapi handle
 170                                 NETCP_CFG_SA_T sa,  //tunnel to attach to
 171                                 nwal_IpType ipType,     //V4 or V6
 172                                 nwalIpAddr_t  * src_ip_addr,  //src (from where)
 173                                 nwalIpAddr_t  * dst_ip_addr,  //dst (us)
 174                                 nwalIpOpt_t * ip_qualifiers,  //other qualifiers
 175                                 NETCP_CFG_ROUTE_HANDLE_T  route,  //Optional route
 176                                 int * perr);
 177
 178 /**
 179  *  @ingroup netapi_cfg_sec_functions
 180  *  @brief netapi_secDelRxPolicy: API to add a recieve security policy
 181  *
 182  *  @details  API to add a recieve security policy
 183  *  @param[in]  h   the NETAPI handle, @ref NETAPI_T
 184  *  @param[in] policy_app_id: Application id returned from call to @ref netapi_secAddRxPolicy
 185  *  @param[out] perr: zero on sucess, non-zero on failure
 186  *  @retval     none
 187  *  @pre        @ref netapi_init @ref,  @ref netapi_secAddRxPolicy
 188 */
 189 void netapi_secDelRxPolicy(NETAPI_T h,
 190                               NETCP_CFG_IPSEC_POLICY_T policy_app_id,
 191                               int *perr);
 192
 193
 194 /**
 195  *  @ingroup netapi_cfg_sec_functions
 196  *  @brief netapi_getSaStats: API to retrieve SA statistics via NWAL.
 197  *
 198  *  @details  *  API to retrieve SA statistics via NWAL.
 199  *  @param[in]  h   the NETAPI handle, @ref NETAPI_T
 200  *  @param[in] pSaStats: Pointer to NETAPI_SA_STATS_T which will get populated by this API call, @ref NETAPI_SA_STATS_T
 201  *  @retval     none
 202  *  @pre        @ref netapi_init @ref,  @ref netapi_secAddSA
 203 */
 204 void  netapi_getSaStats (NETAPI_T                   h,
 205                          NETCP_CFG_SA_T             handle,
 206                          NETAPI_SA_STATS_T*         pSaStats);
 207
 208 #endif