From: Vladimir Medvedkin <vladimir.medvedkin@intel.com>
To: dev@dpdk.org
Cc: konstantin.ananyev@intel.com, bernard.iremonger@intel.com,
akhil.goyal@nxp.com
Subject: [dpdk-dev] [PATCH v6 6/6] doc/ipsec: update ipsec programmer's guide
Date: Thu, 17 Oct 2019 16:48:03 +0100 [thread overview]
Message-ID: <7141ff3797906daf03a38169d21e5f8fcb1230d0.1571322983.git.vladimir.medvedkin@intel.com> (raw)
In-Reply-To: <cover.1571322982.git.vladimir.medvedkin@intel.com>
In-Reply-To: <cover.1571322982.git.vladimir.medvedkin@intel.com>
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(+)
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
-------------
--
2.7.4
next prev parent reply other threads:[~2019-10-17 15:49 UTC|newest]
Thread overview: 69+ messages / expand[flat|nested] mbox.gz Atom feed top
2019-08-13 15:13 [dpdk-dev] [RFC 0/5] ipsec: add inbound SAD Vladimir Medvedkin
2019-08-13 15:13 ` [dpdk-dev] [RFC 1/5] ipsec: add inbound SAD API Vladimir Medvedkin
2019-08-13 15:13 ` [dpdk-dev] [RFC 2/5] ipsec: add SAD create/free API Vladimir Medvedkin
2019-08-13 15:13 ` [dpdk-dev] [RFC 3/5] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-08-13 15:13 ` [dpdk-dev] [RFC 4/5] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-08-13 15:13 ` [dpdk-dev] [RFC 5/5] app: add test-sad application Vladimir Medvedkin
2019-09-03 16:55 ` [dpdk-dev] [PATCH v1 0/5] ipsec: add inbound SAD Vladimir Medvedkin
2019-10-01 17:25 ` [dpdk-dev] [PATCH v2 " Vladimir Medvedkin
2019-10-08 9:40 ` [dpdk-dev] [PATCH v3 " Vladimir Medvedkin
2019-10-08 16:55 ` [dpdk-dev] [PATCH v4 " Vladimir Medvedkin
2019-10-10 16:49 ` [dpdk-dev] [PATCH v5 " Vladimir Medvedkin
2019-10-11 11:34 ` Akhil Goyal
2019-10-17 15:47 ` [dpdk-dev] [PATCH v6 0/6] " Vladimir Medvedkin
2019-10-21 14:35 ` [dpdk-dev] [PATCH v7 0/5] " Vladimir Medvedkin
2019-10-22 7:53 ` Akhil Goyal
2019-10-21 14:35 ` [dpdk-dev] [PATCH v7 1/5] ipsec: add inbound SAD API Vladimir Medvedkin
2019-10-21 14:35 ` [dpdk-dev] [PATCH v7 2/5] ipsec: add SAD create/destroy implementation Vladimir Medvedkin
2019-10-21 14:35 ` [dpdk-dev] [PATCH v7 3/5] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-10-21 14:35 ` [dpdk-dev] [PATCH v7 4/5] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-10-21 14:35 ` [dpdk-dev] [PATCH v7 5/5] app: add test-sad application Vladimir Medvedkin
2019-10-17 15:47 ` [dpdk-dev] [PATCH v6 1/6] ipsec: add inbound SAD API Vladimir Medvedkin
2019-10-17 15:47 ` [dpdk-dev] [PATCH v6 2/6] ipsec: add SAD create/destroy implementation Vladimir Medvedkin
2019-10-17 15:48 ` [dpdk-dev] [PATCH v6 3/6] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-10-17 15:48 ` [dpdk-dev] [PATCH v6 4/6] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-10-17 15:48 ` [dpdk-dev] [PATCH v6 5/6] app: add test-sad application Vladimir Medvedkin
2019-10-21 9:57 ` Akhil Goyal
2019-10-17 15:48 ` Vladimir Medvedkin [this message]
2019-10-18 10:09 ` [dpdk-dev] [PATCH v6 6/6] doc/ipsec: update ipsec programmer's guide Ananyev, Konstantin
2019-10-21 8:19 ` Akhil Goyal
2019-10-10 16:49 ` [dpdk-dev] [PATCH v5 1/5] ipsec: add inbound SAD API Vladimir Medvedkin
2019-10-10 16:49 ` [dpdk-dev] [PATCH v5 2/5] ipsec: add SAD create/destroy implementation Vladimir Medvedkin
2019-10-10 16:49 ` [dpdk-dev] [PATCH v5 3/5] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-10-11 10:42 ` Akhil Goyal
2019-10-10 16:49 ` [dpdk-dev] [PATCH v5 4/5] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-10-10 16:49 ` [dpdk-dev] [PATCH v5 5/5] app: add test-sad application Vladimir Medvedkin
2019-10-08 16:55 ` [dpdk-dev] [PATCH v4 1/5] ipsec: add inbound SAD API Vladimir Medvedkin
2019-10-09 10:49 ` Ananyev, Konstantin
2019-10-08 16:55 ` [dpdk-dev] [PATCH v4 2/5] ipsec: add SAD create/destroy implementation Vladimir Medvedkin
2019-10-09 10:56 ` Ananyev, Konstantin
2019-10-08 16:55 ` [dpdk-dev] [PATCH v4 3/5] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-10-08 16:55 ` [dpdk-dev] [PATCH v4 4/5] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-10-08 16:55 ` [dpdk-dev] [PATCH v4 5/5] app: add test-sad application Vladimir Medvedkin
2019-10-08 9:40 ` [dpdk-dev] [PATCH v3 1/5] ipsec: add inbound SAD API Vladimir Medvedkin
2019-10-08 9:40 ` [dpdk-dev] [PATCH v3 2/5] ipsec: add SAD create/destroy implementation Vladimir Medvedkin
2019-10-08 9:40 ` [dpdk-dev] [PATCH v3 3/5] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-10-08 9:40 ` [dpdk-dev] [PATCH v3 4/5] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-10-08 9:40 ` [dpdk-dev] [PATCH v3 5/5] app: add test-sad application Vladimir Medvedkin
2019-10-01 17:25 ` [dpdk-dev] [PATCH v2 1/5] ipsec: add inbound SAD API Vladimir Medvedkin
2019-10-02 11:24 ` Ananyev, Konstantin
2019-10-01 17:25 ` [dpdk-dev] [PATCH v2 2/5] ipsec: add SAD create/destroy implementation Vladimir Medvedkin
2019-10-02 11:55 ` Ananyev, Konstantin
2019-10-01 17:25 ` [dpdk-dev] [PATCH v2 3/5] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-10-02 12:04 ` Ananyev, Konstantin
2019-10-01 17:25 ` [dpdk-dev] [PATCH v2 4/5] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-10-02 11:16 ` Ananyev, Konstantin
2019-10-01 17:25 ` [dpdk-dev] [PATCH v2 5/5] app: add test-sad application Vladimir Medvedkin
2019-10-02 13:27 ` Ananyev, Konstantin
2019-09-03 16:55 ` [dpdk-dev] [PATCH v1 1/5] ipsec: add inbound SAD API Vladimir Medvedkin
2019-09-14 23:05 ` Ananyev, Konstantin
2019-09-03 16:55 ` [dpdk-dev] [PATCH v1 2/5] ipsec: add SAD create/free API Vladimir Medvedkin
2019-09-12 18:08 ` Ananyev, Konstantin
2019-09-03 16:55 ` [dpdk-dev] [PATCH v1 3/5] ipsec: add SAD add/delete/lookup implementation Vladimir Medvedkin
2019-09-12 17:58 ` Ananyev, Konstantin
2019-10-01 17:24 ` Medvedkin, Vladimir
2019-09-03 16:55 ` [dpdk-dev] [PATCH v1 4/5] test/ipsec: add ipsec SAD autotests Vladimir Medvedkin
2019-09-03 16:55 ` [dpdk-dev] [PATCH v1 5/5] app: add test-sad application Vladimir Medvedkin
2019-09-12 18:30 ` Ananyev, Konstantin
2019-09-12 18:33 ` Ananyev, Konstantin
2019-09-12 18:34 ` [dpdk-dev] [RFC 0/5] ipsec: add inbound SAD Ananyev, Konstantin
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=7141ff3797906daf03a38169d21e5f8fcb1230d0.1571322983.git.vladimir.medvedkin@intel.com \
--to=vladimir.medvedkin@intel.com \
--cc=akhil.goyal@nxp.com \
--cc=bernard.iremonger@intel.com \
--cc=dev@dpdk.org \
--cc=konstantin.ananyev@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).