Authenticated Encryption with Associated Data

Functions
void	lc_aead_zero (struct lc_aead_ctx *ctx)
	Zeroize AEAD context.
void	lc_aead_zero_free (struct lc_aead_ctx *ctx)
	Zeroize and free AEAD context.
int	lc_aead_setkey (struct lc_aead_ctx *ctx, const uint8_t *key, const size_t keylen, const uint8_t *iv, size_t ivlen)
	Set the key for the AEAD encyption or decryption operation.
int	lc_aead_encrypt (struct lc_aead_ctx *ctx, const uint8_t *plaintext, uint8_t *ciphertext, size_t datalen, const uint8_t *aad, size_t aadlen, uint8_t *tag, size_t taglen)
	AEAD-encrypt data in one call.
int	lc_aead_enc_init (struct lc_aead_ctx *ctx, const uint8_t *aad, size_t aadlen)
	Initialize AEAD encryption.
int	lc_aead_enc_update (struct lc_aead_ctx *ctx, const uint8_t *plaintext, uint8_t *ciphertext, size_t datalen)
	AEAD-encrypt data - send partial data.
int	lc_aead_enc_final (struct lc_aead_ctx *ctx, uint8_t *tag, size_t taglen)
	Complete AEAD encryption - Obtain the authentication tag from the encryption operation.
int	lc_aead_decrypt (struct lc_aead_ctx *ctx, const uint8_t *ciphertext, uint8_t *plaintext, size_t datalen, const uint8_t *aad, size_t aadlen, const uint8_t *tag, size_t taglen)
	AEAD-decrypt data in one call.
int	lc_aead_dec_init (struct lc_aead_ctx *ctx, const uint8_t *aad, size_t aadlen)
	Initialize AEAD decryption.
int	lc_aead_dec_update (struct lc_aead_ctx *ctx, const uint8_t *ciphertext, uint8_t *plaintext, size_t datalen)
	AEAD-decrypt data - send partial data.
int	lc_aead_dec_final (struct lc_aead_ctx *ctx, const uint8_t *tag, size_t taglen)
	AEAD-decrypt data - Perform authentication.
uint64_t	lc_aead_algorithm_type (const struct lc_aead *aead)
	Obtain algorithm type usable with lc_alg_status.
uint64_t	lc_aead_ctx_algorithm_type (const struct lc_aead_ctx *ctx)
	Obtain algorithm type usable with lc_alg_status.
uint64_t	lc_rng_ctx_algorithm_type (const struct lc_rng_ctx *ctx)
	Obtain algorithm type usable with lc_alg_status.

Detailed Description

Concept of AEAD algorithms in leancrypto

All AEAD algorithms can be used with the API calls documented below. However, the allocation part is AEAD-algorithm-specific. Thus, perform the following steps

1. Allocation: Use the stack or heap allocation functions documented in lc_chacha20_poly1305.h, lc_aes_gcm.h, lc_ascon_lightweight.h, lc_ascon_keccak.h, lc_cshake_crypt.h, lc_kmac_crypt.h, lc_hash_crypt.h, lc_symhmac.h, or lc_symkmac.h.
2. Use the returned cipher handle with the API calls below.

Function Documentation

lc_aead_algorithm_type()

uint64_t lc_aead_algorithm_type

(

const struct lc_aead *

aead

)

Obtain algorithm type usable with lc_alg_status.

Parameters

[in]

aead

AEAD algorithm instance

Returns

algorithm type

lc_aead_ctx_algorithm_type()

uint64_t lc_aead_ctx_algorithm_type

(

const struct lc_aead_ctx *

ctx

)

Obtain algorithm type usable with lc_alg_status.

Parameters

[in]

ctx

AEAD context handle

Returns

algorithm type

lc_aead_dec_final()

int lc_aead_dec_final	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	tag,
		size_t	taglen )

AEAD-decrypt data - Perform authentication.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[in]	tag	Authentication tag generated by encryption operation
[in]	taglen	Length of tag buffer.

Returns

0 on successful authentication, < 0 on error (-EBADMSG means authentication error)

lc_aead_dec_init()

int lc_aead_dec_init	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	aad,
		size_t	aadlen )

Initialize AEAD decryption.

This call allows multiple successive _update calls to process data.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[in]	aad	Additional authenticate data to be processed - this is data which is not encrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer

Returns

amount of processed bytes on success, < 0 on error

lc_aead_dec_update()

int lc_aead_dec_update	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	datalen )

AEAD-decrypt data - send partial data.

Note

This operation can be invoked multiple times and must be completed with a call to lc_aead_dec_final.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[in]	ciphertext	Ciphertext data to be decrypted
[out]	plaintext	Plaintext data buffer to be filled
[in]	datalen	Length of the plaintext and ciphertext data buffers

Note

the encryption operation is symmetric and generates as much output as input.

Returns

amount of processed bytes on success, < 0 on error

lc_aead_decrypt()

int lc_aead_decrypt	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		size_t	datalen,
		const uint8_t *	aad,
		size_t	aadlen,
		const uint8_t *	tag,
		size_t	taglen )

AEAD-decrypt data in one call.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[in]	ciphertext	Ciphertext data to be decrypted
[out]	plaintext	Plaintext data buffer to be filled
[in]	datalen	Length of the plaintext and ciphertext data buffers

Note

the encryption operation is symmetric and generates as much output as input.

Parameters

[in]	aad	Additional authenticate data to be processed - this is data which is not decrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer
[in]	tag	Authentication tag generated by encryption operation
[in]	taglen	Length of tag buffer.

Returns

0 on successful authentication, < 0 on error (-EBADMSG means authentication error)

lc_aead_enc_final()

int lc_aead_enc_final	(	struct lc_aead_ctx *	ctx,
		uint8_t *	tag,
		size_t	taglen )

Complete AEAD encryption - Obtain the authentication tag from the encryption operation.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[out]	tag	Buffer to be filled with tag
[in]	taglen	Length of tag buffer. The full tag size hc_get_tagsize(). If the buffer is smaller, a truncated tag value is returned.

Returns

amount of processed bytes on success, < 0 on error

lc_aead_enc_init()

int lc_aead_enc_init	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	aad,
		size_t	aadlen )

Initialize AEAD encryption.

This call allows multiple successive _update calls to process data.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[in]	aad	Additional authenticate data to be processed - this is data which is not encrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer

Returns

amount of processed bytes on success, < 0 on error

lc_aead_enc_update()

int lc_aead_enc_update	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	datalen )

AEAD-encrypt data - send partial data.

Note

This operation can be invoked multiple times and must be completed with a call to lc_aead_enc_final.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[in]	plaintext	Plaintext data to be encrypted
[out]	ciphertext	Ciphertext data buffer to be filled
[in]	datalen	Length of the plaintext and ciphertext data buffers

Note

the encryption operation is symmetric and generates as much output as input.

Returns

amount of processed bytes on success, < 0 on error

lc_aead_encrypt()

int lc_aead_encrypt	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		size_t	datalen,
		const uint8_t *	aad,
		size_t	aadlen,
		uint8_t *	tag,
		size_t	taglen )

AEAD-encrypt data in one call.

Parameters

[in]	ctx	AEAD context handle with key set / IV
[in]	plaintext	Plaintext data to be encrypted
[out]	ciphertext	Ciphertext data buffer to be filled
[in]	datalen	Length of the plaintext and ciphertext data buffers

Note

the encryption operation is symmetric and generates as much output as input.

Parameters

[in]	aad	Additional authenticate data to be processed - this is data which is not encrypted, but considered as part of the authentication.
[in]	aadlen	Length of the AAD buffer
[out]	tag	Buffer to be filled with tag
[in]	taglen	Length of tag buffer. The full tag size hc_get_tagsize(). If the buffer is smaller, a truncated tag value is returned.

Returns

amount of processed bytes on success, < 0 on error

lc_aead_setkey()

int lc_aead_setkey	(	struct lc_aead_ctx *	ctx,
		const uint8_t *	key,
		const size_t	keylen,
		const uint8_t *	iv,
		size_t	ivlen )

Set the key for the AEAD encyption or decryption operation.

Parameters

[in]	ctx	AEAD context handle
[in]	key	Buffer with key
[in]	keylen	Length of key buffer
[in]	iv	initialization vector to be used
[in]	ivlen	length of initialization vector

The algorithm supports a key of arbitrary size. The only requirement is that the same key is used for decryption as for encryption.

Returns

0 upon success; < 0 on error

lc_aead_zero()

void lc_aead_zero

(

struct lc_aead_ctx *

ctx

)

Zeroize AEAD context.

Parameters

[in]

ctx

AEAD context to be zeroized

lc_aead_zero_free()

void lc_aead_zero_free

(

struct lc_aead_ctx *

ctx

)

Zeroize and free AEAD context.

Parameters

[in]

ctx

AEAD context to be zeroized and freed

lc_rng_ctx_algorithm_type()

uint64_t lc_rng_ctx_algorithm_type

(

const struct lc_rng_ctx *

ctx

)

Obtain algorithm type usable with lc_alg_status.

Parameters

[in]

ctx

RNG context handle

Returns

algorithm type