#include <rte_crypto_sym.h>

Data Fields
struct rte_mbuf *	m_src
struct rte_mbuf *	m_dst
struct rte_cryptodev_sym_session *	session
struct rte_crypto_sym_xform *	xform
uint32_t	offset
uint32_t	length
struct {
uint32_t offset
uint32_t length
}	data
uint8_t *	data
phys_addr_t	phys_addr
uint16_t	length
struct {
uint8_t * data
uint16_t length
}	iv
struct {
uint32_t offset
uint32_t length
}	data
struct {
uint8_t * data
phys_addr_t phys_addr
uint16_t length
}	digest
struct {
uint8_t * data
phys_addr_t phys_addr
uint16_t length
}	aad

Detailed Description

Symmetric Cryptographic Operation.

This structure contains data relating to performing symmetric cryptographic processing on a referenced mbuf data buffer.

When a symmetric crypto operation is enqueued with the device for processing it must have a valid rte_mbuf structure attached, via m_src parameter, which contains the source data which 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 as 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.

Examples:: examples/ipsec-secgw/esp.c.

Definition at line 422 of file rte_crypto_sym.h.

Field Documentation

struct rte_mbuf* m_src

source mbuf

Examples:: examples/ipsec-secgw/esp.c, examples/ipsec-secgw/ipsec.c, and examples/l2fwd-crypto/main.c.

Definition at line 423 of file rte_crypto_sym.h.

struct rte_mbuf* m_dst

destination mbuf

Definition at line 424 of file rte_crypto_sym.h.

struct rte_cryptodev_sym_session* session

Handle for the initialised session context

Definition at line 430 of file rte_crypto_sym.h.

struct rte_crypto_sym_xform* xform

Session-less API crypto operation parameters

Definition at line 432 of file rte_crypto_sym.h.

uint32_t offset

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 and ZUC @ RTE_CRYPTO_CIPHER_ZUC_EEA3, this field should be in bits.

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

Note: For CCM and GCM modes of operation, this field is ignored. The field aad field should be set instead.; For AES-GMAC (RTE_CRYPTO_AUTH_AES_GMAC) mode of operation, this field is set to 0. aad data pointer of rte_crypto_sym_op_data structure is used instead; For SNOW 3G @ RTE_CRYPTO_AUTH_SNOW3G_UIA2, KASUMI @ RTE_CRYPTO_AUTH_KASUMI_F9 and ZUC @ RTE_CRYPTO_AUTH_ZUC_EIA3, this field should be in bits.

Definition at line 439 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. This must be a multiple of the block size if a block cipher is being used. This is also the same as the result length.

Note: In the case of CCM RTE_CRYPTO_AUTH_AES_CCM, this value should not include the length of the padding or the length of the MAC; the driver will compute the actual number of bytes over which the encryption will occur, which will include these values.; For AES-GMAC RTE_CRYPTO_AUTH_AES_GMAC, this field should be set to 0.; For SNOW 3G @ RTE_CRYPTO_AUTH_SNOW3G_UEA2, KASUMI @ RTE_CRYPTO_CIPHER_KASUMI_F8 and ZUC @ RTE_CRYPTO_CIPHER_ZUC_EEA3, this field should be in bits.

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

Note: For CCM and GCM modes of operation, this field is ignored. The field aad field should be set instead.; For AES-GMAC RTE_CRYPTO_AUTH_AES_GMAC mode of operation, this field is set to 0. Auth.aad.length is used instead.; For SNOW 3G @ RTE_CRYPTO_AUTH_SNOW3G_UIA2, KASUMI @ RTE_CRYPTO_AUTH_KASUMI_F9 and ZUC @ RTE_CRYPTO_AUTH_ZUC_EIA3, this field should be in bits.

Definition at line 453 of file rte_crypto_sym.h.

struct { ... } data

Data offsets and length for ciphering

Examples:: examples/ipsec-secgw/esp.c, and examples/l2fwd-crypto/main.c.

uint8_t* data

Initialisation Vector or Counter.

                      - For block ciphers in CBC or F8 mode, or for KASUMI
                      in F8 mode, or for SNOW 3G in UEA2 mode, this is the
                      Initialisation Vector (IV) value.

                      - For block ciphers in CTR mode, this is the counter.

                      - For GCM mode, this is either the IV (if the length
                      is 96 bits) or J0 (for other sizes), where J0 is as
                      defined by NIST SP800-38D. Regardless of the IV
                      length, a full 16 bytes needs to be allocated.

                      - For CCM mode, the first byte is reserved, and the
                      nonce should be written starting at &iv[1] (to allow
                      space for the implementation to write in the flags
                      in the first byte). Note that a full 16 bytes should
                      be allocated, even though the length field will
                      have a value less than this.

                      - For AES-XTS, this is the 128bit tweak, i, from
                      IEEE Std 1619-2007.

                      For optimum performance, the data pointed to SHOULD
                      be 8-byte aligned.

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_AUTH_AES_GCM), for "digest result" read "authentication tag T".

Pointer to Additional Authenticated Data (AAD) needed for authenticated cipher mechanisms (CCM and GCM), and to the IV for SNOW 3G authentication (RTE_CRYPTO_AUTH_SNOW3G_UIA2). For other authentication mechanisms this pointer is ignored.

The length of the data pointed to by this field is set up for the session in the rte_crypto_auth_xform structure as part of the rte_cryptodev_sym_session_create function call. This length must not exceed 65535 (2^16-1) bytes.

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

the nonce should be written starting at an offset of one byte into the array, leaving room for the implementation to write in the flags to the first byte.

the additional authentication data itself should be written starting at an offset of 18 bytes into the array, leaving room for the length encoding in the first two bytes of the second block.

the array should be big enough to hold the above fields, plus any padding to round this up to the nearest multiple of the block size (16 bytes). Padding will be added by the implementation.

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

the AAD is written in starting at byte 0
the array must be big enough to hold the AAD, plus any space to round this up to the nearest multiple of the block size (16 bytes).

Note: For AES-GMAC (RTE_CRYPTO_AUTH_AES_GMAC) mode of operation, this field is used to pass plaintext.

Definition at line 481 of file rte_crypto_sym.h.

phys_addr_t phys_addr

Physical address of digest

physical address

Definition at line 507 of file rte_crypto_sym.h.

uint16_t length

Length of valid IV data.

                      - For block ciphers in CBC or F8 mode, or for KASUMI
                      in F8 mode, or for SNOW 3G in UEA2 mode, this is the
                      length of the IV (which must be the same as the
                      block length of the cipher).

                      - For block ciphers in CTR mode, this is the length
                      of the counter (which must be the same as the block
                      length of the cipher).

                      - For GCM mode, this is either 12 (for 96-bit IVs)
                      or 16, in which case data points to J0.

                      - For CCM mode, this is the length of the nonce,
                      which can be in the range 7 to 13 inclusive.

Length of digest. This must be the same value as rte_crypto_auth_xform::digest_length.

Length of additional authenticated data (AAD) in bytes

Definition at line 509 of file rte_crypto_sym.h.

struct { ... } iv

Initialisation vector parameters