This commit adds the following:
[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
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
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