ipsec: add SAD create/destroy implementation

[dpdk.git] / doc / guides / prog_guide / ipsec_lib.rst

diff --git a/doc/guides/prog_guide/ipsec_lib.rst b/doc/guides/prog_guide/ipsec_lib.rst
index 992fdf4..f69019e 100644 (file)
--- a/doc/guides/prog_guide/ipsec_lib.rst
+++ b/doc/guides/prog_guide/ipsec_lib.rst
@@ -65,7 +65,7 @@ In that mode the library functions perform
 
   - check SQN
   - prepare *rte_crypto_op* structure for each input packet
-  - verify that integity check and decryption performed by crypto device
+  - verify that integrity check and decryption performed by crypto device
     completed successfully
   - check padding data
   - remove outer IP header (tunnel mode) / update IP header (transport mode)
@@ -88,7 +88,7 @@ In that mode the library functions perform
 
 * for inbound packets:
 
-  - verify that integity check and decryption performed by *rte_security*
+  - verify that integrity check and decryption performed by *rte_security*
     device completed successfully
   - check SQN
   - check padding data
@@ -101,10 +101,10 @@ In that mode the library functions perform
   - generate SQN and IV
   - add outer IP header (tunnel mode) / update IP header (transport mode)
   - add ESP header and trailer, padding and IV data
-  - update *ol_flags* inside *struct  rte_mbuf* to inidicate that
+  - update *ol_flags* inside *struct  rte_mbuf* to indicate that
     inline-crypto processing has to be performed by HW on this packet
   - invoke *rte_security* device specific *set_pkt_metadata()* to associate
-    secuirty device specific data with the packet
+    security device specific data with the packet
 
 RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -113,15 +113,15 @@ In that mode the library functions perform
 
 * for inbound packets:
 
-  - verify that integity check and decryption performed by *rte_security*
+  - verify that integrity check and decryption performed by *rte_security*
     device completed successfully
 
 * for outbound packets:
 
-  - update *ol_flags* inside *struct  rte_mbuf* to inidicate that
+  - update *ol_flags* inside *struct  rte_mbuf* to indicate that
     inline-crypto processing has to be performed by HW on this packet
   - invoke *rte_security* device specific *set_pkt_metadata()* to associate
-    secuirty device specific data with the packet
+    security device specific data with the packet
 
 RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -131,7 +131,7 @@ In that mode the library functions perform
 * for inbound packets:
 
   - prepare *rte_crypto_op* structure for each input packet
-  - verify that integity check and decryption performed by crypto device
+  - verify that integrity check and decryption performed by crypto device
     completed successfully
 
 * for outbound packets:
@@ -143,6 +143,48 @@ In that mode the library functions perform
 To accommodate future custom implementations function pointers
 model is used for both *crypto_prepare* and *process* implementations.
 
+SA database API
+----------------
+
+SA database(SAD) is a table with <key, value> pairs.
+
+Value is an opaque user provided pointer to the user defined SA data structure.
+
+According to RFC4301 each SA can be uniquely identified by a key
+which is either:
+
+  - security parameter index(SPI)
+  - or SPI and destination IP(DIP)
+  - or SPI, DIP and source IP(SIP)
+
+In case of multiple matches, longest matching key will be returned.
+
+Create/destroy
+~~~~~~~~~~~~~~
+
+librte_ipsec SAD implementation provides ability to create/destroy SAD tables.
+
+To create SAD table user has to specify how many entries of each key type is
+required and IP protocol type (IPv4/IPv6).
+As an example:
+
+
+.. code-block:: c
+
+    struct rte_ipsec_sad *sad;
+    struct rte_ipsec_sad_conf conf;
+
+    conf.socket_id = -1;
+    conf.max_sa[RTE_IPSEC_SAD_SPI_ONLY] = some_nb_rules_spi_only;
+    conf.max_sa[RTE_IPSEC_SAD_SPI_DIP] = some_nb_rules_spi_dip;
+    conf.max_sa[RTE_IPSEC_SAD_SPI_DIP_SIP] = some_nb_rules_spi_dip_sip;
+    conf.flags = RTE_IPSEC_SAD_FLAG_RW_CONCURRENCY;
+
+    sad = rte_ipsec_sad_create("test", &conf);
+
+.. note::
+
+    for more information please refer to ipsec library API reference
 
 Supported features
 ------------------
@@ -153,7 +195,7 @@ Supported features
 
 *  ESN and replay window.
 
-*  algorithms: AES-CBC, AES-GCM, HMAC-SHA1, NULL.
+*  algorithms: 3DES-CBC, AES-CBC, AES-CTR, AES-GCM, HMAC-SHA1, NULL.
 
 
 Limitations
@@ -161,8 +203,4 @@ Limitations
 
 The following features are not properly supported in the current version:
 
-*  ESP transport mode for IPv6 packets with extension headers.
-*  Multi-segment packets.
-*  Updates of the fields in inner IP header for tunnel mode
-   (as described in RFC 4301, section 5.1.2).
 *  Hard/soft limit for SA lifetime (time interval/byte count).