Doxygen updates
[keystone-rtos/netapi.git] / 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 /* ============================================================= */
44 /**
45  *   @file netapi_sec.h
46  *   @brief netapi security  header file for user space transport library
47  */
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>
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  */
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;
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;
100 /**
101  * @brief This defines the SA mode of operation to be INFLOW
102  */
103 #define NETAPI_SEC_SA_INFLOW   0x2 
105 /**
106  * @brief This defines the SA mode of operation to be SIDEBAND
107  */
108 #define NETAPI_SEC_SA_SIDEBAND 0x1 
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);
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);
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);
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);
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);
208 #endif