[v4,10/10] doc: add IPsec library guide
Checks
Commit Message
Add IPsec library guide and update release notes.
Signed-off-by: Bernard Iremonger <bernard.iremonger@intel.com>
Signed-off-by: Konstantin Ananyev <konstantin.ananyev@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
Comments
Hi,
14/12/2018 17:27, Konstantin Ananyev:
> Add IPsec library guide and update release notes.
A quick look at the guide hint me that you should check the spelling.
> --- 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 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
> -------------
Please keep the spacing (2 blank lines before heading).
I've seen other minor spacing mistakes in other patches.
Please check, thanks.
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@intel.com>
> Signed-off-by: Konstantin Ananyev <konstantin.ananyev@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
> -------------
> > --- /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
Right now it is not implemented.
But the whole library code structure allows it to be added (if someone would decide to).
> > +
> > +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
I think it is way above my drawing capabilities :)
> > +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.
Ok, anything specific information you think has to be added here?
On 12/20/2018 6:36 PM, Ananyev, Konstantin wrote:
>
>>> --- /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
> Right now it is not implemented.
> But the whole library code structure allows it to be added (if someone would decide to).
specify this here.
>>> +
>>> +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
> I think it is way above my drawing capabilities :)
I think you can refer to
http://doc.dpdk.org/guides/prog_guide/rte_security.html
something similar to that would explain it in a better way.
>
>>> +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.
> Ok, anything specific information you think has to be added here?
Probably a few lines to explain the feature(very brief) and how it is
implemented in ipsec lib and the limitation if any
@@ -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
new file mode 100644
@@ -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.
+
@@ -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
-------------