index d88473a6810d1037e639bab3aee8855ab3783af0..ac824ec9d8884c4ad0dfad1901a258863c92fb1a 100755 (executable)
-/**************************************************************
- * FILE PURPOSE : NETAPI SECURITY CONFIGURATION-
- * user space access to security transport resources on SOC
- **************************************************************
- * @file netapi_sec.h
- *
- * @brief DESCRIPTION: netapi security header file for user space transport
- * library
- *
- * REVISION HISTORY: rev 0.0.1
+/******************************************************************************
+ * FILE PURPOSE: Netapi Security configuration header file
+ ******************************************************************************
+ * FILE NAME: netapi_sec.h
+ *
+ * DESCRIPTION: netapi security header file for user space transport library
+ *
+ * REVISION HISTORY:
*
* Copyright (c) Texas Instruments Incorporated 2010-2011
- *
- * Redistribution and use in source and binary forms, with or without
- * modification, are permitted provided that the following conditions
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
* are met:
*
- * Redistributions of source code must retain the above copyright
+ * Redistributions of source code must retain the above copyright
* notice, this list of conditions and the following disclaimer.
*
* Redistributions in binary form must reproduce the above copyright
- * notice, this list of conditions and the following disclaimer in the
- * documentation and/or other materials provided with the
+ * notice, this list of conditions and the following disclaimer in the
+ * documentation and/or other materials provided with the
* distribution.
*
* Neither the name of Texas Instruments Incorporated nor the names of
* its contributors may be used to endorse or promote products derived
* from this software without specific prior written permission.
*
- * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
- * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
- * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
- * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
- * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+ * A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+ * OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+ * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
- * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
- * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+ * THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+ * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
-*****************************************************************************/
+ *
+ */
+/* ============================================================= */
+
+
+/**
+ * @file netapi_sec.h
+ * @brief netapi security header file for user space transport library
+ */
+
#ifndef __NETAPI_SEC__H
#define __NETAPI_SEC__H
#include "netapi.h"
#include "ti/drv/nwal/nwal.h"
#include <ti/drv/sa/salld.h>
-// To hold SA info */
+
+
+
+/**
+ * @ingroup netapi_structures
+ * @brief NETAPI SA Statistics
+ *
+ * @details Pointer to this strucutre is passed in the call to netapi_getSaStats API.
+ */
+
+
+typedef struct NETAPI_SA_STATS_Tag
+{
+#define NETAPI_IPSEC_STAT_VALID 0x0001
+#define NETAPI_SIDEBAND_DATA_MODE_STAT_VALID 0x0002
+ uint16_t validParams; /** < Bit map indicating the IPSec SA Inflow/Side band data mode stats validity */
+ Sa_IpsecStats_t saIpsecStats; /**< Structure containing IPSEC stats in INFLOW MODE*/
+ Sa_DataModeStats_t dataModeStats; /**< Structure containing IPSEC stats in SIDEBAND MODE */
+} NETAPI_SA_STATS_T;
+
+
+/**
+ * @ingroup netapi_structures
+ * @brief NETAPI security SA information
+ *
+ * @details This structure contains SA information
+ */
typedef struct NETAPI_SEC_SA_INFO_tag
{
- nwal_SaDir dir; /** Direction for the channel. Inbound or Outbound */
- uint32_t spi; /**< IPSec Security Parameter index */
+ nwal_SaDir dir; /**< Direction for the channel. Inbound or Outbound */
+ uint32_t spi; /**< IPSec Security Parameter index */
nwal_IpSecProto proto; /**< IpSec Proto (ESP/AH) */
nwal_saMode saMode; /**< Tunnel/ Transport mode */
nwal_IpType ipType; /**< IPV4 or V6 */
} NETAPI_SEC_SA_INFO_T;
+/**
+ * @brief This defines the SA mode of operation to be INFLOW
+ */
#define NETAPI_SEC_SA_INFLOW 0x2
+
+/**
+ * @brief This defines the SA mode of operation to be SIDEBAND
+ */
#define NETAPI_SEC_SA_SIDEBAND 0x1
-/******************************************************
- ************************API***************************
- *****************************************************/
-
-//**********************************
-//add SA
-//*******************************************
-NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h, //the netapi handle
- int iface_no, //inteface to attach to
- NETAPI_SEC_SA_INFO_T *sa_info ,//info on the SA
- nwalSecKeyParams_t *key_params, //keys,etc
- int mode, //SA implementation mode: inflow or sideband or both
- NETCP_CFG_ROUTE_HANDLE_T route, //Optional route
- void ** data_mode_handle, //returned data mode handle for pktio
- void ** inflow_mode_handle,//returned inflow mode handle for pktio
+/**
+ * @ingroup netapi_cfg_sec_functions
+ * @brief netapi_secAddSA: API to configure an IPSEC SA.
+ *
+ * @details API to configure an IPSec SA. SAs are IPSec security contexts and define a uni-directional
+ * secure path (tunnel or transport). SAs are attached to Mac interfaces that have already
+ * been created. API allows SA to be configured as either inflow or sideband mode
+ * @param[in] @ref NETAPI_T: the NETAPI handle
+ * @param[in] iface_no:interface to attach SA to.
+ * @param[in] sa_info: @ref NETAPI_SEC_SA_INFO_T: information on the SA being added
+ * @param[in] key_params: @ref nwalSecKeyParams_t: security key information for the SA.
+ * @param[in] mode: SA implementation mode @ref NETAPI_SEC_SA_SIDEBAND or @ref NETAPI_SEC_SA_INFLOW
+ * @param[in] route: @ref NETCP_CFG_ROUTE_HANDLE_T
+ * @param[in] data_mode_handle: returned data mode handle for PKTIO
+ * @param[in] inflow_mode_handle: returned inflow mode handle for PKTIO
+ * @param[out] perr: error codem, zero on sucess, non-zero on failure
+ * @retval Aplication id associated with created SA, @ref NETCP_CFG_SA_T
+ * @pre @ref netapi_init
+ */
+NETCP_CFG_SA_T netapi_secAddSA(NETAPI_T h,
+ int iface_no,
+ NETAPI_SEC_SA_INFO_T *sa_info ,
+ nwalSecKeyParams_t *key_params,
+ int mode,
+ NETCP_CFG_ROUTE_HANDLE_T route,
+ void ** data_mode_handle,
+ void ** inflow_mode_handle,
int * perr);
-//*****************************************
-//delete SA
-//*****************************************
+/**
+ * @ingroup netapi_cfg_sec_functions
+ * @brief netapi_secDelSA: API to delete an IPSEC SA.
+ *
+ * @details API to delete an IPSEC SA
+ * @param[in] h the NETAPI handle, @ref NETAPI_T
+ * @param[in] iface_no:interface to attach SA to.
+ * @param[in] sa_app_id: Application id returned from call to @ref netapi_secAddSA
+ * @param[out] perr: zero on sucess, non-zero on failure
+ * @retval none
+ * @pre @ref netapi_init @ref netapi_secAddSA
+*/
void netapi_secDelSA(NETAPI_T h,int iface_no, NETCP_CFG_SA_T sa_app_id, int *perr);
-//******************************************
-// Add RX Security Policy
-//******************************************
+/**
+ * @ingroup netapi_cfg_sec_functions
+ * @brief netapi_secAddRxPolicy: API to add a recieve security policy
+ *
+ * @details API to add a recieve security policy
+ * @param[in] h the NETAPI handle, @ref NETAPI_T
+ * @param[in] sa: Application id returned from call to @ref netapi_secAddSA
+ * @param[in] ipType, @ref nwal_IpType
+ * @param[in] src_ip_addr, @ref nwalIpAddr_t
+ * @param[in] dst_ip_addr, @ref nwalIpAddr_t
+ * @param[in] ip_qualifiers @ref nwalIpOpt_t
+ * @param[in] route: optional route, @ref NETCP_CFG_ROUTE_HANDLE_T
+ * @param[out] perr: zero on sucess, non-zero on failure
+ * @retval Aplication id associated with created receive security policy , @ref NETCP_CFG_IPSEC_POLICY_T
+ * @pre @ref netapi_init @ref netapi_secAddSA
+*/
NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h, //the netapi handle
NETCP_CFG_SA_T sa, //tunnel to attach to
nwal_IpType ipType, //V4 or V6
@@ -101,14 +175,34 @@ NETCP_CFG_IPSEC_POLICY_T netapi_secAddRxPolicy(NETAPI_T h, //the netapi handle
NETCP_CFG_ROUTE_HANDLE_T route, //Optional route
int * perr);
-//******************************************
-// Delete RX Security Policy
-//******************************************
+/**
+ * @ingroup netapi_cfg_sec_functions
+ * @brief netapi_secDelRxPolicy: API to add a recieve security policy
+ *
+ * @details API to add a recieve security policy
+ * @param[in] h the NETAPI handle, @ref NETAPI_T
+ * @param[in] policy_app_id: Application id returned from call to @ref netapi_secAddRxPolicy
+ * @param[out] perr: zero on sucess, non-zero on failure
+ * @retval none
+ * @pre @ref netapi_init @ref, @ref netapi_secAddRxPolicy
+*/
void netapi_secDelRxPolicy(NETAPI_T h,
NETCP_CFG_IPSEC_POLICY_T policy_app_id,
int *perr);
-
+/**
+ * @ingroup netapi_cfg_sec_functions
+ * @brief netapi_getSaStats: API to retrieve SA statistics via NWAL.
+ *
+ * @details * API to retrieve SA statistics via NWAL.
+ * @param[in] h the NETAPI handle, @ref NETAPI_T
+ * @param[in] pSaStats: Pointer to NETAPI_SA_STATS_T which will get populated by this API call, @ref NETAPI_SA_STATS_T
+ * @retval none
+ * @pre @ref netapi_init @ref, @ref netapi_secAddSA
+*/
+void netapi_getSaStats (NETAPI_T h,
+ NETCP_CFG_SA_T handle,
+ NETAPI_SA_STATS_T* pSaStats);
#endif