diff mbox series

[v6,6/6] doc/ipsec: update ipsec programmer's guide

Message ID 7141ff3797906daf03a38169d21e5f8fcb1230d0.1571322983.git.vladimir.medvedkin@intel.com (mailing list archive)
State Superseded, archived
Delegated to: akhil goyal
Headers show
Series ipsec: add inbound SAD | expand

Checks

Context Check Description
ci/checkpatch success coding style OK
ci/Intel-compilation success Compilation OK
ci/travis-robot success Travis build: passed

Commit Message

Vladimir Medvedkin Oct. 17, 2019, 3:48 p.m. UTC
Add section about ipsec SAD
Update release notes

Signed-off-by: Vladimir Medvedkin <vladimir.medvedkin@intel.com>
---
 doc/guides/prog_guide/ipsec_lib.rst    | 152 +++++++++++++++++++++++++++++++++
 doc/guides/rel_notes/release_19_11.rst |   3 +
 2 files changed, 155 insertions(+)

Comments

Ananyev, Konstantin Oct. 18, 2019, 10:09 a.m. UTC | #1
> 
> Add section about ipsec SAD
> Update release notes
> 
> Signed-off-by: Vladimir Medvedkin <vladimir.medvedkin@intel.com>
> ---

Acked-by: Konstantin Ananyev <konstantin.ananyev@intel.com>

> --
> 2.7.4
Akhil Goyal Oct. 21, 2019, 8:19 a.m. UTC | #2
Hi Vladimir,
> 
> Add section about ipsec SAD
> Update release notes
> 
> Signed-off-by: Vladimir Medvedkin <vladimir.medvedkin@intel.com>
> ---
>  doc/guides/prog_guide/ipsec_lib.rst    | 152
> +++++++++++++++++++++++++++++++++
>  doc/guides/rel_notes/release_19_11.rst |   3 +
>  2 files changed, 155 insertions(+)
> 
This patch needs to be split across all other patches.
As per the current convention we should not have separate commits for
Documentation.
Split relevant documentation in each of the patches.
diff mbox series

Patch

diff --git a/doc/guides/prog_guide/ipsec_lib.rst b/doc/guides/prog_guide/ipsec_lib.rst
index 63b75b6..4487e4c 100644
--- a/doc/guides/prog_guide/ipsec_lib.rst
+++ b/doc/guides/prog_guide/ipsec_lib.rst
@@ -143,6 +143,158 @@  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
+
+Add/delete rules
+~~~~~~~~~~~~~~~~
+
+Library also provides methods to add or delete key/value pairs from the SAD.
+To add user has to specify key, key type and a value which is an opaque pointer to SA.
+The key type reflects a set of tuple fields that will be used for lookup of the SA.
+As mentioned above there are 3 types of a key and the representation of a key type is:
+
+.. code-block:: c
+
+        RTE_IPSEC_SAD_SPI_ONLY,
+        RTE_IPSEC_SAD_SPI_DIP,
+        RTE_IPSEC_SAD_SPI_DIP_SIP,
+
+As an example, to add new entry into the SAD for IPv4 addresses:
+
+.. code-block:: c
+
+    struct rte_ipsec_sa *sa;
+    union rte_ipsec_sad_key key;
+
+    key.v4.spi = rte_cpu_to_be_32(spi_val);
+    if (key_type >= RTE_IPSEC_SAD_SPI_DIP) /* DIP is optional*/
+        key.v4.dip = rte_cpu_to_be_32(dip_val);
+    if (key_type == RTE_IPSEC_SAD_SPI_DIP_SIP) /* SIP is optional*/
+        key.v4.sip = rte_cpu_to_be_32(sip_val);
+
+    rte_ipsec_sad_add(sad, &key, key_type, sa);
+
+.. note::
+
+    By performance reason it is better to keep spi/dip/sip in net byte order
+    to eliminate byteswap on lookup
+
+To delete user has to specify key and key type.
+
+Delete code would look like:
+
+.. code-block:: c
+
+    union rte_ipsec_sad_key key;
+
+    key.v4.spi = rte_cpu_to_be_32(necessary_spi);
+    if (key_type >= RTE_IPSEC_SAD_SPI_DIP) /* DIP is optional*/
+        key.v4.dip = rte_cpu_to_be_32(necessary_dip);
+    if (key_type == RTE_IPSEC_SAD_SPI_DIP_SIP) /* SIP is optional*/
+        key.v4.sip = rte_cpu_to_be_32(necessary_sip);
+
+    rte_ipsec_sad_del(sad, &key, key_type);
+
+
+Lookup
+~~~~~~
+Library provides lookup by the given {SPI,DIP,SIP} tuple of
+inbound ipsec packet as a key.
+
+The search key is represented by:
+
+.. code-block:: c
+
+    union rte_ipsec_sad_key {
+        struct rte_ipsec_sadv4_key  v4;
+        struct rte_ipsec_sadv6_key  v6;
+    };
+
+where v4 is a tuple for IPv4:
+
+.. code-block:: c
+
+    struct rte_ipsec_sadv4_key {
+        uint32_t spi;
+        uint32_t dip;
+        uint32_t sip;
+    };
+
+and v6 is a tuple for IPv6:
+
+.. code-block:: c
+
+    struct rte_ipsec_sadv6_key {
+        uint32_t spi;
+        uint8_t dip[16];
+        uint8_t sip[16];
+    };
+
+As an example, lookup related code could look like that:
+
+.. code-block:: c
+
+    int i;
+    union rte_ipsec_sad_key keys[BURST_SZ];
+    const union rte_ipsec_sad_key *keys_p[BURST_SZ];
+    void *vals[BURST_SZ];
+
+    for (i = 0; i < BURST_SZ_MAX; i++) {
+        keys[i].v4.spi = esp_hdr[i]->spi;
+        keys[i].v4.dip = ipv4_hdr[i]->dst_addr;
+        keys[i].v4.sip = ipv4_hdr[i]->src_addr;
+        keys_p[i] = &keys[i];
+    }
+    rte_ipsec_sad_lookup(sad, keys_p, vals, BURST_SZ);
+
+    for (i = 0; i < BURST_SZ_MAX; i++) {
+        if (vals[i] == NULL)
+            printf("SA not found for key index %d\n", i);
+        else
+            printf("SA pointer is %p\n", vals[i]);
+    }
+
 
 Supported features
 ------------------
diff --git a/doc/guides/rel_notes/release_19_11.rst b/doc/guides/rel_notes/release_19_11.rst
index 85953b9..581f311 100644
--- a/doc/guides/rel_notes/release_19_11.rst
+++ b/doc/guides/rel_notes/release_19_11.rst
@@ -115,6 +115,9 @@  New Features
   Added eBPF JIT support for arm64 architecture to improve the eBPF program
   performance.
 
+* **Updated the IPSec library.**
+
+ Added SA Database API to ``librte_ipsec``
 
 Removed Items
 -------------