Authenticated Encryption with Associated Data

Functions
static void	lc_aead_zero (struct lc_aead_ctx *ctx)
	Zeroize AEAD context.
static void	lc_aead_zero_free (struct lc_aead_ctx *ctx)
	Zeroize and free AEAD context.
static 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.
static 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.
static int	lc_aead_enc_init (struct lc_aead_ctx *ctx, const uint8_t *aad, size_t aadlen)
	Initialize AEAD encryption.
static 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.
static 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.
static 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.
static int	lc_aead_dec_init (struct lc_aead_ctx *ctx, const uint8_t *aad, size_t aadlen)
	Initialize AEAD decryption.
static 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.
static int	lc_aead_dec_final (struct lc_aead_ctx *ctx, const uint8_t *tag, size_t taglen)
	AEAD-decrypt data - Perform authentication.

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_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_dec_final()

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

inlinestatic

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)

Definition at line 426 of file lc_aead.h.

lc_aead_dec_init()

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

inlinestatic

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

Definition at line 357 of file lc_aead.h.

lc_aead_dec_update()

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

inlinestatic

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

Definition at line 393 of file lc_aead.h.

lc_aead_decrypt()

static 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 )

inlinestatic

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.
[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)

Definition at line 321 of file lc_aead.h.

lc_aead_enc_final()

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

inlinestatic

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

Definition at line 280 of file lc_aead.h.

lc_aead_enc_init()

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

inlinestatic

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

Definition at line 210 of file lc_aead.h.

lc_aead_enc_update()

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

inlinestatic

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

Definition at line 246 of file lc_aead.h.

lc_aead_encrypt()

static 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 )

inlinestatic

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.
[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

Definition at line 173 of file lc_aead.h.

lc_aead_setkey()

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

inlinestatic

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

Definition at line 133 of file lc_aead.h.

lc_aead_zero()

static void lc_aead_zero ( struct lc_aead_ctx * ctx )

inlinestatic

Zeroize AEAD context.

Parameters

[in]

ctx

AEAD context to be zeroized

Definition at line 86 of file lc_aead.h.

lc_aead_zero_free()

static void lc_aead_zero_free ( struct lc_aead_ctx * ctx )

inlinestatic

Zeroize and free AEAD context.

Parameters

[in]

ctx

AEAD context to be zeroized and freed

Definition at line 109 of file lc_aead.h.