Noise-C
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Typedefs | Functions
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

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
stateThe 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
stateThe RandState object.
bufferThe buffer to fill with random bytes.
lenThe 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
bufferThe buffer to fill with random bytes.
lenThe 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
statePoints 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
stateThe RandState object.
payloadPoints to the original message payload to be padded, which must be large enough to hold the maximum of orig_len or padded_len.
orig_lenThe original length of the payload before padding.
padded_lenThe new length of the payload, including the original data and padding.
padding_modeThe 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
stateThe 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.