Doxygen updates
[keystone-rtos/netapi.git] / ti / runtime / netapi / netapi_sec.h
old mode 100644 (file)
new mode 100755 (executable)
index 6c8486c..ac824ec
@@ -1,56 +1,89 @@
-/**************************************************************
- * 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/runtime/pktlib/pktlib.h"
 #include "ti/drv/nwal/nwal.h"
+#include <ti/drv/sa/salld.h>
+
+
+
+
+/**
+ *  @ingroup netapi_structures
+ *  @brief NETAPI SA Statistics
+ *
+ *  @details Pointer to this strucutre is passed in the call to netapi_getSaStats API.
+ */
 
 
-// To hold SA info */
+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 */
@@ -64,34 +97,75 @@ typedef struct NETAPI_SEC_SA_INFO_tag
 } 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