Noise-C
 All Data Structures Files Functions Variables Typedefs Macros Groups Pages
Typedefs | Functions
HashState API

Typedefs

typedef struct NoiseHashState_s NoiseHashState
 Opaque object that represents a HashState. More...
 

Functions

int noise_hashstate_finalize (NoiseHashState *state, uint8_t *hash, size_t hash_len)
 Finalizes the hash state and returns the hash value. More...
 
int noise_hashstate_free (NoiseHashState *state)
 Frees a HashState object after destroying all sensitive material. More...
 
size_t noise_hashstate_get_block_length (const NoiseHashState *state)
 Gets the length of the block for a HashState object. More...
 
int noise_hashstate_get_hash_id (const NoiseHashState *state)
 Gets the algorithm identifier for a HashState object. More...
 
size_t noise_hashstate_get_hash_length (const NoiseHashState *state)
 Gets the length of the hash output for a HashState object. More...
 
int noise_hashstate_get_max_block_length (void)
 Gets the maximum block length for the supported algorithms. More...
 
int noise_hashstate_get_max_hash_length (void)
 Gets the maximum hash length for the supported algorithms. More...
 
int noise_hashstate_hash_one (NoiseHashState *state, const uint8_t *data, size_t data_len, uint8_t *hash, size_t hash_len)
 Hashes a single data buffer and returns the hash value. More...
 
int noise_hashstate_hash_two (NoiseHashState *state, const uint8_t *data1, size_t data1_len, const uint8_t *data2, size_t data2_len, uint8_t *hash, size_t hash_len)
 Hashes the concatenation of two data buffers and returns the combined hash value. More...
 
int noise_hashstate_hkdf (NoiseHashState *state, const uint8_t *key, size_t key_len, const uint8_t *data, size_t data_len, uint8_t *output1, size_t output1_len, uint8_t *output2, size_t output2_len)
 Hashes input data with a key to generate two output values. More...
 
int noise_hashstate_new_by_id (NoiseHashState **state, int id)
 Creates a new HashState object by its algorithm identifier. More...
 
int noise_hashstate_new_by_name (NoiseHashState **state, const char *name)
 Creates a new HashState object by its algorithm name. More...
 
int noise_hashstate_pbkdf2 (NoiseHashState *state, const uint8_t *passphrase, size_t passphrase_len, const uint8_t *salt, size_t salt_len, size_t iterations, uint8_t *output, size_t output_len)
 Hashes a passphrase and salt using the PBKDF2 key derivation function. More...
 
int noise_hashstate_reset (NoiseHashState *state)
 Resets the hash state. More...
 
int noise_hashstate_update (NoiseHashState *state, const uint8_t *data, size_t data_len)
 Updates the hash state with more data. More...
 

Detailed Description

The HashState API provides access to the hash algorithms within the library. Normally applications won't need to use these functions directly because SymmetricState takes care of hashing operations for the Noise protocol internally.

These functions are provided mainly for testing purposes. However, applications can use them if they need to hash values for some higher-level protocol purpose. This may be preferable to the application having to source its own hash implementations for that purpose.

Typedef Documentation

Opaque object that represents a HashState.

Definition at line 33 of file hashstate.h.

Function Documentation

int noise_hashstate_finalize ( NoiseHashState state,
uint8_t *  hash,
size_t  hash_len 
)

Finalizes the hash state and returns the hash value.

Parameters
stateThe HashState object.
hashThe return buffer for the hash value.
hash_lenThe length of the hash buffer in bytes.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or hash is NULL.
NOISE_ERROR_INVALID_LENGTH if hash_len is not the same as the hash length for the algorithm.
See Also
noise_hashstate_reset(), noise_hashstate_update(), noise_hashstate_get_hash_length()

Definition at line 272 of file hashstate.c.

int noise_hashstate_free ( NoiseHashState state)

Frees a HashState object after destroying all sensitive material.

Parameters
stateThe HashState object to free.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state is NULL.
See Also
noise_hashstate_new_by_id(), noise_hashstate_new_by_name()

Definition at line 156 of file hashstate.c.

size_t noise_hashstate_get_block_length ( const NoiseHashState state)

Gets the length of the block for a HashState object.

Parameters
stateThe HashState object.
Returns
The size of the block in bytes, or 0 if state is NULL.
See Also
noise_hashstate_get_hash_length()

Definition at line 206 of file hashstate.c.

int noise_hashstate_get_hash_id ( const NoiseHashState state)

Gets the algorithm identifier for a HashState object.

Parameters
stateThe HashState object.
Returns
The algorithm identifier, or NOISE_HASH_NONE if state is NULL.

Definition at line 178 of file hashstate.c.

size_t noise_hashstate_get_hash_length ( const NoiseHashState state)

Gets the length of the hash output for a HashState object.

Parameters
stateThe HashState object.
Returns
The size of the hash in bytes, or 0 if state is NULL.
See Also
noise_hashstate_get_block_length()

Definition at line 192 of file hashstate.c.

int noise_hashstate_get_max_block_length ( void  )

Gets the maximum block length for the supported algorithms.

See Also
noise_hashstate_get_max_hash_length()

Definition at line 613 of file hashstate.c.

int noise_hashstate_get_max_hash_length ( void  )

Gets the maximum hash length for the supported algorithms.

See Also
noise_hashstate_get_max_block_length()

Definition at line 603 of file hashstate.c.

int noise_hashstate_hash_one ( NoiseHashState state,
const uint8_t *  data,
size_t  data_len,
uint8_t *  hash,
size_t  hash_len 
)

Hashes a single data buffer and returns the hash value.

Parameters
stateThe HashState object.
dataPoints to the data to be hashed.
data_lenThe length of the data in bytes.
hashThe return buffer for the hash value.
hash_lenThe length of the hash buffer in bytes.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if one of state, data, or hash is NULL.
NOISE_ERROR_INVALID_LENGTH if hash_len is not the same as the hash length for the algorithm.

The data and hash buffers are allowed to overlap.

This is a convenience function that combines the effect of noise_hashstate_reset(), nose_hashstate_update(), and noise_hashstate_finalize().

See Also
noise_hashstate_hash_two(), noise_hashstate_get_hash_length()

Definition at line 309 of file hashstate.c.

int noise_hashstate_hash_two ( NoiseHashState state,
const uint8_t *  data1,
size_t  data1_len,
const uint8_t *  data2,
size_t  data2_len,
uint8_t *  hash,
size_t  hash_len 
)

Hashes the concatenation of two data buffers and returns the combined hash value.

Parameters
stateThe HashState object.
data1Points to the first data buffer to be hashed.
data1_lenThe length of the first data buffer in bytes.
data2Points to the second data buffer to be hashed.
data2_lenThe length of the second data buffer in bytes.
hashThe return buffer for the hash value.
hash_lenThe length of the hash buffer in bytes.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if one of state, data1, data2, or hash is NULL.
NOISE_ERROR_INVALID_LENGTH if hash_len is not the same as the hash length for the algorithm.

The data1, data2, and hash buffers are allowed to overlap.

This is a convenience function that combines the effect of noise_hashstate_reset(), nose_hashstate_update(), and noise_hashstate_finalize().

See Also
noise_hashstate_hash_one(), noise_hashstate_get_hash_length()

Definition at line 352 of file hashstate.c.

int noise_hashstate_hkdf ( NoiseHashState state,
const uint8_t *  key,
size_t  key_len,
const uint8_t *  data,
size_t  data_len,
uint8_t *  output1,
size_t  output1_len,
uint8_t *  output2,
size_t  output2_len 
)

Hashes input data with a key to generate two output values.

Parameters
stateThe HashState object.
keyPoints to the key.
key_lenThe length of the key in bytes.
dataPoints to the data.
data_lenThe length of the data in bytes.
output1The first output buffer to fill.
output1_lenThe length of the first output buffer, which may be shorter than the hash length of the HashState object.
output2The second output buffer to fill.
output2_lenThe length of the second output buffer, which may be shorter than the hash length of the HashState object.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if one of state, key, data, output1, or output2 is NULL.
NOISE_ERROR_INVALID_LENGTH if output1_len or output2_len is greater than the hash length for the HashState object.

Reference: RFC 5868

See Also
noise_hashstate_hash_one()

Definition at line 477 of file hashstate.c.

int noise_hashstate_new_by_id ( NoiseHashState **  state,
int  id 
)

Creates a new HashState object by its algorithm identifier.

Parameters
statePoints to the variable where to store the pointer to the new HashState object.
idThe algorithm identifier; NOISE_HASH_BLAKE2s, NOISE_HASH_SHA256, etc.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state is NULL.
NOISE_ERROR_UNKNOWN_ID if id is unknown.
NOISE_ERROR_NO_MEMORY if there is insufficient memory to allocate the new HashState object.
See Also
noise_hashstate_free(), noise_hashstate_new_by_name()

Definition at line 73 of file hashstate.c.

int noise_hashstate_new_by_name ( NoiseHashState **  state,
const char *  name 
)

Creates a new HashState object by its algorithm name.

Parameters
statePoints to the variable where to store the pointer to the new HashState object.
nameThe name of the cipher algorithm; e.g. "BLAKE2s", "SHA256", etc. This string must be NUL-terminated.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or name is NULL.
NOISE_ERROR_UNKNOWN_NAME if name is unknown.
NOISE_ERROR_NO_MEMORY if there is insufficient memory to allocate the new HashState object.
See Also
noise_hashstate_free(), noise_hashstate_new_by_id()

Definition at line 126 of file hashstate.c.

int noise_hashstate_pbkdf2 ( NoiseHashState state,
const uint8_t *  passphrase,
size_t  passphrase_len,
const uint8_t *  salt,
size_t  salt_len,
size_t  iterations,
uint8_t *  output,
size_t  output_len 
)

Hashes a passphrase and salt using the PBKDF2 key derivation function.

Parameters
stateThe HashState object.
passphrasePoints to the passphrase.
passphrase_lenThe length of the passphrase in bytes.
saltPoints to the salt.
salt_lenThe length of the salt in bytes.
iterationsThe number of hash iterations to use.
outputThe output buffer to put the final hash into.
output_lenThe length of the output in bytes.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if one of state, passphrase, salt, or output is NULL.
NOISE_ERROR_INVALID_LENGTH if the output_len is too large for valid PBKDF2 output.

This function is intended as a utility for applications that need to hash a passphrase to encrypt private keys and other sensitive information.

Reference: RFC 2898

Definition at line 542 of file hashstate.c.

int noise_hashstate_reset ( NoiseHashState state)

Resets the hash state.

Parameters
stateThe HashState object.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state is NULL.
See Also
noise_hashstate_update(), noise_hashstate_finalize()

Definition at line 221 of file hashstate.c.

int noise_hashstate_update ( NoiseHashState state,
const uint8_t *  data,
size_t  data_len 
)

Updates the hash state with more data.

Parameters
stateThe HashState object.
dataThe new data to incorporate into the hash state.
data_lenThe length of the data in bytes.
Returns
NOISE_ERROR_NONE on success.
NOISE_ERROR_INVALID_PARAM if state or data is NULL.
See Also
noise_hashstate_reset(), noise_hashstate_finalize()

Definition at line 245 of file hashstate.c.