rte_security.h - Man Page

struct rte_security_ipsec_tunnel_param
struct rte_security_ipsec_sa_options
struct rte_security_ipsec_lifetime
struct rte_security_ipsec_xform
struct rte_security_macsec_sa
struct rte_security_macsec_sc
struct rte_security_macsec_xform
struct rte_security_pdcp_xform
struct rte_security_docsis_xform
struct rte_security_tls_record_sess_options
struct rte_security_tls_record_lifetime
struct rte_security_tls_record_xform
struct rte_security_session_conf
struct rte_security_capability
struct rte_security_capability_idx

#define RTE_SECURITY_IPSEC_TUNNEL_VERIFY_DST_ADDR   0x1
#define RTE_SEC_CTX_F_FAST_SET_MDATA   0x00000001
#define RTE_SECURITY_MACSEC_NUM_AN   4
#define RTE_SECURITY_MACSEC_SALT_LEN   12
#define RTE_SECURITY_MACSEC_VALIDATE_DISABLE   0
#define RTE_SECURITY_MACSEC_VALIDATE_NO_DISCARD   1
#define RTE_SECURITY_MACSEC_VALIDATE_STRICT   2
#define RTE_SECURITY_MACSEC_VALIDATE_NO_OP   3
#define RTE_SECURITY_TLS_1_2_IMP_NONCE_LEN   4
#define RTE_SECURITY_TLS_1_3_IMP_NONCE_LEN   12
#define RTE_SECURITY_DTLS_1_2_IMP_NONCE_LEN   4
#define RTE_SECURITY_PDCP_ORDERING_CAP   0x00000001
#define RTE_SECURITY_PDCP_DUP_DETECT_CAP   0x00000002
#define RTE_SECURITY_TX_OLOAD_NEED_MDATA   0x00000001
#define RTE_SECURITY_TX_HW_TRAILER_OFFLOAD   0x00000002
#define RTE_SECURITY_RX_HW_TRAILER_OFFLOAD   0x00010000

typedef uint64_t rte_security_dynfield_t
typedef struct rte_mbuf * rte_security_oop_dynfield_t

enum rte_security_ipsec_sa_mode { RTE_SECURITY_IPSEC_SA_MODE_TRANSPORT = 1, RTE_SECURITY_IPSEC_SA_MODE_TUNNEL }
enum rte_security_ipsec_sa_protocol { RTE_SECURITY_IPSEC_SA_PROTO_AH = 1, RTE_SECURITY_IPSEC_SA_PROTO_ESP }
enum rte_security_ipsec_tunnel_type { RTE_SECURITY_IPSEC_TUNNEL_IPV4 = 1, RTE_SECURITY_IPSEC_TUNNEL_IPV6 }
enum rte_security_ipsec_sa_direction { RTE_SECURITY_IPSEC_SA_DIR_EGRESS, RTE_SECURITY_IPSEC_SA_DIR_INGRESS }
enum rte_security_macsec_direction { RTE_SECURITY_MACSEC_DIR_TX, RTE_SECURITY_MACSEC_DIR_RX }
enum rte_security_macsec_alg { RTE_SECURITY_MACSEC_ALG_GCM_128, RTE_SECURITY_MACSEC_ALG_GCM_256, RTE_SECURITY_MACSEC_ALG_GCM_XPN_128, RTE_SECURITY_MACSEC_ALG_GCM_XPN_256 }
enum rte_security_pdcp_domain { RTE_SECURITY_PDCP_MODE_CONTROL, RTE_SECURITY_PDCP_MODE_DATA, RTE_SECURITY_PDCP_MODE_SHORT_MAC }
enum rte_security_pdcp_direction { RTE_SECURITY_PDCP_UPLINK, RTE_SECURITY_PDCP_DOWNLINK }
enum rte_security_pdcp_sn_size { RTE_SECURITY_PDCP_SN_SIZE_5 = 5, RTE_SECURITY_PDCP_SN_SIZE_7 = 7, RTE_SECURITY_PDCP_SN_SIZE_12 = 12, RTE_SECURITY_PDCP_SN_SIZE_15 = 15, RTE_SECURITY_PDCP_SN_SIZE_18 = 18 }
enum rte_security_docsis_direction { RTE_SECURITY_DOCSIS_UPLINK, RTE_SECURITY_DOCSIS_DOWNLINK }
enum rte_security_tls_version { RTE_SECURITY_VERSION_TLS_1_2, RTE_SECURITY_VERSION_TLS_1_3, RTE_SECURITY_VERSION_DTLS_1_2 }
enum rte_security_tls_sess_type { RTE_SECURITY_TLS_SESS_TYPE_READ, RTE_SECURITY_TLS_SESS_TYPE_WRITE }
enum rte_security_session_action_type { RTE_SECURITY_ACTION_TYPE_NONE, RTE_SECURITY_ACTION_TYPE_INLINE_CRYPTO, RTE_SECURITY_ACTION_TYPE_INLINE_PROTOCOL, RTE_SECURITY_ACTION_TYPE_LOOKASIDE_PROTOCOL, RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO }
enum rte_security_session_protocol { RTE_SECURITY_PROTOCOL_IPSEC = 1, RTE_SECURITY_PROTOCOL_MACSEC, RTE_SECURITY_PROTOCOL_PDCP, RTE_SECURITY_PROTOCOL_DOCSIS, RTE_SECURITY_PROTOCOL_TLS_RECORD }

void * rte_security_session_create (void *instance, struct rte_security_session_conf *conf, struct rte_mempool *mp)
int rte_security_session_update (void *instance, void *sess, struct rte_security_session_conf *conf)
unsigned int rte_security_session_get_size (void *instance)
int rte_security_session_destroy (void *instance, void *sess)
int rte_security_macsec_sc_create (void *instance, struct rte_security_macsec_sc *conf)
int rte_security_macsec_sc_destroy (void *instance, uint16_t sc_id, enum rte_security_macsec_direction dir)
int rte_security_macsec_sa_create (void *instance, struct rte_security_macsec_sa *conf)
int rte_security_macsec_sa_destroy (void *instance, uint16_t sa_id, enum rte_security_macsec_direction dir)
static rte_security_dynfield_t * rte_security_dynfield (struct rte_mbuf *mbuf)
static __rte_experimental rte_security_oop_dynfield_t * rte_security_oop_dynfield (struct rte_mbuf *mbuf)
static bool rte_security_dynfield_is_registered (void)
static uint32_t rte_security_ctx_flags_get (void *ctx)
static void rte_security_ctx_flags_set (void *ctx, uint32_t flags)
static uint64_t rte_security_session_opaque_data_get (void *sess)
static void rte_security_session_opaque_data_set (void *sess, uint64_t opaque)
static uint64_t rte_security_session_fast_mdata_get (void *sess)
static void rte_security_session_fast_mdata_set (void *sess, uint64_t fdata)
int __rte_security_set_pkt_metadata (void *instance, void *sess, struct rte_mbuf *m, void *params)
static int rte_security_set_pkt_metadata (void *instance, void *sess, struct rte_mbuf *mb, void *params)
static int __rte_security_attach_session (struct rte_crypto_sym_op *sym_op, void *sess)
static int rte_security_attach_session (struct rte_crypto_op *op, void *sess)
int rte_security_session_stats_get (void *instance, void *sess, struct rte_security_stats *stats)
int rte_security_macsec_sa_stats_get (void *instance, uint16_t sa_id, enum rte_security_macsec_direction dir, struct rte_security_macsec_sa_stats *stats)
int rte_security_macsec_sc_stats_get (void *instance, uint16_t sc_id, enum rte_security_macsec_direction dir, struct rte_security_macsec_sc_stats *stats)
const struct rte_security_capability * rte_security_capabilities_get (void *instance)
const struct rte_security_capability * rte_security_capability_get (void *instance, struct rte_security_capability_idx *idx)
__rte_experimental int rte_security_rx_inject_configure (void *ctx, uint16_t port_id, bool enable)
__rte_experimental uint16_t rte_security_inb_pkt_rx_inject (void *ctx, struct rte_mbuf **pkts, void **sess, uint16_t nb_pkts)

int rte_security_dynfield_offset
int rte_security_oop_dynfield_offset

IPSEC tunnel header verification mode

Controls how outer IP header is verified in inbound.

Definition at line 56 of file rte_security.h.

Driver uses fast metadata update without using driver specific callback. For fast mdata, mbuf dynamic field would be registered by driver via rte_security_dynfield_register().

Definition at line 59 of file rte_security.h.

Maximum number of association numbers for a secure channel.

Definition at line 345 of file rte_security.h.

Salt length for MACsec SA.

Definition at line 347 of file rte_security.h.

Disable Validation of MACsec frame.

Definition at line 418 of file rte_security.h.

Validate MACsec frame but do not discard invalid frame.

Definition at line 420 of file rte_security.h.

Validate MACsec frame and discart invalid frame.

Definition at line 422 of file rte_security.h.

Do not perform any MACsec operation.

Definition at line 424 of file rte_security.h.

Implicit nonce length to be used with AEAD algos in TLS 1.2

Definition at line 601 of file rte_security.h.

Implicit nonce length to be used with AEAD algos in TLS 1.3

Definition at line 603 of file rte_security.h.

Implicit nonce length to be used with AEAD algos in DTLS 1.2

Definition at line 605 of file rte_security.h.

Underlying Hardware/driver which support PDCP may or may not support packet ordering. Set RTE_SECURITY_PDCP_ORDERING_CAP if it support. If it is not set, driver/HW assumes packets received are in order and it will be application's responsibility to maintain ordering.

Definition at line 1340 of file rte_security.h.

Underlying Hardware/driver which support PDCP may or may not detect duplicate packet. Set RTE_SECURITY_PDCP_DUP_DETECT_CAP if it support. If it is not set, driver/HW assumes there is no duplicate packet received.

Definition at line 1346 of file rte_security.h.

HW needs metadata update, see rte_security_set_pkt_metadata().

Definition at line 1348 of file rte_security.h.

HW constructs trailer of packets Transmitted packets will have the trailer added to them by hardware. The next protocol field will be based on the mbuf->inner_esp_next_proto field.

Definition at line 1352 of file rte_security.h.

HW removes trailer of packets Received packets have no trailer, the next protocol field is supplied in the mbuf->inner_esp_next_proto field. Inner packet is not modified.

Definition at line 1358 of file rte_security.h.

Device-specific metadata field type

Definition at line 915 of file rte_security.h.

Out-of-Place(OOP) processing field type

Definition at line 920 of file rte_security.h.

IPSec protocol mode

Enumerator

RTE_SECURITY_IPSEC_SA_MODE_TRANSPORT

IPSec Transport mode

RTE_SECURITY_IPSEC_SA_MODE_TUNNEL

IPSec Tunnel mode

Definition at line 28 of file rte_security.h.

IPSec Protocol

Enumerator

RTE_SECURITY_IPSEC_SA_PROTO_AH

AH protocol

RTE_SECURITY_IPSEC_SA_PROTO_ESP

ESP protocol

Definition at line 36 of file rte_security.h.

IPSEC tunnel type

Enumerator

RTE_SECURITY_IPSEC_TUNNEL_IPV4

Outer header is IPv4

RTE_SECURITY_IPSEC_TUNNEL_IPV6

Outer header is IPv6

Definition at line 44 of file rte_security.h.

IPSec security association direction

Enumerator

RTE_SECURITY_IPSEC_SA_DIR_EGRESS

Encrypt and generate digest

RTE_SECURITY_IPSEC_SA_DIR_INGRESS

Verify digest and decrypt

Definition at line 265 of file rte_security.h.

MACSec packet flow direction

Enumerator

RTE_SECURITY_MACSEC_DIR_TX

Generate SecTag and encrypt/authenticate

RTE_SECURITY_MACSEC_DIR_RX

Remove SecTag and decrypt/verify

Definition at line 337 of file rte_security.h.

MACsec Supported Algorithm list as per IEEE Std 802.1AE.

Enumerator

RTE_SECURITY_MACSEC_ALG_GCM_128

AES-GCM 128 bit block cipher

RTE_SECURITY_MACSEC_ALG_GCM_256

AES-GCM 256 bit block cipher

RTE_SECURITY_MACSEC_ALG_GCM_XPN_128

AES-GCM 128 bit block cipher with unique SSCI

RTE_SECURITY_MACSEC_ALG_GCM_XPN_256

AES-GCM 256 bit block cipher with unique SSCI

Definition at line 410 of file rte_security.h.

PDCP Mode of session

Enumerator

RTE_SECURITY_PDCP_MODE_CONTROL

PDCP control plane

RTE_SECURITY_PDCP_MODE_DATA

PDCP data plane

RTE_SECURITY_PDCP_MODE_SHORT_MAC

PDCP short mac

Definition at line 505 of file rte_security.h.

PDCP Frame direction

Enumerator

RTE_SECURITY_PDCP_UPLINK

Uplink

RTE_SECURITY_PDCP_DOWNLINK

Downlink

Definition at line 512 of file rte_security.h.

PDCP Sequence Number Size selectors

Enumerator

RTE_SECURITY_PDCP_SN_SIZE_5

PDCP_SN_SIZE_5: 5bit sequence number

RTE_SECURITY_PDCP_SN_SIZE_7

PDCP_SN_SIZE_7: 7bit sequence number

RTE_SECURITY_PDCP_SN_SIZE_12

PDCP_SN_SIZE_12: 12bit sequence number

RTE_SECURITY_PDCP_SN_SIZE_15

PDCP_SN_SIZE_15: 15bit sequence number

RTE_SECURITY_PDCP_SN_SIZE_18

PDCP_SN_SIZE_18: 18bit sequence number

Definition at line 518 of file rte_security.h.

DOCSIS direction

Enumerator

RTE_SECURITY_DOCSIS_UPLINK

Uplink

·

Decryption, followed by CRC Verification

RTE_SECURITY_DOCSIS_DOWNLINK

Downlink

·

CRC Generation, followed by Encryption

Definition at line 579 of file rte_security.h.

TLS version

Enumerator

RTE_SECURITY_VERSION_TLS_1_2

TLS 1.2

RTE_SECURITY_VERSION_TLS_1_3

TLS 1.3

RTE_SECURITY_VERSION_DTLS_1_2

DTLS 1.2

Definition at line 608 of file rte_security.h.

TLS session type

Enumerator

RTE_SECURITY_TLS_SESS_TYPE_READ

Record read session

·

Decrypt & digest verification.

RTE_SECURITY_TLS_SESS_TYPE_WRITE

Record write session

·

Encrypt & digest generation.

Definition at line 615 of file rte_security.h.

Security session action type.

Enumerator

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

RTE_SECURITY_ACTION_TYPE_CPU_CRYPTO

Similar to ACTION_TYPE_NONE but crypto processing for security protocol is processed synchronously by a CPU.

Definition at line 731 of file rte_security.h.

Security session protocol definition

Enumerator

RTE_SECURITY_PROTOCOL_IPSEC

IPsec Protocol

RTE_SECURITY_PROTOCOL_MACSEC

MACSec Protocol

RTE_SECURITY_PROTOCOL_PDCP

PDCP Protocol

RTE_SECURITY_PROTOCOL_DOCSIS

DOCSIS Protocol

RTE_SECURITY_PROTOCOL_TLS_RECORD

TLS Record Protocol

Definition at line 755 of file rte_security.h.

Create security session as specified by the session configuration

Parameters

instance security instance
conf session configuration parameters
mp mempool to allocate session objects from

Returns

• On success, pointer to session
• On failure, NULL

Update security session as specified by the session configuration

Parameters

instance security instance
sess session to update parameters
conf update configuration parameters

Returns

• On success returns 0
• On failure returns a negative errno value.

Get the size of the security session data for a device.

Parameters

instance security instance.

Returns

• Size of the private data, if successful
• 0 if device is invalid or does not support the operation.

Free security session header and the session private data and return it to its original mempool.

Parameters

instance security instance
sess security session to be freed

Returns

• 0 if successful.
• -EINVAL if session or context instance is NULL.
• -EBUSY if not all device private data has been freed.
• -ENOTSUP if destroying private data is not supported.
• other negative values in case of freeing private data errors.

Create MACsec security channel (SC).

Parameters

instance security instance
conf MACsec SC configuration params

Returns

• secure channel ID if successful.
• -EINVAL if configuration params are invalid of instance is NULL.
• -ENOTSUP if device does not support MACsec.
• -ENOMEM if PMD is not capable to create more SC.
• other negative value for other errors.

Destroy MACsec security channel (SC).

Parameters

instance security instance
sc_id SC ID to be destroyed
dir direction of the SC

Returns

• 0 if successful.
• -EINVAL if sc_id is invalid or instance is NULL.
• -EBUSY if sc is being used by some session.

Create MACsec security association (SA).

Parameters

instance security instance
conf MACsec SA configuration params

Returns

• positive SA ID if successful.
• -EINVAL if configuration params are invalid of instance is NULL.
• -ENOTSUP if device does not support MACsec.
• -ENOMEM if PMD is not capable to create more SAs.
• other negative value for other errors.

Destroy MACsec security association (SA).

Parameters

instance security instance
sa_id SA ID to be destroyed
dir direction of the SA

Returns

• 0 if successful.
• -EINVAL if sa_id is invalid or instance is NULL.
• -EBUSY if sa is being used by some session.

Get pointer to mbuf field for device-specific metadata.

For performance reason, no check is done, the dynamic field may not be registered.

See also

rte_security_dynfield_is_registered

Parameters

mbuf packet to access

Returns

pointer to mbuf field

Definition at line 937 of file rte_security.h.

Warning

EXPERIMENTAL: this API may change without prior notice

Get pointer to mbuf field for original mbuf pointer when Out-Of-Place(OOP) processing is enabled in security session.

Parameters

mbuf packet to access

Returns

pointer to mbuf field

Definition at line 956 of file rte_security.h.

Check whether the dynamic field is registered.

Returns

true if rte_security_dynfield_register() has been called.

Definition at line 968 of file rte_security.h.

Get security flags from security instance.

Definition at line 978 of file rte_security.h.

Set security flags in security instance.

Definition at line 987 of file rte_security.h.

Get opaque data from session handle

Definition at line 1000 of file rte_security.h.

Set opaque data in session handle

Definition at line 1009 of file rte_security.h.

Get fast mdata from session handle

Definition at line 1020 of file rte_security.h.

Set fast mdata in session handle

Definition at line 1029 of file rte_security.h.

Function to call PMD specific function pointer set_pkt_metadata()

Updates the buffer with device-specific defined metadata

Parameters

instance security instance
sess security session
mb packet mbuf to set metadata on.
params device-specific defined parameters required for metadata

Returns

• On success, zero.
• On failure, a negative value.

Definition at line 1055 of file rte_security.h.

Attach a session to a symmetric crypto operation

Parameters

sym_op crypto operation
sess security session

Definition at line 1077 of file rte_security.h.

Attach a session to a crypto operation. This API is needed only in case of RTE_SECURITY_SESS_CRYPTO_PROTO_OFFLOAD For other rte_security_session_action_type, ol_flags in rte_mbuf may be defined to perform security operations.

Parameters

op crypto operation
sess security session

Definition at line 1094 of file rte_security.h.

Get security session statistics

Parameters

instance security instance
sess security session If security session is NULL then global (per security instance) statistics will be retrieved, if supported. Global statistics collection is not dependent on the per session statistics configuration.
stats statistics

Returns

• On success, return 0
• On failure, a negative value

Get MACsec SA statistics.

Parameters

instance security instance
sa_id SA ID for which stats are needed
dir direction of the SA
stats statistics

Returns

• On success, return 0.
• On failure, a negative value.

Get MACsec SC statistics.

Parameters

instance security instance
sc_id SC ID for which stats are needed
dir direction of the SC
stats SC statistics

Returns

• On success, return 0.
• On failure, a negative value.

Returns array of security instance capabilities

Parameters

instance Security instance.

Returns

• Returns array of security capabilities.
• Return NULL if no capabilities available.

Query if a specific capability is available on security instance

Parameters

instance security instance.
idx security capability index to match against

Returns

• Returns pointer to security capability on match of capability index criteria.
• Return NULL if the capability not matched on security instance.

Warning

EXPERIMENTAL: this API may change, or be removed, without prior notice

Configure security device to inject packets to an ethdev port.

This API must be called only when both security device and the ethdev is in stopped state. The security device need to be configured before any packets are submitted to rte_security_inb_pkt_rx_inject API.

Parameters

ctx Security ctx
port_id Port identifier of the ethernet device to which packets need to be injected.
enable Flag to enable and disable connection between a security device and an ethdev port.

Returns

• 0 if successful.
• -EINVAL if context NULL or port_id is invalid.
• -EBUSY if devices are not in stopped state.
• -ENOTSUP if security device does not support injecting to ethdev port.

See also

rte_security_inb_pkt_rx_inject

Warning

EXPERIMENTAL: this API may change, or be removed, without prior notice

Perform security processing of packets and inject the processed packet to ethdev Rx.

Rx inject would behave similarly to ethdev loopback but with the additional security processing. In case of ethdev loopback, application would be submitting packets to ethdev Tx queues and would be received as is from ethdev Rx queues. With Rx inject, packets would be received after security processing from ethdev Rx queues.

With inline protocol offload capable ethdevs, Rx injection can be used to handle packets which failed the regular security Rx path. This can be due to cases such as outer fragmentation, in which case applications can reassemble the fragments and then subsequently submit for inbound processing and Rx injection, so that packets are received as regular security processed packets.

With lookaside protocol offload capable cryptodevs, Rx injection can be used to perform packet parsing after security processing. This would allow for re-classification after security protocol processing is done (ie, inner packet parsing). The ethdev queue on which the packet would be received would be based on rte_flow rules matching the packet after security processing.

The security device which is injecting packets to ethdev Rx need to be configured using rte_security_rx_inject_configure with enable flag set to true before any packets are submitted.

If hash.fdir.h field is set in mbuf, it would be treated as the value for MARK pattern for the subsequent rte_flow parsing. The packet would appear as if it is received from port field in mbuf.

Since the packet would be received back from ethdev Rx queues, it is expected that application retains/adds L2 header with the mbuf field 'l2_len' reflecting the size of L2 header in the packet.

Parameters

ctx Security ctx
pkts The address of an array of nb_pkts pointers to rte_mbuf structures which contain the packets.
sess The address of an array of nb_pkts pointers to security sessions corresponding to each packet.
nb_pkts The maximum number of packets to process.

Returns

The number of packets successfully injected to ethdev Rx. The return value can be less than the value of the nb_pkts parameter when the PMD internal queues have been filled up.

See also

rte_security_rx_inject_configure

Dynamic mbuf field for device-specific metadata

Dynamic mbuf field for pointer to original mbuf for OOP processing session.