Random Number Generation

Functions
void	lc_rng_check (struct lc_rng_ctx **ctx)
	Get the default leancrypto RNG.
void	lc_rng_zero (struct lc_rng_ctx *ctx)
	Zeroize RNG context.
void	lc_rng_zero_free (struct lc_rng_ctx *ctx)
	Zeroize and free RNG context.
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.
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
int	lc_rng_set_seeded (struct lc_rng_ctx *new_ctx)
	Set an externally defined RNG as the seeded RNG.
uint64_t	lc_rng_algorithm_type (const struct lc_rng *rng)
	Obtain algorithm type usable with lc_alg_status.

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

uint64_t lc_rng_algorithm_type

(

const struct lc_rng *

rng

)

Obtain algorithm type usable with lc_alg_status.

Parameters

[in]

rng

RNG algorithm instance

Returns

algorithm type

lc_rng_check()

void lc_rng_check

(

struct lc_rng_ctx **

ctx

)

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.

lc_rng_generate()

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.

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

lc_rng_seed()

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

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

lc_rng_set_seeded()

int lc_rng_set_seeded

(

struct lc_rng_ctx *

new_ctx

)

Set an externally defined RNG as the seeded RNG.

This call can be performed at any time and any subsequent operation of the leancrypto library service function will use this RNG when drawing new random numbers.

Note

Leancrypto expects the externally defined RNG instance to be fully seeded at all times. The external RNG is responsible for its initialization, initial seed, and reseed. Also, that RNG is responsible for selecting and managing the entropy source(s).

Parameters

[in]

new_ctx

externally defined RNG cipher handle - when using NULL then the leancrypto-internal fully seeded RNG used (again).

Returns

0 upon success; < 0 on error

lc_rng_zero()

void lc_rng_zero

(

struct lc_rng_ctx *

ctx

)

Zeroize RNG context.

Parameters

[in]

ctx

RNG context to be zeroized

lc_rng_zero_free()

void lc_rng_zero_free

(

struct lc_rng_ctx *

ctx

)

Zeroize and free RNG context.

Parameters

[in]

ctx

RNG context to be zeroized and freed

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.