Utilities

Macros
#define	noise_new(type)   ((type *)noise_new_object(sizeof(type)))
	Allocates an object from the system and initializes it. More...

Functions
void	noise_clean (void *data, size_t size)
	Cleans a block of memory to destroy its contents. More...
int	noise_format_fingerprint (int fingerprint_type, char *buffer, size_t len, const uint8_t *public_key, size_t public_key_len)
	Formats the fingerprint for a raw public key value. More...
void	noise_free (void *ptr, size_t size)
	Destroys the contents of a block of memory and free it. More...
int	noise_init (void)
	Initializes the Noise-c library. More...
int	noise_is_equal (const void *s1, const void *s2, size_t size)
	Determine if two blocks of memory are equal in constant time. More...
int	noise_is_zero (const void *data, size_t size)
	Determine if a block of memory consists of all zero bytes. More...
void *	noise_new_object (size_t size)
	Allocates memory from the system for an object. More...

Detailed Description

The functions in this module are intended to assist applications that make use of the Noise protocol library.

The noise_clean() function is probably the most useful function here. It zeroes the contents of a buffer in a way that the compiler will hopefully not optimize away like it might optimize memset().

Macro Definition Documentation

#define noise_new

(

type

)

((type *)noise_new_object(sizeof(type)))

Allocates an object from the system and initializes it.

Parameters

type	The structure type, which determines the size of the requested block, and the return type.

Returns

Pointer to the allocated memory or NULL if the system is out of memory.

The object is assumed to start with a size_t field, which will be initialized with the size of type. This is intended for use with noise_free() to destroy the object's contents when it is deallocated. The remaining bytes are initialized to zero.

See Also

noise_new_object(), noise_free()

Definition at line 35 of file util.h.

Function Documentation

void noise_clean	(	void *	data,
		size_t	size
	)

Cleans a block of memory to destroy its contents.

Parameters

data	Points to the block of memory to be cleaned.
size	The size of the block in bytes.

This function tries to perform the operation in a way that should work around compilers and linkers that optimize away memset() calls for memory that the compiler thinks is no longer live.

Definition at line 170 of file util.c.

int noise_format_fingerprint	(	int	fingerprint_type,
		char *	buffer,
		size_t	len,
		const uint8_t *	public_key,
		size_t	public_key_len
	)

Formats the fingerprint for a raw public key value.

Parameters

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.
public_key	Points to the public key to be formatted.
public_key_len	Length of the public_key in bytes.

Returns

NOISE_ERROR_NONE on success.

NOISE_ERROR_INVALID_PARAM if buffer or public_key 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.

This is a low-level formatting function. It is usually better to call one of noise_dhstate_format_fingerprint(), noise_signstate_format_fingerprint(), or noise_keystate_format_fingerprint() instead.

Definition at line 246 of file util.c.

void noise_free	(	void *	ptr,
		size_t	size
	)

Destroys the contents of a block of memory and free it.

Parameters

ptr	Points to the memory to be freed.
size	The number of bytes at ptr.

See Also

noise_new()

Definition at line 152 of file util.c.

noise_init

(

void

)

Initializes the Noise-c library.

Returns

NOISE_ERROR_NONE on success.

This will initialize the underlying crypto libraries. You don't need to call this if you initialize the crypto libraries (eg. libsodium, OpenSSL) yourself.

Definition at line 87 of file util.c.

int noise_is_equal	(	const void *	s1,
		const void *	s2,
		size_t	size
	)

Determine if two blocks of memory are equal in constant time.

Parameters

s1	Points to the first block of memory.
s2	Points to the second block of memory.
size	Number of bytes in each block.

Returns

Returns 1 if the blocks are equal, 0 if they are not.

Definition at line 188 of file util.c.

int noise_is_zero	(	const void *	data,
		size_t	size
	)

Determine if a block of memory consists of all zero bytes.

Parameters

data	Points to the block of memory.
size	The length of the data in bytes.

Returns

Returns 1 if all bytes of data are zero, or 0 if any of the bytes are non-zero.

Definition at line 211 of file util.c.

void* noise_new_object

(

size_t

size

)

Allocates memory from the system for an object.

Parameters

size	The number of bytes of memory to allocate for the object.

Returns

Pointer to the allocated memory or NULL if the system is out of memory.

If size is greater than or equal to sizeof(size_t), then the first few bytes in the returned memory will be set to size. That is, the object is assumed to start with a size field. The remaining bytes in the object are initialized to zero.

Note

If the caller is allocating a structure, then noise_new() is a better option to ensure type-safety.

See Also

noise_new(), noise_free()

Definition at line 135 of file util.c.