Add IPsec library guide and update release notes.
Signed-off-by: Bernard Iremonger <bernard.iremon...@intel.com>
Signed-off-by: Konstantin Ananyev <konstantin.anan...@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
