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