Message Digest and XOF Support

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

Functions
int	lc_hash_init (struct lc_hash_ctx *hash_ctx)
	Initialize hash context.
void	lc_hash_update (struct lc_hash_ctx *hash_ctx, const uint8_t *in, size_t inlen)
	Update hash.
void	lc_hash_final (struct lc_hash_ctx *hash_ctx, uint8_t *digest)
	Calculate message digest.
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.
size_t	lc_hash_digestsize (struct lc_hash_ctx *hash_ctx)
	Get the size of the message digest.
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).
unsigned int	lc_hash_ctxsize (struct lc_hash_ctx *hash_ctx)
	Get the context size of the message digest implementation.
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.
int	lc_hash (const struct lc_hash *hash, const uint8_t *in, size_t inlen, uint8_t *digest)
	Calculate message digest - one-shot.
int	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.
int	lc_sponge (const struct lc_hash *hash, void *state, unsigned int rounds)
	Perform Sponge permutation on buffer.
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.
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.
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.
uint64_t	lc_hash_algorithm_type (const struct lc_hash *hash)
	Obtain algorithm type usable with lc_alg_status.
uint64_t	lc_hash_ctx_algorithm_type (const struct lc_hash_ctx *ctx)
	Obtain algorithm type usable with lc_alg_status.

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);                                            \
        _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 236 of file lc_hash.h.

Function Documentation

lc_hash()

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

Returns

0 on success; < 0 on error

lc_hash_algorithm_type()

uint64_t lc_hash_algorithm_type

(

const struct lc_hash *

hash

)

Obtain algorithm type usable with lc_alg_status.

Parameters

[in]

hash

Hash algorithm instance

Returns

algorithm type

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

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

Parameters

[in]

hash_ctx

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

lc_hash_ctx_algorithm_type()

uint64_t lc_hash_ctx_algorithm_type

(

const struct lc_hash_ctx *

ctx

)

Obtain algorithm type usable with lc_alg_status.

Parameters

[in]

ctx

Hash context handle

Returns

algorithm type

lc_hash_ctxsize()

unsigned int lc_hash_ctxsize

(

struct lc_hash_ctx *

hash_ctx

)

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.

lc_hash_digestsize()

size_t lc_hash_digestsize

(

struct lc_hash_ctx *

hash_ctx

)

Get the size of the message digest.

Parameters

[in]

hash_ctx

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

lc_hash_final()

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

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.

lc_hash_init()

int lc_hash_init

(

struct lc_hash_ctx *

hash_ctx

)

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.

Returns

0 on success; < 0 on error

lc_hash_set_digestsize()

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.

Parameters

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

lc_hash_update()

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

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

lc_hash_zero()

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.

Parameters

[in]

hash_ctx

Hash context to be zeroized

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

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

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

lc_sponge_add_bytes()

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.

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

lc_sponge_extract_bytes()

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.

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

lc_sponge_newstate()

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.

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

lc_xof()

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

Returns

0 on success; < 0 on error