1 .. SPDX-License-Identifier: BSD-3-Clause
9 The security library provides a framework for management and provisioning
10 of security protocol operations offloaded to hardware based devices. The
11 library defines generic APIs to create and free security sessions which can
12 support full protocol offload as well as inline crypto operation with
13 NIC or crypto devices. The framework currently only supports the IPSec protocol
14 and associated operations, other protocols will be added in future.
19 The security library provides an additional offload capability to an existing
20 crypto device and/or ethernet device.
22 .. code-block:: console
28 +-----------+ +--------------+
29 | NIC PMD | | CRYPTO PMD |
30 +-----------+ +--------------+
34 Currently, the security library does not support the case of multi-process.
35 It will be updated in the future releases.
37 The supported offload types are explained in the sections below.
42 RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO:
43 The crypto processing for security protocol (e.g. IPSec) is processed
44 inline during receive and transmission on NIC port. The flow based
45 security action should be configured on the port.
47 Ingress Data path - The packet is decrypted in RX path and relevant
48 crypto status is set in Rx descriptors. After the successful inline
49 crypto processing the packet is presented to host as a regular Rx packet
50 however all security protocol related headers are still attached to the
51 packet. e.g. In case of IPSec, the IPSec tunnel headers (if any),
52 ESP/AH headers will remain in the packet but the received packet
53 contains the decrypted data where the encrypted data was when the packet
54 arrived. The driver Rx path check the descriptors and and based on the
55 crypto status sets additional flags in the rte_mbuf.ol_flags field.
59 The underlying device may not support crypto processing for all ingress packet
60 matching to a particular flow (e.g. fragmented packets), such packets will
61 be passed as encrypted packets. It is the responsibility of application to
62 process such encrypted packets using other crypto driver instance.
64 Egress Data path - The software prepares the egress packet by adding
65 relevant security protocol headers. Only the data will not be
66 encrypted by the software. The driver will accordingly configure the
67 tx descriptors. The hardware device will encrypt the data before sending the
72 The underlying device may support post encryption TSO.
74 .. code-block:: console
85 | | Tunnel | | <------ Add tunnel header to packet
88 | | ESP | | <------ Add ESP header without trailer to packet
89 | | | | <------ Mark packet to be offloaded, add trailer
90 | +------|------+ | meta-data to mbuf
99 | NIC PMD | <------ Set hw context for inline crypto offload
104 | HW ACCELERATED | <------ Packet Encryption and
105 | NIC | Authentication happens inline
110 Inline protocol offload
111 ~~~~~~~~~~~~~~~~~~~~~~~
113 RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL:
114 The crypto and protocol processing for security protocol (e.g. IPSec)
115 is processed inline during receive and transmission. The flow based
116 security action should be configured on the port.
118 Ingress Data path - The packet is decrypted in the RX path and relevant
119 crypto status is set in the Rx descriptors. After the successful inline
120 crypto processing the packet is presented to the host as a regular Rx packet
121 but all security protocol related headers are optionally removed from the
122 packet. e.g. in the case of IPSec, the IPSec tunnel headers (if any),
123 ESP/AH headers will be removed from the packet and the received packet
124 will contains the decrypted packet only. The driver Rx path checks the
125 descriptors and based on the crypto status sets additional flags in
126 ``rte_mbuf.ol_flags`` field.
130 The underlying device in this case is stateful. It is expected that
131 the device shall support crypto processing for all kind of packets matching
132 to a given flow, this includes fragmented packets (post reassembly).
133 E.g. in case of IPSec the device may internally manage anti-replay etc.
134 It will provide a configuration option for anti-replay behavior i.e. to drop
135 the packets or pass them to driver with error flags set in the descriptor.
137 Egress Data path - The software will send the plain packet without any
138 security protocol headers added to the packet. The driver will configure
139 the security index and other requirement in tx descriptors.
140 The hardware device will do security processing on the packet that includes
141 adding the relevant protocol headers and encrypting the data before sending
142 the packet out. The software should make sure that the buffer
143 has required head room and tail room for any protocol header addition. The
144 software may also do early fragmentation if the resultant packet is expected
145 to cross the MTU size.
150 The underlying device will manage state information required for egress
151 processing. E.g. in case of IPSec, the seq number will be added to the
152 packet, however the device shall provide indication when the sequence number
153 is about to overflow. The underlying device may support post encryption TSO.
155 .. code-block:: console
166 | | Desc | | <------ Mark packet to be offloaded
176 | NIC PMD | <------ Set hw context for inline crypto offload
181 | HW ACCELERATED | <------ Add tunnel, ESP header etc header to
182 | NIC | packet. Packet Encryption and
183 | | Authentication happens inline.
187 Lookaside protocol offload
188 ~~~~~~~~~~~~~~~~~~~~~~~~~~
190 RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL:
191 This extends librte_cryptodev to support the programming of IPsec
192 Security Association (SA) as part of a crypto session creation including
193 the definition. In addition to standard crypto processing, as defined by
194 the cryptodev, the security protocol processing is also offloaded to the
197 Decryption: The packet is sent to the crypto device for security
198 protocol processing. The device will decrypt the packet and it will also
199 optionally remove additional security headers from the packet.
200 E.g. in case of IPSec, IPSec tunnel headers (if any), ESP/AH headers
201 will be removed from the packet and the decrypted packet may contain
206 In case of IPSec the device may internally manage anti-replay etc.
207 It will provide a configuration option for anti-replay behavior i.e. to drop
208 the packets or pass them to driver with error flags set in descriptor.
210 Encryption: The software will submit the packet to cryptodev as usual
211 for encryption, the hardware device in this case will also add the relevant
212 security protocol header along with encrypting the packet. The software
213 should make sure that the buffer has required head room and tail room
214 for any protocol header addition.
218 In the case of IPSec, the seq number will be added to the packet,
219 It shall provide an indication when the sequence number is about to
222 .. code-block:: console
230 | | SADB lookup | | <------ SA maps to cryptodev session
233 | | \--------------------\
234 | | Crypto | | | <- Crypto processing through
235 | | /----------------\ | inline crypto PMD
236 | +------|------+ | | |
237 +--------V--------+ | |
239 +--------V--------+ | | create <-- SA is added to hw
240 | L2 Stack | | | inline using existing create
241 +--------|--------+ | | session sym session APIs
243 +--------V--------+ +---|---|----V---+
244 | | | \---/ | | <--- Add tunnel, ESP header etc
245 | NIC PMD | | INLINE | | header to packet.Packet
246 | | | CRYPTO PMD | | Encryption/Decryption and
247 +--------|--------+ +----------------+ Authentication happens
254 Device Features and Capabilities
255 ---------------------------------
257 Device Capabilities For Security Operations
258 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
260 The device (crypto or ethernet) capabilities which support security operations,
261 are defined by the security action type, security protocol, protocol
262 capabilities and corresponding crypto capabilities for security. For the full
263 scope of the Security capability see definition of rte_security_capability
264 structure in the *DPDK API Reference*.
268 struct rte_security_capability;
270 Each driver (crypto or ethernet) defines its own private array of capabilities
271 for the operations it supports. Below is an example of the capabilities for a
272 PMD which supports the IPSec protocol.
276 static const struct rte_security_capability pmd_security_capabilities[] = {
277 { /* IPsec Lookaside Protocol offload ESP Tunnel Egress */
278 .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
279 .protocol = RTE_SECURITY_PROTOCOL_IPSEC,
281 .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP,
282 .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
283 .direction = RTE_SECURITY_IPSEC_SA_DIR_EGRESS,
286 .crypto_capabilities = pmd_capabilities
288 { /* IPsec Lookaside Protocol offload ESP Tunnel Ingress */
289 .action = RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL,
290 .protocol = RTE_SECURITY_PROTOCOL_IPSEC,
292 .proto = RTE_SECURITY_IPSEC_SA_PROTO_ESP,
293 .mode = RTE_SECURITY_IPSEC_SA_MODE_TUNNEL,
294 .direction = RTE_SECURITY_IPSEC_SA_DIR_INGRESS,
297 .crypto_capabilities = pmd_capabilities
300 .action = RTE_SECURITY_ACTION_TYPE_NONE
303 static const struct rte_cryptodev_capabilities pmd_capabilities[] = {
305 .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
307 .xform_type = RTE_CRYPTO_SYM_XFORM_AUTH,
309 .algo = RTE_CRYPTO_AUTH_SHA1_HMAC,
327 .op = RTE_CRYPTO_OP_TYPE_SYMMETRIC,
329 .xform_type = RTE_CRYPTO_SYM_XFORM_CIPHER,
331 .algo = RTE_CRYPTO_CIPHER_AES_CBC,
349 Capabilities Discovery
350 ~~~~~~~~~~~~~~~~~~~~~~
352 Discovering the features and capabilities of a driver (crypto/ethernet)
353 is achieved through the ``rte_security_capabilities_get()`` function.
357 const struct rte_security_capability *rte_security_capabilities_get(uint16_t id);
359 This allows the user to query a specific driver and get all device
360 security capabilities. It returns an array of ``rte_security_capability`` structures
361 which contains all the capabilities for that device.
363 Security Session Create/Free
364 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
366 Security Sessions are created to store the immutable fields of a particular Security
367 Association for a particular protocol which is defined by a security session
368 configuration structure which is used in the operation processing of a packet flow.
369 Sessions are used to manage protocol specific information as well as crypto parameters.
370 Security sessions cache this immutable data in a optimal way for the underlying PMD
371 and this allows further acceleration of the offload of Crypto workloads.
373 The Security framework provides APIs to create and free sessions for crypto/ethernet
374 devices, where sessions are mempool objects. It is the application's responsibility
375 to create and manage the session mempools. The mempool object size should be able to
376 accommodate the driver's private data of security session.
378 Once the session mempools have been created, ``rte_security_session_create()``
379 is used to allocate and initialize a session for the required crypto/ethernet device.
381 Session APIs need a parameter ``rte_security_ctx`` to identify the crypto/ethernet
382 security ops. This parameter can be retrieved using the APIs
383 ``rte_cryptodev_get_sec_ctx()`` (for crypto device) or ``rte_eth_dev_get_sec_ctx``
386 Sessions already created can be updated with ``rte_security_session_update()``.
388 When a session is no longer used, the user must call ``rte_security_session_destroy()``
389 to free the driver private session data and return the memory back to the mempool.
391 For look aside protocol offload to hardware crypto device, the ``rte_crypto_op``
392 created by the application is attached to the security session by the API
393 ``rte_security_attach_session()``.
395 For Inline Crypto and Inline protocol offload, device specific defined metadata is
396 updated in the mbuf using ``rte_security_set_pkt_metadata()`` if
397 ``DEV_TX_OFFLOAD_SEC_NEED_MDATA`` is set.
399 Security session configuration
400 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
402 Security Session configuration structure is defined as ``rte_security_session_conf``
406 struct rte_security_session_conf {
407 enum rte_security_session_action_type action_type;
408 /**< Type of action to be performed on the session */
409 enum rte_security_session_protocol protocol;
410 /**< Security protocol to be configured */
412 struct rte_security_ipsec_xform ipsec;
413 struct rte_security_macsec_xform macsec;
415 /**< Configuration parameters for security session */
416 struct rte_crypto_sym_xform *crypto_xform;
417 /**< Security Session Crypto Transformations */
420 The configuration structure reuses the ``rte_crypto_sym_xform`` struct for crypto related
421 configuration. The ``rte_security_session_action_type`` struct is used to specify whether the
422 session is configured for Lookaside Protocol offload or Inline Crypto or Inline Protocol
427 enum rte_security_session_action_type {
428 RTE_SECURITY_ACTION_TYPE_NONE,
429 /**< No security actions */
430 RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO,
431 /**< Crypto processing for security protocol is processed inline
432 * during transmission */
433 RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL,
434 /**< All security protocol processing is performed inline during
436 RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL
437 /**< All security protocol processing including crypto is performed
438 * on a lookaside accelerator */
441 The ``rte_security_session_protocol`` is defined as
445 enum rte_security_session_protocol {
446 RTE_SECURITY_PROTOCOL_IPSEC,
447 /**< IPsec Protocol */
448 RTE_SECURITY_PROTOCOL_MACSEC,
449 /**< MACSec Protocol */
452 Currently the library defines configuration parameters for IPSec only. For other
453 protocols like MACSec, structures and enums are defined as place holders which
454 will be updated in the future.
456 IPsec related configuration parameters are defined in ``rte_security_ipsec_xform``
460 struct rte_security_ipsec_xform {
462 /**< SA security parameter index */
465 struct rte_security_ipsec_sa_options options;
466 /**< various SA options */
467 enum rte_security_ipsec_sa_direction direction;
468 /**< IPSec SA Direction - Egress/Ingress */
469 enum rte_security_ipsec_sa_protocol proto;
470 /**< IPsec SA Protocol - AH/ESP */
471 enum rte_security_ipsec_sa_mode mode;
472 /**< IPsec SA Mode - transport/tunnel */
473 struct rte_security_ipsec_tunnel_param tunnel;
474 /**< Tunnel parameters, NULL for transport mode */
481 The rte_security Library API is described in the *DPDK API Reference* document.
483 Flow based Security Session
484 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
486 In the case of NIC based offloads, the security session specified in the
487 'rte_flow_action_security' must be created on the same port as the
488 flow action that is being specified.
490 The ingress/egress flow attribute should match that specified in the security
491 session if the security session supports the definition of the direction.
493 Multiple flows can be configured to use the same security session. For
494 example if the security session specifies an egress IPsec SA, then multiple
495 flows can be specified to that SA. In the case of an ingress IPsec SA then
496 it is only valid to have a single flow to map to that security session.
498 .. code-block:: console
504 | IPsec SA | <------ Build security flow action of
505 | | | ipsec transform
514 | NIC PMD | <------ Add/Remove SA to/from hw context
524 * Add/Delete SA flow:
525 To add a new inline SA construct a rte_flow_item for Ethernet + IP + ESP
526 using the SA selectors and the ``rte_crypto_ipsec_xform`` as the ``rte_flow_action``.
527 Note that any rte_flow_items may be empty, which means it is not checked.
529 .. code-block:: console
531 In its most basic form, IPsec flow specification is as follows:
532 +-------+ +----------+ +--------+ +-----+
533 | Eth | -> | IP4/6 | -> | ESP | -> | END |
534 +-------+ +----------+ +--------+ +-----+
536 However, the API can represent, IPsec crypto offload with any encapsulation:
537 +-------+ +--------+ +-----+
538 | Eth | -> ... -> | ESP | -> | END |
539 +-------+ +--------+ +-----+