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

[Konstantin Ananyev]

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.
+
+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