KMAC Keccak Message Authentaction Code (SP800-185)

Macros
#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.

Functions
int	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.
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.
size_t	lc_kmac_macsize (struct lc_kmac_ctx *kmac_ctx)
	Return the MAC size.
int	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.
int	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.

Detailed Description

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 212 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 236 of file lc_kmac.h.

Function Documentation

lc_kmac()

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

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.

Returns

0 on success; < 0 on error

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

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

Returns

0 on success; < 0 on error

lc_kmac_macsize()

size_t lc_kmac_macsize

(

struct lc_kmac_ctx *

kmac_ctx

)

Return the MAC size.

Parameters

[in]

kmac_ctx

KMAC context

Returns

MAC size

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

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

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.

Returns

0 on success; < 0 on error

lc_kmac_zero()

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.

Parameters

[in]

kmac_ctx

KMAC context to be zeroized

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