[dpdk-dev] [PATCH 02/11] doc: add details of rte security

Akhil Goyal akhil.goyal at nxp.com
Wed Sep 20 12:59:32 CEST 2017


Hi Jerin,

On 9/18/2017 4:43 PM, Jerin Jacob wrote:
> -----Original Message-----
>> Date: Thu, 14 Sep 2017 13:56:42 +0530
>> From: Akhil Goyal <akhil.goyal at nxp.com>
>> To: dev at dpdk.org
>> CC: declan.doherty at intel.com, pablo.de.lara.guarch at intel.com,
>>   hemant.agrawal at nxp.com, radu.nicolau at intel.com, borisp at mellanox.com,
>>   aviadye at mellanox.com, thomas at monjalon.net, sandeep.malik at nxp.com,
>>   jerin.jacob at 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
>>
> 
Thanks for your comments, I would include these in my next version.

-Akhil


More information about the dev mailing list