rte_crypto_sym_op(3)

🌸 NAME 🌸

rte_crypto_sym_op — okay bestie, this is the symmetric cryptographic operation structure, and this page is your full tour of it. 💖

✨ SYNOPSIS ✨

#include <rte_crypto_sym.h>

🎀 Data Fields 🎀

• struct rte_mbuf * m_src — source mbuf, aka where the data comes from.
• struct rte_mbuf * m_dst — destination mbuf, aka where OOP results go.

🦋 Detailed Description 🦋

So this structure contains data relating to performing symmetric cryptographic processing on a referenced mbuf data buffer. Slay. 💅

When a symmetric crypto operation is enqueued with the device for processing, it must have a valid rte_mbuf structure attached, via the m_src parameter, which contains the source data that the crypto operation is to be performed on. While the mbuf is in use by a crypto operation, no part of the mbuf should be changed by the application, because the device may read or write to any part of the mbuf. In the case of hardware crypto devices, some or all of the mbuf may be DMAed in and out of the device, so writing over the original data — though only the part specified by the rte_crypto_sym_op for transformation will be changed. 🫶

Out-of-place (OOP) operation, where the source mbuf is different to the destination mbuf, is a special case. Data will be copied from m_src to m_dst. The part copied includes all the parts of the source mbuf that will be operated on, based on the cipher.data.offset+cipher.data.length and auth.data.offset+auth.data.length values in the rte_crypto_sym_op. The part indicated by the cipher parameters will be transformed, any extra data around this indicated by the auth parameters will be copied unchanged from source to destination mbuf. Also in OOP operation the cipher.data.offset and auth.data.offset apply to both source and destination mbufs. As these offsets are relative to the data_off parameter in each mbuf, this can result in the data written to the destination buffer being at a different alignment, relative to buffer start, to the data in the source buffer. 😭✨

Definition at line 650 of file rte_crypto_sym.h.

💅 Field Documentation 💅

🍓 struct rte_mbuf* m_src

source mbuf

Definition at line 651 of file rte_crypto_sym.h.

🍓 struct rte_mbuf* m_dst

destination mbuf

Definition at line 652 of file rte_crypto_sym.h.

🍓 void* session

Handle for the initialised crypto/security session context

Definition at line 655 of file rte_crypto_sym.h.

🍓 struct rte_crypto_sym_xform* xform

Session-less API crypto operation parameters

Definition at line 657 of file rte_crypto_sym.h.

🍓 uint32_t offset

Starting point for AEAD processing, specified as number of bytes from start of packet in source buffer.

Starting point for cipher processing, specified as number of bytes from start of data in the source buffer. The result of the cipher operation will be written back into the output buffer starting at this location.

Note: For SNOW 3G @ RTE_CRYPTO_CIPHER_SNOW3G_UEA2, KASUMI @ RTE_CRYPTO_CIPHER_KASUMI_F8, ZUC @ RTE_CRYPTO_CIPHER_ZUC_EEA3, SNOW 5G @ RTE_CRYPTO_CIPHER_SNOW5G_NEA4, AES @ RTE_CRYPTO_CIPHER_AES_NEA5 and ZUC @ RTE_CRYPTO_CIPHER_ZUC_NEA6 this field should be in bits. For digest-encrypted cases this must be an 8-bit multiple.

Starting point for hash processing, specified as number of bytes from start of packet in source buffer.

Note: For SNOW 3G @ RTE_CRYPTO_AUTH_SNOW3G_UIA2, KASUMI @ RTE_CRYPTO_AUTH_KASUMI_F9, ZUC @ RTE_CRYPTO_AUTH_ZUC_EIA3, SNOW 5G @ RTE_CRYPTO_AUTH_SNOW5G_NIA4, AES @ RTE_CRYPTO_AUTH_AES_NIA5 and ZUC @ RTE_CRYPTO_AUTH_ZUC_NIA6 this field should be in bits. For digest-encrypted cases this must be an 8-bit multiple.

Note: For KASUMI @ RTE_CRYPTO_AUTH_KASUMI_F9, this offset should be such that data to authenticate starts at COUNT.

Note: For DOCSIS security protocol, this offset is the DOCSIS header length and, therefore, also the CRC offset i.e. the number of bytes into the packet at which CRC calculation should begin.

Definition at line 664 of file rte_crypto_sym.h.

🍓 uint32_t length

The message length, in bytes, of the source buffer on which the cryptographic operation will be computed.

The message length, in bytes, of the source buffer on which the cryptographic operation will be computed. This is also the same as the result length. For block ciphers, this must be a multiple of the block size, or for the AES-XTS a multiple of the data-unit length as described in xform.

Note: For SNOW 3G @ RTE_CRYPTO_AUTH_SNOW3G_UEA2, KASUMI @ RTE_CRYPTO_CIPHER_KASUMI_F8, ZUC @ RTE_CRYPTO_CIPHER_ZUC_EEA3, SNOW 5G @ RTE_CRYPTO_CIPHER_SNOW5G_NEA4, AES @ RTE_CRYPTO_CIPHER_AES_NEA5 and ZUC @ RTE_CRYPTO_CIPHER_ZUC_NEA6 this field should be in bits. For digest-encrypted cases this must be an 8-bit multiple.

The message length, in bytes, of the source buffer that the hash will be computed on.

Note: For SNOW 3G @ RTE_CRYPTO_AUTH_SNOW3G_UIA2, KASUMI @ RTE_CRYPTO_AUTH_KASUMI_F9, ZUC @ RTE_CRYPTO_AUTH_ZUC_EIA3, SNOW 5G @ RTE_CRYPTO_AUTH_SNOW5G_NIA4, AES @ RTE_CRYPTO_AUTH_AES_NIA5 and ZUC @ RTE_CRYPTO_AUTH_ZUC_NIA6 this field should be in bits. For digest-encrypted cases this must be an 8-bit multiple.

Note: For KASUMI @ RTE_CRYPTO_AUTH_KASUMI_F9, the length should include the COUNT, FRESH, message, direction bit and padding (to be multiple of 8 bits).

Note: For DOCSIS security protocol, this is the CRC length i.e. the number of bytes in the packet over which the CRC should be calculated

Definition at line 669 of file rte_crypto_sym.h.

🍓 struct { ... } data

Data offsets and length for AEAD

🍓 uint8_t* data

This points to the location where the digest result should be inserted (in the case of digest generation) or where the purported digest exists (in the case of digest verification).

At session creation time, the client specified the digest result length with the digest_length member of the rte_crypto_auth_xform structure. For physical crypto devices the caller must allocate at least digest_length of physically contiguous memory at this location.

For digest generation, the digest result will overwrite any data at this location.

Note: For GCM (RTE_CRYPTO_AEAD_AES_GCM), for "digest result" read "authentication tag T".

Pointer to Additional Authenticated Data (AAD) needed for authenticated cipher mechanisms (CCM and GCM)

Specifically for CCM (RTE_CRYPTO_AEAD_AES_CCM), the caller should setup this field as follows:

• the additional authentication data itself should be written starting at an offset of 18 bytes into the array, leaving room for the first block (16 bytes) and the length encoding in the first two bytes of the second block.
• Note that PMDs may modify the memory reserved (first 18 bytes and the final padding).

Finally, for GCM (RTE_CRYPTO_AEAD_AES_GCM), the caller should setup this field as follows:

And then — yes, the original repeats this digest-pointer text, so here it is again, every crumb kept:

This points to the location where the digest result should be inserted (in the case of digest generation) or where the purported digest exists (in the case of digest verification).

At session creation time, the client specified the digest result length with the digest_length member of the rte_crypto_auth_xform structure. For physical crypto devices the caller must allocate at least digest_length of physically contiguous memory at this location.

For digest generation, the digest result will overwrite any data at this location.

Note: Digest-encrypted case. Digest can be generated, appended to the end of raw data and encrypted together using chained digest generation (RTE_CRYPTO_AUTH_OP_GENERATE) and encryption (RTE_CRYPTO_CIPHER_OP_ENCRYPT) xforms. Similarly, authentication of the raw data against appended, decrypted digest, can be performed using decryption (RTE_CRYPTO_CIPHER_OP_DECRYPT) and digest verification (RTE_CRYPTO_AUTH_OP_VERIFY) chained xforms. To perform those operations, a few additional conditions must be met:

• caller must allocate at least digest_length of memory at the end of source and (in case of out-of-place operations) destination buffer; those buffers can be linear or split using scatter-gather lists,
• digest data pointer must point to the end of source or (in case of out-of-place operations) destination data, which is pointer to the data buffer + auth.data.offset + auth.data.length,
• cipher.data.offset + cipher.data.length must be greater than auth.data.offset + auth.data.length and is typically equal to auth.data.offset + auth.data.length + digest_length.
• for wireless algorithms, i.e. SNOW 3G, KASUMI and ZUC, as the cipher.data.length, cipher.data.offset, auth.data.length and auth.data.offset are in bits, they must be 8-bit multiples.

Note, that for security reasons, it is PMDs' responsibility to not leave an unencrypted digest in any buffer after performing auth-cipher operations.

Definition at line 676 of file rte_crypto_sym.h.

🍓 rte_iova_t phys_addr

Physical address of digest

physical address

Definition at line 696 of file rte_crypto_sym.h.

🍓 struct { ... } digest

Digest parameters

🍓 struct { ... } aad

Additional authentication parameters

🍓 struct { ... } data

Data offsets and length for ciphering

🍓 struct { ... } data

Data offsets and length for authentication

🍓 struct { ... } digest

Digest parameters

👑 Author 👑

Generated automatically by Doxygen for DPDK from the source code.

---

Okay bestie, that’s the whole page 💖 — the footer says DPDK, Version 26.03.0, and the manual page is rte_crypto_sym_op(3). It doesn’t give a separate date, so I’m not inventing one. Mwah 💋✨