From patchwork Fri Dec 28 15:17:43 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: "Ananyev, Konstantin" X-Patchwork-Id: 49341 X-Patchwork-Delegate: gakhil@marvell.com Return-Path: X-Original-To: patchwork@dpdk.org Delivered-To: patchwork@dpdk.org Received: from [92.243.14.124] (localhost [127.0.0.1]) by dpdk.org (Postfix) with ESMTP id 72A3F1B1E6; Fri, 28 Dec 2018 16:18:37 +0100 (CET) Received: from mga02.intel.com (mga02.intel.com [134.134.136.20]) by dpdk.org (Postfix) with ESMTP id 25D426C9B for ; Fri, 28 Dec 2018 16:18:03 +0100 (CET) X-Amp-Result: SKIPPED(no attachment in message) X-Amp-File-Uploaded: False Received: from fmsmga001.fm.intel.com ([10.253.24.23]) by orsmga101.jf.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 28 Dec 2018 07:18:02 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,409,1539673200"; d="scan'208";a="133474501" Received: from sivswdev08.ir.intel.com (HELO localhost.localdomain) ([10.237.217.47]) by fmsmga001.fm.intel.com with ESMTP; 28 Dec 2018 07:18:01 -0800 From: Konstantin Ananyev To: dev@dpdk.org Cc: akhil.goyal@nxp.com, Konstantin Ananyev , Bernard Iremonger Date: Fri, 28 Dec 2018 15:17:43 +0000 Message-Id: <1546010263-16257-11-git-send-email-konstantin.ananyev@intel.com> X-Mailer: git-send-email 1.7.0.7 In-Reply-To: <1544804589-10338-1-git-send-email-konstantin.ananyev@intel.com> References: <1544804589-10338-1-git-send-email-konstantin.ananyev@intel.com> To: dev@dpdk.org Subject: [dpdk-dev] [PATCH v5 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: , Errors-To: dev-bounces@dpdk.org Sender: "dev" 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 -------------