From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from dpdk.org (dpdk.org [92.243.14.124]) by inbox.dpdk.org (Postfix) with ESMTP id 36049A317C for ; Thu, 17 Oct 2019 17:49:09 +0200 (CEST) Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id BE2471EA42; Thu, 17 Oct 2019 17:48:30 +0200 (CEST) Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by dpdk.org (Postfix) with ESMTP id 90C231E9F1 for ; Thu, 17 Oct 2019 17:48:18 +0200 (CEST) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from orsmga005.jf.intel.com ([10.7.209.41]) by fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 17 Oct 2019 08:48:18 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.67,308,1566889200"; d="scan'208";a="371174165" Received: from silpixa00400072.ir.intel.com ([10.237.222.213]) by orsmga005.jf.intel.com with ESMTP; 17 Oct 2019 08:48:16 -0700 From: Vladimir Medvedkin To: dev@dpdk.org Cc: konstantin.ananyev@intel.com, bernard.iremonger@intel.com, akhil.goyal@nxp.com Date: Thu, 17 Oct 2019 16:48:03 +0100 Message-Id: <7141ff3797906daf03a38169d21e5f8fcb1230d0.1571322983.git.vladimir.medvedkin@intel.com> X-Mailer: git-send-email 2.7.4 In-Reply-To: References: In-Reply-To: References: Subject: [dpdk-dev] [PATCH v6 6/6] doc/ipsec: update ipsec programmer's guide X-BeenThere: dev@dpdk.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" Add section about ipsec SAD Update release notes Signed-off-by: Vladimir Medvedkin --- 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 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