SymmetricState API

Typedefs
typedef struct NoiseSymmetricState_s	NoiseSymmetricState
	Opaque object that represents a SymmetricState. More...

Functions
int	noise_symmetricstate_decrypt_and_hash (NoiseSymmetricState *state, NoiseBuffer *buffer)
	Decrypts a block of data with this SymmetricState object and adds the ciphertext to the handshake hash. More...
int	noise_symmetricstate_encrypt_and_hash (NoiseSymmetricState *state, NoiseBuffer *buffer)
	Encrypts a block of data with this SymmetricState object and adds the ciphertext to the handshake hash. More...
int	noise_symmetricstate_free (NoiseSymmetricState *state)
	Frees a SymmetricState object after destroying all sensitive material. More...
size_t	noise_symmetricstate_get_mac_length (const NoiseSymmetricState *state)
	Gets the current length of packet MAC values for a SymmetricState object. More...
int	noise_symmetricstate_get_protocol_id (const NoiseSymmetricState *state, NoiseProtocolId *id)
	Gets the protocol identifier associated with a SymmetricState object. More...
int	noise_symmetricstate_mix_hash (NoiseSymmetricState *state, const uint8_t *input, size_t size)
	Mixes new input data into the handshake hash. More...
int	noise_symmetricstate_mix_key (NoiseSymmetricState *state, const uint8_t *input, size_t size)
	Mixes new input data into the chaining key. More...
int	noise_symmetricstate_new_by_id (NoiseSymmetricState **state, const NoiseProtocolId *id)
	Creates a new SymmetricState object from a protocol identifier. More...
int	noise_symmetricstate_new_by_name (NoiseSymmetricState **state, const char *name)
	Creates a new SymmetricState object from a protocol name. More...
int	noise_symmetricstate_split (NoiseSymmetricState *state, NoiseCipherState **c1, NoiseCipherState **c2)
	Splits the transport encryption CipherState objects out of this SymmetricState object. More...

Detailed Description

Typedef Documentation

NoiseSymmetricState

Opaque object that represents a SymmetricState.

Definition at line 33 of file symmetricstate.h.

Function Documentation

int noise_symmetricstate_decrypt_and_hash	(	NoiseSymmetricState *	state,
		NoiseBuffer *	buffer
	)

Decrypts a block of data with this SymmetricState object and adds the ciphertext to the handshake hash.

Parameters

state	The SymmetricState object.
buffer	The buffer containing the ciphertext plus MAC on entry and the plaintext on exit.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or buffer is NULL.

NOISE_ERROR_MAC_FAILURE if the MAC check failed.

NOISE_ERROR_INVALID_STATE if this SymmetricState has already been split.

NOISE_ERROR_INVALID_NONCE if the nonce previously overflowed.

NOISE_ERROR_INVALID_LENGTH if the data in buffer is larger than 65535 bytes or too small to contain the MAC value.

The ciphertext is decrypted in-place with the plaintext also written to buffer. In other words, it is assumed that the ciphertext plus MAC is in an input buffer ready to be processed once the MAC has been checked and the ciphertext has been decrypted.

See Also

noise_symmetricstate_encrypt_and_hash()

Definition at line 403 of file symmetricstate.c.

int noise_symmetricstate_encrypt_and_hash	(	NoiseSymmetricState *	state,
		NoiseBuffer *	buffer
	)

Encrypts a block of data with this SymmetricState object and adds the ciphertext to the handshake hash.

Parameters

state	The SymmetricState object.
buffer	The buffer containing the plaintext on entry and the ciphertext plus MAC on exit.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or buffer is NULL.

NOISE_ERROR_INVALID_NONCE if the nonce previously overflowed

NOISE_ERROR_INVALID_LENGTH if the ciphertext plus MAC is too large to fit within the maximum size of buffer and to also remain within 65535 bytes.

The plaintext is encrypted in-place with the ciphertext also written to buffer. There must be enough room on the end of buffer to hold the extra MAC value that will be appended. In other words, it is assumed that the plaintext is in an output buffer ready to be transmitted once the data has been encrypted and the final packet length has been determined.

The noise_symmetricstate_get_mac_length() function can be used to determine the size of the MAC value that will be added, which may be zero if the encryption key has not been set up yet.

See Also

noise_symmetricstate_decrypt_and_hash(), noise_symmetricstate_get_mac_length()

Definition at line 353 of file symmetricstate.c.

int noise_symmetricstate_free

(

NoiseSymmetricState *

state

)

Frees a SymmetricState object after destroying all sensitive material.

Parameters

state

The SymmetricState object to free.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state is NULL.

See Also

noise_symmetricstate_new_by_id(), noise_symmetricstate_new_by_name()

Definition at line 209 of file symmetricstate.c.

size_t noise_symmetricstate_get_mac_length

(

const NoiseSymmetricState *

state

)

Gets the current length of packet MAC values for a SymmetricState object.

Parameters

state

The SymmetricState object.

Returns

The size of the MAC in bytes. Returns zero if state is NULL, the encryption key has not been set yet, or the SymmetricState has been split.

This function can be used to determine the size of the MAC value that will be added to the next packet that will be encrypted with noise_symmetricstate_encrypt_and_hash(). Early in the handshake when packets are still being exchanged in plaintext, the size will be zero.

See Also

noise_symmetricstate_encrypt_and_hash()

Definition at line 464 of file symmetricstate.c.

int noise_symmetricstate_get_protocol_id	(	const NoiseSymmetricState *	state,
		NoiseProtocolId *	id
	)

Gets the protocol identifier associated with a SymmetricState object.

Parameters

state	The SymmetricState object.
id	Return buffer for the protocol identifier, which consists of fields that identify the cipher algorithm, hash algorith, handshake pattern, etc.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or id is NULL.

Definition at line 238 of file symmetricstate.c.

int noise_symmetricstate_mix_hash	(	NoiseSymmetricState *	state,
		const uint8_t *	input,
		size_t	size
	)

Mixes new input data into the handshake hash.

Parameters

state	The SymmetricState object.
input	Points to the input data to mix in.
size	The size of the input data in bytes.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or input is NULL.

NOISE_ERROR_INVALID_STATE if the state has already been split.

See Also

noise_symmetricstate_mix_key(), noise_symmetricstate_split()

Definition at line 304 of file symmetricstate.c.

int noise_symmetricstate_mix_key	(	NoiseSymmetricState *	state,
		const uint8_t *	input,
		size_t	size
	)

Mixes new input data into the chaining key.

Parameters

state	The SymmetricState object.
input	Points to the input data to mix in.
size	The size of the input data in bytes.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or input is NULL.

NOISE_ERROR_INVALID_STATE if the state has already been split.

See Also

noise_symmetricstate_mix_hash(), noise_symmetricstate_split()

Definition at line 263 of file symmetricstate.c.

int noise_symmetricstate_new_by_id	(	NoiseSymmetricState **	state,
		const NoiseProtocolId *	id
	)

Creates a new SymmetricState object from a protocol identifier.

Parameters

state	Points to the variable where to store the pointer to the new SymmetricState object.
id	The protocol identifier as a set of algorithm identifiers.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state or id is NULL.

NOISE_ERROR_UNKNOWN_ID if the protocol id is unknown.

NOISE_ERROR_INVALID_LENGTH if the full name corresponding to id is too long.

NOISE_ERROR_NOT_APPLICABLE if the lengths of the hash output or the cipher key are incompatible.

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

See Also

noise_symmetricstate_free(), noise_symmetricstate_new_by_name()

Definition at line 135 of file symmetricstate.c.

int noise_symmetricstate_new_by_name	(	NoiseSymmetricState **	state,
		const char *	name
	)

Creates a new SymmetricState object from a protocol name.

Parameters

state	Points to the variable where to store the pointer to the new SymmetricState object.
name	The name of the Noise protocol to use. 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 the protocol name is unknown.

NOISE_ERROR_NOT_APPLICABLE if the lengths of the hash output or the cipher key are incompatible.

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

See Also

noise_symmetricstate_free(), noise_symmetricstate_new_by_id()

Definition at line 176 of file symmetricstate.c.

int noise_symmetricstate_split	(	NoiseSymmetricState *	state,
		NoiseCipherState **	c1,
		NoiseCipherState **	c2
	)

Splits the transport encryption CipherState objects out of this SymmetricState object.

Parameters

state	The SymmetricState object.
c1	Points to the variable where to place the pointer to the first CipherState object. This can be NULL if the application is using a one-way handshake pattern.
c2	Points to the variable where to place the pointer to the second CipherState object. This can be NULL if the application is using a one-way handshake pattern.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if state is NULL.

NOISE_ERROR_INVALID_PARAM if both c1 and c2 are NULL.

NOISE_ERROR_INVALID_STATE if the state has already been split.

NOISE_ERROR_NO_MEMORY if there is insufficient memory to create the new CipherState objects.

Once a SymmetricState has been split, it is effectively finished and cannot be used for future encryption or hashing operations. If those operations are invoked, the relevant functions will return NOISE_ERROR_INVALID_STATE.

The c1 object should be used to protect messages from the initiator to the responder, and the c2 object should be used to protect messages from the responder to the initiator.

If the handshake pattern is one-way, then the application should call noise_cipherstate_free() on the object that is not needed. Alternatively, the application can pass NULL to noise_symmetricstate_split() as the c1 or c2 argument and the second CipherState will not be created at all.

Definition at line 515 of file symmetricstate.c.