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. It will be popluated with the requested statistics.  Currently only IPSEC stats are valid.
64  */
65 typedef struct NETAPI_SA_STATS_Tag
66 {
67 #define NETAPI_IPSEC_STAT_VALID                 0x0001 /**< Indicates to user application that IPSEC stats are valid for INFLOW mode */
68 #define NETAPI_SIDEBAND_DATA_MODE_STAT_VALID    0x0002 /**< Indicates to user application that IPSEC stats are valid for SIDEBAND mode */
69     uint16_t            validParams;            /**< Bit map indicating the IPSec SA Inflow/Side band data mode stats validity */
70     Sa_IpsecStats_t     saIpsecStats;           /**<  Structure containing IPSEC stats in INFLOW MODE*/
71     Sa_DataModeStats_t  dataModeStats;          /**<  Structure containing IPSEC stats in SIDEBAND MODE */
72 } NETAPI_SA_STATS_T;
75 /**
76  *  @ingroup netapi_structures
77  *  @brief NETAPI security SA information
78  *
79  *  @details This structure contains the information necessary to create a security association (for either for inflow mode or sideband mode)
80  */
81 typedef struct NETAPI_SEC_SA_INFO_tag
82 {
83     nwal_SaDir          dir;            /**< Direction for the channel. Inbound or Outbound */
84     uint32_t            spi;            /**< IPSec Security Parameter index */
85     nwal_IpSecProto     proto;          /**< IpSec Proto (ESP/AH) */
86     nwal_saMode         saMode;         /**< Tunnel/ Transport mode (sideband RX/TX) */
87     nwal_IpType         ipType;         /**< IPV4 or V6 (sideband RX/TX) */
88     nwalIpAddr_t        src;            /**< Source IP Address (remote) (sideband RX) */
89     nwalIpAddr_t        dst;            /**< DST IP Address (local) (sideband RX) */
90     uint32_t            replayWindow;   /**< Replay Window Size (sideband RX) */
91     nwal_saAALG         authMode;       /**< Authentication Algorithm */
92     nwal_saEALG         cipherMode;     /**< Encryption Algorithm */
93     uint32_t            esnLo;          /**< Initial Value of Extended Sequence Number LSB (sideband TX) */
94     uint32_t            esnHi;          /**< Initial Value of Extended Sequence Number MSB (sideband TX) */
95 } NETAPI_SEC_SA_INFO_T;
98 /**
99  * @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
100  */
101 #define NETAPI_SEC_SA_INFLOW   0x2
103 /**
104  * @brief This defines the SA mode of operation to be SIDEBAND.  This means that Security Acclerator is to be used a traditional accelerator.
105  */
106 #define NETAPI_SEC_SA_SIDEBAND 0x1
108 /**
109  *  @ingroup netapi_cfg_sec_functions
110  *  @brief netapi_secAddSA  API to configure an IPSEC SA.
111  *
112  *  @details API to configure an IPSec SA. SAs are IPSec security contexts and define a uni-directional
113  *           secure path (tunnel or transport). SAs are attached to MAC interfaces that have already
114  *           been created. API allows SA to be configured as either inflow or sideband mode. This API is used for both receive and transmit SAs.
115  *  @param[in]  h            The NETAPI handle, @ref NETAPI_T
116  *  @param[in]  iface_no     Interface to attach SA to.
117  *  @param[in]  sa_info      Information on the SA being added, @ref NETAPI_SEC_SA_INFO_T
118  *  @param[in]  key_params   Security key information for the SA.
119  *  @param[in]  mode         SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
120  *  @param[in]  route        @ref NETCP_CFG_ROUTE_HANDLE_T
121  *  @param[in]  data_mode_handle     Returned data mode handle for PKTIO (in the case of sideband SAs)
122  *  @param[in]  inflow_mode_handle   Returned inflow mode handle for PKTIO (in the case of TX inflow SAs)
123  *  @param[out]  perr        Pointer to error code.
124  *  @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).
125  *  @pre        @ref netapi_init
126  */
127 NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h,
128                                 int iface_no,
129                                 NETAPI_SEC_SA_INFO_T *sa_info,
130                                 nwalSecKeyParams_t *key_params,
131                                 int mode,
132                                 NETCP_CFG_ROUTE_HANDLE_T  route,
133                                 void ** data_mode_handle,
134                                 void ** inflow_mode_handle,
135                                 int * perr);
137 /**
138  *  @ingroup netapi_cfg_sec_functions
139  *  @brief  netapi_secDelSA: API to delete an IPSEC SA. 
140  *
141  *  @details API to delete an IPSEC SA
142  *  @param[in]  h       The NETAPI handle, @ref NETAPI_T
143  *  @param[in] iface_no Interface to attach SA to.
144  *  @param[in] sa_app_id Application id returned from call to @ref netapi_secAddSA
145  *  @param[out] perr Pointer to error code.
146  *  @retval     none
147  *  @pre        @ref netapi_init @ref netapi_secAddSA
148 */
149 void netapi_secDelSA(NETAPI_T h,int iface_no, NETCP_CFG_SA_T  sa_app_id,  int *perr);
151 /**
152  *  @ingroup netapi_cfg_sec_functions
153  *  @brief netapi_secAddRxPolicy: API to add a recieve security policy 
154  *
155  *  @details API to add a recieve security policy
156  *  @param[in]  h       The NETAPI handle @ref NETAPI_T
157  *  @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.
158  *  @param[in] ipType   IPV4 or IPV6
159  *  @param[in] src_ip_addr  source IP for policy check
160  *  @param[in] dst_ip_addr  destination IP for policy check
161  *  @param[in] ip_qualifiers  IP qualifiers for policy check (see @ref  nwaIpOpt_t)
162  *  @param[in] route    Optional route @ref NETCP_CFG_ROUTE_HANDLE_T
163  *  @param[out] perr    Pointer to error code.
164  *  @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
165  *  @pre        @ref netapi_init @ref netapi_secAddSA
166 */
167 NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h,
168                                 NETCP_CFG_SA_T sa,
169                                 nwal_IpType ipType,
170                                 nwalIpAddr_t  * src_ip_addr,
171                                 nwalIpAddr_t  * dst_ip_addr,
172                                 nwalIpOpt_t * ip_qualifiers,
173                                 NETCP_CFG_ROUTE_HANDLE_T  route,
174                                 int * perr);
176 /**
177  *  @ingroup netapi_cfg_sec_functions
178  *  @brief netapi_secDelRxPolicy: API to add a recieve security policy 
179  *
180  *  @details API to add a recieve security policy
181  *  @param[in]  h               The NETAPI handle, @ref NETAPI_T
182  *  @param[in] policy_app_id    Application id returned from call to @ref netapi_secAddRxPolicy
183  *  @param[out] perr            Pointer to error code.
184  *  @retval     none
185  *  @pre        @ref netapi_init, @ref netapi_secAddRxPolicy
186 */
187 void netapi_secDelRxPolicy(NETAPI_T h,
188                            NETCP_CFG_IPSEC_POLICY_T policy_app_id, 
189                            int *perr);
192 /**
193  *  @ingroup netapi_cfg_sec_functions
194  *  @brief netapi_getSaStats: API to retrieve SA statistics via NWAL.
195  *
196  *  @details API to retrieve SA statistics via NWAL.
197  *  @param[in]  h   The NETAPI handle, @ref NETAPI_T
198  *  @param[in]  handle @ref NETCP_CFG_SA_T
199  *  @param[out] pSaStats Pointer to SA stats which will get populated by this API call @ref NETAPI_SA_STATS_T
200  *  @retval     none
201  *  @pre        @ref netapi_init, @ref netapi_secAddSA
202 */
203 void  netapi_getSaStats (NETAPI_T                   h,
204                          NETCP_CFG_SA_T             handle,
205                          NETAPI_SA_STATS_T*         pSaStats);
207 #endif