Message Digest and XOF Support

Macros
#define	LC_HASH_CTX_ON_STACK(name, hashname)
	Allocate stack memory for the hash context.

Functions
static void	lc_hash_init (struct lc_hash_ctx *hash_ctx)
	Initialize hash context.
static void	lc_hash_update (struct lc_hash_ctx *hash_ctx, const uint8_t *in, size_t inlen)
	Update hash.
static void	lc_hash_final (struct lc_hash_ctx *hash_ctx, uint8_t *digest)
	Calculate message digest.
static void	lc_hash_set_digestsize (struct lc_hash_ctx *hash_ctx, size_t digestsize)
	Set the size of the message digest - this call is intended for SHAKE.
static size_t	lc_hash_digestsize (struct lc_hash_ctx *hash_ctx)
	Get the size of the message digest.
static unsigned int	lc_hash_blocksize (struct lc_hash_ctx *hash_ctx)
	Get the block size of the message digest (or the "rate" in terms of Sponge-based algorithms)
static unsigned int	lc_hash_ctxsize (struct lc_hash_ctx *hash_ctx)
	Get the context size of the message digest implementation.
static void	lc_hash_zero (struct lc_hash_ctx *hash_ctx)
	Zeroize Hash context allocated with either LC_HASH_CTX_ON_STACK or lc_hmac_alloc.
int	lc_hash_alloc (const struct lc_hash *hash, struct lc_hash_ctx **hash_ctx)
	Allocate Hash context on heap.
void	lc_hash_zero_free (struct lc_hash_ctx *hash_ctx)
	Zeroize and free hash context.
void	lc_hash (const struct lc_hash *hash, const uint8_t *in, size_t inlen, uint8_t *digest)
	Calculate message digest - one-shot.
void	lc_xof (const struct lc_hash *xof, const uint8_t *in, size_t inlen, uint8_t *digest, size_t digestlen)
	Calculate message digest for an XOF - one-shot.
static int	lc_sponge (const struct lc_hash *hash, void *state, unsigned int rounds)
	Perform Sponge permutation on buffer.
static int	lc_sponge_add_bytes (const struct lc_hash *hash, void *state, const uint8_t *data, size_t offset, size_t length)
	Function to add (in GF(2), using bitwise exclusive-or) data given as bytes into the sponge state.
static int	lc_sponge_extract_bytes (const struct lc_hash *hash, const void *state, uint8_t *data, size_t offset, size_t length)
	Function to retrieve data from the state. The bit positions that are retrieved by this function are from offset*8 to offset*8 + length*8.
static int	lc_sponge_newstate (const struct lc_hash *hash, void *state, const uint8_t *data, size_t offset, size_t length)
	Function to insert a complete new sponge state.

Detailed Description

Concept of hashes in leancrypto

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

1. Allocation: Use the stack or heap allocation functions documented in lc_cshake.h, lc_sha3.h, lc_sha256.h, lc_sha512.h, lc_ascon_hash.h.
2. Use the returned cipher handle with the API calls below.

Macro Definition Documentation

LC_HASH_CTX_ON_STACK

#define LC_HASH_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_HASH_CTX_SIZE(hashname),               \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_hash_ctx *name = (struct lc_hash_ctx *)name##_ctx_buf;            \
        LC_HASH_SET_CTX(name, hashname);                                            \
        lc_hash_zero(name);                                                         \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the hash context.

Parameters

[in]	name	Name of the stack variable
[in]	hashname	Pointer of type struct hash referencing the hash implementation to be used - see lc_sha256.h, lc_sha3.h, lc_sha512.h, lc_ascon_hash.h

Definition at line 307 of file lc_hash.h.

Function Documentation

lc_hash()

void lc_hash	(	const struct lc_hash *	hash,
		const uint8_t *	in,
		size_t	inlen,
		uint8_t *	digest )

Calculate message digest - one-shot.

Parameters

[in]	hash	Reference to hash implementation to be used to perform hash calculation with - see lc_sha256.h, lc_sha3.h, lc_sha512.h, lc_ascon_hash.h
[in]	in	Buffer holding the data whose MAC shall be calculated
[in]	inlen	Length of the input buffer
[out]	digest	Buffer with at least the size of the message digest.

The hash calculation operates entirely on the stack.

lc_hash_alloc()

int lc_hash_alloc	(	const struct lc_hash *	hash,
		struct lc_hash_ctx **	hash_ctx )

Allocate Hash context on heap.

Parameters

[in]	hash	Reference to hash implementation to be used to perform hash calculation with - see lc_sha256.h, lc_sha3.h, lc_sha512.h, lc_ascon_hash.h
[out]	hash_ctx	Allocated hash context

Returns

: 0 on success, < 0 on error

lc_hash_blocksize()

static unsigned int lc_hash_blocksize ( struct lc_hash_ctx * hash_ctx )

inlinestatic

Get the block size of the message digest (or the "rate" in terms of Sponge-based algorithms)

Parameters

[in]

hash_ctx

Reference to hash context implementation to be used to perform hash calculation with.

Definition at line 250 of file lc_hash.h.

lc_hash_ctxsize()

static unsigned int lc_hash_ctxsize ( struct lc_hash_ctx * hash_ctx )

inlinestatic

Get the context size of the message digest implementation.

Parameters

[in]

hash_ctx

Reference to hash context implementation to be used to perform hash calculation with.

Definition at line 268 of file lc_hash.h.

lc_hash_digestsize()

static size_t lc_hash_digestsize ( struct lc_hash_ctx * hash_ctx )

inlinestatic

Get the size of the message digest.

Parameters

[in]

hash_ctx

Reference to hash context implementation to be used to perform hash calculation with.

Definition at line 231 of file lc_hash.h.

lc_hash_final()

static void lc_hash_final ( struct lc_hash_ctx * hash_ctx, uint8_t * digest )

inlinestatic

Calculate message digest.

For SHAKE, it is permissible to calculate the final digest in chunks by invoking the message digest calculation multiple times. The following code example illustrates it:

size_t outlen = full_size;
 
lc_hash_init(ctx);
lc_hash_update(ctx, msg, msg_len);
// Set an arbitrary digest size as needed
lc_hash_set_digestsize(ctx, 42);
for (len = outlen; len > 0;
     len -= lc_hash_digestsize(ctx),
     out += lc_hash_digestsize(ctx)) {
         if (len < lc_hash_digestsize(ctx))
                 lc_hash_set_digestsize(ctx, len);
         lc_hash_final(ctx, out);
}

See the test shake_squeeze_more_tester.c for an example.

Parameters

[in]	hash_ctx	Reference to hash context implementation to be used to perform hash calculation with.
[out]	digest	Buffer with at least the size of the message digest.

Definition at line 192 of file lc_hash.h.

lc_hash_init()

static void lc_hash_init ( struct lc_hash_ctx * hash_ctx )

inlinestatic

Initialize hash context.

Parameters

[in]

hash_ctx

Reference to hash context implementation to be used to perform hash calculation with.

The caller must provide an allocated hash_ctx. This can be achieved by using LC_HASH_CTX_ON_STACK or by using hash_alloc.

Definition at line 130 of file lc_hash.h.

lc_hash_set_digestsize()

static void lc_hash_set_digestsize ( struct lc_hash_ctx * hash_ctx, size_t digestsize )

inlinestatic

Set the size of the message digest - this call is intended for SHAKE.

Parameters

[in]	hash_ctx	Reference to hash context implementation to be used to perform hash calculation with.
[in]	digestsize	Size of the requested digest.

Definition at line 211 of file lc_hash.h.

lc_hash_update()

static void lc_hash_update ( struct lc_hash_ctx * hash_ctx, const uint8_t * in, size_t inlen )

inlinestatic

Update hash.

Parameters

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

Definition at line 150 of file lc_hash.h.

lc_hash_zero()

static void lc_hash_zero ( struct lc_hash_ctx * hash_ctx )

inlinestatic

Zeroize Hash context allocated with either LC_HASH_CTX_ON_STACK or lc_hmac_alloc.

Parameters

[in]

hash_ctx

Hash context to be zeroized

Definition at line 286 of file lc_hash.h.

lc_hash_zero_free()

void lc_hash_zero_free

(

struct lc_hash_ctx *

hash_ctx

)

Zeroize and free hash context.

Parameters

[in]

hash_ctx

hash context to be zeroized and freed

lc_sponge()

static int lc_sponge ( const struct lc_hash * hash, void * state, unsigned int rounds )

inlinestatic

Perform Sponge permutation on buffer.

Warning

This call does NOT constitute a hash. It is ONLY a raw sponge permutation with the accelerated implementation of the given hash reference. If you do not understand this comment, you MUST NOT use this interface.

Parameters

[in]	hash	Reference to hash implementation to be used to perform Sponge calculation with - see lc_sha3.h, lc_ascon_hash.h
[in]	state	State buffer of 200 bytes (Keccak) or 320 bits (Ascon) aligned to LC_HASH_COMMON_ALIGNMENT.
[in]	rounds	Number of sponge rounds - may be ignored by sponge implementation

Returns

: 0 on success, < 0 on error

Definition at line 390 of file lc_hash.h.

lc_sponge_add_bytes()

static int lc_sponge_add_bytes ( const struct lc_hash * hash, void * state, const uint8_t * data, size_t offset, size_t length )

inlinestatic

Function to add (in GF(2), using bitwise exclusive-or) data given as bytes into the sponge state.

The bit positions that are affected by this function are from offset*8 to offset*8 + length*8.

Parameters

[in]	hash	Reference to hash implementation to be used to perform Sponge calculation with - see lc_sha3.h, lc_ascon_hash.h
[in]	state	Pointer to the state.
[in]	data	Pointer to the input data.
[in]	offset	Offset in bytes within the state.
[in]	length	Number of bytes.

Warning

The caller is responsible that offset / length points to data within the state (within the size of LC_SHA3_STATE_SIZE for Keccak or LC_ASCON_HASH_STATE_SIZE for Ascon).

Precondition

0 ≤ offset < (width in bytes)

0 ≤ offset + length ≤ (width in bytes)

Returns

: 0 on success, < 0 on error

Definition at line 425 of file lc_hash.h.

lc_sponge_extract_bytes()

static int lc_sponge_extract_bytes ( const struct lc_hash * hash, const void * state, uint8_t * data, size_t offset, size_t length )

inlinestatic

Function to retrieve data from the state. The bit positions that are retrieved by this function are from offset*8 to offset*8 + length*8.

Parameters

[in]	hash	Reference to hash implementation to be used to perform sponge calculation with - see lc_sha3.h, lc_ascon_hash.h
[in]	state	Pointer to the state.
[out]	data	Pointer to the area where to store output data.
[in]	offset	Offset in bytes within the state.
[in]	length	Number of bytes.

Warning

The caller is responsible that offset / length points to data within the state (within the size of LC_SHA3_STATE_SIZE for Keccak or LC_ASCON_HASH_STATE_SIZE for Ascon).

Precondition

0 ≤ offset < (width in bytes)

0 ≤ offset + length ≤ (width in bytes)

Returns

: 0 on success, < 0 on error

Definition at line 459 of file lc_hash.h.

lc_sponge_newstate()

static int lc_sponge_newstate ( const struct lc_hash * hash, void * state, const uint8_t * data, size_t offset, size_t length )

inlinestatic

Function to insert a complete new sponge state.

Parameters

[in]	hash	Reference to hash implementation to be used to perform sponge calculation with - see lc_sha3.h, lc_ascon_hash.h
[in]	state	Pointer to the state.
[out]	data	Pointer to new state
[in]	offset	Offset in bytes within the state.
[in]	length	Number of bytes.

Warning

The caller is responsible that offset / length points to data within the state (within the size of LC_SHA3_STATE_SIZE for Keccak or LC_ASCON_HASH_STATE_SIZE for Ascon).

Returns

: 0 on success, < 0 on error

Definition at line 488 of file lc_hash.h.

lc_xof()

void lc_xof	(	const struct lc_hash *	xof,
		const uint8_t *	in,
		size_t	inlen,
		uint8_t *	digest,
		size_t	digestlen )

Calculate message digest for an XOF - one-shot.

Parameters

[in]	xof	Reference to hash implementation to be used to perform hash calculation with - see lc_sha3.h, lc_ascon_hash.h
[in]	in	Buffer holding the data whose MAC shall be calculated
[in]	inlen	Length of the input buffer
[out]	digest	Buffer with at least the size of the message digest.
[in]	digestlen	Size of the message digest to calculate.

The hash calculation operates entirely on the stack.