[v6,6/6] doc/ipsec: update ipsec programmer's guide
Checks
Commit Message
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
>
> 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
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.
@@ -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
------------------
@@ -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
-------------