From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga12.intel.com (mga12.intel.com [192.55.52.136]) by dpdk.org (Postfix) with ESMTP id 6ACF11B901 for ; Fri, 14 Dec 2018 17:28:06 +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 fmsmga106.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 14 Dec 2018 08:28:05 -0800 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.56,353,1539673200"; d="scan'208";a="107477940" Received: from sivswdev08.ir.intel.com (HELO localhost.localdomain) ([10.237.217.47]) by fmsmga007.fm.intel.com with ESMTP; 14 Dec 2018 08:28:04 -0800 From: Konstantin Ananyev To: dev@dpdk.org Cc: Konstantin Ananyev , Bernard Iremonger Date: Fri, 14 Dec 2018 16:27:58 +0000 Message-Id: <1544804878-11920-1-git-send-email-konstantin.ananyev@intel.com> X-Mailer: git-send-email 1.7.0.7 In-Reply-To: <1544110714-4514-2-git-send-email-konstantin.ananyev@intel.com> References: <1544110714-4514-2-git-send-email-konstantin.ananyev@intel.com> Subject: [dpdk-dev] [PATCH v4 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: Fri, 14 Dec 2018 16:28:07 -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 | 74 ++++++++++++++++++++++++++ doc/guides/rel_notes/release_19_02.rst | 10 ++++ 3 files changed, 85 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..f3b783c20 --- /dev/null +++ b/doc/guides/prog_guide/ipsec_lib.rst @@ -0,0 +1,74 @@ +.. SPDX-License-Identifier: BSD-3-Clause + Copyright(c) 2018 Intel Corporation. + +IPsec Packet Processing Library +=============================== + +The DPDK provides a library for IPsec data-path processing. +The library utilizes existing DPDK crypto-dev and +security API to provide application with transparent and +high peromant 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 that library. + +SA level API +------------ + +This API operates on IPsec 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 felids (ol_flags, tx_offloads, etc.). +* initialize/un-initialize given SA based on user provided parameters. + +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 crypto-dev API (enqueue/deque model) library introduces +asynchronous API for IPsec packets destined to be processed by crypto-device. + +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 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*. + +Current implementation supports all four currently defined rte_security types: +* RTE_SECURITY_ACTION_TYPE_NONE + +* RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO + +* RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL + +* RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL + +To accommodate future custom implementations function pointers +model is used for both for *crypto_prepare* and *process* +impelementations. + +Supported features: +* ESP protocol tunnel mode. + +* ESP protocol transport mode. + +* ESN and replay window. + +* algorithms: AES-CBC, AES-GCM, HMAC-SHA1, NULL. + diff --git a/doc/guides/rel_notes/release_19_02.rst b/doc/guides/rel_notes/release_19_02.rst index e86ef9511..e88289f73 100644 --- a/doc/guides/rel_notes/release_19_02.rst +++ b/doc/guides/rel_notes/release_19_02.rst @@ -60,6 +60,16 @@ New Features * Added the handler to get firmware version string. * Added support for multicast filtering. +* **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