Key Derivation Functions used with RNG API

Macros
#define	LC_KMAC_KDF_DRNG_CTX_ON_STACK(name, hashname)
	Allocate stack memory for the KMAC DRNG context.
#define	LC_HKDF_DRNG_CTX_ON_STACK(name, hashname)
	Allocate stack memory for the HKDF DRNG context.
#define	LC_CTR_KDF_DRNG_CTX_ON_STACK(name, hashname)
	Allocate stack memory for the Counter KDF DRNG context.

Functions
int	lc_kmac_rng_alloc (struct lc_rng_ctx **state, const struct lc_hash *hash)
	Allocation of a KMAC DRNG context.
int	lc_hkdf_rng_alloc (struct lc_rng_ctx **state, const struct lc_hash *hash)
	Allocation of a HKDF DRNG context.
int	lc_kdf_ctr_rng_alloc (struct lc_rng_ctx **state, const struct lc_hash *hash)
	Allocation of a Counter KDF DRNG context.

Variables
const struct lc_rng *	lc_kmac_rng

Detailed Description

The HKDF can be used as an RNG context for aggregated algorithms like Kyber or Dilithium. The idea is that the KDF state can be initialized from an input data to deterministically derive the values required for the algorithms the RNG context is used with.

Macro Definition Documentation

LC_CTR_KDF_DRNG_CTX_ON_STACK

#define LC_CTR_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_CTR_KDF_DRNG_CTX_SIZE(hashname),       \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_rng_ctx *name = (struct lc_rng_ctx *)name##_ctx_buf;              \
        LC_CTR_KDF_RNG_CTX(name, hashname);                                         \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the Counter KDF DRNG context.

Parameters

[in]	name	Name of the stack variable
[in]	hashname	Reference to lc_hash implementation used for CTR KDF

Warning

You MUST seed the DRNG!

Definition at line 131 of file lc_kdf_ctr.h.

LC_HKDF_DRNG_CTX_ON_STACK

#define LC_HKDF_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_HKDF_DRNG_CTX_SIZE(hashname),          \
                                          LC_HASH_COMMON_ALIGNMENT);                \
        struct lc_rng_ctx *name = (struct lc_rng_ctx *)name##_ctx_buf;              \
        LC_HKDF_RNG_CTX(name, hashname);                                            \
        _Pragma("GCC diagnostic pop")

Allocate stack memory for the HKDF DRNG context.

Parameters

[in]	name	Name of the stack variable
[in]	hashname	Reference to lc_hash implementation used for HKDF

Warning

You MUST seed the DRNG!

Definition at line 202 of file lc_hkdf.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.

Warning

You MUST seed the DRNG!

Definition at line 344 of file lc_kmac.h.

Function Documentation

lc_hkdf_rng_alloc()

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

Allocation of a HKDF DRNG context.

Parameters

[out]	state	HKDF DRNG context allocated by the function
[in]	hash	Reference to lc_hash implementation used for HKDF

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.

Warning

You MUST seed the DRNG!

Returns

0 upon success; < 0 on error

lc_kdf_ctr_rng_alloc()

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

Allocation of a Counter KDF DRNG context.

Parameters

[out]	state	Counter KDF DRNG context allocated by the function
[in]	hash	Reference to lc_hash implementation used for CTR KDF

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.

Warning

You MUST seed the DRNG!

Returns

0 upon success; < 0 on error

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.

Warning

You MUST seed the DRNG!

Returns

0 upon success; < 0 on error

Variable Documentation

lc_kmac_rng

const struct lc_rng* lc_kmac_rng

extern

The KMAC can be used as an RNG context for aggregated algorithms like Kyber or Dilithium. The idea is that KMAC acts as a key derivation function whose state can be initialized from an input data to deterministically derive the values required for the algorithms the RNG context is used with.

This RNG state is NOT intended to serve as a general-purpose deterministic random number generator. For using KMAC as a such general-purpose DRNG, see the API provided with lc_kmac256_drng.h.