#include "lc_hash.h"
#include "lc_sha3.h"

Include dependency graph for lc_cshake.h:

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

Macros
#define	LC_CSHAKE_FLAGS_SUPPORT_REINIT (1 << 0)
#define	LC_CSHAKE_CTX_ON_STACK(name, hashname)
	Allocate stack memory for the CSHAKE context.
#define	LC_CSHAKE_CTX_ON_STACK_REINIT(name, hashname)
	Allocate stack memory for the CSHAKE context.

Functions
int	lc_cshake_init (struct lc_hash_ctx ctx, const uint8_t n, size_t nlen, const uint8_t *s, size_t slen)
	Initialize the hash state following the cSHAKE specification.
static void	lc_cshake_final (struct lc_hash_ctx ctx, uint8_t out, size_t outlen)
	Generate a cSHAKE message digest from a given state.
int	lc_cshake_ctx_init (struct lc_cshake_ctx cshake_ctx, const uint8_t n, size_t nlen, const uint8_t *s, size_t slen)
	Initialize the hash state with re-init support following the cSHAKE specification.
void	lc_cshake_ctx_reinit (struct lc_cshake_ctx *cshake_ctx)
	Re-initialize CSHAKE context after a cshake_final operation.
void	lc_cshake_ctx_update (struct lc_cshake_ctx cshake_ctx, const uint8_t in, size_t inlen)
	Update CSHAKE.
void	lc_cshake_ctx_final (struct lc_cshake_ctx cshake_ctx, uint8_t out, size_t outlen)
	Generate a cSHAKE message digest from a given state.
int	lc_cshake_ctx_alloc (const struct lc_hash hash, struct lc_cshake_ctx *cshake_ctx, uint32_t flags)
	Allocate CSHAKE context on heap.
void	lc_cshake_ctx_zero_free (struct lc_cshake_ctx *cshake_ctx)
	Zeroize and free CSHAKE context.
static void	lc_cshake_ctx_zero (struct lc_cshake_ctx *cshake_ctx)
	Zeroize CSHAKE context allocated with either LC_CSHAKE_CTX_ON_STACK or lc_cshake_alloc.

Macro Definition Documentation

◆ LC_CSHAKE_CTX_ON_STACK

#define LC_CSHAKE_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_CSHAKE_CTX_SIZE(hashname),             \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_cshake_ctx *name = (struct lc_cshake_ctx *)name##_ctx_buf;        \
        LC_CSHAKE_SET_CTX(name, hashname);                                          \
        lc_cshake_ctx_zero(name);                                                   \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the CSHAKE 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 239 of file lc_cshake.h.

◆ LC_CSHAKE_CTX_ON_STACK_REINIT

#define LC_CSHAKE_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_CSHAKE_CTX_SIZE_REINIT(hashname),      \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_cshake_ctx *name = (struct lc_cshake_ctx *)name##_ctx_buf;        \
        LC_CSHAKE_SET_CTX_REINIT(name, hashname);                                   \
        lc_cshake_ctx_zero(name);                                                   \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the CSHAKE context.

This allocates the memory with re-initialization support. See CSHAKE_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 262 of file lc_cshake.h.

◆ LC_CSHAKE_FLAGS_SUPPORT_REINIT

#define LC_CSHAKE_FLAGS_SUPPORT_REINIT (1 << 0)

Definition at line 197 of file lc_cshake.h.

Function Documentation

◆ lc_cshake_ctx_alloc()

int lc_cshake_ctx_alloc	(	const struct lc_hash *	hash,
		struct lc_cshake_ctx **	cshake_ctx,
		uint32_t	flags )

Allocate CSHAKE context on heap.

NOTE: This is defined for cshake256 as of now.

Parameters

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

Returns: 0 on success, < 0 on error

◆ lc_cshake_ctx_final()

void lc_cshake_ctx_final	(	struct lc_cshake_ctx *	cshake_ctx,
		uint8_t *	out,
		size_t	outlen )

Generate a cSHAKE message digest from a given state.

The function can be invoked repeatedly to squeeze more data from the cSHAKE state.

Parameters

[in]	cshake_ctx	Initialized hash context
[out]	out	Buffer allocated by caller that is filled with the message digest data.
[in]	outlen	Size of the output buffer to be filled.

◆ lc_cshake_ctx_init()

int lc_cshake_ctx_init	(	struct lc_cshake_ctx *	cshake_ctx,
		const uint8_t *	n,
		size_t	nlen,
		const uint8_t *	s,
		size_t	slen )

Initialize the hash state with re-init support following the cSHAKE specification.

Parameters

[in]	cshake_ctx	Initialized hash context
[in]	n	N is a function-name bit string, used by NIST to define functions based on cSHAKE. When no function other than cSHAKE is desired, N is set to the empty string.
[in]	nlen	Length of n
[in]	s	S is a customization bit string. The user selects this string to define a variant of the function. When no customization is desired, S is set to the empty string.
[in]	slen	Length of s

Returns: 0 on success; < 0 on error

◆ lc_cshake_ctx_reinit()

void lc_cshake_ctx_reinit ( struct lc_cshake_ctx * cshake_ctx )

Re-initialize CSHAKE context after a cshake_final operation.

This operation allows the CSHAKE context to be used again with the same key set during cshake_init.

Parameters

[in] cshake_ctx Reference to cshake context implementation to be used to perform CSHAKE calculation with.

◆ lc_cshake_ctx_update()

void lc_cshake_ctx_update	(	struct lc_cshake_ctx *	cshake_ctx,
		const uint8_t *	in,
		size_t	inlen )

Update CSHAKE.

Parameters

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

◆ lc_cshake_ctx_zero()

void lc_cshake_ctx_zero ( struct lc_cshake_ctx * cshake_ctx )

inlinestatic

Zeroize CSHAKE context allocated with either LC_CSHAKE_CTX_ON_STACK or lc_cshake_alloc.

Parameters

[in] cshake_ctx CSHAKE context to be zeroized

Definition at line 212 of file lc_cshake.h.

◆ lc_cshake_ctx_zero_free()

void lc_cshake_ctx_zero_free ( struct lc_cshake_ctx * cshake_ctx )

Zeroize and free CSHAKE context.

Parameters

[in] cshake_ctx CSHAKE context to be zeroized and freed

◆ lc_cshake_final()

void lc_cshake_final	(	struct lc_hash_ctx *	ctx,
		uint8_t *	out,
		size_t	outlen )

inlinestatic

Generate a cSHAKE message digest from a given state.

The function can be invoked repeatedly to squeeze more data from the cSHAKE state.

Parameters

[in]	ctx	Initialized hash context
[out]	out	Buffer allocated by caller that is filled with the message digest data.
[in]	outlen	Size of the output buffer to be filled.

Definition at line 76 of file lc_cshake.h.

◆ lc_cshake_init()

int lc_cshake_init	(	struct lc_hash_ctx *	ctx,
		const uint8_t *	n,
		size_t	nlen,
		const uint8_t *	s,
		size_t	slen )

Initialize the hash state following the cSHAKE specification.

To invoke cSHAKE, perform the following steps:

lc_cshake_init lc_hash_set_digestsize lc_hash_update ... lc_hash_update lc_hash_final

Or use the helper lc_cshake_final:

lc_cshake_init lc_hash_update ... lc_hash_update lc_cshake_final

Parameters

[in]	ctx	Initialized hash context
[in]	n	N is a function-name bit string, used by NIST to define functions based on cSHAKE. When no function other than cSHAKE is desired, N is set to the empty string.
[in]	nlen	Length of n
[in]	s	S is a customization bit string. The user selects this string to define a variant of the function. When no customization is desired, S is set to the empty string.
[in]	slen	Length of s

Returns: 0 on success; < 0 on error

Macros

Functions

Macro Definition Documentation

◆ LC_CSHAKE_CTX_ON_STACK

◆ LC_CSHAKE_CTX_ON_STACK_REINIT

◆ LC_CSHAKE_FLAGS_SUPPORT_REINIT

Function Documentation

◆ lc_cshake_ctx_alloc()

◆ lc_cshake_ctx_final()

◆ lc_cshake_ctx_init()

◆ lc_cshake_ctx_reinit()

◆ lc_cshake_ctx_update()

◆ lc_cshake_ctx_zero()

◆ lc_cshake_ctx_zero_free()

◆ lc_cshake_final()

◆ lc_cshake_init()