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

[Akhil Goyal]

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