[dpdk-dev] [PATCH v4 10/10] doc: add IPsec library guide

Akhil Goyal akhil.goyal at nxp.com
Wed Dec 19 17:01:18 CET 2018



On 12/14/2018 9:57 PM, Konstantin Ananyev wrote:
> Add IPsec library guide and update release notes.
>
> Signed-off-by: Bernard Iremonger <bernard.iremonger at intel.com>
> Signed-off-by: Konstantin Ananyev <konstantin.ananyev at intel.com>
> ---
>   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.
I do not see AH processing in the 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
> +
probably a code flow diagram should be added and explained in detail for 
each of the action types
> +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.
The supported features should be elaborated further more.
> +
> 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
>   -------------



More information about the dev mailing list