From mboxrd@z Thu Jan 1 00:00:00 1970 From: Aviad Yehezkel Subject: Re: [PATCH v4 02/12] doc: add details of rte security Date: Sun, 15 Oct 2017 15:47:48 +0300 Message-ID: <8f9b1446-d80b-3cf5-602e-032538456c9f@dev.mellanox.co.il> References: <20171006181151.4758-1-akhil.goyal@nxp.com> <20171014221734.15511-1-akhil.goyal@nxp.com> <20171014221734.15511-3-akhil.goyal@nxp.com> Mime-Version: 1.0 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: 7bit To: dev@dpdk.org Return-path: Received: from mail-wm0-f68.google.com (mail-wm0-f68.google.com [74.125.82.68]) by dpdk.org (Postfix) with ESMTP id AFF6E1B2FD for ; Sun, 15 Oct 2017 14:47:51 +0200 (CEST) Received: by mail-wm0-f68.google.com with SMTP id u138so28686020wmu.5 for ; Sun, 15 Oct 2017 05:47:51 -0700 (PDT) Received: from [10.0.38.219] ([193.47.165.251]) by smtp.gmail.com with ESMTPSA id p45sm4309110edc.30.2017.10.15.05.47.49 for (version=TLS1_2 cipher=ECDHE-RSA-AES128-GCM-SHA256 bits=128/128); Sun, 15 Oct 2017 05:47:50 -0700 (PDT) In-Reply-To: <20171014221734.15511-3-akhil.goyal@nxp.com> Content-Language: en-US List-Id: DPDK patches and discussions List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: dev-bounces@dpdk.org Sender: "dev" On 10/15/2017 1:17 AM, Akhil Goyal wrote: > Signed-off-by: Hemant Agrawal > Signed-off-by: Akhil Goyal > Acked-by: John McNamara > --- > doc/api/doxy-api-index.md | 3 +- > doc/api/doxy-api.conf | 1 + > doc/guides/prog_guide/index.rst | 1 + > doc/guides/prog_guide/rte_security.rst | 559 +++++++++++++++++++++++++++++++++ > 4 files changed, 563 insertions(+), 1 deletion(-) > create mode 100644 doc/guides/prog_guide/rte_security.rst > > diff --git a/doc/api/doxy-api-index.md b/doc/api/doxy-api-index.md > index 990815f..7c680dc 100644 > --- a/doc/api/doxy-api-index.md > +++ b/doc/api/doxy-api-index.md > @@ -58,7 +58,8 @@ The public API headers are grouped by topics: > [ixgbe] (@ref rte_pmd_ixgbe.h), > [i40e] (@ref rte_pmd_i40e.h), > [bnxt] (@ref rte_pmd_bnxt.h), > - [crypto_scheduler] (@ref rte_cryptodev_scheduler.h) > + [crypto_scheduler] (@ref rte_cryptodev_scheduler.h), > + [security] (@ref rte_security.h) > > - **memory**: > [memseg] (@ref rte_memory.h), > diff --git a/doc/api/doxy-api.conf b/doc/api/doxy-api.conf > index 9e9fa56..567691b 100644 > --- a/doc/api/doxy-api.conf > +++ b/doc/api/doxy-api.conf > @@ -70,6 +70,7 @@ INPUT = doc/api/doxy-api-index.md \ > lib/librte_reorder \ > lib/librte_ring \ > lib/librte_sched \ > + lib/librte_security \ > lib/librte_table \ > lib/librte_timer \ > lib/librte_vhost > diff --git a/doc/guides/prog_guide/index.rst b/doc/guides/prog_guide/index.rst > index b5ad6b8..46cb4fe 100644 > --- a/doc/guides/prog_guide/index.rst > +++ b/doc/guides/prog_guide/index.rst > @@ -46,6 +46,7 @@ Programmer's Guide > rte_flow > traffic_management > cryptodev_lib > + rte_security > link_bonding_poll_mode_drv_lib > timer_lib > hash_lib > diff --git a/doc/guides/prog_guide/rte_security.rst b/doc/guides/prog_guide/rte_security.rst > new file mode 100644 > index 0000000..0708856 > --- /dev/null > +++ b/doc/guides/prog_guide/rte_security.rst > @@ -0,0 +1,559 @@ > +.. BSD LICENSE > + Copyright 2017 NXP. > + > + Redistribution and use in source and binary forms, with or without > + modification, are permitted provided that the following conditions > + are met: > + > + * Redistributions of source code must retain the above copyright > + notice, this list of conditions and the following disclaimer. > + * Redistributions in binary form must reproduce the above copyright > + notice, this list of conditions and the following disclaimer in > + the documentation and/or other materials provided with the > + distribution. > + * Neither the name of NXP nor the names of its > + contributors may be used to endorse or promote products derived > + from this software without specific prior written permission. > + > + THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS > + "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT > + LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR > + A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT > + OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, > + SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT > + LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, > + DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY > + THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT > + (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE > + OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. > + > + > +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 full protocol offload as well as inline crypto operation with > +NIC or crypto devices. The framework currently only supports the IPSec protocol > +and associated operations, other protocols will be added in future. > + > +Design Principles > +----------------- > + > +The security library provides an additional offload capability to an existing > +crypto device and/or ethernet device. > + > +.. code-block:: console > + > + +---------------+ > + | rte_security | > + +---------------+ > + \ / > + +-----------+ +--------------+ > + | NIC PMD | | CRYPTO PMD | > + +-----------+ +--------------+ > + > +The supported offload types are explained in the sections below. > + > +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 > +however 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 descriptors and and based on the > +crypto status sets additional flags in the rte_mbuf.ol_flags field. > + > +.. note:: > + > + The underlying device may not support crypto processing for 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 application to > + process such encrypted packets using other crypto driver instance. > + > +Egress Data path - The software prepares the egress packet by adding > +relevant security protocol headers. Only the data will not be > +encrypted by the software. The driver will accordingly configure the > +tx descriptors. The hardware 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------+ | > + | | SADB lookup | | > + | +------|------+ | > + | +------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 and > + | NIC | Authentication happens inline > + | | > + +-----------------+ > + > + > +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 the RX path and relevant > +crypto status is set in the Rx descriptors. After the successful inline > +crypto processing the packet is presented to the host as a regular Rx packet > +but all security protocol related headers are optionally removed from the > +packet. e.g. in the 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 checks the > +descriptors and based on the crypto status sets additional flags in > +``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 fragmented packets (post reassembly). > + E.g. in case of IPSec the device may internally manage anti-replay etc. > + It will provide a configuration option for anti-replay behavior i.e. to drop > + the packets or pass them to driver with error flags set in the descriptor. > + > +Egress Data path - The software will send the plain packet without any > +security protocol headers added to the packet. The driver will configure > +the security index and other requirement in tx descriptors. > +The hardware device will do security processing on the packet that includes > +adding the relevant protocol headers and encrypting the data before sending > +the packet out. The software should make sure that the buffer > +has required head room and tail room for any protocol header addition. The > +software may also do early fragmentation if the resultant packet is expected > +to cross the MTU size. > + > + > +.. 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 the > + packet, however the device shall provide indication when the sequence number > + is about to overflow. The underlying device may support post encryption TSO. > + > +.. code-block:: console > + > + Egress Data Path > + | > + +--------|--------+ > + | egress IPsec | > + | | | > + | +------V------+ | > + | | SADB lookup | | > + | +------|------+ | > + | +------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 and > + | | Authentication happens inline. > + +-----------------+ > + > + > +Lookaside protocol offload > +~~~~~~~~~~~~~~~~~~~~~~~~~~ > + > +RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL: > +This extends librte_cryptodev to support the programming of IPsec > +Security Association (SA) as part of a 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 additional security headers from the packet. > +E.g. in case of IPSec, IPSec tunnel headers (if any), ESP/AH headers > +will be removed from the packet and the decrypted packet may contain > +plain data only. > + > +.. note:: > + > + In case of IPSec the device may internally manage anti-replay etc. > + It will provide a configuration option for anti-replay behavior i.e. to drop > + the packets or pass them to driver with error flags set in descriptor. > + > +Encryption: The software will submit the packet to cryptodev as usual > +for encryption, the hardware device in this case will also add the relevant > +security protocol header along with encrypting the packet. The software > +should make sure that the buffer has required head room and tail room > +for any protocol header addition. > + > +.. note:: > + > + In the case of IPSec, the seq number will be added to the packet, > + It shall provide an indication when the sequence number is about to > + overflow. > + > +.. code-block:: console > + > + Egress Data Path > + | > + +--------|--------+ > + | egress IPsec | > + | | | > + | +------V------+ | > + | | SADB lookup | | <------ SA maps to cryptodev session > + | +------|------+ | > + | +------|------+ | > + | | \--------------------\ > + | | 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 definition of rte_security_capability > +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 Tunnel 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 device > +security capabilities. It returns an array of ``rte_security_capability`` structures > +which contains all the capabilities for that 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 Security 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. The mempool object size should be able to > +accommodate the driver's private data of security 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. > + > +Session APIs need a parameter ``rte_security_ctx`` to identify the crypto/ethernet > +security ops. This parameter can be retreived using the APIs > +``rte_cryptodev_get_sec_ctx()`` (for crypto device) or ``rte_eth_dev_get_sec_ctx`` > +(for ethernet port). > + > +Sessions already created can be updated with ``rte_security_session_update()``. > + > +When a session is no longer used, the user must call ``rte_security_session_destroy()`` > +to free the 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. > + > +Security 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`` struct for crypto related > +configuration. The ``rte_security_session_action_type`` struct is used to 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 the 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 | > + | | > + +--------|--------+ > + > +* 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 | > + +-------+ +--------+ +-----+ Tested-by: Aviad Yehezkel