Typedefs
typedef struct NoiseCipherState_s	NoiseCipherState
	Opaque object that represents a CipherState. More...

Functions
int	noise_cipherstate_decrypt (NoiseCipherState state, NoiseBuffer buffer)
	Decrypts a block of data with this CipherState object. More...

int	noise_cipherstate_decrypt_with_ad (NoiseCipherState state, const uint8_t ad, size_t ad_len, NoiseBuffer *buffer)
	Decrypts a block of data with this CipherState object. More...

int	noise_cipherstate_encrypt (NoiseCipherState state, NoiseBuffer buffer)
	Encrypts a block of data with this CipherState object. More...

int	noise_cipherstate_encrypt_with_ad (NoiseCipherState state, const uint8_t ad, size_t ad_len, NoiseBuffer *buffer)
	Encrypts a block of data with this CipherState object. More...

int	noise_cipherstate_free (NoiseCipherState *state)
	Frees a CipherState object after destroying all sensitive material. More...

int	noise_cipherstate_get_cipher_id (const NoiseCipherState *state)
	Gets the algorithm identifier for a CipherState object. More...

size_t	noise_cipherstate_get_key_length (const NoiseCipherState *state)
	Gets the length of the encryption key for a CipherState object. More...

size_t	noise_cipherstate_get_mac_length (const NoiseCipherState *state)
	Gets the length of packet MAC values for a CipherState object. More...

int	noise_cipherstate_get_max_key_length (void)
	Gets the maximum key length for the supported algorithms. More...

int	noise_cipherstate_get_max_mac_length (void)
	Gets the maximum MAC length for the supported algorithms. More...

int	noise_cipherstate_has_key (const NoiseCipherState *state)
	Determine if the key has been set on a CipherState object. More...

int	noise_cipherstate_init_key (NoiseCipherState state, const uint8_t key, size_t key_len)
	Initializes the key on a CipherState object. More...

int	noise_cipherstate_new_by_id (NoiseCipherState **state, int id)
	Creates a new CipherState object by its algorithm identifier. More...

int	noise_cipherstate_new_by_name (NoiseCipherState *state, const char name)
	Creates a new CipherState object by its algorithm name. More...

int	noise_cipherstate_set_nonce (NoiseCipherState *state, uint64_t nonce)
	Sets the nonce value for this cipherstate object. More...

Detailed Description

CipherState objects are used to encrypt or decrypt data during a session. Once the handshake has completed, noise_symmetricstate_split() will create two CipherState objects for encrypting packets sent to the other party, and decrypting packets received from the other party.

Typedef Documentation

NoiseCipherState

Opaque object that represents a CipherState.

Definition at line 32 of file cipherstate.h.

Function Documentation

int noise_cipherstate_decrypt	(	NoiseCipherState *	state,
		NoiseBuffer *	buffer
	)

Decrypts a block of data with this CipherState object.

Parameters

state	The CipherState 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_NONCE if the nonce previously overflowed.; NOISE_ERROR_INVALID_LENGTH if the size of buffer is larger than 65535 bytes or is too small to contain the MAC value.

This is a convenience function which decrypts the contents of a buffer without any associated data. It is otherwise identical to noise_cipherstate_decrypt_with_ad().

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.

The following example demonstrates how to initialize a buffer for use with this function. The message is a byte array containing ciphertext_size bytes of ciphertext plus MAC on entry. On exit, buffer.size will contain the number of bytes of plaintext:

NoiseBuffer buffer;
noise_buffer_set_inout(buffer, message, ciphertext_size, sizeof(message));
noise_cipherstate_decrypt(state, &buffer);
// The plaintext is the buffer.size bytes starting at buffer.data

See Also: noise_cipherstate_decrypt_with_ad()

Definition at line 493 of file cipherstate.c.

int noise_cipherstate_decrypt_with_ad	(	NoiseCipherState *	state,
		const uint8_t *	ad,
		size_t	ad_len,
		NoiseBuffer *	buffer
	)

Decrypts a block of data with this CipherState object.

Parameters

state	The CipherState object.
ad	Points to the associated data, which can be NULL only if ad_len is zero.
ad_len	The length of the associated data in bytes.
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_INVALID_PARAM if ad is NULL and ad_len is not zero.; NOISE_ERROR_MAC_FAILURE if the MAC check failed.; NOISE_ERROR_INVALID_NONCE if the nonce previously overflowed.; NOISE_ERROR_INVALID_LENGTH if the size of buffer is larger than 65535 bytes or is 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.

The following example demonstrates how to initialize a buffer for use with this function. The message is a byte array containing ciphertext_size bytes of ciphertext plus MAC on entry. On exit, buffer.size will contain the number of bytes of plaintext:

NoiseBuffer buffer;
noise_buffer_set_inout(buffer, message, ciphertext_size, sizeof(message));
noise_cipherstate_decrypt_with_ad(state, ad, ad_len, &buffer);
// The plaintext is the buffer.size bytes starting at buffer.data

See Also: noise_cipherstate_encrypt_with_ad(), noise_cipherstate_get_mac_length()

Definition at line 374 of file cipherstate.c.

int noise_cipherstate_encrypt	(	NoiseCipherState *	state,
		NoiseBuffer *	buffer
	)

Encrypts a block of data with this CipherState object.

Parameters

state	The CipherState 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.

This is a convenience function which encrypts the contents of a buffer without any associated data. It is otherwise identical to noise_cipherstate_encrypt_with_ad().

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 following example demonstrates how to initialize a buffer for use with this function. The message is a byte array containing plaintext_size bytes of plaintext on entry. On exit, buffer.size will contain the number of bytes of ciphertext plus MAC to be transmitted:

NoiseBuffer buffer;
noise_buffer_set_inout(buffer, message, plaintext_size, sizeof(message));
noise_cipherstate_encrypt(state, &buffer);
// Transmit the buffer.size bytes starting at buffer.data

See Also: noise_cipherstate_encrypt_with_ad()

Definition at line 451 of file cipherstate.c.

int noise_cipherstate_encrypt_with_ad	(	NoiseCipherState *	state,
		const uint8_t *	ad,
		size_t	ad_len,
		NoiseBuffer *	buffer
	)

Encrypts a block of data with this CipherState object.

Parameters

state	The CipherState object.
ad	Points to the associated data, which can be NULL only if ad_len is zero.
ad_len	The length of the associated data in bytes.
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_PARAM if ad is NULL and ad_len is not zero.; 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 following example demonstrates how to initialize a buffer for use with this function. The message is a byte array containing plaintext_size bytes of plaintext on entry. On exit, buffer.size will contain the number of bytes of ciphertext plus MAC to be transmitted:

NoiseBuffer buffer;
noise_buffer_set_inout(buffer, message, plaintext_size, sizeof(message));
noise_cipherstate_encrypt_with_ad(state, ad, ad_len, &buffer);
// Transmit the buffer.size bytes starting at buffer.data

See Also: noise_cipherstate_decrypt_with_ad(), noise_cipherstate_get_mac_length()

Definition at line 294 of file cipherstate.c.

int noise_cipherstate_free ( NoiseCipherState * state )

Frees a CipherState object after destroying all sensitive material.

Parameters

state The CipherState object to free.

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

See Also: noise_cipherstate_new_by_id(), noise_cipherstate_new_by_name()

Definition at line 152 of file cipherstate.c.

int noise_cipherstate_get_cipher_id ( const NoiseCipherState * state )

Gets the algorithm identifier for a CipherState object.

Parameters

state The CipherState object.

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

Definition at line 174 of file cipherstate.c.

size_t noise_cipherstate_get_key_length ( const NoiseCipherState * state )

Gets the length of the encryption key for a CipherState object.

Parameters

state The CipherState object.

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

See Also: noise_cipherstate_get_mac_length()

Definition at line 188 of file cipherstate.c.

size_t noise_cipherstate_get_mac_length ( const NoiseCipherState * state )

Gets the length of packet MAC values for a CipherState object.

Parameters

state The CipherState object.

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

See Also: noise_cipherstate_get_key_length()

Definition at line 202 of file cipherstate.c.

int noise_cipherstate_get_max_key_length ( void )

Gets the maximum key length for the supported algorithms.

See Also: noise_cipherstate_get_max_mac_length()

Definition at line 541 of file cipherstate.c.

int noise_cipherstate_get_max_mac_length ( void )

Gets the maximum MAC length for the supported algorithms.

See Also: noise_cipherstate_get_max_key_length()

Definition at line 551 of file cipherstate.c.

int noise_cipherstate_has_key ( const NoiseCipherState * state )

Determine if the key has been set on a CipherState object.

Parameters

state The CipherState object.

Returns: Returns 1 if the key has been set, or 0 if the key has not been set (or state is NULL).

See Also: noise_cipherstate_init_key()

Definition at line 247 of file cipherstate.c.

int noise_cipherstate_init_key	(	NoiseCipherState *	state,
		const uint8_t *	key,
		size_t	key_len
	)

Initializes the key on a CipherState object.

Parameters

state	The CipherState object.
key	Points to the key.
key_len	The length of the key in bytes.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state or key is NULL.; NOISE_ERROR_INVALID_LENGTH if key_len is the wrong length for this cipher.

See Also: noise_cipherstate_get_key_length(), noise_cipherstate_has_key()

Definition at line 222 of file cipherstate.c.

int noise_cipherstate_new_by_id	(	NoiseCipherState **	state,
		int	id
	)

Creates a new CipherState object by its algorithm identifier.

Parameters

state	Points to the variable where to store the pointer to the new CipherState object.
id	The algorithm identifier; NOISE_CIPHER_CHACHAPOLY, NOISE_CIPHER_AESGCM, etc.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state is NULL.; NOISE_ERROR_UNKNOWN_ID if id is unknown.; or NOISE_ERROR_NO_MEMORY if there is insufficient memory to allocate the new CipherState object.

See Also: noise_cipherstate_free(), noise_cipherstate_new_by_name()

Definition at line 77 of file cipherstate.c.

int noise_cipherstate_new_by_name	(	NoiseCipherState **	state,
		const char *	name
	)

Creates a new CipherState object by its algorithm name.

Parameters

state	Points to the variable where to store the pointer to the new CipherState object.
name	The name of the cipher algorithm; e.g. "ChaChaPoly". 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 CipherState object.

See Also: noise_cipherstate_free(), noise_cipherstate_new_by_id()

Definition at line 122 of file cipherstate.c.

int noise_cipherstate_set_nonce	(	NoiseCipherState *	state,
		uint64_t	nonce
	)

Sets the nonce value for this cipherstate object.

Parameters

state	The CipherState object.
nonce	The new nonce value to set. This must be greater than or equal to the current nonce value in the state.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state is NULL.; NOISE_ERROR_INVALID_STATE if the key has not been set yet.; NOISE_ERROR_INVALID_NONCE if nonce is smaller than the current value.

Warning: This function is intended for testing purposes only. It is dangerous to set the nonce back to a previously-used value so this function will actively prevent that from happening.

See Also: noise_cipherstate_init_key()

Definition at line 517 of file cipherstate.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation