Typedefs
typedef struct NoiseSignState_s	NoiseSignState
	Opaque object that represents a SignState. More...

Functions
int	noise_signstate_clear_key (NoiseSignState *state)
	Clears the key in a SignState object. More...

int	noise_signstate_copy (NoiseSignState state, const NoiseSignState from)
	Copies the keys from one SignState object to another. More...

int	noise_signstate_format_fingerprint (const NoiseSignState state, int fingerprint_type, char buffer, size_t len)
	Formats the public key fingerprint for the key within a SignState. More...

int	noise_signstate_free (NoiseSignState *state)
	Frees a SignState object after destroying all sensitive material. More...

int	noise_signstate_generate_keypair (NoiseSignState *state)
	Generates a new key pair within a SignState object. More...

int	noise_signstate_get_keypair (const NoiseSignState 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 SignState object. More...

int	noise_signstate_get_max_key_length (void)
	Gets the maximum length of signing keys for the supported algorithms. More...

int	noise_signstate_get_max_signature_length (void)
	Gets the maximum length of signatures for the supported algorithms. More...

size_t	noise_signstate_get_private_key_length (const NoiseSignState *state)
	Gets the length of the private key for a SignState object. More...

int	noise_signstate_get_public_key (const NoiseSignState state, uint8_t public_key, size_t public_key_len)
	Gets the public key value from a SignState object. More...

size_t	noise_signstate_get_public_key_length (const NoiseSignState *state)
	Gets the length of the public key for a SignState object. More...

int	noise_signstate_get_sign_id (const NoiseSignState *state)
	Gets the algorithm identifier for a SignState object. More...

size_t	noise_signstate_get_signature_length (const NoiseSignState *state)
	Gets the length of the signature for a SignState object. More...

int	noise_signstate_has_keypair (const NoiseSignState *state)
	Determine if a SignState object contains a keypair. More...

int	noise_signstate_has_public_key (const NoiseSignState *state)
	Determine if a SignState object contains a public key. More...

int	noise_signstate_new_by_id (NoiseSignState **state, int id)
	Creates a new SignState object by its algorithm identifier. More...

int	noise_signstate_new_by_name (NoiseSignState *state, const char name)
	Creates a new SignState object by its algorithm name. More...

int	noise_signstate_set_keypair (NoiseSignState 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 SignState object. More...

int	noise_signstate_set_keypair_private (NoiseSignState state, const uint8_t private_key, size_t private_key_len)
	Sets the keypair within a SignState object based on a private key only. More...

int	noise_signstate_set_public_key (NoiseSignState state, const uint8_t public_key, size_t public_key_len)
	Sets the public key in a SignState object. More...

int	noise_signstate_sign (const NoiseSignState state, const uint8_t message, size_t message_len, uint8_t *signature, size_t signature_len)
	Signs a message to create a digital signature. More...

int	noise_signstate_verify (const NoiseSignState state, const uint8_t message, size_t message_len, const uint8_t *signature, size_t signature_len)
	Verifies a digital signature on a message. More...

Detailed Description

SignState 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_signstate_sign() can be used to create a digital signature with a keypair, or noise_signstate_verify() can be used to verify a digital signature with a public key.

Typedef Documentation

NoiseSignState

Opaque object that represents a SignState.

Definition at line 33 of file signstate.h.

Function Documentation

int noise_signstate_clear_key ( NoiseSignState * state )

Clears the key in a SignState object.

Parameters

state The SignState object.

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

See Also: noise_signstate_has_keypair(), noise_signstate_has_public_key()

Definition at line 507 of file signstate.c.

int noise_signstate_copy	(	NoiseSignState *	state,
		const NoiseSignState *	from
	)

Copies the keys from one SignState object to another.

Parameters

state	The SignState to copy into.
from	The SignState 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 609 of file signstate.c.

int noise_signstate_format_fingerprint	(	const NoiseSignState *	state,
		int	fingerprint_type,
		char *	buffer,
		size_t	len
	)

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

Parameters

state	The SignState 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 652 of file signstate.c.

int noise_signstate_free ( NoiseSignState * state )

Frees a SignState object after destroying all sensitive material.

Parameters

state The SignState object to free.

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

See Also: noise_signstate_new_by_id(), noise_signstate_new_by_name()

Definition at line 138 of file signstate.c.

int noise_signstate_generate_keypair ( NoiseSignState * state )

Generates a new key pair within a SignState object.

Parameters

state The SignState 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_signstate_sign(), noise_signstate_set_keypair()

Definition at line 264 of file signstate.c.

int noise_signstate_get_keypair	(	const NoiseSignState *	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 SignState object.

Parameters

state	The SignState 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_signstate_set_keypair(), noise_signstate_get_public_key()

Definition at line 395 of file signstate.c.

int noise_signstate_get_max_key_length ( void )

Gets the maximum length of signing keys for the supported algorithms.

See Also: noise_signstate_get_max_signature_length()

Definition at line 677 of file signstate.c.

int noise_signstate_get_max_signature_length ( void )

Gets the maximum length of signatures for the supported algorithms.

See Also: noise_signstate_get_max_key_length()

Definition at line 687 of file signstate.c.

size_t noise_signstate_get_private_key_length ( const NoiseSignState * state )

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

Parameters

state The SignState object.

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

See Also: noise_signstate_get_public_key_length(), noise_signstate_get_signature_length()

Definition at line 190 of file signstate.c.

int noise_signstate_get_public_key	(	const NoiseSignState *	state,
		uint8_t *	public_key,
		size_t	public_key_len
	)

Gets the public key value from a SignState object.

Parameters

state	The SignState 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.; NOISE_ERROR_INVALID_STATE if the public key has not been set on the SignState object yet.

See Also: noise_signstate_set_public_key(), noise_signstate_get_public_key_length()

Definition at line 482 of file signstate.c.

size_t noise_signstate_get_public_key_length ( const NoiseSignState * state )

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

Parameters

state The SignState object.

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

See Also: noise_signstate_get_private_key_length(), noise_signstate_get_signature_length()

Definition at line 175 of file signstate.c.

int noise_signstate_get_sign_id ( const NoiseSignState * state )

Gets the algorithm identifier for a SignState object.

Parameters

state The SignState object.

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

Definition at line 160 of file signstate.c.

size_t noise_signstate_get_signature_length ( const NoiseSignState * state )

Gets the length of the signature for a SignState object.

Parameters

state The SignState object.

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

See Also: noise_signstate_get_public_key_length(), noise_signstate_get_private_key_length()

Definition at line 205 of file signstate.c.

int noise_signstate_has_keypair ( const NoiseSignState * state )

Determine if a SignState object contains a keypair.

Parameters

state The SignState 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_signstate_set_keypair(), noise_signstate_has_public_key(), noise_signstate_clear_key()

Definition at line 222 of file signstate.c.

int noise_signstate_has_public_key ( const NoiseSignState * state )

Determine if a SignState object contains a public key.

Parameters

state The SignState 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_signstate_set_keypair(), noise_signstate_has_public_key(), noise_signstate_clear_key()

Definition at line 242 of file signstate.c.

int noise_signstate_new_by_id	(	NoiseSignState **	state,
		int	id
	)

Creates a new SignState object by its algorithm identifier.

Parameters

state	Points to the variable where to store the pointer to the new SignState object.
id	The algorithm identifier; e.g. NOISE_SIGN_ED5519.

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 SignState object.

See Also: noise_signstate_free(), noise_signstate_new_by_name()

Definition at line 67 of file signstate.c.

int noise_signstate_new_by_name	(	NoiseSignState **	state,
		const char *	name
	)

Creates a new SignState object by its algorithm name.

Parameters

state	Points to the variable where to store the pointer to the new SignState object.
name	The name of the digital signature algorithm; e.g. "Ed25519". 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 SignState object.

See Also: noise_signstate_free(), noise_signstate_new_by_id()

Definition at line 108 of file signstate.c.

int noise_signstate_set_keypair	(	NoiseSignState *	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 SignState object.

Parameters

state	The SignState 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_signstate_sign().

See Also: noise_signstate_get_keypair(), noise_signstate_set_public_key(), noise_signstate_set_keypair_private()

Definition at line 301 of file signstate.c.

int noise_signstate_set_keypair_private	(	NoiseSignState *	state,
		const uint8_t *	private_key,
		size_t	private_key_len
	)

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

Parameters

state	The SignState 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_signstate_sign().

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_signstate_get_keypair(), noise_signstate_set_public_key(), noise_signstate_set_keypair()

Definition at line 352 of file signstate.c.

int noise_signstate_set_public_key	(	NoiseSignState *	state,
		const uint8_t *	public_key,
		size_t	public_key_len
	)

Sets the public key in a SignState object.

Parameters

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

After this function succeeds, the SignState 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_signstate_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_signstate_verify().

See Also: noise_signstate_get_public_key(), noise_signstate_set_keypair()

Definition at line 443 of file signstate.c.

int noise_signstate_sign	(	const NoiseSignState *	state,
		const uint8_t *	message,
		size_t	message_len,
		uint8_t *	signature,
		size_t	signature_len
	)

Signs a message to create a digital signature.

Parameters

state	The SignState object containing the private key.
message	Points to the message to be signed, which is usually a short hash value.
message_len	The length of the message to be signed.
signature	Points to the signature on exit.
signature_len	The length of the signature buffer in bytes.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state, message, or signature is NULL.; NOISE_ERROR_INVALID_LENGTH if signature_len is not correct for the algorithm.; NOISE_ERROR_INVALID_PRIVATE_KEY if state does not contain a private key or the private key is invalid.; NOISE_ERROR_INVALID_PUBLIC_KEY if the public key in state is invalid.

See Also: noise_signstate_generate_keypair(), noise_signstate_verify()

Definition at line 545 of file signstate.c.

int noise_signstate_verify	(	const NoiseSignState *	state,
		const uint8_t *	message,
		size_t	message_len,
		const uint8_t *	signature,
		size_t	signature_len
	)

Verifies a digital signature on a message.

Parameters

state	The SignState object containing the private key.
message	Points to the message whose signature should be verified, which is usually a short hash value.
message_len	The length of the message to be verified.
signature	Points to the signature to be verified.
signature_len	The length of the signature in bytes.

Returns: NOISE_ERROR_NONE on success.; NOISE_ERROR_INVALID_PARAM if state, message, or signature is NULL.; NOISE_ERROR_INVALID_LENGTH if signature_len is not correct for the algorithm.; NOISE_ERROR_INVALID_PUBLIC_KEY if state does not contain a public key or the public key is invalid.; NOISE_ERROR_INVALID_SIGNATURE if the signature is not valid for the message using this public key.

See Also: noise_signstate_set_public_key(), noise_signstate_sign()

Definition at line 583 of file signstate.c.

Typedefs

Functions

Detailed Description

Typedef Documentation

Function Documentation