From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga11.intel.com (mga11.intel.com [192.55.52.93]) by dpdk.org (Postfix) with ESMTP id 951081B3EC for ; Thu, 3 Jan 2019 21:16:45 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga007.fm.intel.com ([10.253.24.52]) by fmsmga102.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 03 Jan 2019 12:16:45 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,436,1539673200"; d="scan'208";a="111922279" Received: from sivswdev08.ir.intel.com (HELO localhost.localdomain) ([10.237.217.47]) by fmsmga007.fm.intel.com with ESMTP; 03 Jan 2019 12:16:44 -0800 From: Konstantin Ananyev To: dev@dpdk.org Cc: akhil.goyal@nxp.com, Konstantin Ananyev , Bernard Iremonger Date: Thu, 3 Jan 2019 20:16:26 +0000 Message-Id: <1546546586-22009-11-git-send-email-konstantin.ananyev@intel.com> X-Mailer: git-send-email 1.7.0.7 In-Reply-To: <1546010263-16257-2-git-send-email-konstantin.ananyev@intel.com> References: <1546010263-16257-2-git-send-email-konstantin.ananyev@intel.com> To: dev@dpdk.org Subject: [dpdk-dev] [PATCH v6 10/10] doc: add IPsec library 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: , X-List-Received-Date: Thu, 03 Jan 2019 20:16:46 -0000 Add IPsec library guide and update release notes. Signed-off-by: Bernard Iremonger Signed-off-by: Konstantin Ananyev --- doc/guides/prog_guide/index.rst | 1 + doc/guides/prog_guide/ipsec_lib.rst | 168 +++++++++++++++++++++++++ doc/guides/rel_notes/release_19_02.rst | 11 ++ 3 files changed, 180 insertions(+) create mode 100644 doc/guides/prog_guide/ipsec_lib.rst diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst index ba8c1f6ad..6726b1e8d 100644 --- a/doc/guides/prog_guide/index.rst +++ b/doc/guides/prog_guide/index.rst @@ -54,6 +54,7 @@ Programmer's Guide vhost_lib metrics_lib bpf_lib + ipsec_lib source_org dev_kit_build_system dev_kit_root_make_help diff --git a/doc/guides/prog_guide/ipsec_lib.rst b/doc/guides/prog_guide/ipsec_lib.rst new file mode 100644 index 000000000..e50d357c8 --- /dev/null +++ b/doc/guides/prog_guide/ipsec_lib.rst @@ -0,0 +1,168 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Intel Corporation. + +IPsec Packet Processing Library +=============================== + +DPDK provides a library for IPsec data-path processing. +The library utilizes the existing DPDK crypto-dev and +security API to provide the application with a transparent and +high performant IPsec packet processing API. +The library is concentrated on data-path protocols processing +(ESP and AH), IKE protocol(s) implementation is out of scope +for this library. + +SA level API +------------ + +This API operates on the IPsec Security Association (SA) level. +It provides functionality that allows user for given SA to process +inbound and outbound IPsec packets. + +To be more specific: + +* for inbound ESP/AH packets perform decryption, authentication, integrity checking, remove ESP/AH related headers +* for outbound packets perform payload encryption, attach ICV, update/add IP headers, add ESP/AH headers/trailers, +* setup related mbuf fields (ol_flags, tx_offloads, etc.). +* initialize/un-initialize given SA based on user provided parameters. + +The SA level API is based on top of crypto-dev/security API and relies on +them to perform actual cipher and integrity checking. + +Due to the nature of the crypto-dev API (enqueue/dequeue model) the library +introduces an asynchronous API for IPsec packets destined to be processed by +the crypto-device. + +The expected API call sequence for data-path processing would be: + +.. code-block:: c + + /* enqueue for processing by crypto-device */ + rte_ipsec_pkt_crypto_prepare(...); + rte_cryptodev_enqueue_burst(...); + /* dequeue from crypto-device and do final processing (if any) */ + rte_cryptodev_dequeue_burst(...); + rte_ipsec_pkt_crypto_group(...); /* optional */ + rte_ipsec_pkt_process(...); + +For packets destined for inline processing no extra overhead +is required and the synchronous API call: rte_ipsec_pkt_process() +is sufficient for that case. + +.. note:: + + For more details about the IPsec API, please refer to the *DPDK API Reference*. + +The current implementation supports all four currently defined +rte_security types: + +RTE_SECURITY_ACTION_TYPE_NONE +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In that mode the library functions perform + +* for inbound packets: + + - check SQN + - prepare *rte_crypto_op* structure for each input packet + - verify that integity check and decryption performed by crypto device + completed successfully + - check padding data + - remove outer IP header (tunnel mode) / update IP header (transport mode) + - remove ESP header and trailer, padding, IV and ICV data + - update SA replay window + +* for outbound packets: + + - generate SQN and IV + - add outer IP header (tunnel mode) / update IP header (transport mode) + - add ESP header and trailer, padding and IV data + - prepare *rte_crypto_op* structure for each input packet + - verify that crypto device operations (encryption, ICV generation) + were completed successfully + +RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In that mode the library functions perform + +* for inbound packets: + + - verify that integity check and decryption performed by *rte_security * + device completed successfully + - check SQN + - check padding data + - remove outer IP header (tunnel mode) / update IP header (transport mode) + - remove ESP header and trailer, padding, IV and ICV data + - update SA replay window + +* for outbound packets: + + - 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 + 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 + +RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +In that mode the library functions perform + +* for inbound packets: + + - verify that integity check and decryption performed by *rte_security * + device completed successfully + +* for outbound packets: + + - update *ol_flags* inside *struct rte_mbuf* to inidicate 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 + +RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 + completed successfully + +* for outbound packets: + + - prepare *rte_crypto_op* structure for each input packet + - verify that crypto device operations (encryption, ICV generation) + were completed successfully + +To accommodate future custom implementations function pointers +model is used for both *crypto_prepare* and *process* implementations. + + +Supported features +------------------ + +* ESP protocol tunnel mode both IPv4/IPv6. + +* ESP protocol transport mode both IPv4/IPv6. + +* ESN and replay window. + +* algorithms: AES-CBC, AES-GCM, HMAC-SHA1, NULL. + + +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). diff --git a/doc/guides/rel_notes/release_19_02.rst b/doc/guides/rel_notes/release_19_02.rst index 22c2dff4e..1a9885c44 100644 --- a/doc/guides/rel_notes/release_19_02.rst +++ b/doc/guides/rel_notes/release_19_02.rst @@ -105,6 +105,17 @@ New Features Added a new performance test tool to test the compressdev PMD. The tool tests compression ratio and compression throughput. +* **Added IPsec Library.** + + Added an experimental library ``librte_ipsec`` to provide ESP tunnel and + transport support for IPv4 and IPv6 packets. + + The library provides support for AES-CBC ciphering and AES-CBC with HMAC-SHA1 + algorithm-chaining, and AES-GCM and NULL algorithms only at present. It is + planned to add more algorithms in future releases. + + See :doc:`../prog_guide/ipsec_lib` for more information. + Removed Items ------------- -- 2.17.1