Key Derivation Functions used with RNG API

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

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 225 of file lc_hkdf.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