-----Original Message-----
> Date: Thu, 14 Sep 2017 13:56:42 +0530
> From: Akhil Goyal <akhil.go...@nxp.com>
> To: dev@dpdk.org
> CC: declan.dohe...@intel.com, pablo.de.lara.gua...@intel.com,
> hemant.agra...@nxp.com, radu.nico...@intel.com, bor...@mellanox.com,
> avia...@mellanox.com, tho...@monjalon.net, sandeep.ma...@nxp.com,
> jerin.ja...@caviumnetworks.com
> Subject: [PATCH 02/11] doc: add details of rte security
> X-Mailer: git-send-email 2.9.3
> +Security Library
> +================
> +
> +The security library provides a framework for management and provisioning
> +of security protocol operations offloaded to hardware based devices. The
> +library defines generic APIs to create and free security sessions which can
> +support complete protocol offload as well as inline crypto operation with
> +NIC or crypto devices. The framework currently only supports IPSEC protocol
> +and it's operations, other protocols will be added in future.
> +
> +Design Principles
> +-----------------
> +
> +The security library provides an additional offload capability to existing
> +crypto device and/or ethernet device.
> +
> +.. code-block:: console
> +
> + +---------------+
> + | rte_security |
> + +---------------+
> + \ /
> + +-----------+ +--------------+
> + | NIC PMD | | CRYPTO PMD |
> + +-----------+ +--------------+
> +
> +Following offload types can be supported:
> +
> +Inline Crypto
> +~~~~~~~~~~~~~
> +
> +RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO:
> +The crypto processing for security protocol (e.g. IPSEC) is processed
> +inline during receive and transmission on NIC port. The flow based
> +security action should be configured on the port.
> +
> +Ingress Data path - The packet is decrypted in RX path and relevant
> +crypto status is set in rx descriptors. After the successful inline
> +crypto processing the packet is presented to host as a regular rx packet
> +but all security protocol related headers are still attached to the
> +packet. e.g. In case of IPSEC, the IPSEC tunnel headers (if any),
> +ESP/AH headers will remain in the packet but the received packet
> +contains the decrypted data where the encrypted data was when the packet
> +arrived. The driver rx path check the descriptos and and based on the
s/descriptos/descriptors
> +crypto status sets additional flags in the rte_mbuf.ol_flags field.
> +
> +.. note::
> +
> + The underlying device may not support crypto processing all ingress
> packet
> + matching to a particular flow (e.g. fragmented packets), such packets
> will
> + be passed as encrypted packets. It is the responsibility of driver to
^^^^^^^^^^^
Do you mean application here instead of driver?
> + process such encrypted packets using other crypto driver instance.
> +
> +Egress Data path - The software prepares the egress packet by adding
> +relevant security protocol headers in the packets. Only the data will not be
> +encryptoed by the software. The driver will accordingly configure the
s/encryptoed/encrypted
> +tx descriptors. The HW device will encrypt the data before sending the
> +the packet out.
> +
> +.. note::
> +
> + The underlying device may support post encryption TSO.
> +
> +.. code-block:: console
> +
> + Egress Data Path
> + |
> + +--------|--------+
> + | egress IPsec |
> + | | |
> + | +------V------+ |
> + | | SABD lookup | |
> + | +------|------+ |
s/SABD/SADB
> + | +------V------+ |
> + | | Tunnel | | <------ Add tunnel header to packet
> + | +------|------+ |
> + | +------V------+ |
> + | | ESP | | <------ Add ESP header without trailer to
> packet
> + | | | | <------ Mark packet to be offloaded, add
> trailer
> + | +------|------+ | meta-data to mbuf
> + +--------V--------+
> + |
> + +--------V--------+
> + | L2 Stack |
> + +--------|--------+
> + |
> + +--------V--------+
> + | |
> + | NIC PMD | <------ Set hw context for inline crypto
> offload
> + | |
> + +--------|--------+
> + |
> + +--------|--------+
> + | HW ACCELERATED | <------ Packet Encryption/Decryption and
Only packet Encryption here. Right?
> + | NIC | Authentication happens inline
> + | |
> + +--------|--------+
^^^
I guess the "|" can be removed.
> +
> +
> +Inline protocol offload
> +~~~~~~~~~~~~~~~~~~~~~~~
> +
> +RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL:
> +The crypto and protocol processing for security protocol (e.g. IPSEC)
> +is processed inline during receive and transmission. The flow based
> +security action should be configured on the port.
> +
> +Ingress Data path - The packet is decrypted in RX path and relevant
> +crypto status is set in rx descriptors. After the successful inline
> +crypto processing the packet is presented to host as a regular rx packet
> +but all security protocol related headers optionally removed from the
> +packet. e.g. In case of IPSEC, the IPSEC tunnel headers (if any),
> +ESP/AH headers will be removed from the packet and the received packet
> +will contains the decrypted packet only. The driver rx path check the
> +descriptos and and based on the crypto status sets additional flags in
s/descriptos/descriptors
> +the rte_mbuf.ol_flags field.
> +
> +.. note::
> +
> + The underlying device in this case is stateful.It is expected that
> + the device shall support crypto processing for all kind of packets
> matching
> + to a given flow, this includes fragemented packets (post reassembly).
s/fragemented/fragmented
> + e.g. In case of IPSEC the device may internally manage anti-replay etc.
> + It will provide configuration option for anti-replay behavior i.e. to
> drop
> + the packets or pass them to driver with err flags set in descriptor.
> +
> +Egress Data path - The software will send the unencryptoed packet
s/unencryptoed/clear
> +without any security protocol headers added to the packet.The driver
> +will configure the security index and requirement in the tx descriptors.
> +The HW device will do security processing on the packet that includes
> +adding the relevant protocol headers and encrypt the data before sending
> +the the packet out.The software should make sure that the buffer
> +has required header and tailer space for any protocol header addition. The
> +software may also do early fragmentation if the resulatant packet is expected
> +to cross MTU.
> +
> +
> +.. note::
> +
> + The underlying device will manage state information required for egress
> + processing. e.g. In case of IPSEC, the seq number will be added to be the
> + packet, It shall provide indication when sequence number is about to
> + overflow. The underlying device may support post encryption TSO.
> +
> +.. code-block:: console
> +
> + Egress Data Path
> + |
> + +--------|--------+
> + | egress IPsec |
> + | | |
> + | +------V------+ |
> + | | SABD lookup | |
> + | +------|------+ |
s/SABD/SADB
> + | +------V------+ |
> + | | Desc | | <------ Mark packet to be offloaded
> + | +------|------+ |
> + +--------V--------+
> + |
> + +--------V--------+
> + | L2 Stack |
> + +--------|--------+
> + |
> + +--------V--------+
> + | |
> + | NIC PMD | <------ Set hw context for inline crypto
> offload
> + | |
> + +--------|--------+
> + |
> + +--------|--------+
> + | HW ACCELERATED | <------ Add tunnel, ESP header etc header to
> + | NIC | packet.Packet Encryption/Decryption and
Only packet Encryption here. Right?
> + | | Authentication happens inline.
> + +--------|--------+
I guess the "|" can be removed.
> +
> +
> +Lookaside protocol offload
> +~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL:
> +This extend the librte_cryptodev to support the programming of IPsec
> +Security Association (SA) as part of crypto session creation including
> +the definition. In addition to standard crypto processing, as defined by
> +the cryptodev, the security protocol processing is also offloaded to the
> +crypto device.
> +
> +Decryption: The packet is sent to the crypto device for security
> +protocol processing. The device will decrypt the packet and it will also
> +optionally remove the additional security headers from the packet.
> +e.g. In case of IPSEC, the IPSEC tunnel headers (if any), ESP/AH headers
> +will be removed from the packet and the decrypted packet may contains
> +the decrypted packet only.
> +
> +.. note::
> +
> + In case of IPSEC the device may internally manage anti-replay etc.
> + It will provide configuration option for anti-replay behavior i.e. to
> drop
> + the packets or pass them to driver with err flags set in descriptor.
> +
> +Encryption: The software will submit the packet to cryptodev as usual
> +to encryption, the HW device in this case will also add relevant
> +security protocol header along with encrypting the packet. The software
> +should make sure that the buffer has required header and tailer space
head room and tail room
> +for any protocol header addition.
> +
> +.. note::
> +
> + In case of IPSEC, the seq number will be added to be the packet,
> + It shall provide indication when sequence number is about to
> + overflow.
> +
> +.. code-block:: console
> +
> + Egress Data Path
> + |
> + +--------|--------+
> + | egress IPsec |
> + | | |
> + | +------V------+ |
> + | | SABD lookup | | <------ SA maps to cryptodev session
> + | +------|------+ |
s/SABD/SADB
> + | +------|------+ |
> + | | \--------------------\
> + | | Crypto | | | <- Crypto processing through
> + | | /----------------\ | inline crypto PMD
> + | +------|------+ | | |
> + +--------V--------+ | |
> + | | |
> + +--------V--------+ | | create <-- SA is added to hw
> + | L2 Stack | | | inline using existing create
> + +--------|--------+ | | session sym session APIs
> + | | | |
> + +--------V--------+ +---|---|----V---+
> + | | | \---/ | | <--- Add tunnel, ESP header
> etc
> + | NIC PMD | | INLINE | | header to packet.Packet
> + | | | CRYPTO PMD | | Encryption/Decryption
> and
> + +--------|--------+ +----------------+ Authentication happens
> + | inline.
> + +--------|--------+
> + | NIC |
> + +--------|--------+
> + V
> +
> +Device Features and Capabilities
> +---------------------------------
> +
> +Device Capabilities For Security Operations
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +The device(crypto or ethernet) capabilities which support security
> operations,
> +are defined by the security action type, security protocol, protocol
> +capabilities and corresponding crypto capabilities for security. For the full
> +scope of the Security capability see the definition of the structure in the
> +*DPDK API Reference*.
> +
> +.. code-block:: c
> +
> + struct rte_security_capability;
> +
> +Each driver(crypto or ethernet) defines its own private array of capabilities
> +for the operations it supports. Below is an example of the capabilities for a
> +PMD which supports the IPSec protocol.
> +
> +.. code-block:: c
> +
> + static const struct rte_security_capability pmd_security_capabilities[]
> = {
> + { /* IPsec Lookaside Protocol offload ESP Transport Egress */
> + .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
> + .protocol = RTE_SECURITY_PROTOCOL_IPSEC,
> + .ipsec = {
> + .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP,
> + .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
> + .direction = RTE_SECURITY_IPSEC_SA_DIR_EGRESS,
> + .options = { 0 }
> + },
> + .crypto_capabilities = pmd_capabilities
> + },
> + { /* IPsec Lookaside Protocol offload ESP Tunnel Ingress */
> + .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
> + .protocol = RTE_SECURITY_PROTOCOL_IPSEC,
> + .ipsec = {
> + .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP,
> + .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
> + .direction = RTE_SECURITY_IPSEC_SA_DIR_INGRESS,
> + .options = { 0 }
> + },
> + .crypto_capabilities = pmd_capabilities
> + },
> + {
> + .action = RTE_SECURITY_ACTION_TYPE_NONE
> + }
> + };
> + static const struct rte_cryptodev_capabilities pmd_capabilities[] = {
> + { /* SHA1 HMAC */
> + .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
> + .sym = {
> + .xform_type = RTE_CRYPTO_SYM_XFORM_AUTH,
> + .auth = {
> + .algo = RTE_CRYPTO_AUTH_SHA1_HMAC,
> + .block_size = 64,
> + .key_size = {
> + .min = 64,
> + .max = 64,
> + .increment = 0
> + },
> + .digest_size = {
> + .min = 12,
> + .max = 12,
> + .increment = 0
> + },
> + .aad_size = { 0 },
> + .iv_size = { 0 }
> + }
> + }
> + },
> + { /* AES CBC */
> + .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
> + .sym = {
> + .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER,
> + .cipher = {
> + .algo = RTE_CRYPTO_CIPHER_AES_CBC,
> + .block_size = 16,
> + .key_size = {
> + .min = 16,
> + .max = 32,
> + .increment = 8
> + },
> + .iv_size = {
> + .min = 16,
> + .max = 16,
> + .increment = 0
> + }
> + }
> + }
> + }
> + }
> +
> +
> +Capabilities Discovery
> +~~~~~~~~~~~~~~~~~~~~~~
> +
> +Discovering the features and capabilities of a driver(crypto/ethernet)
> +is achieved through the ``rte_security_capabilities_get`` function.
> +
> +.. code-block:: c
> +
> + const struct rte_security_capability
> *rte_security_capabilities_get(uint16_t id);
> +
> +This allows the user to query a specific driver and get all the device
> +security capabilities. It returns an array of ``rte_security_capability``
> structure
> +which contains all the capabilities for the device.
> +
> +Security Session Create/Free
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +Security Sessions are created to store the immutable fields of a particular
> Security
> +association for a particular protocol which is defined by a security session
> +configuration structure which is used in the operation processing of a
> packet flow.
> +Sessions are used to manage protocol specific information as well as crypto
> parameters.
> +Security sessions cache this immutable data in a optimal way for the
> underlying PMD
> +and this allows further acceleration of the offload of Crypto workloads.
> +
> +The Secutiry framework provides APIs to create and free sessions for
> crypto/ethernet
> +devices, where sessions are mempool objects. It is the application's
> responsibility
> +to create and manage the session mempools. Mempool object size should be
> able to
> +accommodate the driver's private data of the session.
> +
> +Once the session mempools have been created,
> ``rte_security_session_create()``
> +is used to allocate and initialize a session for the required
> crypto/ethernet device.
> +Sessions already created can be updated with the
> ``rte_security_session_update``.
> +
> +When a session is no longer used, user must call
> ``rte_security_session_destroy()``
> +to free driver private session data and return the memory back to the
> mempool.
> +
> +For look aside protocol offload to hardware crypto device, the
> ``rte_crypto_op``
> +created by the application is attached to the security session by the API
> +``rte_security_attach_session``.
> +
> +For Inline Crypto and Inline protocol offload, device specific defined
> metadata is
> +updated in the mbuf using ``rte_security_set_pkt_metadata``.
If DEV_TX_OFFLOAD_SEC_NEED_MDATA is set.
> +
> +Session configuration
> +~~~~~~~~~~~~~~~~~~~~~
> +
> +Security Session configuration structure is defined as
> ``rte_security_session_conf``
> +
> +.. code-block:: c
> +
> + struct rte_security_session_conf {
> + enum rte_security_session_action_type action_type;
> + /**< Type of action to be performed on the session */
> + enum rte_security_session_protocol protocol;
> + /**< Security protocol to be configured */
> + union {
> + struct rte_security_ipsec_xform ipsec;
> + struct rte_security_macsec_xform macsec;
> + };
> + /**< Configuration parameters for security session */
> + struct rte_crypto_sym_xform *crypto_xform;
> + /**< Security Session Crypto Transformations */
> + };
> +
> +The configuration structure reuses the ``rte_crypto_sym_xform`` for crypto
> related
> +configuration. ``rte_security_session_action_type`` specify whether the
> session is
> +configured for Lookaside Protocol offload or Inline Crypto or Inline Protocol
> +Offload.
> +
> +.. code-block:: c
> +
> + enum rte_security_session_action_type {
> + RTE_SECURITY_ACTION_TYPE_NONE,
> + /**< No security actions */
> + RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO,
> + /**< Crypto processing for security protocol is processed inline
> + * during transmission */
> + RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL,
> + /**< All security protocol processing is performed inline during
> + * transmission */
> + RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
> + /**< All security protocol processing including crypto is performed
> + * on a lookaside accelerator */
> + };
> +
> +The ``rte_security_session_protocol`` is defined as
> +
> +.. code-block:: c
> +
> + enum rte_security_session_protocol {
> + RTE_SECURITY_PROTOCOL_IPSEC,
> + /**< IPsec Protocol */
> + RTE_SECURITY_PROTOCOL_MACSEC,
> + /**< MACSec Protocol */
> + };
> +
> +Currently the library defines configuration parameters for IPSec only. For
> other
> +protocols like MACSec, structures and enums are defined as place holders
> which
> +will be updated in the future.
> +
> +IPsec related configuration parameters are defined in
> ``rte_security_ipsec_xform``
> +
> +.. code-block:: c
> +
> + struct rte_security_ipsec_xform {
> + uint32_t spi;
> + /**< SA security parameter index */
> + uint32_t salt;
> + /**< SA salt */
> + struct rte_security_ipsec_sa_options options;
> + /**< various SA options */
> + enum rte_security_ipsec_sa_direction direction;
> + /**< IPSec SA Direction - Egress/Ingress */
> + enum rte_security_ipsec_sa_protocol proto;
> + /**< IPsec SA Protocol - AH/ESP */
> + enum rte_security_ipsec_sa_mode mode;
> + /**< IPsec SA Mode - transport/tunnel */
> + struct rte_security_ipsec_tunnel_param tunnel;
> + /**< Tunnel parameters, NULL for transport mode */
> + };
> +
> +
> +Security API
> +~~~~~~~~~~~~
> +
> +The rte_security Library API is described in the *DPDK API Reference*
> document.
> +
> +Flow based Security Session
> +~~~~~~~~~~~~~~~~~~~~~~~~~~~
> +
> +In case of NIC based offloads, the security session specified in the
> +'rte_flow_action_security' must be created on the same port as the
> +flow action that is being specified.
> +
> +The ingress/egress flow attribute should match that specified in the security
> +session if the security session supports the definition of the direction.
> +
> +Multiple flows can be configured to use the same security session. For
> +example if the security session specifies an egress IPsec SA, then multiple
> +flows can be specified to that SA. In the case of an ingress IPsec SA then
> +it is only valid to have a single flow to map to that security session.
> +
> +.. code-block:: console
> +
> + Configuration Path
> + |
> + +--------|--------+
> + | Add/Remove |
> + | IPsec SA | <------ Build security flow action of
> + | | | ipsec transform
> + |--------|--------|
> + |
> + +--------V--------+
> + | Flow API |
> + +--------|--------+
> + |
> + +--------V--------+
> + | |
> + | NIC PMD | <------ Add/Remove SA to/from hw context
> + | |
> + +--------|--------+
> + |
> + +--------|--------+
> + | HW ACCELERATED |
> + | NIC |
> + | |
> + +--------|--------+
> +
> +o Add/Delete SA flow:
> + To add a new inline SA construct a rte_flow_item for Ethernet + IP + ESP
> + using the SA selectors and the rte_crypto_ipsec_xform as the
> rte_flow_action.
> + Note that any rte_flow_items may be empty, which means it is not checked.
> +
> +.. code-block:: console
> +
> + In its most basic form, IPsec flow specification is as follows:
> + +-------+ +----------+ +--------+ +-----+
> + | Eth | -> | IP4/6 | -> | ESP | -> | END |
> + +-------+ +----------+ +--------+ +-----+
> +
> + However, the API can represent, IPsec crypto offload with any
> encapsulation:
> + +-------+ +--------+ +-----+
> + | Eth | -> ... -> | ESP | -> | END |
> + +-------+ +--------+ +-----+
> --
> 2.9.3
>
