xref: /dpdk/doc/guides/prog_guide/rte_security.rst (revision e30b2833c47c79e0b5fae1de31ae07975f440282)
1d81734caSHemant Agrawal..  SPDX-License-Identifier: BSD-3-Clause
2a11aeb09SAkhil Goyal    Copyright 2017,2020 NXP
340ff8c99SAkhil Goyal
440ff8c99SAkhil Goyal
540ff8c99SAkhil Goyal
640ff8c99SAkhil GoyalSecurity Library
740ff8c99SAkhil Goyal================
840ff8c99SAkhil Goyal
940ff8c99SAkhil GoyalThe security library provides a framework for management and provisioning
1040ff8c99SAkhil Goyalof security protocol operations offloaded to hardware based devices. The
1140ff8c99SAkhil Goyallibrary defines generic APIs to create and free security sessions which can
1240ff8c99SAkhil Goyalsupport full protocol offload as well as inline crypto operation with
13e44b3fafSDavid CoyleNIC or crypto devices. The framework currently only supports the IPsec, PDCP
14e44b3fafSDavid Coyleand DOCSIS protocols and associated operations, other protocols will be added
15e44b3fafSDavid Coylein the future.
1640ff8c99SAkhil Goyal
1740ff8c99SAkhil GoyalDesign Principles
1840ff8c99SAkhil Goyal-----------------
1940ff8c99SAkhil Goyal
2040ff8c99SAkhil GoyalThe security library provides an additional offload capability to an existing
2140ff8c99SAkhil Goyalcrypto device and/or ethernet device.
2240ff8c99SAkhil Goyal
2340ff8c99SAkhil Goyal.. code-block:: console
2440ff8c99SAkhil Goyal
2540ff8c99SAkhil Goyal               +---------------+
2640ff8c99SAkhil Goyal               | rte_security  |
2740ff8c99SAkhil Goyal               +---------------+
2840ff8c99SAkhil Goyal                 \            /
2940ff8c99SAkhil Goyal        +-----------+    +--------------+
3040ff8c99SAkhil Goyal        |  NIC PMD  |    |  CRYPTO PMD  |
3140ff8c99SAkhil Goyal        +-----------+    +--------------+
3240ff8c99SAkhil Goyal
3340ff8c99SAkhil Goyal.. note::
3440ff8c99SAkhil Goyal
3540ff8c99SAkhil Goyal    Currently, the security library does not support the case of multi-process.
3640ff8c99SAkhil Goyal    It will be updated in the future releases.
3740ff8c99SAkhil Goyal
3840ff8c99SAkhil GoyalThe supported offload types are explained in the sections below.
3940ff8c99SAkhil Goyal
4040ff8c99SAkhil GoyalInline Crypto
4140ff8c99SAkhil Goyal~~~~~~~~~~~~~
4240ff8c99SAkhil Goyal
4340ff8c99SAkhil GoyalRTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO:
44d629b7b5SJohn McNamaraThe crypto processing for security protocol (e.g. IPsec) is processed
4540ff8c99SAkhil Goyalinline during receive and transmission on NIC port. The flow based
4640ff8c99SAkhil Goyalsecurity action should be configured on the port.
4740ff8c99SAkhil Goyal
4840ff8c99SAkhil GoyalIngress Data path - The packet is decrypted in RX path and relevant
4940ff8c99SAkhil Goyalcrypto status is set in Rx descriptors. After the successful inline
5040ff8c99SAkhil Goyalcrypto processing the packet is presented to host as a regular Rx packet
5140ff8c99SAkhil Goyalhowever all security protocol related headers are still attached to the
52d629b7b5SJohn McNamarapacket. e.g. In case of IPsec, the IPsec tunnel headers (if any),
5340ff8c99SAkhil GoyalESP/AH headers will remain in the packet but the received packet
5440ff8c99SAkhil Goyalcontains the decrypted data where the encrypted data was when the packet
55f43d3dbbSDavid Marchandarrived. The driver Rx path check the descriptors and based on the
5640ff8c99SAkhil Goyalcrypto status sets additional flags in the rte_mbuf.ol_flags field.
5740ff8c99SAkhil Goyal
5840ff8c99SAkhil Goyal.. note::
5940ff8c99SAkhil Goyal
6040ff8c99SAkhil Goyal    The underlying device may not support crypto processing for all ingress packet
6140ff8c99SAkhil Goyal    matching to a particular flow (e.g. fragmented packets), such packets will
6240ff8c99SAkhil Goyal    be passed as encrypted packets. It is the responsibility of application to
6340ff8c99SAkhil Goyal    process such encrypted packets using other crypto driver instance.
6440ff8c99SAkhil Goyal
6540ff8c99SAkhil GoyalEgress Data path - The software prepares the egress packet by adding
6640ff8c99SAkhil Goyalrelevant security protocol headers. Only the data will not be
6740ff8c99SAkhil Goyalencrypted by the software. The driver will accordingly configure the
6840ff8c99SAkhil Goyaltx descriptors. The hardware device will encrypt the data before sending the
69f43d3dbbSDavid Marchandpacket out.
7040ff8c99SAkhil Goyal
7140ff8c99SAkhil Goyal.. note::
7240ff8c99SAkhil Goyal
7340ff8c99SAkhil Goyal    The underlying device may support post encryption TSO.
7440ff8c99SAkhil Goyal
7540ff8c99SAkhil Goyal.. code-block:: console
7640ff8c99SAkhil Goyal
7740ff8c99SAkhil Goyal          Egress Data Path
7840ff8c99SAkhil Goyal                 |
7940ff8c99SAkhil Goyal        +--------|--------+
8040ff8c99SAkhil Goyal        |  egress IPsec   |
8140ff8c99SAkhil Goyal        |        |        |
8240ff8c99SAkhil Goyal        | +------V------+ |
8340ff8c99SAkhil Goyal        | | SADB lookup | |
8440ff8c99SAkhil Goyal        | +------|------+ |
8540ff8c99SAkhil Goyal        | +------V------+ |
8640ff8c99SAkhil Goyal        | |   Tunnel    | |   <------ Add tunnel header to packet
8740ff8c99SAkhil Goyal        | +------|------+ |
8840ff8c99SAkhil Goyal        | +------V------+ |
8940ff8c99SAkhil Goyal        | |     ESP     | |   <------ Add ESP header without trailer to packet
9040ff8c99SAkhil Goyal        | |             | |   <------ Mark packet to be offloaded, add trailer
9140ff8c99SAkhil Goyal        | +------|------+ |            meta-data to mbuf
9240ff8c99SAkhil Goyal        +--------V--------+
9340ff8c99SAkhil Goyal                 |
9440ff8c99SAkhil Goyal        +--------V--------+
9540ff8c99SAkhil Goyal        |    L2 Stack     |
9640ff8c99SAkhil Goyal        +--------|--------+
9740ff8c99SAkhil Goyal                 |
9840ff8c99SAkhil Goyal        +--------V--------+
9940ff8c99SAkhil Goyal        |                 |
10040ff8c99SAkhil Goyal        |     NIC PMD     |   <------ Set hw context for inline crypto offload
10140ff8c99SAkhil Goyal        |                 |
10240ff8c99SAkhil Goyal        +--------|--------+
10340ff8c99SAkhil Goyal                 |
10440ff8c99SAkhil Goyal        +--------|--------+
10540ff8c99SAkhil Goyal        |  HW ACCELERATED |   <------ Packet Encryption and
10640ff8c99SAkhil Goyal        |        NIC      |           Authentication happens inline
10740ff8c99SAkhil Goyal        |                 |
10840ff8c99SAkhil Goyal        +-----------------+
10940ff8c99SAkhil Goyal
11040ff8c99SAkhil Goyal
11140ff8c99SAkhil GoyalInline protocol offload
11240ff8c99SAkhil Goyal~~~~~~~~~~~~~~~~~~~~~~~
11340ff8c99SAkhil Goyal
11440ff8c99SAkhil GoyalRTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL:
115d629b7b5SJohn McNamaraThe crypto and protocol processing for security protocol (e.g. IPsec)
11640ff8c99SAkhil Goyalis processed inline during receive and transmission.  The flow based
11740ff8c99SAkhil Goyalsecurity action should be configured on the port.
11840ff8c99SAkhil Goyal
11940ff8c99SAkhil GoyalIngress Data path - The packet is decrypted in the RX path and relevant
12040ff8c99SAkhil Goyalcrypto status is set in the Rx descriptors. After the successful inline
12140ff8c99SAkhil Goyalcrypto processing the packet is presented to the host as a regular Rx packet
12240ff8c99SAkhil Goyalbut all security protocol related headers are optionally removed from the
123d629b7b5SJohn McNamarapacket. e.g. in the case of IPsec, the IPsec tunnel headers (if any),
12440ff8c99SAkhil GoyalESP/AH headers will be removed from the packet and the received packet
12540ff8c99SAkhil Goyalwill contains the decrypted packet only. The driver Rx path checks the
12640ff8c99SAkhil Goyaldescriptors and based on the crypto status sets additional flags in
1271a08c379SAnoob Joseph``rte_mbuf.ol_flags`` field. The driver would also set device-specific
1281a08c379SAnoob Josephmetadata in ``rte_mbuf.udata64`` field. This will allow the application
1291a08c379SAnoob Josephto identify the security processing done on the packet.
13040ff8c99SAkhil Goyal
13140ff8c99SAkhil Goyal.. note::
13240ff8c99SAkhil Goyal
13340ff8c99SAkhil Goyal    The underlying device in this case is stateful. It is expected that
13440ff8c99SAkhil Goyal    the device shall support crypto processing for all kind of packets matching
13540ff8c99SAkhil Goyal    to a given flow, this includes fragmented packets (post reassembly).
136d629b7b5SJohn McNamara    E.g. in case of IPsec the device may internally manage anti-replay etc.
13740ff8c99SAkhil Goyal    It will provide a configuration option for anti-replay behavior i.e. to drop
13840ff8c99SAkhil Goyal    the packets or pass them to driver with error flags set in the descriptor.
13940ff8c99SAkhil Goyal
14040ff8c99SAkhil GoyalEgress Data path - The software will send the plain packet without any
14140ff8c99SAkhil Goyalsecurity protocol headers added to the packet. The driver will configure
14240ff8c99SAkhil Goyalthe security index and other requirement in tx descriptors.
14340ff8c99SAkhil GoyalThe hardware device will do security processing on the packet that includes
14440ff8c99SAkhil Goyaladding the relevant protocol headers and encrypting the data before sending
14540ff8c99SAkhil Goyalthe packet out. The software should make sure that the buffer
14640ff8c99SAkhil Goyalhas required head room and tail room for any protocol header addition. The
14740ff8c99SAkhil Goyalsoftware may also do early fragmentation if the resultant packet is expected
14840ff8c99SAkhil Goyalto cross the MTU size.
14940ff8c99SAkhil Goyal
15040ff8c99SAkhil Goyal
15140ff8c99SAkhil Goyal.. note::
15240ff8c99SAkhil Goyal
15340ff8c99SAkhil Goyal    The underlying device will manage state information required for egress
154d629b7b5SJohn McNamara    processing. E.g. in case of IPsec, the seq number will be added to the
15540ff8c99SAkhil Goyal    packet, however the device shall provide indication when the sequence number
15640ff8c99SAkhil Goyal    is about to overflow. The underlying device may support post encryption TSO.
15740ff8c99SAkhil Goyal
15840ff8c99SAkhil Goyal.. code-block:: console
15940ff8c99SAkhil Goyal
16040ff8c99SAkhil Goyal         Egress Data Path
16140ff8c99SAkhil Goyal                 |
16240ff8c99SAkhil Goyal        +--------|--------+
16340ff8c99SAkhil Goyal        |  egress IPsec   |
16440ff8c99SAkhil Goyal        |        |        |
16540ff8c99SAkhil Goyal        | +------V------+ |
16640ff8c99SAkhil Goyal        | | SADB lookup | |
16740ff8c99SAkhil Goyal        | +------|------+ |
16840ff8c99SAkhil Goyal        | +------V------+ |
16940ff8c99SAkhil Goyal        | |   Desc      | |   <------ Mark packet to be offloaded
17040ff8c99SAkhil Goyal        | +------|------+ |
17140ff8c99SAkhil Goyal        +--------V--------+
17240ff8c99SAkhil Goyal                 |
17340ff8c99SAkhil Goyal        +--------V--------+
17440ff8c99SAkhil Goyal        |    L2 Stack     |
17540ff8c99SAkhil Goyal        +--------|--------+
17640ff8c99SAkhil Goyal                 |
17740ff8c99SAkhil Goyal        +--------V--------+
17840ff8c99SAkhil Goyal        |                 |
17940ff8c99SAkhil Goyal        |     NIC PMD     |   <------ Set hw context for inline crypto offload
18040ff8c99SAkhil Goyal        |                 |
18140ff8c99SAkhil Goyal        +--------|--------+
18240ff8c99SAkhil Goyal                 |
18340ff8c99SAkhil Goyal        +--------|--------+
18440ff8c99SAkhil Goyal        |  HW ACCELERATED |   <------ Add tunnel, ESP header etc header to
18540ff8c99SAkhil Goyal        |        NIC      |           packet. Packet Encryption and
18640ff8c99SAkhil Goyal        |                 |           Authentication happens inline.
18740ff8c99SAkhil Goyal        +-----------------+
18840ff8c99SAkhil Goyal
18940ff8c99SAkhil Goyal
19040ff8c99SAkhil GoyalLookaside protocol offload
19140ff8c99SAkhil Goyal~~~~~~~~~~~~~~~~~~~~~~~~~~
19240ff8c99SAkhil Goyal
19340ff8c99SAkhil GoyalRTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL:
19440ff8c99SAkhil GoyalThis extends librte_cryptodev to support the programming of IPsec
19540ff8c99SAkhil GoyalSecurity Association (SA) as part of a crypto session creation including
19640ff8c99SAkhil Goyalthe definition. In addition to standard crypto processing, as defined by
19740ff8c99SAkhil Goyalthe cryptodev, the security protocol processing is also offloaded to the
19840ff8c99SAkhil Goyalcrypto device.
19940ff8c99SAkhil Goyal
20040ff8c99SAkhil GoyalDecryption: The packet is sent to the crypto device for security
20140ff8c99SAkhil Goyalprotocol processing. The device will decrypt the packet and it will also
20240ff8c99SAkhil Goyaloptionally remove additional security headers from the packet.
203d629b7b5SJohn McNamaraE.g. in case of IPsec, IPsec tunnel headers (if any), ESP/AH headers
20440ff8c99SAkhil Goyalwill be removed from the packet and the decrypted packet may contain
20540ff8c99SAkhil Goyalplain data only.
20640ff8c99SAkhil Goyal
20740ff8c99SAkhil Goyal.. note::
20840ff8c99SAkhil Goyal
209d629b7b5SJohn McNamara    In case of IPsec the device may internally manage anti-replay etc.
21040ff8c99SAkhil Goyal    It will provide a configuration option for anti-replay behavior i.e. to drop
21140ff8c99SAkhil Goyal    the packets or pass them to driver with error flags set in descriptor.
21240ff8c99SAkhil Goyal
21340ff8c99SAkhil GoyalEncryption: The software will submit the packet to cryptodev as usual
21440ff8c99SAkhil Goyalfor encryption, the hardware device in this case will also add the relevant
21540ff8c99SAkhil Goyalsecurity protocol header along with encrypting the packet. The software
21640ff8c99SAkhil Goyalshould make sure that the buffer has required head room and tail room
21740ff8c99SAkhil Goyalfor any protocol header addition.
21840ff8c99SAkhil Goyal
21940ff8c99SAkhil Goyal.. note::
22040ff8c99SAkhil Goyal
221d629b7b5SJohn McNamara    In the case of IPsec, the seq number will be added to the packet,
22240ff8c99SAkhil Goyal    It shall provide an indication when the sequence number is about to
22340ff8c99SAkhil Goyal    overflow.
22440ff8c99SAkhil Goyal
22540ff8c99SAkhil Goyal.. code-block:: console
22640ff8c99SAkhil Goyal
22740ff8c99SAkhil Goyal          Egress Data Path
22840ff8c99SAkhil Goyal                 |
22940ff8c99SAkhil Goyal        +--------|--------+
23040ff8c99SAkhil Goyal        |  egress IPsec   |
23140ff8c99SAkhil Goyal        |        |        |
23240ff8c99SAkhil Goyal        | +------V------+ |
23340ff8c99SAkhil Goyal        | | SADB lookup | |   <------ SA maps to cryptodev session
23440ff8c99SAkhil Goyal        | +------|------+ |
23540ff8c99SAkhil Goyal        | +------|------+ |
23640ff8c99SAkhil Goyal        | |      \--------------------\
23740ff8c99SAkhil Goyal        | |    Crypto   | |           |  <- Crypto processing through
23840ff8c99SAkhil Goyal        | |      /----------------\   |     inline crypto PMD
23940ff8c99SAkhil Goyal        | +------|------+ |       |   |
24040ff8c99SAkhil Goyal        +--------V--------+       |   |
24140ff8c99SAkhil Goyal                 |                |   |
24240ff8c99SAkhil Goyal        +--------V--------+       |   |  create   <-- SA is added to hw
24340ff8c99SAkhil Goyal        |    L2 Stack     |       |   |  inline       using existing create
24440ff8c99SAkhil Goyal        +--------|--------+       |   |  session      sym session APIs
24540ff8c99SAkhil Goyal                 |                |   |    |
24640ff8c99SAkhil Goyal        +--------V--------+   +---|---|----V---+
24740ff8c99SAkhil Goyal        |                 |   |   \---/    |   | <--- Add tunnel, ESP header etc
24840ff8c99SAkhil Goyal        |     NIC PMD     |   |   INLINE   |   |      header to packet.Packet
24940ff8c99SAkhil Goyal        |                 |   | CRYPTO PMD |   |      Encryption/Decryption and
25040ff8c99SAkhil Goyal        +--------|--------+   +----------------+      Authentication happens
25140ff8c99SAkhil Goyal                 |                                    inline.
25240ff8c99SAkhil Goyal        +--------|--------+
25340ff8c99SAkhil Goyal        |       NIC       |
25440ff8c99SAkhil Goyal        +--------|--------+
25540ff8c99SAkhil Goyal                 V
25640ff8c99SAkhil Goyal
2578b593b8cSAkhil GoyalPDCP Flow Diagram
2588b593b8cSAkhil Goyal~~~~~~~~~~~~~~~~~
2598b593b8cSAkhil Goyal
2608b593b8cSAkhil GoyalBased on 3GPP TS 36.323 Evolved Universal Terrestrial Radio Access (E-UTRA);
2618b593b8cSAkhil GoyalPacket Data Convergence Protocol (PDCP) specification
2628b593b8cSAkhil Goyal
2638b593b8cSAkhil Goyal.. code-block:: c
2648b593b8cSAkhil Goyal
2658b593b8cSAkhil Goyal        Transmitting PDCP Entity          Receiving PDCP Entity
2668b593b8cSAkhil Goyal                  |                                   ^
2678b593b8cSAkhil Goyal                  |                       +-----------|-----------+
2688b593b8cSAkhil Goyal                  V                       | In order delivery and |
2698b593b8cSAkhil Goyal        +---------|----------+            | Duplicate detection   |
2708b593b8cSAkhil Goyal        | Sequence Numbering |            |  (Data Plane only)    |
2718b593b8cSAkhil Goyal        +---------|----------+            +-----------|-----------+
2728b593b8cSAkhil Goyal                  |                                   |
2738b593b8cSAkhil Goyal        +---------|----------+            +-----------|----------+
2748b593b8cSAkhil Goyal        | Header Compression*|            | Header Decompression*|
2758b593b8cSAkhil Goyal        | (Data-Plane only)  |            |   (Data Plane only)  |
2768b593b8cSAkhil Goyal        +---------|----------+            +-----------|----------+
2778b593b8cSAkhil Goyal                  |                                   |
2788b593b8cSAkhil Goyal        +---------|-----------+           +-----------|----------+
2798b593b8cSAkhil Goyal        | Integrity Protection|           |Integrity Verification|
2808b593b8cSAkhil Goyal        | (Control Plane only)|           | (Control Plane only) |
2818b593b8cSAkhil Goyal        +---------|-----------+           +-----------|----------+
2828b593b8cSAkhil Goyal        +---------|-----------+            +----------|----------+
2838b593b8cSAkhil Goyal        |     Ciphering       |            |     Deciphering     |
2848b593b8cSAkhil Goyal        +---------|-----------+            +----------|----------+
2858b593b8cSAkhil Goyal        +---------|-----------+            +----------|----------+
2868b593b8cSAkhil Goyal        |   Add PDCP header   |            | Remove PDCP Header  |
2878b593b8cSAkhil Goyal        +---------|-----------+            +----------|----------+
2888b593b8cSAkhil Goyal                  |                                   |
2898b593b8cSAkhil Goyal                  +----------------->>----------------+
2908b593b8cSAkhil Goyal
2918b593b8cSAkhil Goyal
2928b593b8cSAkhil Goyal.. note::
2938b593b8cSAkhil Goyal
2948b593b8cSAkhil Goyal    * Header Compression and decompression are not supported currently.
2958b593b8cSAkhil Goyal
2968b593b8cSAkhil GoyalJust like IPsec, in case of PDCP also header addition/deletion, cipher/
2978b593b8cSAkhil Goyalde-cipher, integrity protection/verification is done based on the action
2988b593b8cSAkhil Goyaltype chosen.
2998b593b8cSAkhil Goyal
300e44b3fafSDavid CoyleDOCSIS Protocol
301e44b3fafSDavid Coyle~~~~~~~~~~~~~~~
302e44b3fafSDavid Coyle
303e44b3fafSDavid CoyleThe Data Over Cable Service Interface Specification (DOCSIS) support comprises
304e44b3fafSDavid Coylethe combination of encryption/decryption and CRC generation/verification, for
305e44b3fafSDavid Coyleuse in a DOCSIS-MAC pipeline.
306e44b3fafSDavid Coyle
307e44b3fafSDavid Coyle.. code-block:: c
308e44b3fafSDavid Coyle
309e44b3fafSDavid Coyle
310e44b3fafSDavid Coyle               Downlink                       Uplink
311e44b3fafSDavid Coyle               --------                       ------
312e44b3fafSDavid Coyle
313e44b3fafSDavid Coyle            Ethernet frame                Ethernet frame
314e44b3fafSDavid Coyle           from core network              to core network
315e44b3fafSDavid Coyle                  |                              ^
316e44b3fafSDavid Coyle                  ~                              |
317e44b3fafSDavid Coyle                  |                              ~         ----+
318e44b3fafSDavid Coyle                  V                              |             |
319e44b3fafSDavid Coyle        +---------|----------+        +----------|---------+   |
320e44b3fafSDavid Coyle        |   CRC generation   |        |  CRC verification  |   |
321e44b3fafSDavid Coyle        +---------|----------+        +----------|---------+   |   combined
322e44b3fafSDavid Coyle                  |                              |             > Crypto + CRC
323e44b3fafSDavid Coyle        +---------|----------+        +----------|---------+   |
324e44b3fafSDavid Coyle        |     Encryption     |        |     Decryption     |   |
325e44b3fafSDavid Coyle        +---------|----------+        +----------|---------+   |
326e44b3fafSDavid Coyle                  |                              ^             |
327e44b3fafSDavid Coyle                  ~                              |         ----+
328e44b3fafSDavid Coyle                  |                              ~
329e44b3fafSDavid Coyle                  V                              |
330e44b3fafSDavid Coyle             DOCSIS frame                  DOCSIS frame
331e44b3fafSDavid Coyle            to Cable Modem               from Cable Modem
332e44b3fafSDavid Coyle
333e44b3fafSDavid CoyleThe encryption/decryption is a combination of CBC and CFB modes using either AES
334e44b3fafSDavid Coyleor DES algorithms as specified in the DOCSIS Security Specification (from DPDK
335e44b3fafSDavid Coylelib_rtecryptodev perspective, these are RTE_CRYPTO_CIPHER_AES_DOCSISBPI and
336e44b3fafSDavid CoyleRTE_CRYPTO_CIPHER_DES_DOCSISBPI).
337e44b3fafSDavid Coyle
338e44b3fafSDavid CoyleThe CRC is Ethernet CRC-32 as specified in Ethernet/[ISO/IEC 8802-3].
339e44b3fafSDavid Coyle
340e44b3fafSDavid Coyle.. note::
341e44b3fafSDavid Coyle
342e44b3fafSDavid Coyle    * The offset and length of data for which CRC needs to be computed are
343e44b3fafSDavid Coyle      specified via the auth offset and length fields of the rte_crypto_sym_op.
344e44b3fafSDavid Coyle    * Other DOCSIS protocol functionality such as Header Checksum (HCS)
345e44b3fafSDavid Coyle      calculation may be added in the future.
346e44b3fafSDavid Coyle
34740ff8c99SAkhil GoyalDevice Features and Capabilities
34840ff8c99SAkhil Goyal---------------------------------
34940ff8c99SAkhil Goyal
35040ff8c99SAkhil GoyalDevice Capabilities For Security Operations
35140ff8c99SAkhil Goyal~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
35240ff8c99SAkhil Goyal
35340ff8c99SAkhil GoyalThe device (crypto or ethernet) capabilities which support security operations,
35440ff8c99SAkhil Goyalare defined by the security action type, security protocol, protocol
35540ff8c99SAkhil Goyalcapabilities and corresponding crypto capabilities for security. For the full
35640ff8c99SAkhil Goyalscope of the Security capability see definition of rte_security_capability
35740ff8c99SAkhil Goyalstructure in the *DPDK API Reference*.
35840ff8c99SAkhil Goyal
35940ff8c99SAkhil Goyal.. code-block:: c
36040ff8c99SAkhil Goyal
36140ff8c99SAkhil Goyal   struct rte_security_capability;
36240ff8c99SAkhil Goyal
36340ff8c99SAkhil GoyalEach driver (crypto or ethernet) defines its own private array of capabilities
36440ff8c99SAkhil Goyalfor the operations it supports. Below is an example of the capabilities for a
3658b593b8cSAkhil GoyalPMD which supports the IPsec and PDCP protocol.
36640ff8c99SAkhil Goyal
36740ff8c99SAkhil Goyal.. code-block:: c
36840ff8c99SAkhil Goyal
36940ff8c99SAkhil Goyal    static const struct rte_security_capability pmd_security_capabilities[] = {
37040ff8c99SAkhil Goyal        { /* IPsec Lookaside Protocol offload ESP Tunnel Egress */
37140ff8c99SAkhil Goyal                .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
37240ff8c99SAkhil Goyal                .protocol = RTE_SECURITY_PROTOCOL_IPSEC,
37340ff8c99SAkhil Goyal                .ipsec = {
37440ff8c99SAkhil Goyal                        .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP,
37540ff8c99SAkhil Goyal                        .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
37640ff8c99SAkhil Goyal                        .direction = RTE_SECURITY_IPSEC_SA_DIR_EGRESS,
37740ff8c99SAkhil Goyal                        .options = { 0 }
37840ff8c99SAkhil Goyal                },
37940ff8c99SAkhil Goyal                .crypto_capabilities = pmd_capabilities
38040ff8c99SAkhil Goyal        },
38140ff8c99SAkhil Goyal        { /* IPsec Lookaside Protocol offload ESP Tunnel Ingress */
38240ff8c99SAkhil Goyal                .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
38340ff8c99SAkhil Goyal                .protocol = RTE_SECURITY_PROTOCOL_IPSEC,
38440ff8c99SAkhil Goyal                .ipsec = {
38540ff8c99SAkhil Goyal                        .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP,
38640ff8c99SAkhil Goyal                        .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
38740ff8c99SAkhil Goyal                        .direction = RTE_SECURITY_IPSEC_SA_DIR_INGRESS,
38840ff8c99SAkhil Goyal                        .options = { 0 }
38940ff8c99SAkhil Goyal                },
39040ff8c99SAkhil Goyal                .crypto_capabilities = pmd_capabilities
39140ff8c99SAkhil Goyal        },
3928b593b8cSAkhil Goyal        { /* PDCP Lookaside Protocol offload Data Plane */
3938b593b8cSAkhil Goyal                .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
3948b593b8cSAkhil Goyal                .protocol = RTE_SECURITY_PROTOCOL_PDCP,
3958b593b8cSAkhil Goyal                .pdcp = {
3968b593b8cSAkhil Goyal                        .domain = RTE_SECURITY_PDCP_MODE_DATA,
3978b593b8cSAkhil Goyal                        .capa_flags = 0
3988b593b8cSAkhil Goyal                },
3998b593b8cSAkhil Goyal                .crypto_capabilities = pmd_capabilities
4008b593b8cSAkhil Goyal        },
4018b593b8cSAkhil Goyal        { /* PDCP Lookaside Protocol offload Control */
4028b593b8cSAkhil Goyal                .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
4038b593b8cSAkhil Goyal                .protocol = RTE_SECURITY_PROTOCOL_PDCP,
4048b593b8cSAkhil Goyal                .pdcp = {
4058b593b8cSAkhil Goyal                        .domain = RTE_SECURITY_PDCP_MODE_CONTROL,
4068b593b8cSAkhil Goyal                        .capa_flags = 0
4078b593b8cSAkhil Goyal                },
4088b593b8cSAkhil Goyal                .crypto_capabilities = pmd_capabilities
4098b593b8cSAkhil Goyal        },
41040ff8c99SAkhil Goyal        {
41140ff8c99SAkhil Goyal                .action = RTE_SECURITY_ACTION_TYPE_NONE
41240ff8c99SAkhil Goyal        }
41340ff8c99SAkhil Goyal    };
41440ff8c99SAkhil Goyal    static const struct rte_cryptodev_capabilities pmd_capabilities[] = {
41540ff8c99SAkhil Goyal        {    /* SHA1 HMAC */
41640ff8c99SAkhil Goyal            .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
41740ff8c99SAkhil Goyal            .sym = {
41840ff8c99SAkhil Goyal                .xform_type = RTE_CRYPTO_SYM_XFORM_AUTH,
41940ff8c99SAkhil Goyal                .auth = {
42040ff8c99SAkhil Goyal                    .algo = RTE_CRYPTO_AUTH_SHA1_HMAC,
42140ff8c99SAkhil Goyal                    .block_size = 64,
42240ff8c99SAkhil Goyal                    .key_size = {
42340ff8c99SAkhil Goyal                        .min = 64,
42440ff8c99SAkhil Goyal                        .max = 64,
42540ff8c99SAkhil Goyal                        .increment = 0
42640ff8c99SAkhil Goyal                    },
42740ff8c99SAkhil Goyal                    .digest_size = {
42840ff8c99SAkhil Goyal                        .min = 12,
42940ff8c99SAkhil Goyal                        .max = 12,
43040ff8c99SAkhil Goyal                        .increment = 0
43140ff8c99SAkhil Goyal                    },
43240ff8c99SAkhil Goyal                    .aad_size = { 0 },
43340ff8c99SAkhil Goyal                    .iv_size = { 0 }
43440ff8c99SAkhil Goyal                }
43540ff8c99SAkhil Goyal            }
43640ff8c99SAkhil Goyal        },
43740ff8c99SAkhil Goyal        {    /* AES CBC */
43840ff8c99SAkhil Goyal            .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
43940ff8c99SAkhil Goyal            .sym = {
44040ff8c99SAkhil Goyal                .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER,
44140ff8c99SAkhil Goyal                .cipher = {
44240ff8c99SAkhil Goyal                    .algo = RTE_CRYPTO_CIPHER_AES_CBC,
44340ff8c99SAkhil Goyal                    .block_size = 16,
44440ff8c99SAkhil Goyal                    .key_size = {
44540ff8c99SAkhil Goyal                        .min = 16,
44640ff8c99SAkhil Goyal                        .max = 32,
44740ff8c99SAkhil Goyal                        .increment = 8
44840ff8c99SAkhil Goyal                    },
44940ff8c99SAkhil Goyal                    .iv_size = {
45040ff8c99SAkhil Goyal                        .min = 16,
45140ff8c99SAkhil Goyal                        .max = 16,
45240ff8c99SAkhil Goyal                        .increment = 0
45340ff8c99SAkhil Goyal                    }
45440ff8c99SAkhil Goyal                }
45540ff8c99SAkhil Goyal            }
45640ff8c99SAkhil Goyal        }
45740ff8c99SAkhil Goyal    }
45840ff8c99SAkhil Goyal
459e44b3fafSDavid CoyleBelow is an example of the capabilities for a PMD which supports the DOCSIS
460e44b3fafSDavid Coyleprotocol.
461e44b3fafSDavid Coyle
462e44b3fafSDavid Coyle.. code-block:: c
463e44b3fafSDavid Coyle
464e44b3fafSDavid Coyle    static const struct rte_security_capability pmd_security_capabilities[] = {
465e44b3fafSDavid Coyle        { /* DOCSIS Uplink */
466e44b3fafSDavid Coyle                .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
467e44b3fafSDavid Coyle                .protocol = RTE_SECURITY_PROTOCOL_DOCSIS,
468e44b3fafSDavid Coyle                .docsis = {
469e44b3fafSDavid Coyle                        .direction = RTE_SECURITY_DOCSIS_UPLINK
470e44b3fafSDavid Coyle                },
471e44b3fafSDavid Coyle                .crypto_capabilities = pmd_capabilities
472e44b3fafSDavid Coyle        },
473e44b3fafSDavid Coyle        { /* DOCSIS Downlink */
474e44b3fafSDavid Coyle                .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
475e44b3fafSDavid Coyle                .protocol = RTE_SECURITY_PROTOCOL_DOCSIS,
476e44b3fafSDavid Coyle                .docsis = {
477e44b3fafSDavid Coyle                        .direction = RTE_SECURITY_DOCSIS_DOWNLINK
478e44b3fafSDavid Coyle                },
479e44b3fafSDavid Coyle                .crypto_capabilities = pmd_capabilities
480e44b3fafSDavid Coyle        },
481e44b3fafSDavid Coyle        {
482e44b3fafSDavid Coyle                .action = RTE_SECURITY_ACTION_TYPE_NONE
483e44b3fafSDavid Coyle        }
484e44b3fafSDavid Coyle    };
485e44b3fafSDavid Coyle    static const struct rte_cryptodev_capabilities pmd_capabilities[] = {
486e44b3fafSDavid Coyle        {    /* AES DOCSIS BPI */
487e44b3fafSDavid Coyle            .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
488e44b3fafSDavid Coyle            .sym = {
489e44b3fafSDavid Coyle                .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER,
490e44b3fafSDavid Coyle                .cipher = {
491e44b3fafSDavid Coyle                    .algo = RTE_CRYPTO_CIPHER_AES_DOCSISBPI,
492e44b3fafSDavid Coyle                    .block_size = 16,
493e44b3fafSDavid Coyle                    .key_size = {
494e44b3fafSDavid Coyle                        .min = 16,
495e44b3fafSDavid Coyle                        .max = 32,
496e44b3fafSDavid Coyle                        .increment = 16
497e44b3fafSDavid Coyle                    },
498e44b3fafSDavid Coyle                    .iv_size = {
499e44b3fafSDavid Coyle                        .min = 16,
500e44b3fafSDavid Coyle                        .max = 16,
501e44b3fafSDavid Coyle                        .increment = 0
502e44b3fafSDavid Coyle                    }
503e44b3fafSDavid Coyle                }
504e44b3fafSDavid Coyle            }
505e44b3fafSDavid Coyle        },
506e44b3fafSDavid Coyle
507e44b3fafSDavid Coyle        RTE_CRYPTODEV_END_OF_CAPABILITIES_LIST()
508e44b3fafSDavid Coyle    };
50940ff8c99SAkhil Goyal
51040ff8c99SAkhil GoyalCapabilities Discovery
51140ff8c99SAkhil Goyal~~~~~~~~~~~~~~~~~~~~~~
51240ff8c99SAkhil Goyal
51340ff8c99SAkhil GoyalDiscovering the features and capabilities of a driver (crypto/ethernet)
51440ff8c99SAkhil Goyalis achieved through the ``rte_security_capabilities_get()`` function.
51540ff8c99SAkhil Goyal
51640ff8c99SAkhil Goyal.. code-block:: c
51740ff8c99SAkhil Goyal
51840ff8c99SAkhil Goyal   const struct rte_security_capability *rte_security_capabilities_get(uint16_t id);
51940ff8c99SAkhil Goyal
52040ff8c99SAkhil GoyalThis allows the user to query a specific driver and get all device
52140ff8c99SAkhil Goyalsecurity capabilities. It returns an array of ``rte_security_capability`` structures
52240ff8c99SAkhil Goyalwhich contains all the capabilities for that device.
52340ff8c99SAkhil Goyal
52440ff8c99SAkhil GoyalSecurity Session Create/Free
52540ff8c99SAkhil Goyal~~~~~~~~~~~~~~~~~~~~~~~~~~~~
52640ff8c99SAkhil Goyal
52740ff8c99SAkhil GoyalSecurity Sessions are created to store the immutable fields of a particular Security
52840ff8c99SAkhil GoyalAssociation for a particular protocol which is defined by a security session
52940ff8c99SAkhil Goyalconfiguration structure which is used in the operation processing of a packet flow.
53040ff8c99SAkhil GoyalSessions are used to manage protocol specific information as well as crypto parameters.
53140ff8c99SAkhil GoyalSecurity sessions cache this immutable data in a optimal way for the underlying PMD
53240ff8c99SAkhil Goyaland this allows further acceleration of the offload of Crypto workloads.
53340ff8c99SAkhil Goyal
53440ff8c99SAkhil GoyalThe Security framework provides APIs to create and free sessions for crypto/ethernet
53540ff8c99SAkhil Goyaldevices, where sessions are mempool objects. It is the application's responsibility
536*e30b2833SAkhil Goyalto create and manage two session mempools - one for session and other for session
537*e30b2833SAkhil Goyalprivate data. The private session data mempool object size should be able to
538*e30b2833SAkhil Goyalaccommodate the driver's private data of security session. The application can get
539*e30b2833SAkhil Goyalthe size of session private data using API ``rte_security_session_get_size``.
540*e30b2833SAkhil GoyalAnd the session mempool object size should be enough to accommodate
541*e30b2833SAkhil Goyal``rte_security_session``.
54240ff8c99SAkhil Goyal
54340ff8c99SAkhil GoyalOnce the session mempools have been created, ``rte_security_session_create()``
54440ff8c99SAkhil Goyalis used to allocate and initialize a session for the required crypto/ethernet device.
54540ff8c99SAkhil Goyal
54640ff8c99SAkhil GoyalSession APIs need a parameter ``rte_security_ctx`` to identify the crypto/ethernet
54740ff8c99SAkhil Goyalsecurity ops. This parameter can be retrieved using the APIs
54840ff8c99SAkhil Goyal``rte_cryptodev_get_sec_ctx()`` (for crypto device) or ``rte_eth_dev_get_sec_ctx``
54940ff8c99SAkhil Goyal(for ethernet port).
55040ff8c99SAkhil Goyal
55140ff8c99SAkhil GoyalSessions already created can be updated with ``rte_security_session_update()``.
55240ff8c99SAkhil Goyal
55340ff8c99SAkhil GoyalWhen a session is no longer used, the user must call ``rte_security_session_destroy()``
55440ff8c99SAkhil Goyalto free the driver private session data and return the memory back to the mempool.
55540ff8c99SAkhil Goyal
55640ff8c99SAkhil GoyalFor look aside protocol offload to hardware crypto device, the ``rte_crypto_op``
55740ff8c99SAkhil Goyalcreated by the application is attached to the security session by the API
55840ff8c99SAkhil Goyal``rte_security_attach_session()``.
55940ff8c99SAkhil Goyal
56040ff8c99SAkhil GoyalFor Inline Crypto and Inline protocol offload, device specific defined metadata is
56140ff8c99SAkhil Goyalupdated in the mbuf using ``rte_security_set_pkt_metadata()`` if
56240ff8c99SAkhil Goyal``DEV_TX_OFFLOAD_SEC_NEED_MDATA`` is set.
56340ff8c99SAkhil Goyal
5641a08c379SAnoob JosephFor inline protocol offloaded ingress traffic, the application can register a
5651a08c379SAnoob Josephpointer, ``userdata`` , in the security session. When the packet is received,
5661a08c379SAnoob Joseph``rte_security_get_userdata()`` would return the userdata registered for the
5671a08c379SAnoob Josephsecurity session which processed the packet.
5681a08c379SAnoob Joseph
5691a08c379SAnoob Joseph.. note::
5701a08c379SAnoob Joseph
5711a08c379SAnoob Joseph    In case of inline processed packets, ``rte_mbuf.udata64`` field would be
5721a08c379SAnoob Joseph    used by the driver to relay information on the security processing
5731a08c379SAnoob Joseph    associated with the packet. In ingress, the driver would set this in Rx
5741a08c379SAnoob Joseph    path while in egress, ``rte_security_set_pkt_metadata()`` would perform a
5751a08c379SAnoob Joseph    similar operation. The application is expected not to modify the field
5761a08c379SAnoob Joseph    when it has relevant info. For ingress, this device-specific 64 bit value
5771a08c379SAnoob Joseph    is required to derive other information (like userdata), required for
5781a08c379SAnoob Joseph    identifying the security processing done on the packet.
5791a08c379SAnoob Joseph
58040ff8c99SAkhil GoyalSecurity session configuration
58140ff8c99SAkhil Goyal~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
58240ff8c99SAkhil Goyal
58340ff8c99SAkhil GoyalSecurity Session configuration structure is defined as ``rte_security_session_conf``
58440ff8c99SAkhil Goyal
58540ff8c99SAkhil Goyal.. code-block:: c
58640ff8c99SAkhil Goyal
58740ff8c99SAkhil Goyal    struct rte_security_session_conf {
58840ff8c99SAkhil Goyal        enum rte_security_session_action_type action_type;
58940ff8c99SAkhil Goyal        /**< Type of action to be performed on the session */
59040ff8c99SAkhil Goyal        enum rte_security_session_protocol protocol;
59140ff8c99SAkhil Goyal        /**< Security protocol to be configured */
59240ff8c99SAkhil Goyal        union {
59340ff8c99SAkhil Goyal                struct rte_security_ipsec_xform ipsec;
59440ff8c99SAkhil Goyal                struct rte_security_macsec_xform macsec;
5958b593b8cSAkhil Goyal                struct rte_security_pdcp_xform pdcp;
596e44b3fafSDavid Coyle                struct rte_security_docsis_xform docsis;
59740ff8c99SAkhil Goyal        };
59840ff8c99SAkhil Goyal        /**< Configuration parameters for security session */
59940ff8c99SAkhil Goyal        struct rte_crypto_sym_xform *crypto_xform;
60040ff8c99SAkhil Goyal        /**< Security Session Crypto Transformations */
6011a08c379SAnoob Joseph        void *userdata;
6021a08c379SAnoob Joseph        /**< Application specific userdata to be saved with session */
60340ff8c99SAkhil Goyal    };
60440ff8c99SAkhil Goyal
60540ff8c99SAkhil GoyalThe configuration structure reuses the ``rte_crypto_sym_xform`` struct for crypto related
60640ff8c99SAkhil Goyalconfiguration. The ``rte_security_session_action_type`` struct is used to specify whether the
60740ff8c99SAkhil Goyalsession is configured for Lookaside Protocol offload or Inline Crypto or Inline Protocol
60840ff8c99SAkhil GoyalOffload.
60940ff8c99SAkhil Goyal
61040ff8c99SAkhil Goyal.. code-block:: c
61140ff8c99SAkhil Goyal
61240ff8c99SAkhil Goyal    enum rte_security_session_action_type {
61340ff8c99SAkhil Goyal        RTE_SECURITY_ACTION_TYPE_NONE,
61440ff8c99SAkhil Goyal        /**< No security actions */
61540ff8c99SAkhil Goyal        RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO,
61640ff8c99SAkhil Goyal        /**< Crypto processing for security protocol is processed inline
6175d6d7e44SMarcin Smoczynski         * during transmission
6185d6d7e44SMarcin Smoczynski         */
61940ff8c99SAkhil Goyal        RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL,
62040ff8c99SAkhil Goyal        /**< All security protocol processing is performed inline during
6215d6d7e44SMarcin Smoczynski         * transmission
6225d6d7e44SMarcin Smoczynski         */
6235d6d7e44SMarcin Smoczynski        RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
62440ff8c99SAkhil Goyal        /**< All security protocol processing including crypto is performed
6255d6d7e44SMarcin Smoczynski         * on a lookaside accelerator
6265d6d7e44SMarcin Smoczynski         */
6275d6d7e44SMarcin Smoczynski        RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO
6285d6d7e44SMarcin Smoczynski        /**< Similar to ACTION_TYPE_NONE but crypto processing for security
6295d6d7e44SMarcin Smoczynski         * protocol is processed synchronously by a CPU.
6305d6d7e44SMarcin Smoczynski         */
63140ff8c99SAkhil Goyal    };
63240ff8c99SAkhil Goyal
63340ff8c99SAkhil GoyalThe ``rte_security_session_protocol`` is defined as
63440ff8c99SAkhil Goyal
63540ff8c99SAkhil Goyal.. code-block:: c
63640ff8c99SAkhil Goyal
63740ff8c99SAkhil Goyal    enum rte_security_session_protocol {
6388b593b8cSAkhil Goyal        RTE_SECURITY_PROTOCOL_IPSEC = 1,
63940ff8c99SAkhil Goyal        /**< IPsec Protocol */
64040ff8c99SAkhil Goyal        RTE_SECURITY_PROTOCOL_MACSEC,
64140ff8c99SAkhil Goyal        /**< MACSec Protocol */
6428b593b8cSAkhil Goyal        RTE_SECURITY_PROTOCOL_PDCP,
6438b593b8cSAkhil Goyal        /**< PDCP Protocol */
644e44b3fafSDavid Coyle        RTE_SECURITY_PROTOCOL_DOCSIS,
645e44b3fafSDavid Coyle        /**< DOCSIS Protocol */
64640ff8c99SAkhil Goyal    };
64740ff8c99SAkhil Goyal
6488b593b8cSAkhil GoyalCurrently the library defines configuration parameters for IPsec and PDCP only.
6498b593b8cSAkhil GoyalFor other protocols like MACSec, structures and enums are defined as place holders
6508b593b8cSAkhil Goyalwhich will be updated in the future.
65140ff8c99SAkhil Goyal
65240ff8c99SAkhil GoyalIPsec related configuration parameters are defined in ``rte_security_ipsec_xform``
65340ff8c99SAkhil Goyal
6548b593b8cSAkhil GoyalPDCP related configuration parameters are defined in ``rte_security_pdcp_xform``
6558b593b8cSAkhil Goyal
656e44b3fafSDavid CoyleDOCSIS related configuration parameters are defined in ``rte_security_docsis_xform``
657e44b3fafSDavid Coyle
65840ff8c99SAkhil Goyal
65940ff8c99SAkhil GoyalSecurity API
66040ff8c99SAkhil Goyal~~~~~~~~~~~~
66140ff8c99SAkhil Goyal
66240ff8c99SAkhil GoyalThe rte_security Library API is described in the *DPDK API Reference* document.
66340ff8c99SAkhil Goyal
66440ff8c99SAkhil GoyalFlow based Security Session
66540ff8c99SAkhil Goyal~~~~~~~~~~~~~~~~~~~~~~~~~~~
66640ff8c99SAkhil Goyal
66740ff8c99SAkhil GoyalIn the case of NIC based offloads, the security session specified in the
66840ff8c99SAkhil Goyal'rte_flow_action_security' must be created on the same port as the
66940ff8c99SAkhil Goyalflow action that is being specified.
67040ff8c99SAkhil Goyal
67140ff8c99SAkhil GoyalThe ingress/egress flow attribute should match that specified in the security
67240ff8c99SAkhil Goyalsession if the security session supports the definition of the direction.
67340ff8c99SAkhil Goyal
67440ff8c99SAkhil GoyalMultiple flows can be configured to use the same security session. For
67540ff8c99SAkhil Goyalexample if the security session specifies an egress IPsec SA, then multiple
67640ff8c99SAkhil Goyalflows can be specified to that SA. In the case of an ingress IPsec SA then
67740ff8c99SAkhil Goyalit is only valid to have a single flow to map to that security session.
67840ff8c99SAkhil Goyal
67940ff8c99SAkhil Goyal.. code-block:: console
68040ff8c99SAkhil Goyal
68140ff8c99SAkhil Goyal         Configuration Path
68240ff8c99SAkhil Goyal                 |
68340ff8c99SAkhil Goyal        +--------|--------+
68440ff8c99SAkhil Goyal        |    Add/Remove   |
68540ff8c99SAkhil Goyal        |     IPsec SA    |   <------ Build security flow action of
68640ff8c99SAkhil Goyal        |        |        |           ipsec transform
68740ff8c99SAkhil Goyal        |--------|--------|
68840ff8c99SAkhil Goyal                 |
68940ff8c99SAkhil Goyal        +--------V--------+
69040ff8c99SAkhil Goyal        |   Flow API      |
69140ff8c99SAkhil Goyal        +--------|--------+
69240ff8c99SAkhil Goyal                 |
69340ff8c99SAkhil Goyal        +--------V--------+
69440ff8c99SAkhil Goyal        |                 |
69540ff8c99SAkhil Goyal        |     NIC PMD     |   <------ Add/Remove SA to/from hw context
69640ff8c99SAkhil Goyal        |                 |
69740ff8c99SAkhil Goyal        +--------|--------+
69840ff8c99SAkhil Goyal                 |
69940ff8c99SAkhil Goyal        +--------|--------+
70040ff8c99SAkhil Goyal        |  HW ACCELERATED |
70140ff8c99SAkhil Goyal        |        NIC      |
70240ff8c99SAkhil Goyal        |                 |
70340ff8c99SAkhil Goyal        +--------|--------+
70440ff8c99SAkhil Goyal
70540ff8c99SAkhil Goyal* Add/Delete SA flow:
70640ff8c99SAkhil Goyal  To add a new inline SA construct a rte_flow_item for Ethernet + IP + ESP
70740ff8c99SAkhil Goyal  using the SA selectors and the ``rte_crypto_ipsec_xform`` as the ``rte_flow_action``.
70840ff8c99SAkhil Goyal  Note that any rte_flow_items may be empty, which means it is not checked.
70940ff8c99SAkhil Goyal
71040ff8c99SAkhil Goyal.. code-block:: console
71140ff8c99SAkhil Goyal
71240ff8c99SAkhil Goyal    In its most basic form, IPsec flow specification is as follows:
71340ff8c99SAkhil Goyal        +-------+     +----------+    +--------+    +-----+
71440ff8c99SAkhil Goyal        |  Eth  | ->  |   IP4/6  | -> |   ESP  | -> | END |
71540ff8c99SAkhil Goyal        +-------+     +----------+    +--------+    +-----+
71640ff8c99SAkhil Goyal
71740ff8c99SAkhil Goyal    However, the API can represent, IPsec crypto offload with any encapsulation:
71840ff8c99SAkhil Goyal        +-------+            +--------+    +-----+
71940ff8c99SAkhil Goyal        |  Eth  | ->  ... -> |   ESP  | -> | END |
72040ff8c99SAkhil Goyal        +-------+            +--------+    +-----+
721