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
51 #include "netapi.h"
52 #include "ti/drv/nwal/nwal.h"
53 #include <ti/drv/sa/salld.h>
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 */
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
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
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;
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;
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
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
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);
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);
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);
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);
246 /**
247 * @ingroup cfg_security_functions
248 * @brief netapi_secGetChanCtxInfo API to retrieve SA and PA channel handles for security
249 * context if already configured
250 *
251 * @details API to retrieve SA and PA channel handles for security
252 * context if already configured
253 * @param[in] h The NETAPI handle, @ref NETAPI_T
254 * @param[in] sa_app_id Application id returned from call to @ref netapi_secAddSA
255 * @param[in] policy_app_id Application id returned from call to @ref netapi_secAddPolicy
256 * @param[out] pPaHandleOuterIP Pointer to PA LLD handle for outer IP
257 * @param[out] pPaHandleInnerIP Pointer to PA LLD handle for inner IP
258 * @param[out] pSaHandle Pointer to SA LLD
259 * @retval none
260 * @pre @ref netapi_init, @ref netapi_secAddSA
261 */
262 void netapi_secGetChanCtxInfo(NETAPI_T h,
263 NETCP_CFG_SA_T sa_app_id,
264 NETCP_CFG_IPSEC_POLICY_T policy_app_id,
265 NETCP_CFG_PA_HANDLE_T* pPaHandleOuterIP,
266 NETCP_CFG_PA_HANDLE_T* pPaHandleInnerIP,
267 NETCP_CFG_SA_HANDLE_T* pSaHandle);
269 #endif