Random Number Generation

Functions
static void	lc_rng_check (struct lc_rng_ctx **ctx)
	Get the default leancrypto RNG.
static void	lc_rng_zero (struct lc_rng_ctx *ctx)
	Zeroize RNG context.
static void	lc_rng_zero_free (struct lc_rng_ctx *ctx)
	Zeroize and free RNG context.
static int	lc_rng_generate (struct lc_rng_ctx *ctx, const uint8_t *addtl_input, size_t addtl_input_len, uint8_t *out, size_t outlen)
	Obtain random numbers.
static int	lc_rng_seed (struct lc_rng_ctx *ctx, const uint8_t *seed, size_t seedlen, const uint8_t *persbuf, size_t perslen)
	(Re)Seed the RNG

Variables
struct lc_rng_ctx *	lc_seeded_rng
	One common instance of a seeded DRNG. The caller does not need to consider the seeding and reseeding - it is automatically and transparently handled. Thus, this structure can be directly used for the lc_rng API by a caller and have a properly seeded DRNG.

Detailed Description

Concept of RNGs in leancrypto

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

1. Allocation: Use the stack or heap allocation functions documented in lc_xdrbg.h, lc_cshake256_drng.h, lc_kmac256_drng.h, lc_hash_drbg.h, lc_hmac_sha512.h.
2. Use the returned cipher handle with the API calls below.

Function Documentation

lc_rng_check()

static void lc_rng_check ( struct lc_rng_ctx ** ctx )

inlinestatic

Get the default leancrypto RNG.

Parameters

[in,out]

ctx

Random Number Generator context to analyze

The function checks if an RNG was already provided and only returns the default RNG context if none was provided.

Definition at line 85 of file lc_rng.h.

lc_rng_generate()

static int lc_rng_generate ( struct lc_rng_ctx * ctx, const uint8_t * addtl_input, size_t addtl_input_len, uint8_t * out, size_t outlen )

inlinestatic

Obtain random numbers.

Parameters

[in]	ctx	allocated RNG cipher handle
[in]	addtl_input	Additional input to diversify state
[in]	addtl_input_len	Length of additional input buffer
[out]	out	allocated buffer that is to be filled with random numbers
[in]	outlen	length of out indicating the size of the random number byte string to be generated

Generate random numbers and fill the buffer provided by the caller.

Returns

0 upon success; < 0 on error

Definition at line 143 of file lc_rng.h.

lc_rng_seed()

static int lc_rng_seed ( struct lc_rng_ctx * ctx, const uint8_t * seed, size_t seedlen, const uint8_t * persbuf, size_t perslen )

inlinestatic

(Re)Seed the RNG

Parameters

[in]	ctx	allocated RNG cipher handle
[in]	seed	buffer with the seed data
[in]	seedlen	length of seed
[in]	persbuf	Personalization / additional information buffer - may be NULL
[in]	perslen	Length of personalization / additional information buffer

When calling the function, the DRNG is seeded or reseeded. If it is reseeded, the old state information is mixed into the new state.

Returns

0 upon success; < 0 on error

Definition at line 177 of file lc_rng.h.

lc_rng_zero()

static void lc_rng_zero ( struct lc_rng_ctx * ctx )

inlinestatic

Zeroize RNG context.

Parameters

[in]

ctx

RNG context to be zeroized

Definition at line 99 of file lc_rng.h.

lc_rng_zero_free()

static void lc_rng_zero_free ( struct lc_rng_ctx * ctx )

inlinestatic

Zeroize and free RNG context.

Parameters

[in]

ctx

RNG context to be zeroized and freed

Definition at line 119 of file lc_rng.h.

Variable Documentation

lc_seeded_rng

struct lc_rng_ctx* lc_seeded_rng

extern

One common instance of a seeded DRNG. The caller does not need to consider the seeding and reseeding - it is automatically and transparently handled. Thus, this structure can be directly used for the lc_rng API by a caller and have a properly seeded DRNG.

NOTE: The caller must ensure that a lock is applied around the use of this variable if there is the potential of concurrent use.