#include "lc_hash.h"
#include "lc_rng.h"
#include "lc_sha3.h"
#include "lc_memset_secure.h"

Include dependency graph for lc_kmac.h:

This graph shows which files directly or indirectly include this file:

Macros
#define	LC_KMAC_FLAGS_SUPPORT_REINIT (1 << 0)

#define	LC_KMAC_CTX_ON_STACK(name, hashname)
	Allocate stack memory for the KMAC context.

#define	LC_KMAC_CTX_ON_STACK_REINIT(name, hashname)
	Allocate stack memory for the KMAC context.

#define	LC_KMAC_KDF_DRNG_CTX_SIZE(hashname) (sizeof(struct lc_rng_ctx) + LC_KMAC_CTX_SIZE(hashname))

#define	LC_KMAC_KDF_DRNG_SET_CTX(name, hashname) LC_KMAC_SET_CTX(name, hashname)

#define	LC_KMAC_KDF_RNG_CTX(name, hashname)

#define	LC_KMAC_KDF_DRNG_CTX_ON_STACK(name, hashname)
	Allocate stack memory for the KMAC DRNG context.

Functions
void	lc_kmac_init (struct lc_kmac_ctx kmac_ctx, const uint8_t key, size_t klen, const uint8_t *s, size_t slen)
	Initialize KMAC context.

void	lc_kmac_reinit (struct lc_kmac_ctx *kmac_ctx)
	Re-initialize KMAC context after a kmac_final operation.

void	lc_kmac_update (struct lc_kmac_ctx kmac_ctx, const uint8_t in, size_t inlen)
	Update KMAC.

void	lc_kmac_final (struct lc_kmac_ctx kmac_ctx, uint8_t mac, size_t maclen)
	Calculate KMAC MAC.

void	lc_kmac_final_xof (struct lc_kmac_ctx kmac_ctx, uint8_t mac, size_t maclen)
	Calculate KMAC MAC in XOF mode.

int	lc_kmac_alloc (const struct lc_hash hash, struct lc_kmac_ctx *kmac_ctx, uint32_t flags)
	Allocate KMAC context on heap.

void	lc_kmac_zero_free (struct lc_kmac_ctx *kmac_ctx)
	Zeroize and free KMAC context.

static void	lc_kmac_zero (struct lc_kmac_ctx *kmac_ctx)
	Zeroize KMAC context allocated with either LC_KMAC_CTX_ON_STACK or lc_kmac_alloc.

static size_t	lc_kmac_macsize (struct lc_kmac_ctx *kmac_ctx)
	Return the MAC size.

static void	lc_kmac (const struct lc_hash hash, const uint8_t key, size_t keylen, const uint8_t s, size_t slen, const uint8_t in, size_t inlen, uint8_t *mac, size_t maclen)
	Calculate KMAC - one-shot.

static void	lc_kmac_xof (const struct lc_hash hash, const uint8_t key, size_t keylen, const uint8_t s, size_t slen, const uint8_t in, size_t inlen, uint8_t *mac, size_t maclen)
	Calculate KMAC in XOF mode - one-shot.

int	lc_kmac_rng_alloc (struct lc_rng_ctx *state, const struct lc_hash hash)
	Allocation of a KMAC DRNG context.

Variables
const struct lc_rng *	lc_kmac_rng

Macro Definition Documentation

◆ LC_KMAC_CTX_ON_STACK

#define LC_KMAC_CTX_ON_STACK	(		name,
			hashname )

Value:

        _Pragma("GCC diagnostic push")                                              \
                _Pragma("GCC diagnostic ignored \"-Wvla\"") _Pragma(                \
                        "GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                           \
                                          LC_KMAC_CTX_SIZE(hashname),               \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_kmac_ctx *name = (struct lc_kmac_ctx *)name##_ctx_buf;            \
        LC_KMAC_SET_CTX(name, hashname);                                            \
        lc_kmac_zero(name);                                                         \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the KMAC context.

This allocates the memory without re-initialization support

Parameters

[in]	name	Name of the stack variable - use lc_cshake256 or lc_cshake128
[in]	hashname	Pointer of type struct hash referencing the hash implementation to be used

Definition at line 214 of file lc_kmac.h.

◆ LC_KMAC_CTX_ON_STACK_REINIT

#define LC_KMAC_CTX_ON_STACK_REINIT	(		name,
			hashname )

Value:

        _Pragma("GCC diagnostic push")                                              \
                _Pragma("GCC diagnostic ignored \"-Wvla\"") _Pragma(                \
                        "GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                           \
                                          LC_KMAC_CTX_SIZE_REINIT(hashname),        \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_kmac_ctx *name = (struct lc_kmac_ctx *)name##_ctx_buf;            \
        LC_KMAC_SET_CTX_REINIT(name, hashname);                                     \
        lc_kmac_zero(name);                                                         \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the KMAC context.

This allocates the memory with re-initialization support. See KMAC_FLAGS_SUPPORT_REINIT for the explanation about re-initialization.

Parameters

[in]	name	Name of the stack variable - use lc_cshake256 or lc_cshake128
[in]	hashname	Pointer of type struct hash referencing the hash implementation to be used

Definition at line 237 of file lc_kmac.h.

◆ LC_KMAC_FLAGS_SUPPORT_REINIT

#define LC_KMAC_FLAGS_SUPPORT_REINIT (1 << 0)

Definition at line 170 of file lc_kmac.h.

◆ LC_KMAC_KDF_DRNG_CTX_ON_STACK

#define LC_KMAC_KDF_DRNG_CTX_ON_STACK	(		name,
			hashname )

Value:

        _Pragma("GCC diagnostic push")                                              \
                _Pragma("GCC diagnostic ignored \"-Wvla\"") _Pragma(                \
                        "GCC diagnostic ignored \"-Wdeclaration-after-statement\"") \
                        LC_ALIGNED_BUFFER(name##_ctx_buf,                           \
                                          LC_KMAC_KDF_DRNG_CTX_SIZE(hashname),      \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_rng_ctx *name = (struct lc_rng_ctx *)name##_ctx_buf;              \
        LC_KMAC_KDF_RNG_CTX(name, hashname);                                        \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the KMAC DRNG context.

Parameters

[in]	name	Name of the stack variable
[in]	hashname	Reference to lc_hash implementation - use lc_cshake256 or lc_cshake128.

Definition at line 361 of file lc_kmac.h.

◆ LC_KMAC_KDF_DRNG_CTX_SIZE

#define LC_KMAC_KDF_DRNG_CTX_SIZE ( hashname ) (sizeof(struct lc_rng_ctx) + LC_KMAC_CTX_SIZE(hashname))

Definition at line 343 of file lc_kmac.h.

◆ LC_KMAC_KDF_DRNG_SET_CTX

#define LC_KMAC_KDF_DRNG_SET_CTX	(		name,
			hashname ) LC_KMAC_SET_CTX(name, hashname)

Definition at line 346 of file lc_kmac.h.

◆ LC_KMAC_KDF_RNG_CTX

#define LC_KMAC_KDF_RNG_CTX	(		name,
			hashname )

Value:

        LC_RNG_CTX(name, lc_kmac_rng);                                         \
        LC_KMAC_KDF_DRNG_SET_CTX(((struct lc_kmac_ctx *)(name->rng_state)),    \
                                 hashname);                                    \
        lc_rng_zero(name)

Definition at line 348 of file lc_kmac.h.

Function Documentation

◆ lc_kmac()

static void lc_kmac	(	const struct lc_hash *	hash,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	s,
		size_t	slen,
		const uint8_t *	in,
		size_t	inlen,
		uint8_t *	mac,
		size_t	maclen )

inlinestatic

Calculate KMAC - one-shot.

Parameters

[in]	hash	Reference to hash implementation to be used to perform KMAC calculation with. Use lc_cshake256 or lc_cshake128.
[in]	key	MAC key of arbitrary size
[in]	keylen	Size of the MAC key
[in]	in	Buffer holding the data whose MAC shall be calculated
[in]	inlen	Length of the input buffer
[in]	s	Optional customization string - if not needed, use NULL
[in]	slen	Size of s
[out]	mac	Buffer with at least the size of the message digest.
[in]	maclen	Size of the requested MAC

The KMAC calculation operates entirely on the stack.

Definition at line 283 of file lc_kmac.h.

◆ lc_kmac_alloc()

int lc_kmac_alloc	(	const struct lc_hash *	hash,
		struct lc_kmac_ctx **	kmac_ctx,
		uint32_t	flags )

Allocate KMAC context on heap.

NOTE: This is defined for cshake256 as of now.

Parameters

[in]	hash	Reference to hash implementation to be used to perform KMAC calculation with. Use cshake256!
[out]	kmac_ctx	Allocated KMAC context
[in]	flags	Zero or more of the flags defined below

Returns: 0 on success, < 0 on error

◆ lc_kmac_final()

void lc_kmac_final	(	struct lc_kmac_ctx *	kmac_ctx,
		uint8_t *	mac,
		size_t	maclen )

Calculate KMAC MAC.

If the cipher handle shall be used for a new KMAC operation with the same key after this call, you MUST re-initialize the handle with kmac_reinit.

Parameters

[in]	kmac_ctx	Reference to kmac context implementation to be used to perform KMAC calculation with.
[out]	mac	Buffer with at least the size of the message digest that is returned by kmac_macsize.
[in]	maclen	Size of the requested MAC

◆ lc_kmac_final_xof()

void lc_kmac_final_xof	(	struct lc_kmac_ctx *	kmac_ctx,
		uint8_t *	mac,
		size_t	maclen )

Calculate KMAC MAC in XOF mode.

If the cipher handle shall be used for a new KMAC operation with the same key after this call, you MUST re-initialize the handle with kmac_reinit.

This call is can be to be invoked multiple times It generates more message digest.

E.g. the following calls are equal:

size_t maclen = LC_SHA3_256_SIZE_BLOCK * 3 + 5;

lc_kmac_final_xof(ctx, mac, maclen);

and

lc_kmac_final_xof(ctx, mac, LC_SHA3_256_SIZE_BLOCK + 1);
lc_kmac_final_xof(ctx, mac + LC_SHA3_256_SIZE_BLOCK + 1,
                  2 * LC_SHA3_256_SIZE_BLOCK + 1);
lc_kmac_final_xof(ctx, mac + 3 * LC_SHA3_256_SIZE_BLOCK + 2, 3);

Parameters

[in]	kmac_ctx	Reference to kmac context implementation to be used to perform KMAC calculation with.
[out]	mac	Buffer to hold the message digest
[in]	maclen	Size of the requested MAC

◆ lc_kmac_init()

void lc_kmac_init	(	struct lc_kmac_ctx *	kmac_ctx,
		const uint8_t *	key,
		size_t	klen,
		const uint8_t *	s,
		size_t	slen )

Initialize KMAC context.

Parameters

[in]	kmac_ctx	Reference to kmac context implementation to be used to perform KMAC calculation with.
[in]	key	MAC key of arbitrary size
[in]	klen	Size of the MAC key
[in]	s	Optional customization string - if not needed, use NULL
[in]	slen	Size of s

The caller must provide an allocated kmac_ctx. This can be achieved by using KMAC_CTX_ON_STACK or by using kmac_alloc.

◆ lc_kmac_macsize()

static size_t lc_kmac_macsize ( struct lc_kmac_ctx * kmac_ctx )

inlinestatic

Return the MAC size.

Parameters

[in] kmac_ctx KMAC context

Returns: MAC size

Definition at line 256 of file lc_kmac.h.

◆ lc_kmac_reinit()

void lc_kmac_reinit ( struct lc_kmac_ctx * kmac_ctx )

Re-initialize KMAC context after a kmac_final operation.

This operation allows the KMAC context to be used again with the same key set during kmac_init.

Parameters

[in] kmac_ctx Reference to kmac context implementation to be used to perform KMAC calculation with.

◆ lc_kmac_rng_alloc()

int lc_kmac_rng_alloc	(	struct lc_rng_ctx **	state,
		const struct lc_hash *	hash )

Allocation of a KMAC DRNG context.

Parameters

[out]	state	KMAC DRNG context allocated by the function
[in]	hash	Reference to hash implementation to be used to perform RNG operation with. Use lc_cshake256 or lc_cshake128.

The cipher handle including its memory is allocated with this function.

The memory is pinned so that the DRNG state cannot be swapped out to disk.

You need to seed the DRNG!

Returns: 0 upon success; < 0 on error

◆ lc_kmac_update()

void lc_kmac_update	(	struct lc_kmac_ctx *	kmac_ctx,
		const uint8_t *	in,
		size_t	inlen )

Update KMAC.

Parameters

[in]	kmac_ctx	Reference to kmac context implementation to be used to perform KMAC calculation with.
[in]	in	Buffer holding the data whose MAC shall be calculated
[in]	inlen	Length of the input buffer

◆ lc_kmac_xof()

static void lc_kmac_xof	(	const struct lc_hash *	hash,
		const uint8_t *	key,
		size_t	keylen,
		const uint8_t *	s,
		size_t	slen,
		const uint8_t *	in,
		size_t	inlen,
		uint8_t *	mac,
		size_t	maclen )

inlinestatic

Calculate KMAC in XOF mode - one-shot.

Parameters

[in]	hash	Reference to hash implementation to be used to perform KMAC calculation with. Use lc_cshake256 or lc_cshake128.
[in]	key	MAC key of arbitrary size
[in]	keylen	Size of the MAC key
[in]	in	Buffer holding the data whose MAC shall be calculated
[in]	inlen	Length of the input buffer
[in]	s	Optional customization string - if not needed, use NULL
[in]	slen	Size of s
[out]	mac	Buffer with at least the size of the message digest.
[in]	maclen	Size of the requested MAC

The KMAC calculation operates entirely on the stack.

Definition at line 313 of file lc_kmac.h.

◆ lc_kmac_zero()

static void lc_kmac_zero ( struct lc_kmac_ctx * kmac_ctx )

inlinestatic

Zeroize KMAC context allocated with either LC_KMAC_CTX_ON_STACK or lc_kmac_alloc.

Parameters

[in] kmac_ctx KMAC context to be zeroized

Definition at line 185 of file lc_kmac.h.

◆ lc_kmac_zero_free()

void lc_kmac_zero_free ( struct lc_kmac_ctx * kmac_ctx )

Zeroize and free KMAC context.

Parameters

[in] kmac_ctx KMAC context to be zeroized and freed

Variable Documentation

◆ lc_kmac_rng

const struct lc_rng* lc_kmac_rng

extern

Macros

Functions

Variables

Macro Definition Documentation

◆ LC_KMAC_CTX_ON_STACK

◆ LC_KMAC_CTX_ON_STACK_REINIT

◆ LC_KMAC_FLAGS_SUPPORT_REINIT

◆ LC_KMAC_KDF_DRNG_CTX_ON_STACK

◆ LC_KMAC_KDF_DRNG_CTX_SIZE

◆ LC_KMAC_KDF_DRNG_SET_CTX

◆ LC_KMAC_KDF_RNG_CTX

Function Documentation

◆ lc_kmac()

◆ lc_kmac_alloc()

◆ lc_kmac_final()

◆ lc_kmac_final_xof()

◆ lc_kmac_init()

◆ lc_kmac_macsize()

◆ lc_kmac_reinit()

◆ lc_kmac_rng_alloc()

◆ lc_kmac_update()

◆ lc_kmac_xof()

◆ lc_kmac_zero()

◆ lc_kmac_zero_free()

Variable Documentation

◆ lc_kmac_rng