Macros
#define	LC_SYM_CTX_ON_STACK(name, symname)
	Allocate stack memory for the sym context.

Functions
void	lc_aes_kw_encrypt (struct lc_sym_ctx ctx, const uint8_t in, uint8_t *out, size_t len)
	AES KW encrypt.
int	lc_aes_kw_decrypt (struct lc_sym_ctx ctx, const uint8_t in, uint8_t *out, size_t len)
	AES KW decrypt.
void	cc20_block (struct lc_sym_state state, uint32_t stream)
	ChaCha20 block function.
int	lc_sym_init (struct lc_sym_ctx *ctx)
	Initialize symmetric context.
int	lc_sym_setkey (struct lc_sym_ctx ctx, const uint8_t key, size_t keylen)
	Set key.
int	lc_sym_setiv (struct lc_sym_ctx ctx, const uint8_t iv, size_t ivlen)
	Set IV.
void	lc_sym_encrypt (struct lc_sym_ctx ctx, const uint8_t in, uint8_t *out, size_t len)
	Symmetric encryption.
void	lc_sym_decrypt (struct lc_sym_ctx ctx, const uint8_t in, uint8_t *out, size_t len)
	Symmetric decryption.
void	lc_sym_zero (struct lc_sym_ctx *ctx)
	Zeroize symmetric context allocated with either LC_SYM_CTX_ON_STACK or lc_sym_alloc.
int	lc_sym_alloc (const struct lc_sym sym, struct lc_sym_ctx *ctx)
	Allocate symmetric algorithm context on heap.
void	lc_sym_zero_free (struct lc_sym_ctx *ctx)
	Symmetric algorithm deallocation and properly zeroization function to frees all buffers and the cipher handle.
uint64_t	lc_sym_algorithm_type (const struct lc_sym *sym)
	Obtain algorithm type usable with lc_alg_status.
uint64_t	lc_sym_ctx_algorithm_type (const struct lc_sym_ctx *ctx)
	Obtain algorithm type usable with lc_alg_status.

Detailed Description

Concept of symmetric algorithms in leancrypto

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

Allocation: Use the stack or heap allocation functions documented in lc_aes.h, lc_chacha20.h.
Use the returned cipher handle with the API calls below.

Macro Definition Documentation

◆ LC_SYM_CTX_ON_STACK

#define LC_SYM_CTX_ON_STACK	(		name,
			symname )

Value:

        _Pragma("GCC diagnostic push")                                              \
                _Pragma("GCC diagnostic ignored \"-Wvla\"") _Pragma(                \
                        "GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                           \
                                          LC_SYM_CTX_SIZE(symname),                 \
                                          LC_SYM_COMMON_ALIGNMENT);                 \
        struct lc_sym_ctx *name = (struct lc_sym_ctx *)name##_ctx_buf;              \
        LC_SYM_SET_CTX(name, symname);                                              \
        lc_sym_zero(name);                                                          \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the sym context.

Parameters

[in]	name	Name of the stack variable
[in]	symname	Pointer of type struct sym referencing the sym implementation to be used

Definition at line 254 of file lc_sym.h.

Function Documentation

◆ cc20_block()

void cc20_block	(	struct lc_sym_state *	state,
		uint32_t *	stream )

ChaCha20 block function.

Block operation from the ChaCah20 state

Parameters

[in]	state	ChaCha20 state from which to derive the block output
[out]	stream	ChaCha20 key stream output

◆ lc_aes_kw_decrypt()

int lc_aes_kw_decrypt	(	struct lc_sym_ctx *	ctx,
		const uint8_t *	in,
		uint8_t *	out,
		size_t	len )

AES KW decrypt.

Parameters

[in]	ctx	Reference to sym context implementation to be used to perform sym calculation with.
[in]	in	Ciphertext to be decrypted
[out]	out	Plaintext resulting of the decryption
[in]	len	Size of the input / output buffer

Returns: 0 on success, -EBADMSG on authentication error

The plaintext and the ciphertext buffer may be identical to support in-place cryptographic operations.

NOTE: The output buffer MAY be 8 bytes smaller than the input buffer.

This function is a helper function. It provides the same operation as lc_sym_decrypt. The difference is that it also performs the authentication.

◆ lc_aes_kw_encrypt()

void lc_aes_kw_encrypt	(	struct lc_sym_ctx *	ctx,
		const uint8_t *	in,
		uint8_t *	out,
		size_t	len )

AES KW encrypt.

Parameters

[in]	ctx	Reference to sym context implementation to be used to perform sym calculation with.
[in]	in	Plaintext to be encrypted
[out]	out	Ciphertext resulting of the encryption
[in]	len	Size of the input / output buffer

The plaintext and the ciphertext buffer may be identical to support in-place cryptographic operations.

NOTE: The output buffer MUST be 8 bytes larger than the input buffer!

This function is a helper function. It provides the same operation as lc_sym_encrypt. The difference is that it also obtains the tag from the AES KW operation.

◆ lc_sym_algorithm_type()

uint64_t lc_sym_algorithm_type ( const struct lc_sym * sym )

Obtain algorithm type usable with lc_alg_status.

Parameters

[in] sym AEAD algorithm instance

Returns: algorithm type

◆ lc_sym_alloc()

int lc_sym_alloc	(	const struct lc_sym *	sym,
		struct lc_sym_ctx **	ctx )

Allocate symmetric algorithm context on heap.

Parameters

[in]	sym	Symmetric algorithm implementation of type struct lc_sym
[out]	ctx	Allocated symmetrc algorithm context

Returns: 0 on success, < 0 on error

◆ lc_sym_ctx_algorithm_type()

uint64_t lc_sym_ctx_algorithm_type ( const struct lc_sym_ctx * ctx )

Obtain algorithm type usable with lc_alg_status.

Parameters

[in] ctx Symmetric context handle

Returns: algorithm type

◆ lc_sym_decrypt()

void lc_sym_decrypt	(	struct lc_sym_ctx *	ctx,
		const uint8_t *	in,
		uint8_t *	out,
		size_t	len )

Symmetric decryption.

Parameters

[in]	ctx	Reference to sym context implementation to be used to perform sym calculation with.
[in]	in	Ciphertext to be decrypted
[out]	out	Plaintext resulting of the decryption
[in]	len	Size of the input / output buffer

The plaintext and the ciphertext buffer may be identical to support in-place cryptographic operations.

Note

This call is allowed to be called multiple times to operate in stream mode. However, the caller must enforce the following:

All invocations except for the last data block must contain data that is always a multiple of 16 bytes.
Only the last invocation is allowed to be not a multiple of 16 bytes for algorithms that allow it (e.g. XTS, CTR)

◆ lc_sym_encrypt()

void lc_sym_encrypt	(	struct lc_sym_ctx *	ctx,
		const uint8_t *	in,
		uint8_t *	out,
		size_t	len )

Symmetric encryption.

Parameters

[in]	ctx	Reference to sym context implementation to be used to perform sym calculation with.
[in]	in	Plaintext to be encrypted
[out]	out	Ciphertext resulting of the encryption
[in]	len	Size of the input / output buffer

The plaintext and the ciphertext buffer may be identical to support in-place cryptographic operations.

Note

This call is allowed to be called multiple times to operate in stream mode. However, the caller must enforce the following:

All invocations except for the last data block must contain data that is always a multiple of 16 bytes.
Only the last invocation is allowed to be not a multiple of 16 bytes for algorithms that allow it (e.g. XTS, CTR)

◆ lc_sym_init()

int lc_sym_init ( struct lc_sym_ctx * ctx )

Initialize symmetric context.

Parameters

[in] ctx Reference to sym context implementation to be used to perform sym calculation with.

The caller must provide an allocated ctx.

◆ lc_sym_setiv()

int lc_sym_setiv	(	struct lc_sym_ctx *	ctx,
		const uint8_t *	iv,
		size_t	ivlen )

Set IV.

Note: For XTS, it is required that this function call MUST come AFTER the lc_sym_setkey invocation as the tweak value is immediately calculated from the IV using the XTS key.

Parameters

[in]	ctx	Reference to sym context implementation to be used to set the IV.
[in]	iv	IV to be set
[in]	ivlen	IV length to be set

Returns: 0 on success, < 0 on error

◆ lc_sym_setkey()

int lc_sym_setkey	(	struct lc_sym_ctx *	ctx,
		const uint8_t *	key,
		size_t	keylen )

Set key.

Note: For XTS, it is required that this function call MUST come BEFORE the lc_sym_setiv invocation as the tweak value is immediately calculated from the IV using the XTS key.

Parameters

[in]	ctx	Reference to sym context implementation to be used to set the key.
[in]	key	Key to be set
[in]	keylen	Key length to be set

Returns: 0 on success, < 0 on error

◆ lc_sym_zero()

void lc_sym_zero ( struct lc_sym_ctx * ctx )

Zeroize symmetric context allocated with either LC_SYM_CTX_ON_STACK or lc_sym_alloc.

Parameters

[in] ctx Symmetric context to be zeroized

◆ lc_sym_zero_free()

void lc_sym_zero_free ( struct lc_sym_ctx * ctx )

Symmetric algorithm deallocation and properly zeroization function to frees all buffers and the cipher handle.

Parameters

[in] ctx Symmtric algorithm context handle

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ LC_SYM_CTX_ON_STACK

Function Documentation

◆ cc20_block()

◆ lc_aes_kw_decrypt()

◆ lc_aes_kw_encrypt()

◆ lc_sym_algorithm_type()

◆ lc_sym_alloc()

◆ lc_sym_ctx_algorithm_type()

◆ lc_sym_decrypt()

◆ lc_sym_encrypt()

◆ lc_sym_init()

◆ lc_sym_setiv()

◆ lc_sym_setkey()

◆ lc_sym_zero()

◆ lc_sym_zero_free()