Fix for SDOCM00107501:Compilation issues observed when compiling with C++
[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 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 /* ============================================================= */
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
52 #ifdef __cplusplus
53 extern "C" {
54 #endif
57 #include "netapi.h"
58 #include "ti/drv/nwal/nwal.h"
59 #include <ti/drv/sa/salld.h>
64 /**
65  *  @ingroup cfg_security_structures
66  *  @brief NETAPI SA Statistics
67  *
68  *  @details Pointer to this structure is passed in the call to netapi_getSaStats API. It will be popluated with the requested statistics.
69  */
70 typedef struct NETAPI_SA_STATS_Tag
71 {
72 /**
73  * Bit map indicating the IPSec SA Inflow/Side band data mode stats validity
74  * <br>
75  * The validParams field indicates to the caller which stats being returned by calling the @ref netapi_getSaStats are valid.
76  *      @ref NETAPI_IPSEC_STAT_VALID, @ref NETAPI_SIDEBAND_DATA_MODE_STAT_VALID
77  */
78     uint16_t            validParams;            /**< Bit map indicating the IPSec SA Inflow/Side band data mode stats validity */
80 /**
81  * @def NETAPI_IPSEC_STAT_VALID
82  * @ingroup security_constants
83  *      Indicates to user application that IPSEC stats are valid for INFLOW mode
84  */
85 #define NETAPI_IPSEC_STAT_VALID                 0x0001 
87 /**
88  * @def NETAPI_SIDEBAND_DATA_MODE_STAT_VALID
89  * @ingroup security_constants
90  *      Indicates to user application that IPSEC stats are valid for SIDEBAND mode
91  */
92 #define NETAPI_SIDEBAND_DATA_MODE_STAT_VALID    0x0002
94     Sa_IpsecStats_t     saIpsecStats;           /**<  Structure containing IPSEC stats for INFLOW MODE*/
95     Sa_DataModeStats_t  dataModeStats;          /**<  Structure containing Data Mode stats for SIDEBAND MODE */
96 } NETAPI_SA_STATS_T;
99 /**
100  *  @ingroup cfg_security_structures
101  *  @brief NETAPI security SA information
102  *
103  *  @details This structure contains the information necessary to create a security association (for either for inflow mode or sideband mode)
104  */
105 typedef struct NETAPI_SEC_SA_INFO_tag
107     nwal_SaDir          dir;            /**< Direction for the channel. Inbound or Outbound */
108     uint32_t            spi;            /**< IPSec Security Parameter index */
109     nwal_IpSecProto     proto;          /**< IpSec Proto (ESP/AH) */
110     nwal_saMode         saMode;         /**< Tunnel/ Transport mode (sideband RX/TX) */
111     nwal_IpType         ipType;         /**< IPV4 or V6 (sideband RX/TX) */
112     nwalIpAddr_t        src;            /**< Source IP Address (remote) (sideband RX) */
113     nwalIpAddr_t        dst;            /**< DST IP Address (local) (sideband RX) */
114     uint32_t            replayWindow;   /**< Replay Window Size (sideband RX) */
115     nwal_saAALG         authMode;       /**< Authentication Algorithm */
116     nwal_saEALG         cipherMode;     /**< Encryption Algorithm */
117     uint32_t            esnLo;          /**< Initial Value of Extended Sequence Number LSB (sideband TX) */
118     uint32_t            esnHi;          /**< Initial Value of Extended Sequence Number MSB (sideband TX) */
119 } NETAPI_SEC_SA_INFO_T;
123 /**
124  * @brief This defines the SA mode of operation to be INFLOW. This means that IPSEC will be applied 
125  *        as the packet is being received or just before it is transmitted. This is a more efficient 
126  *        way to use SA and saves host cycles.
127  * @ingroup security_constants
128  */
129 #define NETAPI_SEC_SA_INFLOW   0x2
131 /**
132  * @brief This defines the SA mode of operation to be SIDEBAND. This means that Security Acclerator is
133  *        to be used a traditional accelerator where for RX, the packet will first be received on host 
134  *        and then sent back to SA for crypto.  For TX the packet will first be sent to SA for crypto,
135  *        returned to host and then sent to NETCP for transmit.
136  * @ingroup security_constants
137  */
138 #define NETAPI_SEC_SA_SIDEBAND 0x1
140 /**
141  *  @ingroup cfg_security_functions
142  *  @brief netapi_secAddSA  API to add an IPSEC SA.
143  *
144  *  @details API to add an IPSec SA. SAs are IPSec security contexts and define a uni-directional
145  *           secure path (tunnel or transport). SAs are attached to MAC interfaces that have already
146  *           been created. API allows SA to be configured as either inflow or sideband mode. This API is used for both receive and transmit SAs.
147  *  @param[in]  h            The NETAPI handle, @ref NETAPI_T
148  *  @param[in]  iface_no     Interface to attach SA to.
149  *  @param[in]  sa_info      Information on the SA being added, @ref NETAPI_SEC_SA_INFO_T
150  *  @param[in]  key_params   Security key information for the SA.
151  *  @param[in]  mode         SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
152  *  @param[in]  route        Optional: @ref NETCP_CFG_ROUTE_HANDLE_T
153  *  @param[in]  data_mode_handle     Returned data mode handle for PKTIO (in the case of sideband SAs)
154  *  @param[in]  inflow_mode_handle   Returned inflow mode handle for PKTIO (in the case of TX inflow SAs)
155  *  @param[in]  user_data     Optional: pointer to user provided data associated with SA, optional
156  *  @param[out]  perr        Pointer to error code.
157  *  @retval     Application id associated with created SA @ref NETCP_CFG_SA_T. 
158  *              This ID is used when referencing this SA in subsequent APIs (eg. to delete it).
159  *              Also in the case of Receive Inflow,  packets will be tagged with this ID so that s/w will know 
160  *              that the packet has already been decrypted, authenticated and window-replay checked.
161  *              (note: if a RX policy is matched also then the ID associated with the policy will be tagged instead).
162  *  @pre        @ref netapi_init
163  */
164 NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T                     h,
165                                 int iface_no,
166                                 NETAPI_SEC_SA_INFO_T*       sa_info,
167                                 nwalSecKeyParams_t*         key_params,
168                                 int                         mode,
169                                 NETCP_CFG_ROUTE_HANDLE_T    route,
170                                 void**                      data_mode_handle,
171                                 void**                      inflow_mode_handle,
172                                 void*                       user_data,
173                                 int*                        perr);
174 /**
175  *  @ingroup cfg_security_functions
176  *  @brief  netapi_secDelSA: API to delete an IPSEC SA. 
177  *
178  *  @details API to delete an IPSEC SA
179  *  @param[in]  h       The NETAPI handle, @ref NETAPI_T
180  *  @param[in] iface_no Interface to attach SA to.
181  *  @param[in] sa_app_id Application id returned from call to @ref netapi_secAddSA
182  *  @param[out] perr Pointer to error code.
183  *  @retval     none
184  *  @pre        @ref netapi_init @ref netapi_secAddSA
185 */
186 void netapi_secDelSA(NETAPI_T       h,
187                      int            iface_no, 
188                      NETCP_CFG_SA_T sa_app_id,
189                      int*           perr);
191 /**
192  *  @ingroup cfg_security_functions
193  *  @brief netapi_secAddRxPolicy: API to add a receive security policy
194  *
195  *  @details API to add a receive security policy
196  *  @param[in]  h       The NETAPI handle @ref NETAPI_T
197  *  @param[in] sa       Application id returned from call to @ref netapi_secAddSA.  
198  *                      This SA must have beeen configured for (a) RX and (b) Inflow mode.
199  *  @param[in] ipType   IPV4 or IPV6
200  *  @param[in] src_ip_addr  source IP for policy check
201  *  @param[in] dst_ip_addr  destination IP for policy check
202  *  @param[in] ip_qualifiers  IP qualifiers for policy check
203  *  @param[in] route    Optional: @ref NETCP_CFG_ROUTE_HANDLE_T
204  *  @param[in]  user_data   Optional: pointer to user provided data associated with policy
205  *  @param[out] perr    Pointer to error code.
206  *  @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
207  *  @pre        @ref netapi_init @ref netapi_secAddSA
208 */
209 NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T                     h,
210                                                NETCP_CFG_SA_T               sa,
211                                                nwal_IpType                  ipType,
212                                                nwalIpAddr_t*                src_ip_addr,
213                                                nwalIpAddr_t*                dst_ip_addr,
214                                                nwalIpOpt_t*                 ip_qualifiers,
215                                                NETCP_CFG_ROUTE_HANDLE_T     route,
216                                                void*                        user_data,
217                                                int*                         perr);
219 /**
220  *  @ingroup cfg_security_functions
221  *  @brief netapi_secDelRxPolicy: API to add a receive security policy
222  *
223  *  @details API to add a receive security policy
224  *  @param[in]  h               The NETAPI handle, @ref NETAPI_T
225  *  @param[in] policy_app_id    Application id returned from call to @ref netapi_secAddRxPolicy
226  *  @param[out] perr            Pointer to error code.
227  *  @retval     none
228  *  @pre        @ref netapi_init, @ref netapi_secAddRxPolicy
229 */
230 void netapi_secDelRxPolicy(NETAPI_T                 h,
231                            NETCP_CFG_IPSEC_POLICY_T policy_app_id, 
232                            int*                     perr);
235 /**
236  *  @ingroup cfg_security_functions
237  *  @brief netapi_getSaStats: API to retrieve SA statistics via NWAL.
238  *
239  *  @details API to retrieve SA statistics via NWAL.
240  *  @param[in]  h   The NETAPI handle, @ref NETAPI_T
241  *  @param[in]  handle @ref NETCP_CFG_SA_T
242  *  @param[out] pSaStats Pointer to SA stats which will get populated by this API call @ref NETAPI_SA_STATS_T
243  *  @retval     none
244  *  @pre        @ref netapi_init, @ref netapi_secAddSA
245 */
246 void  netapi_getSaStats (NETAPI_T                   h,
247                          NETCP_CFG_SA_T             handle,
248                          NETAPI_SA_STATS_T*         pSaStats);
252 /**
253  *  @ingroup cfg_security_functions
254  *  @brief  API to retrieve internal context information from channel resources
255  *          maintained by NWAL. Selective NetCP PA/SA channel handles are exposed
256  *          to handle the case of multiple owner use case for PA/SA LLD
257  *  @details API to retrieve internal context information from channel resources
258  *          maintained by NWAL. Selective NetCP PA/SA channel handles are exposed
259  *          to handle the case of multiple owner use case for PA/SA LLD
260  *  @param[in]   h      The NETAPI handle, @ref NETAPI_T
261  *  @param[in]   appId  Application Id returned from any config APIs
262  *  @param[out]  pInfo  NWAL Channel context information
263  *  @retval     none
264  *  @pre        @ref netapi_init, @ref netapi_secAddSA
265  */
266 void netapi_secGetChanCtxInfo(NETAPI_T h,
267                            NETCP_CFG_APP_ID_T appId,
268                            nwalChanCxtInfo_t* pInfo);
271 #ifdef __cplusplus
273 #endif
274 #endif