API Description

Data ciphering and authentication.

Data Structures
union	odp_crypto_cipher_algos_t
	Cipher algorithms in a bit field structure. More...

union	odp_crypto_auth_algos_t
	Authentication algorithms in a bit field structure. More...

struct	odp_crypto_key
	Crypto API key structure. More...

struct	odp_crypto_session_param_t
	Crypto API session creation parameters. More...

struct	odp_crypto_packet_op_param_t
	Crypto packet API per packet operation parameters. More...

struct	odp_crypto_op_status
	Crypto API per packet operation completion status. More...

struct	odp_crypto_packet_result_t
	Crypto packet API operation result. More...

struct	odp_crypto_capability_t
	Crypto capabilities. More...

struct	odp_crypto_cipher_capability_t
	Cipher algorithm capabilities. More...

struct	odp_crypto_auth_capability_t
	Authentication algorithm capabilities. More...

Macros
#define	ODP_CRYPTO_SESSION_INVALID (0xffffffffffffffffULL)
	Invalid session handle.

Typedefs
typedef uint64_t	odp_crypto_session_t
	Crypto API opaque session handle.

typedef union odp_crypto_cipher_algos_t	odp_crypto_cipher_algos_t
	Cipher algorithms in a bit field structure.

typedef union odp_crypto_auth_algos_t	odp_crypto_auth_algos_t
	Authentication algorithms in a bit field structure.

typedef struct odp_crypto_key	odp_crypto_key_t
	Crypto API key structure.

typedef enum odp_crypto_op_type_t	odp_crypto_op_type_t
	Type of odp_crypto_op()/odp_crypto_op_enq() calls.

typedef struct odp_crypto_session_param_t	odp_crypto_session_param_t
	Crypto API session creation parameters.

typedef struct odp_crypto_packet_op_param_t	odp_crypto_packet_op_param_t
	Crypto packet API per packet operation parameters.

typedef struct odp_crypto_op_status	odp_crypto_op_status_t
	Crypto API per packet operation completion status.

typedef struct odp_crypto_packet_result_t	odp_crypto_packet_result_t
	Crypto packet API operation result.

typedef struct odp_crypto_capability_t	odp_crypto_capability_t
	Crypto capabilities.

typedef struct odp_crypto_cipher_capability_t	odp_crypto_cipher_capability_t
	Cipher algorithm capabilities.

typedef struct odp_crypto_auth_capability_t	odp_crypto_auth_capability_t
	Authentication algorithm capabilities.

Enumerations
enum	odp_crypto_op_mode_t { ODP_CRYPTO_SYNC , ODP_CRYPTO_ASYNC }
	Crypto API operation mode. More...

enum	odp_crypto_op_t { ODP_CRYPTO_OP_ENCODE , ODP_CRYPTO_OP_DECODE }
	Crypto API operation. More...

enum	odp_cipher_alg_t { ODP_CIPHER_ALG_NULL , ODP_CIPHER_ALG_DES , ODP_CIPHER_ALG_3DES_CBC , ODP_CIPHER_ALG_3DES_ECB , ODP_CIPHER_ALG_AES_CBC , ODP_CIPHER_ALG_AES_CTR , ODP_CIPHER_ALG_AES_ECB , ODP_CIPHER_ALG_AES_CFB128 , ODP_CIPHER_ALG_AES_XTS , ODP_CIPHER_ALG_AES_GCM , ODP_CIPHER_ALG_AES_CCM , ODP_CIPHER_ALG_CHACHA20_POLY1305 , ODP_CIPHER_ALG_KASUMI_F8 , ODP_CIPHER_ALG_SNOW3G_UEA2 , ODP_CIPHER_ALG_AES_EEA2 , ODP_CIPHER_ALG_ZUC_EEA3 , ODP_CIPHER_ALG_SNOW_V , ODP_CIPHER_ALG_SNOW_V_GCM , ODP_CIPHER_ALG_SM4_ECB , ODP_CIPHER_ALG_SM4_CBC , ODP_CIPHER_ALG_SM4_CTR , ODP_CIPHER_ALG_SM4_GCM , ODP_CIPHER_ALG_SM4_CCM }
	Crypto API cipher algorithm. More...

enum	odp_auth_alg_t { ODP_AUTH_ALG_NULL , ODP_AUTH_ALG_MD5_HMAC , ODP_AUTH_ALG_SHA1_HMAC , ODP_AUTH_ALG_SHA224_HMAC , ODP_AUTH_ALG_SHA256_HMAC , ODP_AUTH_ALG_SHA384_HMAC , ODP_AUTH_ALG_SHA512_HMAC , ODP_AUTH_ALG_SHA3_224_HMAC , ODP_AUTH_ALG_SHA3_256_HMAC , ODP_AUTH_ALG_SHA3_384_HMAC , ODP_AUTH_ALG_SHA3_512_HMAC , ODP_AUTH_ALG_AES_GCM , ODP_AUTH_ALG_AES_GMAC , ODP_AUTH_ALG_AES_CCM , ODP_AUTH_ALG_AES_CMAC , ODP_AUTH_ALG_AES_XCBC_MAC , ODP_AUTH_ALG_CHACHA20_POLY1305 , ODP_AUTH_ALG_KASUMI_F9 , ODP_AUTH_ALG_SNOW3G_UIA2 , ODP_AUTH_ALG_AES_EIA2 , ODP_AUTH_ALG_ZUC_EIA3 , ODP_AUTH_ALG_SNOW_V_GCM , ODP_AUTH_ALG_SNOW_V_GMAC , ODP_AUTH_ALG_SM3_HMAC , ODP_AUTH_ALG_SM4_GCM , ODP_AUTH_ALG_SM4_GMAC , ODP_AUTH_ALG_SM4_CCM , ODP_AUTH_ALG_MD5 , ODP_AUTH_ALG_SHA1 , ODP_AUTH_ALG_SHA224 , ODP_AUTH_ALG_SHA256 , ODP_AUTH_ALG_SHA384 , ODP_AUTH_ALG_SHA512 , ODP_AUTH_ALG_SHA3_224 , ODP_AUTH_ALG_SHA3_256 , ODP_AUTH_ALG_SHA3_384 , ODP_AUTH_ALG_SHA3_512 , ODP_AUTH_ALG_SM3 }
	Crypto API authentication algorithm. More...

enum	odp_crypto_op_type_t { ODP_CRYPTO_OP_TYPE_LEGACY , ODP_CRYPTO_OP_TYPE_BASIC , ODP_CRYPTO_OP_TYPE_OOP , ODP_CRYPTO_OP_TYPE_BASIC_AND_OOP }
	Type of odp_crypto_op()/odp_crypto_op_enq() calls. More...

enum	odp_crypto_ses_create_err_t { ODP_CRYPTO_SES_ERR_NONE , ODP_CRYPTO_SES_ERR_ENOMEM , ODP_CRYPTO_SES_ERR_CIPHER , ODP_CRYPTO_SES_ERR_AUTH , ODP_CRYPTO_SES_ERR_ALG_COMBO , ODP_CRYPTO_SES_ERR_ALG_ORDER , ODP_CRYPTO_SES_ERR_PARAMS }
	Crypto API session creation return code. More...

enum	odp_crypto_alg_err_t { ODP_CRYPTO_ALG_ERR_NONE , ODP_CRYPTO_ALG_ERR_DATA_SIZE , ODP_CRYPTO_ALG_ERR_ICV_CHECK , ODP_CRYPTO_ALG_ERR_OTHER }
	Crypto API algorithm return code. More...

Functions
int	odp_crypto_capability (odp_crypto_capability_t *capa)
	Query crypto capabilities. More...

int	odp_crypto_cipher_capability (odp_cipher_alg_t cipher, odp_crypto_cipher_capability_t capa[], int num)
	Query supported cipher algorithm capabilities. More...

int	odp_crypto_auth_capability (odp_auth_alg_t auth, odp_crypto_auth_capability_t capa[], int num)
	Query supported authentication algorithm capabilities. More...

int	odp_crypto_session_create (const odp_crypto_session_param_t param, odp_crypto_session_t session, odp_crypto_ses_create_err_t *status)
	Crypto session creation. More...

int	odp_crypto_session_destroy (odp_crypto_session_t session)
	Crypto session destroy. More...

uint64_t	odp_crypto_session_to_u64 (odp_crypto_session_t hdl)
	Get printable value for an odp_crypto_session_t. More...

void	odp_crypto_session_param_init (odp_crypto_session_param_t *param)
	Initialize crypto session parameters. More...

odp_packet_t	odp_crypto_packet_from_event (odp_event_t ev)
	Return crypto processed packet that is associated with event. More...

odp_event_t	odp_crypto_packet_to_event (odp_packet_t pkt)
	Convert crypto packet handle to event. More...

int	odp_crypto_result (odp_crypto_packet_result_t *result, odp_packet_t packet)
	Get crypto operation results from a crypto processed packet. More...

int	odp_crypto_op (const odp_packet_t pkt_in[], odp_packet_t pkt_out[], const odp_crypto_packet_op_param_t param[], int num_pkt)
	Crypto packet operation. More...

int	odp_crypto_op_enq (const odp_packet_t pkt_in[], const odp_packet_t pkt_out[], const odp_crypto_packet_op_param_t param[], int num_pkt)
	Crypto packet operation. More...

Enumeration Type Documentation

◆ odp_crypto_op_mode_t

enum odp_crypto_op_mode_t

Crypto API operation mode.

Enumerator
ODP_CRYPTO_SYNC	Synchronous, return results immediately.
ODP_CRYPTO_ASYNC	Asynchronous, return results via posted event.

Definition at line 40 of file api/spec/crypto_types.h.

◆ odp_crypto_op_t

enum odp_crypto_op_t

Crypto API operation.

Enumerator
ODP_CRYPTO_OP_ENCODE	Encrypt and/or compute authentication ICV.
ODP_CRYPTO_OP_DECODE	Decrypt and/or verify authentication ICV.

Definition at line 50 of file api/spec/crypto_types.h.

◆ odp_cipher_alg_t

enum odp_cipher_alg_t

Crypto API cipher algorithm.

Enumerator
ODP_CIPHER_ALG_NULL	No cipher algorithm specified.
ODP_CIPHER_ALG_DES	DES.
ODP_CIPHER_ALG_3DES_CBC	Triple DES with cipher block chaining.
ODP_CIPHER_ALG_3DES_ECB	Triple DES with Electronic Codebook.
ODP_CIPHER_ALG_AES_CBC	AES with cipher block chaining.
ODP_CIPHER_ALG_AES_CTR	AES with counter mode.
ODP_CIPHER_ALG_AES_ECB	AES with electronic codebook.
ODP_CIPHER_ALG_AES_CFB128	AES with 128-bit cipher feedback.
ODP_CIPHER_ALG_AES_XTS	AES with XEX-based tweaked-codebook mode with ciphertext stealing (XTS)
ODP_CIPHER_ALG_AES_GCM	AES-GCM. AES in Galois/Counter Mode (GCM) algorithm. GCM provides both authentication and ciphering of data (authenticated encryption) in the same operation. Hence this algorithm must be paired always with ODP_AUTH_ALG_AES_GCM authentication.
ODP_CIPHER_ALG_AES_CCM	AES-CCM. AES in Counter with CBC-MAC (CCM) mode algorithm. CCM provides both authentication and ciphering of data (authenticated encryption) in the same operation. Hence this algorithm must be paired always with ODP_AUTH_ALG_AES_CCM authentication.
ODP_CIPHER_ALG_CHACHA20_POLY1305	ChaCha20-Poly1305. ChaCha20 with Poly1305 provide both authentication and ciphering of data (authenticated encryption) in the same operation. Hence this algorithm must be paired always with ODP_AUTH_ALG_CHACHA20_POLY1305 authentication.
ODP_CIPHER_ALG_KASUMI_F8	Confidentiality F8 algorithm (UEA1) KASUMI-based F8 algorithm (also known as UEA1). IV should be formatted according to the 3GPP TS 35.201: COUNT \|\| BEARER \|\| DIRECTION \|\| 0...0
ODP_CIPHER_ALG_SNOW3G_UEA2	Confidentiality UEA2 algorithm (128-EEA1) SNOW 3G-based UEA2 algorithm (also known as 128-EEA1). IV (128 bits) should be formatted according to the ETSI/SAGE UEA2 & UIA2 specification: COUNT \|\| BEARER \|\| DIRECTION \|\| 0...0 \|\| COUNT \|\| BEARER \|\| DIRECTION \|\| 0...0 \|\|
ODP_CIPHER_ALG_AES_EEA2	Confidentiality 128-EEA2 algorithm. AES-CTR-based 128-EEA2 algorithm. IV (128 bits) should be formatted according to the ETSI/SAGE 128-EAA2 & 128-EIA2 specification: COUNT \|\| BEARER \|\| DIRECTION \|\| 0....0
ODP_CIPHER_ALG_ZUC_EEA3	ZUC based confidentiality algorithm. 128-EEA3/128-NEA3 algorithm when key length is 128 bits. IV (128 bits) should be formatted according to the ETSI/SAGE 128-EEA3 & 128-EIA3 specification: COUNT \|\| BEARER \|\| DIRECTION \|\| 0...0 \|\| COUNT \|\| BEARER \|\| DIRECTION \|\| 0...0 \|\| 256-bit key length support is experimental and subject to change. The following variants may be supported: - ZUC-256 with 25 byte IV (of which 184 bits are variable) as specified in "The ZUC-256 Stream Cipher". - ZUC-256 with 16 byte IV as specified in "An Addendum to the ZUC-256 Stream Cipher", https://eprint.iacr.org/2021/1439
ODP_CIPHER_ALG_SNOW_V	SNOW-V stream cipher.
ODP_CIPHER_ALG_SNOW_V_GCM	SNOW-V-GCM AEAD algorithm. SNOW-V-GCM provides both authentication and encryption. This cipher algorithm must always be paired with ODP_AUTH_ALG_SNOW_V_GCM auth algorithm in crypto session creation.
ODP_CIPHER_ALG_SM4_ECB	SM4 block cipher in ECB mode.
ODP_CIPHER_ALG_SM4_CBC	SM4 block cipher in CBC mode.
ODP_CIPHER_ALG_SM4_CTR	SM4 block cipher in CTR mode.
ODP_CIPHER_ALG_SM4_GCM	SM4-GCM AEAD algorithm. SM4-GCM provides both authentication and encryption. This cipher algorithm must always be paired with ODP_AUTH_ALG_SM4_GCM auth algorithm in crypto session creation.
ODP_CIPHER_ALG_SM4_CCM	SM4-CCM AEAD algorithm. SM4-CCM provides both authentication and encryption. This cipher algorithm must always be paired with ODP_AUTH_ALG_SM4_CCM auth algorithm in crypto session creation.

Definition at line 60 of file api/spec/crypto_types.h.

◆ odp_auth_alg_t

enum odp_auth_alg_t

Crypto API authentication algorithm.

Enumerator
ODP_AUTH_ALG_NULL	No authentication algorithm specified.
ODP_AUTH_ALG_MD5_HMAC	HMAC-MD5. MD5 algorithm in HMAC mode
ODP_AUTH_ALG_SHA1_HMAC	HMAC-SHA-1. SHA-1 algorithm in HMAC mode
ODP_AUTH_ALG_SHA224_HMAC	HMAC-SHA-224. SHA-224 algorithm in HMAC mode
ODP_AUTH_ALG_SHA256_HMAC	HMAC-SHA-256. SHA-256 algorithm in HMAC mode
ODP_AUTH_ALG_SHA384_HMAC	HMAC-SHA-384. SHA-384 algorithm in HMAC mode
ODP_AUTH_ALG_SHA512_HMAC	HMAC-SHA-512. SHA-512 algorithm in HMAC mode
ODP_AUTH_ALG_SHA3_224_HMAC	HMAC using SHA3-224.
ODP_AUTH_ALG_SHA3_256_HMAC	HMAC using SHA3-256.
ODP_AUTH_ALG_SHA3_384_HMAC	HMAC using SHA3-384.
ODP_AUTH_ALG_SHA3_512_HMAC	HMAC using SHA3-512.
ODP_AUTH_ALG_AES_GCM	AES-GCM. AES in Galois/Counter Mode (GCM) algorithm. GCM provides both authentication and ciphering of data (authenticated encryption) in the same operation. Hence this algorithm must be paired always with ODP_CIPHER_ALG_AES_GCM cipher.
ODP_AUTH_ALG_AES_GMAC	AES-GMAC. AES Galois Message Authentication Code (GMAC) algorithm. AES-GMAC is based on AES-GCM operation, but provides authentication only. Hence this algorithm can be paired only with ODP_CIPHER_ALG_NULL cipher. NIST and RFC specifications of GMAC refer to all data to be authenticated as AAD. In ODP the data to be authenticated, i.e. AAD, is ODP packet data and specified using the auth_range parameter. The aad_length and aad_ptr parameters, which would require the data to be contiguous in memory, are ignored with AES-GMAC. GMAC needs an initialization vector, which must be passed via operation parameters (auth_iv_ptr).
ODP_AUTH_ALG_AES_CCM	AES-CCM. AES in Counter with CBC-MAC (CCM) mode algorithm. CCM provides both authentication and ciphering of data (authenticated encryption) in the same operation. Hence this algorithm must be paired always with ODP_CIPHER_ALG_AES_CCM cipher.
ODP_AUTH_ALG_AES_CMAC	AES-CMAC. AES Cipher-based Message Authentication Code (CMAC) algorithm. CMAC is a keyed hash function that is based on a symmetric key block cipher, such as the AES.
ODP_AUTH_ALG_AES_XCBC_MAC	AES-XCBC-MAC. AES CBC MAC for arbitrary-length messages (XCBC-MAC).
ODP_AUTH_ALG_CHACHA20_POLY1305	ChaCha20-Poly1305 AEAD. ChaCha20 with Poly1305 provide both authentication and ciphering of data (authenticated encryption) in the same operation. Hence this algorithm must be paired always with ODP_CIPHER_ALG_CHACHA20_POLY1305 cipher.
ODP_AUTH_ALG_KASUMI_F9	Integrity F9 algorithm (UIA1) KASUMI-based F9 algorithm (also known as UIA1). IV (9 bytes) is a concatenation of COUNT (32b), FRESH (32b) and DIRECTION (LSB-aligned, 1b). IV (8 bytes) is a concatenation of COUNT (32b) and FRESH (32b) DIRECTION (1b) and padding should come at the end of message.
ODP_AUTH_ALG_SNOW3G_UIA2	Integrity UIA2 algorithm (128-EIA1) SNOW 3G-based UIA2 algorithm (also known as 128-EIA1). IV (128 bits) should be formatted according to the ETSI/SAGE UEA2 & UIA2 specification: COUNT \|\| FRESH \|\| DIRECTION XOR COUNT0 \|\| COUNT1 .. COUNT31 \|\| FRESH0 .. FRESH15 \|\| FRESH16 XOR DIRECTION \|\| FRESH17 .. FRESH31
ODP_AUTH_ALG_AES_EIA2	Integrity 128-EIA2 algorithm. AES_CMAC-based 128-EIA2 algorithm. IV (64 bits) should be formatted according to the ETSI/SAGE 128-EEA2 & 128-EIA2 specification: COUNT \|\| BEARER \|\| DIRECTION \|\| 0....0
ODP_AUTH_ALG_ZUC_EIA3	ZUC-based integrity algorithm. 128-EIA3/128-NIA3 algorithm when key length is 128 bits. IV (128 bits) should be formatted according to the ETSI/SAGE 128-EEA3 & 128-EIA2 specification: COUNT \|\| BEARER \|\| DIRECTION XOR COUNT0 \|\| COUNT1 .. COUNT31 \|\| BEARER \|\| 0...0 \|\| DIRECTION \|\| 0...0 256-bit key length support is experimental and subject to change. The following variants may be supported: - ZUC-256 with 25 byte IV (of which 184 bits are variable) and 32/64/128 bit MAC as specified in "The ZUC-256 Stream Cipher". - ZUC-256 with 16 byte IV and 32/64/128 bit MAC as specified in "An Addendum to the ZUC-256 Stream Cipher", https://eprint.iacr.org/2021/1439
ODP_AUTH_ALG_SNOW_V_GCM	SNOW-V-GCM AEAD algorithm. SNOW-V-GCM provides both authentication and encryption. This auth algorithm must always be paired with ODP_CIPHER_ALG_SNOW_V_GCM cipher algorithm in crypto session creation.
ODP_AUTH_ALG_SNOW_V_GMAC	SNOW-V-GMAC. SNOW-V-GMAC is similar to SNOW-V-GCM without any ciphered data. This algorithm can be paired only with ODP_CIPHER_ALG_NULL. Unlike with SNOW-V-GCM, authenticated data is not provided as AAD in ODP but as packet data indicated by the auth_range. The auth_aad_len session parameter and the aad_ptr operation parameter are ignored. GMAC needs an initialization vector, which must be passed via operation parameters (auth_iv_ptr).
ODP_AUTH_ALG_SM3_HMAC	HMAC using SM3.
ODP_AUTH_ALG_SM4_GCM	SM4-GCM AEAD algorithm. SM4-GCM provides both authentication and encryption. This auth algorithm must always be paired with ODP_CIPHER_ALG_SM4_GCM cipher algorithm in crypto session creation.
ODP_AUTH_ALG_SM4_GMAC	SM4-GMAC. SM4-GMAC is similar to SM4-GCM without any ciphered data. This algorithm can be paired only with ODP_CIPHER_ALG_NULL. Unlike with SM4-GCM, authenticated data is not provided as AAD in ODP but as packet data indicated by the auth_range. The auth_aad_len session parameter and the aad_ptr operation parameter are ignored. GMAC needs an initialization vector, which must be passed via operation parameters (auth_iv_ptr).
ODP_AUTH_ALG_SM4_CCM	SM4-CCM AEAD algorithm. SM4-CCM provides both authentication and encryption. This auth algorithm must always be paired with ODP_CIPHER_ALG_SM4_CCM cipher algorithm in crypto session creation.
ODP_AUTH_ALG_MD5	MD5 algorithm.
ODP_AUTH_ALG_SHA1	SHA1 algorithm.
ODP_AUTH_ALG_SHA224	224 bit SHA2 algorithm
ODP_AUTH_ALG_SHA256	256 bit SHA2 algorithm
ODP_AUTH_ALG_SHA384	384 bit SHA2 algorithm
ODP_AUTH_ALG_SHA512	512 bit SHA2 algorithm
ODP_AUTH_ALG_SHA3_224	SHA-3 hash function producing 224-bit digests.
ODP_AUTH_ALG_SHA3_256	SHA-3 hash function producing 256-bit digests.
ODP_AUTH_ALG_SHA3_384	SHA-3 hash function producing 384-bit digests.
ODP_AUTH_ALG_SHA3_512	SHA-3 hash function producing 512-bit digests.
ODP_AUTH_ALG_SM3	SM3 hash function.

Definition at line 207 of file api/spec/crypto_types.h.

◆ odp_crypto_op_type_t

enum odp_crypto_op_type_t

Type of odp_crypto_op()/odp_crypto_op_enq() calls.

Enumerator
ODP_CRYPTO_OP_TYPE_LEGACY	Input packet data and metadata are copied to the output packet and then processed. Output packet is allocated by the caller or by ODP. This is the default value but will be deprecated in the future.
ODP_CRYPTO_OP_TYPE_BASIC	Input packet data and metadata are copied to the output packet and then processed. Output packet is allocated by ODP.
ODP_CRYPTO_OP_TYPE_OOP	Out-of-place crypto operation. Output packet is provided by the caller and the input packet is not consumed nor modified. Output of the crypto operation is written in the caller provided output packet without affecting other data and metadata of the output packet. Memory layout of the output packet may change during the operation. Crypto output is the processed crypto_range, auth_range and MAC/digest (in encode sessions) of the input packet.
ODP_CRYPTO_OP_TYPE_BASIC_AND_OOP	Basic or out-of-place crypto operation depending on op params. If the output packet specified in a crypto operation (i.e. pkt_out[i] is ODP_PACKET_INVALID) then the packet is processed the same way as in the ODP_CRYPTO_OP_TYPE_BASIC operation type. Otherwise the packet is processed as in the ODP_CRYPTO_OP_TYPE_OOP operation type. Sessions of this operation type may have lower performance than the more specific operation types.

Definition at line 693 of file api/spec/crypto_types.h.

◆ odp_crypto_ses_create_err_t

enum odp_crypto_ses_create_err_t

Crypto API session creation return code.

Enumerator
ODP_CRYPTO_SES_ERR_NONE	Session created.
ODP_CRYPTO_SES_ERR_ENOMEM	Creation failed, no resources.
ODP_CRYPTO_SES_ERR_CIPHER	Creation failed, bad cipher params.
ODP_CRYPTO_SES_ERR_AUTH	Creation failed, bad auth params.
ODP_CRYPTO_SES_ERR_ALG_COMBO	Unsupported combination of algorithms. The combination of cipher and auth algorithms with their specific parameters is not supported even if the algorithms appear in capabilities and are supported in combination with other algorithms or other algorithm specific parameters.
ODP_CRYPTO_SES_ERR_ALG_ORDER	Unsupported order of cipher and auth. The requested mutual order of ciphering and authentication is not supported with the chosen individual cipher and authentication algorithms.
ODP_CRYPTO_SES_ERR_PARAMS	Unsupported combination of session creation parameters. The combination of provided session creation parameters is not supported. This error can occur when there are limitations that are not expressible through crypto capabilities or other error status values.

Definition at line 1030 of file api/spec/crypto_types.h.

◆ odp_crypto_alg_err_t

enum odp_crypto_alg_err_t

Crypto API algorithm return code.

Enumerator
ODP_CRYPTO_ALG_ERR_NONE	Algorithm successful.
ODP_CRYPTO_ALG_ERR_DATA_SIZE	Invalid range or packet size.
ODP_CRYPTO_ALG_ERR_ICV_CHECK	Computed ICV value mismatch.
ODP_CRYPTO_ALG_ERR_OTHER	Other error.

Definition at line 1070 of file api/spec/crypto_types.h.

Function Documentation

◆ odp_crypto_capability()

int odp_crypto_capability ( odp_crypto_capability_t * capa )

Query crypto capabilities.

Outputs crypto capabilities on success.

Parameters

[out] capa Pointer to capability structure for output

Return values

0	on success
<0	on failure

Examples: ipsec_crypto/odp_ipsec.c, odp_crypto.c, and odp_sysinfo.c.

◆ odp_crypto_cipher_capability()

int odp_crypto_cipher_capability	(	odp_cipher_alg_t	cipher,
		odp_crypto_cipher_capability_t	capa[],
		int	num
	)

Query supported cipher algorithm capabilities.

Outputs all supported configuration options for the algorithm. Output is sorted (from the smallest to the largest) first by key length, then by IV length.

Parameters

	cipher	Cipher algorithm
[out]	capa	Array of capability structures for output
	num	Maximum number of capability structures to output

Returns: Number of capability structures for the algorithm. If this is larger than 'num', only 'num' first structures were output and application may call the function again with a larger value of 'num'.

Return values

<0	on failure

Examples: ipsec_crypto/odp_ipsec.c, odp_crypto.c, and odp_sysinfo.c.

◆ odp_crypto_auth_capability()

int odp_crypto_auth_capability	(	odp_auth_alg_t	auth,
		odp_crypto_auth_capability_t	capa[],
		int	num
	)

Query supported authentication algorithm capabilities.

Outputs all supported configuration options for the algorithm. Output is sorted (from the smallest to the largest) first by digest length, then by key length.

Parameters

	auth	Authentication algorithm
[out]	capa	Array of capability structures for output
	num	Maximum number of capability structures to output

Returns: Number of capability structures for the algorithm. If this is larger than 'num', only 'num' first structures were output and application may call the function again with a larger value of 'num'.

Return values

<0	on failure

Examples: ipsec_crypto/odp_ipsec.c, odp_crypto.c, and odp_sysinfo.c.

◆ odp_crypto_session_create()

int odp_crypto_session_create	(	const odp_crypto_session_param_t *	param,
		odp_crypto_session_t *	session,
		odp_crypto_ses_create_err_t *	status
	)

Crypto session creation.

Create a crypto session according to the session parameters. Use odp_crypto_session_param_init() to initialize parameters into their default values. If call ends up with an error no new session will be created.

The parameter structure as well as the key and IV data pointed to by it can be freed after the call.

Parameters

	param	Session parameters
[out]	session	Created session else ODP_CRYPTO_SESSION_INVALID
[out]	status	Failure code if unsuccessful

Return values

0	on success
<0	on failure

Examples: odp_crypto.c.

◆ odp_crypto_session_destroy()

int odp_crypto_session_destroy ( odp_crypto_session_t session )

Crypto session destroy.

Destroy an unused session. Result is undefined if session is being used (i.e. asynchronous operation is in progress).

Parameters

session Session handle

Return values

0	on success
<0	on failure

Examples: odp_crypto.c.

◆ odp_crypto_session_to_u64()

uint64_t odp_crypto_session_to_u64 ( odp_crypto_session_t hdl )

Get printable value for an odp_crypto_session_t.

Parameters

hdl	odp_crypto_session_t handle to be printed

Returns: uint64_t value that can be used to print/display this handle

Note: This routine is intended to be used for diagnostic purposes to enable applications to generate a printable value that represents an odp_crypto_session_t handle.

◆ odp_crypto_session_param_init()

void odp_crypto_session_param_init ( odp_crypto_session_param_t * param )

Initialize crypto session parameters.

Initialize an odp_crypto_session_param_t to its default values for all fields.

Parameters

param Pointer to odp_crypto_session_param_t to be initialized

Examples: odp_crypto.c.

◆ odp_crypto_packet_from_event()

odp_packet_t odp_crypto_packet_from_event ( odp_event_t ev )

Return crypto processed packet that is associated with event.

Get packet handle to an crypto processed packet event. Event subtype must be ODP_EVENT_PACKET_CRYPTO. Crypto operation results can be examined with odp_crypto_result().

Note: any invalid parameters will cause undefined behavior and may cause the application to abort or crash.

Parameters

ev	Event handle

Returns: Packet handle

Examples: odp_crypto.c.

◆ odp_crypto_packet_to_event()

odp_event_t odp_crypto_packet_to_event ( odp_packet_t pkt )

Convert crypto packet handle to event.

The packet handle must be an output of an crypto operation.

Parameters

pkt	Packet handle from crypto operation

Returns: Event handle

◆ odp_crypto_result()

int odp_crypto_result	(	odp_crypto_packet_result_t *	result,
		odp_packet_t	packet
	)

Get crypto operation results from a crypto processed packet.

Crypto operations of all types (SYNC and ASYNC) produce packets which contain crypto result metadata. This function returns success status of the crypto operation that was applied to a packet and optionally writes additional information in a result structure.

If the crypto operation succeeded, zero is returned and the values written in the cipher_status and auth_status fields of the result structure have undefined values.

If the crypto operation failed, -1 is returned and the cipher_status and auth_status fields of the result structure indicate the reason for the failure.

The subtype of the passed packet must be ODP_EVENT_PACKET_CRYPTO, otherwise the result of the call is undefined.

Parameters

	packet	A crypto processed packet (ODP_EVENT_PACKET_CRYPTO)
[out]	result	Pointer to operation result for output or NULL

Return values

0	Crypto operation succeeded
-1	Crypto operation failed
<-1	Failed to get crypto operation status of the packet

Examples: ipsec_crypto/odp_ipsec.c, and odp_crypto.c.

◆ odp_crypto_op()

int odp_crypto_op	(	const odp_packet_t	pkt_in[],
		odp_packet_t	pkt_out[],
		const odp_crypto_packet_op_param_t	param[],
		int	num_pkt
	)

Crypto packet operation.

Performs the SYNC cryptographic operations specified during session creation on the packets. All arrays should be of num_pkt size.

Result of the crypto operation can be checked using odp_crypto_result(). Parse flags in packet metadata are not affected by the crypto operation. In particular, odp_packet_has_error() can not be used for checking if the crypto operation succeeded.

Use of the pkt_out parameter depends on the configured crypto operation type as described below.

ODP_CRYPTO_OP_TYPE_LEGACY:

Caller should initialize each element of pkt_out either with the desired output packet handle or with ODP_PACKET_INVALID to make ODP allocate a new packet from provided pool.

All packet data and metadata are copied from the input packet to the output packet before the requested crypto operation is performed to the output packet. If an output packet is given to the operation, it must be at least as long as the input packet and, in encode operations, long enough for the hash result to be fully inside the packet data. Memory layout of the output packet may change during the crypto operation. If the output packet is longer than needed, it is not truncated and the extra data bytes retain their content.

It is ok to pass the same packet handle as both the input packet and the output packet for the same crypto operation. In that case the input packet is consumed but returned as the output packet (with possibly different memory layout).

ODP_CRYPTO_OP_TYPE_BASIC:

ODP allocates the output packet from the pool from which the input packet was allocated. The processed input packet is consumed. All packet data and metadata are copied from the input packet to the output packet before the requested crypto operation is applied to the output packet. Memory layout (including packet data pointers, head and tail room, segmentation) of the output packet may differ from that of the input packet.

The value of pkt_out[n] is ignored as pkt_out[n] is used purely as an output parameter that returns the handle of the newly allocated packet.

ODP_CRYPTO_OP_TYPE_OOP:

Writes the output bytes of the crypto operation in a caller provided output packet passed through pkt_out[n]. Input packets are not consumed nor modified. Memory layout (including packet data pointers, head and tail room, segmentation) of the output packet may change during the operation.

Crypto output is the processed crypto_range, auth_range and MAC/digest (in encode sessions) of the input packet. The operation behaves as if crypto range and auth range were first copied from the input packet to the output packet and then the crypto operation was applied to the output packet.

Auth range of (AEAD) algorithms that ignore auth range is not copied.

The offset of the crypto range and auth range in the output packet is the same as in the input packet, adjusted by dst_offset_shift operation parameter.

pkt_out[n] must be a valid handle to a packet that is long enough to contain the shifted crypto range, auth range and, in encode sessions, the MAC/digest result. pkt_out[n] must not be the same as any input packet or any other output packet.

OOP_CRYPTO_OP_TYPE_BASIC_AND_OOP:

Behaves as the ODP_CRYPTO_OP_TYPE_BASIC operation type if pkt_out[n] is ODP_PACKET_INVALID. Otherwise behaves as the ODP_CRYPTO_OP_TYPE_OOP operation type.

Parameters

	pkt_in	Packets to be processed
[in,out]	pkt_out	Packet handle array for resulting packets
	param	Operation parameters array
	num_pkt	Number of packets to be processed

Returns: Number of input packets processed (0 ... num_pkt)

Return values

<0	on failure

Examples: ipsec_crypto/odp_ipsec.c, and odp_crypto.c.

◆ odp_crypto_op_enq()

int odp_crypto_op_enq	(	const odp_packet_t	pkt_in[],
		const odp_packet_t	pkt_out[],
		const odp_crypto_packet_op_param_t	param[],
		int	num_pkt
	)

Crypto packet operation.

Performs the ASYNC cryptographic operations specified during session creation on the packets. Behaves otherwise like odp_crypto_op() but returns output packets through events.

With operation types other than ODP_CRYPTO_OP_TYPE_LEGACY, packet data of processed packets may not be valid before odp_crypto_result() has been called.

With ODP_CRYPTO_OP_TYPE_OOP, an enqueued input packet is consumed but returned back unmodified after the crypto operation is complete. The caller may not access the input packet until getting the handle back through odp_crypto_result().

All arrays should be of num_pkt size, except that pkt_out parameter is ignored when the crypto operation type is ODP_CRYPTO_OP_TYPE_BASIC.

From packet ordering perspective this function behaves as if each input packet was enqueued to a crypto session specific ODP queue in the order the packets appear in the parameter array. The conceptual session input queue has the same order type (ODP_QUEUE_ORDER_KEEP or ODP_QUEUE_ORDER_IGNORE) as the completion queue of the session. The order of output events of a crypto session in a completion queue is the same as the order of the corresponding input packets in the conceptual session input queue. The order of output events of different crypto sessions is not defined even when they go through the same crypto completion queue.

Parameters

pkt_in	Packets to be processed
pkt_out	Packet handle array for resulting packets
param	Operation parameters array
num_pkt	Number of packets to be processed

Returns: Number of input packets consumed (0 ... num_pkt)

Return values

<0	on failure

Examples: ipsec_crypto/odp_ipsec.c, and odp_crypto.c.

API Description

Data Structures

Macros

Typedefs

Enumerations

Functions

Enumeration Type Documentation

◆ odp_crypto_op_mode_t

◆ odp_crypto_op_t

◆ odp_cipher_alg_t

◆ odp_auth_alg_t

◆ odp_crypto_op_type_t

◆ odp_crypto_ses_create_err_t

◆ odp_crypto_alg_err_t

Function Documentation

◆ odp_crypto_capability()

◆ odp_crypto_cipher_capability()

◆ odp_crypto_auth_capability()

◆ odp_crypto_session_create()

◆ odp_crypto_session_destroy()

◆ odp_crypto_session_to_u64()

◆ odp_crypto_session_param_init()

◆ odp_crypto_packet_from_event()

◆ odp_crypto_packet_to_event()

◆ odp_crypto_result()

◆ odp_crypto_op()

◆ odp_crypto_op_enq()