Typedefs
typedef struct NoiseDHState_s	NoiseDHState
	Opaque object that represents a DHState. More...

Functions
int	noise_dhstate_calculate (const NoiseDHState private_key_state, const NoiseDHState public_key_state, uint8_t *shared_key, size_t shared_key_len)
	Performs a Diffie-Hellman calculation. More...

int	noise_dhstate_clear_key (NoiseDHState *state)
	Clears the key in a DHState object. More...

int	noise_dhstate_copy (NoiseDHState state, const NoiseDHState from)
	Copies the keys from one DHState object to another. More...

int	noise_dhstate_format_fingerprint (const NoiseDHState state, int fingerprint_type, char buffer, size_t len)
	Formats the public key fingerprint for the key within a DHState. More...

int	noise_dhstate_free (NoiseDHState *state)
	Frees a DHState object after destroying all sensitive material. More...

int	noise_dhstate_generate_dependent_keypair (NoiseDHState state, const NoiseDHState other)
	Generates a new key pair within a DHState object that may depend upon the parameters from another DHState object. More...

int	noise_dhstate_generate_keypair (NoiseDHState *state)
	Generates a new key pair within a DHState object. More...

int	noise_dhstate_get_dh_id (const NoiseDHState *state)
	Gets the algorithm identifier for a DHState object. More...

int	noise_dhstate_get_keypair (const NoiseDHState state, uint8_t private_key, size_t private_key_len, uint8_t *public_key, size_t public_key_len)
	Gets the keypair from within a DHState object. More...

size_t	noise_dhstate_get_private_key_length (const NoiseDHState *state)
	Gets the length of the private key for a DHState object. More...

int	noise_dhstate_get_public_key (const NoiseDHState state, uint8_t public_key, size_t public_key_len)
	Gets the public key value from a DHState object. More...

size_t	noise_dhstate_get_public_key_length (const NoiseDHState *state)
	Gets the length of the public key for a DHState object. More...

int	noise_dhstate_get_role (const NoiseDHState *state)
	Gets the role that a DHState object will play in a handshake. More...

size_t	noise_dhstate_get_shared_key_length (const NoiseDHState *state)
	Gets the length of the shared key for a DHState object. More...

int	noise_dhstate_has_keypair (const NoiseDHState *state)
	Determine if a DHState object contains a keypair. More...

int	noise_dhstate_has_public_key (const NoiseDHState *state)
	Determine if a DHState object contains a public key. More...

int	noise_dhstate_is_ephemeral_only (const NoiseDHState *state)
	Determine if a DHState object only supports ephemeral keys. More...

int	noise_dhstate_is_null_public_key (const NoiseDHState *state)
	Determine if the public key in a DHState object has the special null value. More...

int	noise_dhstate_new_by_id (NoiseDHState **state, int id)
	Creates a new DHState object by its algorithm identifier. More...

int	noise_dhstate_new_by_name (NoiseDHState *state, const char name)
	Creates a new DHState object by its algorithm name. More...

int	noise_dhstate_set_keypair (NoiseDHState state, const uint8_t private_key, size_t private_key_len, const uint8_t *public_key, size_t public_key_len)
	Sets the keypair within a DHState object. More...

int	noise_dhstate_set_keypair_private (NoiseDHState state, const uint8_t private_key, size_t private_key_len)
	Sets the keypair within a DHState object based on a private key only. More...

int	noise_dhstate_set_null_public_key (NoiseDHState *state)
	Sets the public key in a DHState object to the special null value. More...

int	noise_dhstate_set_public_key (NoiseDHState state, const uint8_t public_key, size_t public_key_len)
	Sets the public key in a DHState object. More...

int	noise_dhstate_set_role (NoiseDHState *state, int role)
	Sets the role that a DHState object will play in a handshake. More...

Detailed Description

DHState objects are used to store the keypairs for the local party or the public keys for remote parties. Once the keys have been set, noise_dhstate_calculate() can be used to perform a Diffie-Hellman operation with two DHState objects.

Typedef Documentation

NoiseDHState

Opaque object that represents a DHState.

Definition at line 33 of file dhstate.h.

Function Documentation

int noise_dhstate_calculate	(	const NoiseDHState *	private_key_state,
		const NoiseDHState *	public_key_state,
		uint8_t *	shared_key,
		size_t	shared_key_len
	)

Performs a Diffie-Hellman calculation.

Parameters

private_key_state	Points to the DHState containing the private key.
public_key_state	Points to the DHState containing the public key.
shared_key	Points to the shared key on exit.
shared_key_len	The length of the shared_key buffer in bytes.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if private_key_state, public_key_state, or shared_key is NULL.; NOISE_ERROR_INVALID_PARAM if private_key_state and public_key_state do not have the same algorithm identifier.; NOISE_ERROR_INVALID_LENGTH if shared_key_len is not correct for the algorithm.; NOISE_ERROR_INVALID_PRIVATE_KEY if private_key_state does not contain a private key or the private key is invalid.; NOISE_ERROR_INVALID_PUBLIC_KEY if the public key in public_key_state is invalid.

If the input public key is the special null value, then the output shared_key will also be the null value and NOISE_ERROR_NONE will be returned.

See Also: noise_dhstate_generate_keypair()

Definition at line 686 of file dhstate.c.

int noise_dhstate_clear_key ( NoiseDHState * state )

Clears the key in a DHState object.

Parameters

state The DHState object.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state is NULL.

See Also: noise_dhstate_has_keypair(), noise_dhstate_has_public_key()

Definition at line 622 of file dhstate.c.

int noise_dhstate_copy	(	NoiseDHState *	state,
		const NoiseDHState *	from
	)

Copies the keys from one DHState object to another.

Parameters

state	The DHState to copy into.
from	The DHState to copy from.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state or from is NULL.; NOISE_ERROR_NOT_APPLICABLE if from does not have the same key type identifier as state.

Definition at line 730 of file dhstate.c.

int noise_dhstate_format_fingerprint	(	const NoiseDHState *	state,
		int	fingerprint_type,
		char *	buffer,
		size_t	len
	)

Formats the public key fingerprint for the key within a DHState.

Parameters

state	The DHState object.
fingerprint_type	The type of fingerprint to format, NOISE_FINGERPRINT_BASIC or NOISE_FINGERPRINT_FULL.
buffer	The buffer to write the fingerprint string to, including a terminating NUL.
len	The length of buffer in bytes.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state or buffer is NULL.; NOISE_ERROR_INVALID_PARAM if fingerprint_type is not a supported fingerprint type.; NOISE_ERROR_INVALID_LENGTH if len is not large enough to hold the entire fingerprint string.; NOISE_ERROR_INVALID_STATE if a public key has not been set on state yet.

Fingerprints are created by hashing the public key with SHA256 and then formatting the value in hexadecimal with bytes separated by colons. If the fingerprint_type is NOISE_FINGERPRINT_BASIC, then the SHA256 hash value is truncated to the first 16 bytes. If the type is NOISE_FINGERPRINT_FULL, then the entire 32 byte hash value is formatted.

Definition at line 776 of file dhstate.c.

int noise_dhstate_free ( NoiseDHState * state )

Frees a DHState object after destroying all sensitive material.

Parameters

state The DHState object to free.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state is NULL.

See Also: noise_dhstate_new_by_id(), noise_dhstate_new_by_name()

Definition at line 146 of file dhstate.c.

int noise_dhstate_generate_dependent_keypair	(	NoiseDHState *	state,
		const NoiseDHState *	other
	)

Generates a new key pair within a DHState object that may depend upon the parameters from another DHState object.

Parameters

state	The DHState object.
other	The other DHState object to obtain parameters from, which may be NULL.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state or is NULL.; NOISE_ERROR_INVALID_PARAM if state and other do not have the same algorithm identifier.; NOISE_ERROR_INVALID_STATE if dependent parameters are required but other does not currently contain any.

This function is intended for generating ephemeral keypairs for algorithms like New Hope where the keypair for Bob depends upon parameters that are transmitted in Alice's public key. If the algorithm does not require dependent parameters to generate the keypair, other is ignored.

Note: This function needs to generate random key material for the private key, so the system random number generator must be properly seeded before calling this function.

See Also: noise_dhstate_calculate(), noise_dhstate_set_keypair()

Definition at line 332 of file dhstate.c.

int noise_dhstate_generate_keypair ( NoiseDHState * state )

Generates a new key pair within a DHState object.

Parameters

state The DHState object.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state is NULL.

Note: This function needs to generate random key material for the private key, so the system random number generator must be properly seeded before calling this function.

See Also: noise_dhstate_calculate(), noise_dhstate_set_keypair()

Definition at line 289 of file dhstate.c.

int noise_dhstate_get_dh_id ( const NoiseDHState * state )

Gets the algorithm identifier for a DHState object.

Parameters

state The DHState object.

Returns: The algorithm identifier, or NOISE_DH_NONE if state is NULL.

Definition at line 168 of file dhstate.c.

int noise_dhstate_get_keypair	(	const NoiseDHState *	state,
		uint8_t *	private_key,
		size_t	private_key_len,
		uint8_t *	public_key,
		size_t	public_key_len
	)

Gets the keypair from within a DHState object.

Parameters

state	The DHState object.
private_key	Points to the buffer to receive the private key.
private_key_len	The private key buffer length in bytes.
public_key	Points to the buffer to receive the public key.
public_key_len	The public key buffer length in bytes.

Returns: NOISE_ERROR on success.; NOISE_ERROR_INVALID_PARAM if state, private_key, or public_key is NULL.; NOISE_ERROR_INVALID_LENGTH if either private_key_len or public_key_len is incorrect for the algorithm.; NOISE_ERROR_INVALID_STATE if state does not contain a keypair.

See Also: noise_dhstate_set_keypair(), noise_dhstate_get_public_key()

Definition at line 462 of file dhstate.c.

size_t noise_dhstate_get_private_key_length ( const NoiseDHState * state )

Gets the length of the private key for a DHState object.

Parameters

state The DHState object.

Returns: The size of the private key in bytes, or 0 if state is NULL.

See Also: noise_dhstate_get_public_key_length(), noise_dhstate_get_shared_key_length()

Definition at line 198 of file dhstate.c.

int noise_dhstate_get_public_key	(	const NoiseDHState *	state,
		uint8_t *	public_key,
		size_t	public_key_len
	)

Gets the public key value from a DHState object.

Parameters

state	The DHState object.
public_key	The buffer to receive the public key value.
public_key_len	The public key length in bytes.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state or public_key is NULL.; NOISE_ERROR_INVALID_LENGTH if public_key_len is incorrect for this algorithm.

See Also: noise_dhstate_set_public_key(), noise_dhstate_get_public_key_length()

Definition at line 551 of file dhstate.c.

size_t noise_dhstate_get_public_key_length ( const NoiseDHState * state )

Gets the length of the public key for a DHState object.

Parameters

state The DHState object.

Returns: The size of the public key in bytes, or 0 if state is NULL.

See Also: noise_dhstate_get_private_key_length(), noise_dhstate_get_shared_key_length()

Definition at line 183 of file dhstate.c.

int noise_dhstate_get_role ( const NoiseDHState * state )

Gets the role that a DHState object will play in a handshake.

Parameters

state The DHState object.

Returns: The role, NOISE_ROLE_INITIATOR or NOISE_ROLE_RESPONDER, or zero if the role has not been set yet.

See Also: noise_dhstate_set_role()

Definition at line 805 of file dhstate.c.

size_t noise_dhstate_get_shared_key_length ( const NoiseDHState * state )

Gets the length of the shared key for a DHState object.

Parameters

state The DHState object.

Returns: The size of the shared key in bytes, or 0 if state is NULL.

See Also: noise_dhstate_get_public_key_length(), noise_dhstate_get_private_key_length()

Definition at line 213 of file dhstate.c.

int noise_dhstate_has_keypair ( const NoiseDHState * state )

Determine if a DHState object contains a keypair.

Parameters

state The DHState object.

Returns: Returns 1 if state contains both a private key and a public key. Returns 0 if state is NULL or it only contains a public key.

See Also: noise_dhstate_set_keypair(), noise_dhstate_has_public_key(), noise_dhstate_clear_key()

Definition at line 247 of file dhstate.c.

int noise_dhstate_has_public_key ( const NoiseDHState * state )

Determine if a DHState object contains a public key.

Parameters

state The DHState object.

Returns: Returns 1 if state contains a public key (and optionally a private key). Returns 0 if state is NULL or it does not contain a public key.

See Also: noise_dhstate_set_keypair(), noise_dhstate_has_public_key(), noise_dhstate_clear_key()

Definition at line 267 of file dhstate.c.

int noise_dhstate_is_ephemeral_only ( const NoiseDHState * state )

Determine if a DHState object only supports ephemeral keys.

Parameters

state The DHState object.

Returns: Non-zero if the DHState object only supports ephemeral keys, or zero if the DHState object supports both static and ephemeral keys.

Some algorithms like "NewHope" can only be used to generate ephemeral keys during a session and have no support for long-term static keys.

Definition at line 230 of file dhstate.c.

int noise_dhstate_is_null_public_key ( const NoiseDHState * state )

Determine if the public key in a DHState object has the special null value.

Parameters

state The DHState object.

Returns: Returns non-zero if the public key within state is the special null value; zero otherwise.

See Also: noise_dhstate_set_null_public_key()

Definition at line 602 of file dhstate.c.

int noise_dhstate_new_by_id	(	NoiseDHState **	state,
		int	id
	)

Creates a new DHState object by its algorithm identifier.

Parameters

state	Points to the variable where to store the pointer to the new DHState object.
id	The algorithm identifier; NOISE_DH_CURVE25519, NOISE_DH_CURVE448, 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 DHState object.

See Also: noise_dhstate_free(), noise_dhstate_new_by_name()

Definition at line 67 of file dhstate.c.

int noise_dhstate_new_by_name	(	NoiseDHState **	state,
		const char *	name
	)

Creates a new DHState object by its algorithm name.

Parameters

state	Points to the variable where to store the pointer to the new DHState object.
name	The name of the Diffie-Hellman algorithm; e.g. "25519". 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 DHState object.

See Also: noise_dhstate_free(), noise_dhstate_new_by_id()

Definition at line 116 of file dhstate.c.

int noise_dhstate_set_keypair	(	NoiseDHState *	state,
		const uint8_t *	private_key,
		size_t	private_key_len,
		const uint8_t *	public_key,
		size_t	public_key_len
	)

Sets the keypair within a DHState object.

Parameters

state	The DHState object.
private_key	Points to the private key.
private_key_len	The private key length in bytes.
public_key	Points to the public key.
public_key_len	The public key length in bytes.

Returns: NOISE_ERROR on success.; NOISE_ERROR_INVALID_PARAM if state, private_key, or public_key is NULL.; NOISE_ERROR_INVALID_LENGTH if either private_key_len or public_key_len is incorrect for the algorithm.; NOISE_ERROR_INVALID_PRIVATE_KEY if private_key is not valid.; NOISE_ERROR_INVALID_PUBLIC_KEY if public_key is not valid.

The algorithm may decide to defer NOISE_ERROR_INVALID_PRIVATE_KEY or NOISE_ERROR_INVALID_PUBLIC_KEY to later when the keypair is actually used during noise_dhstate_calculate().

See Also: noise_dhstate_get_keypair(), noise_dhstate_set_public_key(), noise_dhstate_set_keypair_private()

Definition at line 374 of file dhstate.c.

int noise_dhstate_set_keypair_private	(	NoiseDHState *	state,
		const uint8_t *	private_key,
		size_t	private_key_len
	)

Sets the keypair within a DHState object based on a private key only.

Parameters

state	The DHState object.
private_key	Points to the private key.
private_key_len	The private key length in bytes.

Returns: NOISE_ERROR on success.; NOISE_ERROR_INVALID_PARAM if state or private_key is NULL.; NOISE_ERROR_INVALID_LENGTH if either private_key_len is incorrect for the algorithm.; NOISE_ERROR_INVALID_PRIVATE_KEY if private_key is not valid.; NOISE_ERROR_INVALID_PUBLIC_KEY if public_key that is derived from the private_key is not valid.

The algorithm may decide to defer NOISE_ERROR_INVALID_PRIVATE_KEY or NOISE_ERROR_INVALID_PUBLIC_KEY to later when the keypair is actually used during noise_dhstate_calculate().

This function only takes the private key as an argument. The public key in the keypair is derived from the private key.

See Also: noise_dhstate_get_keypair(), noise_dhstate_set_public_key(), noise_dhstate_set_keypair()

Definition at line 423 of file dhstate.c.

int noise_dhstate_set_null_public_key ( NoiseDHState * state )

Sets the public key in a DHState object to the special null value.

Parameters

state The DHState object.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state is NULL.; NOISE_ERROR_INVALID_PARAM if state does not support null public keys.

See Also: noise_dhstate_is_null_public_key()

Definition at line 576 of file dhstate.c.

int noise_dhstate_set_public_key	(	NoiseDHState *	state,
		const uint8_t *	public_key,
		size_t	public_key_len
	)

Sets the public key in a DHState object.

Parameters

state	The DHState object.
public_key	Points to the public key.
public_key_len	The public key length in bytes.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state or public_key is NULL.; NOISE_ERROR_INVALID_LENGTH if public_key_len is incorrect for the algorithm.; NOISE_ERROR_INVALID_PUBLIC_KEY if public_key is not valid and it is not the special null value.

After this function succeeds, the DHState will only contain a public key. Any existing private key will be cleared. Thus, this function is useful to set the public key of a remote party. Use noise_dhstate_set_keypair() to set both the public and private key for the local party.

The algorithm may decide to defer NOISE_ERROR_INVALID_PUBLIC_KEY to later when the public key is actually used during noise_dhstate_calculate().

See Also: noise_dhstate_get_public_key(), noise_dhstate_set_keypair()

Definition at line 511 of file dhstate.c.

int noise_dhstate_set_role	(	NoiseDHState *	state,
		int	role
	)

Sets the role that a DHState object will play in a handshake.

Parameters

state	The DHState object.
role	The role, NOISE_ROLE_INITIATOR or NOISE_ROLE_RESPONDER, or zero if the role is unspecified.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state is NULL.; NOISE_ERROR_INVALID_PARAM if role is not one of NOISE_ROLE_INITIATOR, NOISE_ROLE_RESPONDER, or zero.

This function is intended for use with algorithms that have a different method for calculating public keys and shared secrets for the two parties in a communication. An example is the post-quantum SIDH algorithm where "Alice" and "Bob" differ in the calculations they perform.

To assist with supporting such algorithms, the HandshakeState labels DHState objects as either initiator or responder depending upon who owns that specific key. The algorithm-specific back end can then use the role information to determine which object it wants to treat as "Alice" and which object should be treated as "Bob".

See Also: noise_dhstate_get_role()

Definition at line 835 of file dhstate.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation