RandState API

Typedefs
typedef struct NoiseRandState_s	NoiseRandState
	Opaque object that represents a random number generator. More...

Functions
int	noise_randstate_free (NoiseRandState *state)
	Frees a RandState object after destroying all sensitive material. More...
int	noise_randstate_generate (NoiseRandState *state, uint8_t *buffer, size_t len)
	Generates random bytes for use by the application. More...
int	noise_randstate_generate_simple (uint8_t *buffer, size_t len)
	Generates random data without first creating a RandState object. More...
int	noise_randstate_new (NoiseRandState **state)
	Creates a new random number generator. More...
int	noise_randstate_pad (NoiseRandState *state, uint8_t *payload, size_t orig_len, size_t padded_len, int padding_mode)
	Adds padding bytes to the end of a message payload. More...
int	noise_randstate_reseed (NoiseRandState *state)
	Reseeds the random number generator from operating system entropy. More...

Detailed Description

The RandState API is provided as a convenience for applications that need to generate extra random data during the course of a higher-level protocol that runs over the Noise protocol.

One use for random data is to pad message payloads to a uniform length prior to encryption. The noise_randstate_pad() function provides a convenient method to do this.

Typedef Documentation

NoiseRandState

Opaque object that represents a random number generator.

Definition at line 33 of file randstate.h.

Function Documentation

int noise_randstate_free

(

NoiseRandState *

state

)

Frees a RandState object after destroying all sensitive material.

Parameters

state

The RandState object to free.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state is NULL.

See Also

noise_randstate_new()

Definition at line 147 of file randstate.c.

int noise_randstate_generate	(	NoiseRandState *	state,
		uint8_t *	buffer,
		size_t	len
	)

Generates random bytes for use by the application.

Parameters

state	The RandState object.
buffer	The buffer to fill with random bytes.
len	The number of random bytes to generate.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or buffer is NULL.

This function will periodically reseed the random number generator from operating system entropy. The application can force a reseed at any time by calling noise_randstate_reseed(), but it is usually better to let the RandState API decide when to reseed on its own.

See Also

noise_randstate_pad(), noise_randstate_reseed(), noise_randstate_generate_simple()

Definition at line 264 of file randstate.c.

int noise_randstate_generate_simple	(	uint8_t *	buffer,
		size_t	len
	)

Generates random data without first creating a RandState object.

Parameters

buffer	The buffer to fill with random bytes.
len	The number of random bytes to generate.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if buffer is NULL.

This function is provided for the convenience of applications that only need to generate a small amount of random data.

See Also

noise_randstate_generate()

Definition at line 391 of file randstate.c.

int noise_randstate_new

(

NoiseRandState **

state

)

Creates a new random number generator.

Parameters

state

Points to the variable where to store the pointer to the new RandState object.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state is NULL.

NOISE_ERROR_NO_MEMORY if there is insufficient memory to allocate the new RandState object.

See Also

noise_randstate_free(), noise_randstate_generate()

Definition at line 115 of file randstate.c.

int noise_randstate_pad	(	NoiseRandState *	state,
		uint8_t *	payload,
		size_t	orig_len,
		size_t	padded_len,
		int	padding_mode
	)

Adds padding bytes to the end of a message payload.

Parameters

state	The RandState object.
payload	Points to the original message payload to be padded, which must be large enough to hold the maximum of orig_len or padded_len.
orig_len	The original length of the payload before padding.
padded_len	The new length of the payload, including the original data and padding.
padding_mode	The padding mode to use, NOISE_PADDING_ZERO or NOISE_PADDING_RANDOM. If the padding mode is unknown, then NOISE_PADDING_RANDOM will be used instead.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or payload is NULL.

This function is intended for padding message payloads prior to them being encrypted with noise_handshakestate_write_message() or noise_cipherstate_encrypt_with_ad(). If the padding_mode is NOISE_PADDING_RANDOM, then the random bytes are generated using noise_randstate_generate().

The number of padding bytes added will be padded_len - orig_len. If padded_len is less than or equal to orig_len, then no padding bytes will be added. Essentially, this function pads the payload to a minimum length. Larger payloads are transmitted as-is.

See Also

noise_cipherstate_rand_bytes()

Definition at line 349 of file randstate.c.

int noise_randstate_reseed

(

NoiseRandState *

state

)

Reseeds the random number generator from operating system entropy.

Parameters

state

The RandState object.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state is NULL.

This function forces the random number generator to fetch fresh entropy from the operating system. Normally this isn't necessary because noise_randstate_generate() will reseed automatically when necessary.

If the application needs to generate a highly critical value such as a new keypair then it may want to force a reseed. Even this isn't necessary for DHState and SignState which already seek fresh operating system entropy when generating keypairs.

See Also

noise_randstate_generate()

Definition at line 177 of file randstate.c.