Additional 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 cfg_security_structures
61  *  @brief NETAPI SA Statistics
62  *
63  *  @details Pointer to this strucutre is passed in the call to netapi_getSaStats API. It will be popluated with the requested statistics.
64  *  Currently only IPSEC stats are valid.
65  */
66 typedef struct NETAPI_SA_STATS_Tag
67 {
68 /**
69  * Bit map indicating the IPSec SA Inflow/Side band data mode stats validity
70  * <br>
71  * The validParams field indicates to the caller which stats being returned by calling the @ref netapi_getSaStats are valid.
72  *      @ref NETAPI_IPSEC_STAT_VALID, @ref NETAPI_SIDEBAND_DATA_MODE_STAT_VALID
73  */
74     uint16_t            validParams;            /**< Bit map indicating the IPSec SA Inflow/Side band data mode stats validity */
76 /**
77  * @def NETAPI_IPSEC_STAT_VALID
78  * @ingroup security_constants
79  *      Indicates to user application that IPSEC stats are valid for INFLOW mode
80  */
81 #define NETAPI_IPSEC_STAT_VALID                 0x0001 
83 /**
84  * @def NETAPI_SIDEBAND_DATA_MODE_STAT_VALID
85  * @ingroup security_constants
86  *      Indicates to user application that IPSEC stats are valid for SIDEBAND mode 
87  */
88 #define NETAPI_SIDEBAND_DATA_MODE_STAT_VALID    0x0002
90     Sa_IpsecStats_t     saIpsecStats;           /**<  Structure containing IPSEC stats in INFLOW MODE*/
91     Sa_DataModeStats_t  dataModeStats;          /**<  Structure containing IPSEC stats in SIDEBAND MODE */
92 } NETAPI_SA_STATS_T;
95 /**
96  *  @ingroup cfg_security_structures
97  *  @brief NETAPI security SA information
98  *
99  *  @details This structure contains the information necessary to create a security association (for either for inflow mode or sideband mode)
100  */
101 typedef struct NETAPI_SEC_SA_INFO_tag
103     nwal_SaDir          dir;            /**< Direction for the channel. Inbound or Outbound */
104     uint32_t            spi;            /**< IPSec Security Parameter index */
105     nwal_IpSecProto     proto;          /**< IpSec Proto (ESP/AH) */
106     nwal_saMode         saMode;         /**< Tunnel/ Transport mode (sideband RX/TX) */
107     nwal_IpType         ipType;         /**< IPV4 or V6 (sideband RX/TX) */
108     nwalIpAddr_t        src;            /**< Source IP Address (remote) (sideband RX) */
109     nwalIpAddr_t        dst;            /**< DST IP Address (local) (sideband RX) */
110     uint32_t            replayWindow;   /**< Replay Window Size (sideband RX) */
111     nwal_saAALG         authMode;       /**< Authentication Algorithm */
112     nwal_saEALG         cipherMode;     /**< Encryption Algorithm */
113     uint32_t            esnLo;          /**< Initial Value of Extended Sequence Number LSB (sideband TX) */
114     uint32_t            esnHi;          /**< Initial Value of Extended Sequence Number MSB (sideband TX) */
115 } NETAPI_SEC_SA_INFO_T;
119 /**
120  * @brief This defines the SA mode of operation to be INFLOW.  This means that IPSEC will be applied as the packet is being received or just before it is transmitted TBD
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 to be used a traditional accelerator TBD
127  * @ingroup security_constants
128  */
129 #define NETAPI_SEC_SA_SIDEBAND 0x1
131 /**
132  *  @ingroup cfg_security_functions
133  *  @brief netapi_secAddSA  API to configure an IPSEC SA.
134  *
135  *  @details API to configure an IPSec SA. SAs are IPSec security contexts and define a uni-directional
136  *           secure path (tunnel or transport). SAs are attached to MAC interfaces that have already
137  *           been created. API allows SA to be configured as either inflow or sideband mode. This API is used for both receive and transmit SAs.
138  *  @param[in]  h            The NETAPI handle, @ref NETAPI_T
139  *  @param[in]  iface_no     Interface to attach SA to.
140  *  @param[in]  sa_info      Information on the SA being added, @ref NETAPI_SEC_SA_INFO_T
141  *  @param[in]  key_params   Security key information for the SA.
142  *  @param[in]  mode         SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
143  *  @param[in]  route        @ref NETCP_CFG_ROUTE_HANDLE_T
144  *  @param[in]  data_mode_handle     Returned data mode handle for PKTIO (in the case of sideband SAs)
145  *  @param[in]  inflow_mode_handle   Returned inflow mode handle for PKTIO (in the case of TX inflow SAs)
146  *  @param[out]  perr        Pointer to error code.
147  *  @retval     Application id associated with created SA @ref NETCP_CFG_SA_T. This ID is used when referencing this SA in subsequent APIs (eg. to delete it). Also in the case of Receive Inflow,  packets will be tagged with this ID so that s/w will know that the packet has already been decrypted, authenticated and window-replay checked. (note: if a RX policy is matched also then the ID associated with the policy will be tagged instead).
148  *  @pre        @ref netapi_init
149  */
150 NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h,
151                                 int iface_no,
152                                 NETAPI_SEC_SA_INFO_T *sa_info,
153                                 nwalSecKeyParams_t *key_params,
154                                 int mode,
155                                 NETCP_CFG_ROUTE_HANDLE_T  route,
156                                 void ** data_mode_handle,
157                                 void ** inflow_mode_handle,
158                                 int * perr);
160 /**
161  *  @ingroup cfg_security_functions
162  *  @brief  netapi_secDelSA: API to delete an IPSEC SA. 
163  *
164  *  @details API to delete an IPSEC SA
165  *  @param[in]  h       The NETAPI handle, @ref NETAPI_T
166  *  @param[in] iface_no Interface to attach SA to.
167  *  @param[in] sa_app_id Application id returned from call to @ref netapi_secAddSA
168  *  @param[out] perr Pointer to error code.
169  *  @retval     none
170  *  @pre        @ref netapi_init @ref netapi_secAddSA
171 */
172 void netapi_secDelSA(NETAPI_T h,int iface_no, NETCP_CFG_SA_T  sa_app_id,  int *perr);
174 /**
175  *  @ingroup cfg_security_functions
176  *  @brief netapi_secAddRxPolicy: API to add a recieve security policy 
177  *
178  *  @details API to add a recieve security policy
179  *  @param[in]  h       The NETAPI handle @ref NETAPI_T
180  *  @param[in] sa       Application id returned from call to @ref netapi_secAddSA.  This SA must have beeen configured for (a) RX and (b) Inflow mode.
181  *  @param[in] ipType   IPV4 or IPV6
182  *  @param[in] src_ip_addr  source IP for policy check
183  *  @param[in] dst_ip_addr  destination IP for policy check
184  *  @param[in] ip_qualifiers  IP qualifiers for policy check
185  *  @param[in] route    Optional route @ref NETCP_CFG_ROUTE_HANDLE_T
186  *  @param[out] perr    Pointer to error code.
187  *  @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
188  *  @pre        @ref netapi_init @ref netapi_secAddSA
189 */
190 NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h,
191                                 NETCP_CFG_SA_T sa,
192                                 nwal_IpType ipType,
193                                 nwalIpAddr_t  * src_ip_addr,
194                                 nwalIpAddr_t  * dst_ip_addr,
195                                 nwalIpOpt_t * ip_qualifiers,
196                                 NETCP_CFG_ROUTE_HANDLE_T  route,
197                                 int * perr);
199 /**
200  *  @ingroup cfg_security_functions
201  *  @brief netapi_secDelRxPolicy: API to add a recieve security policy 
202  *
203  *  @details API to add a recieve security policy
204  *  @param[in]  h               The NETAPI handle, @ref NETAPI_T
205  *  @param[in] policy_app_id    Application id returned from call to @ref netapi_secAddRxPolicy
206  *  @param[out] perr            Pointer to error code.
207  *  @retval     none
208  *  @pre        @ref netapi_init, @ref netapi_secAddRxPolicy
209 */
210 void netapi_secDelRxPolicy(NETAPI_T h,
211                            NETCP_CFG_IPSEC_POLICY_T policy_app_id, 
212                            int *perr);
215 /**
216  *  @ingroup cfg_security_functions
217  *  @brief netapi_getSaStats: API to retrieve SA statistics via NWAL.
218  *
219  *  @details API to retrieve SA statistics via NWAL.
220  *  @param[in]  h   The NETAPI handle, @ref NETAPI_T
221  *  @param[in]  handle @ref NETCP_CFG_SA_T
222  *  @param[out] pSaStats Pointer to SA stats which will get populated by this API call @ref NETAPI_SA_STATS_T
223  *  @retval     none
224  *  @pre        @ref netapi_init, @ref netapi_secAddSA
225 */
226 void  netapi_getSaStats (NETAPI_T                   h,
227                          NETCP_CFG_SA_T             handle,
228                          NETAPI_SA_STATS_T*         pSaStats);
230 #endif