util.h File Reference

Useful utility functions for CECIES. More...

#include <time.h>
#include <stdio.h>
#include <stddef.h>
#include <stdlib.h>
#include <stdint.h>
#include "types.h"
#include "constants.h"

Include dependency graph for util.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Macros
#define	CECIES_MIN(x, y)   (((x) < (y)) ? (x) : (y))
#define	CECIES_MAX(x, y)   (((x) > (y)) ? (x) : (y))
#define	cecies_fprintf   cecies_fprintf_fptr

Functions
static size_t	cecies_calc_aes_cbc_ciphertext_length (const size_t plaintext_length)
static size_t	cecies_calc_compression_bound (const size_t data_length)
static size_t	cecies_calc_output_buffer_needed_size (const size_t input_buffer_length, const size_t key_size)
static size_t	cecies_curve25519_calc_output_buffer_needed_size (const size_t input_buffer_length)
static size_t	cecies_curve448_calc_output_buffer_needed_size (const size_t input_buffer_length)
static size_t	cecies_calc_base64_length (const size_t data_length)
CECIES_API int	cecies_hexstr2bin (const char *hexstr, size_t hexstr_length, uint8_t *output, size_t output_size, size_t *output_length)
CECIES_API int	cecies_bin2hexstr (const uint8_t *bin, size_t bin_length, char *output, size_t output_size, size_t *output_length, int uppercase)
CECIES_API char *	cecies_get_version_str ()
CECIES_API uint64_t	cecies_get_version_nr ()
CECIES_API int	cecies_is_fprintf_enabled ()
static int	cecies_printvoid (FILE *stream, const char *format,...)
CECIES_API void	cecies_enable_fprintf ()
CECIES_API void	cecies_disable_fprintf ()
static unsigned long long int	cecies_get_random_big_integer ()
CECIES_API void	cecies_dev_urandom (uint8_t *output_buffer, size_t output_buffer_size)
CECIES_API void	cecies_free (void *mem)

Detailed Description

Useful utility functions for CECIES.

Author

Raphael Beck

Macro Definition Documentation

CECIES_MAX

#define CECIES_MAX	(		x,
			y
	)		(((x) > (y)) ? (x) : (y))

x > y ? x : y

CECIES_MIN

#define CECIES_MIN	(		x,
			y
	)		(((x) < (y)) ? (x) : (y))

x < y ? x : y

Function Documentation

cecies_bin2hexstr()

CECIES_API int cecies_bin2hexstr	(	const uint8_t *	bin,
		size_t	bin_length,
		char *	output,
		size_t	output_size,
		size_t *	output_length,
		int	uppercase
	)

Converts a byte array to a hex string.

A NUL-terminator is appended at the end of the output buffer, so make sure to allocate at least (bin_length * 2) + 1 bytes!

Parameters

bin	The binary data to convert into hex string.
bin_length	Length of the bin array.
output	Where to write the hex string into.
output_size	Maximum capacity of the output buffer. Make sure to allocate at least (bin_length * 2) + 1 bytes!
output_length	[OPTIONAL] Where to write the output string length into. This is always gonna be bin_length * 2, but you can still choose to write it out just to be sure. If you want to omit this: no problem.. just pass NULL!
uppercase	Should the output string characters be UPPER- or lowercase? Pass 0 for false, anything else for true.

Returns

0 if conversion succeeded. 1 if one or more required arguments were NULL or invalid. 2 if the output buffer size is insufficient: please allocate at least (bin_length * 2) + 1 bytes!

cecies_calc_aes_cbc_ciphertext_length()

static size_t cecies_calc_aes_cbc_ciphertext_length ( const size_t  plaintext_length )

inlinestatic

Calculates the length of an AES-CBC ciphertext given a specific plaintext data length (in bytes).

Parameters

plaintext_length

The amount of bytes to encrypt.

Returns

The ciphertext length (a multiple of the blocksize).

cecies_calc_base64_length()

static size_t cecies_calc_base64_length ( const size_t  data_length )

inlinestatic

Calculates the output length in bytes after base64-encoding data_length bytes (includes +1 for a NUL-terminator character)..

Parameters

data_length

The number of bytes you'd base64-encode.

Returns

((4 * data_length / 3 + 3) & ~3) + 1

cecies_calc_compression_bound()

static size_t cecies_calc_compression_bound ( const size_t  data_length )

inlinestatic

Estimates the required buffer size that would be needed to compress data_length bytes of data.

Parameters

data_length

How many bytes to compress.

Returns

The minimum amount of bytes to allocate for a compression of data_length bytes to conclude safely.

cecies_calc_output_buffer_needed_size()

static size_t cecies_calc_output_buffer_needed_size ( const size_t  input_buffer_length, const size_t  key_size  )

inlinestatic

Gets the minimum amount of needed buffer size for an encryption with a given plaintext data length.

Parameters

input_buffer_length	The amount of bytes to encrypt.
key_size	Size in bytes of the used ephemeral key (X448 keys are slightly bigger than X25519).

Returns

The min. buffer size for encrypting input_buffer_length bytes of data.

cecies_curve25519_calc_output_buffer_needed_size()

static size_t cecies_curve25519_calc_output_buffer_needed_size ( const size_t  input_buffer_length )

inlinestatic

Gets the minimum amount of needed buffer size for a given Curve25519 encryption with a given plaintext data length.

Parameters

input_buffer_length

The amount of bytes to encrypt.

Returns

The min. buffer size for encrypting input_buffer_length bytes of data.

cecies_curve448_calc_output_buffer_needed_size()

static size_t cecies_curve448_calc_output_buffer_needed_size ( const size_t  input_buffer_length )

inlinestatic

Gets the minimum amount of needed buffer size for a given Curve448 encryption with a given plaintext data length.

Parameters

input_buffer_length

The amount of bytes to encrypt.

Returns

The min. buffer size for encrypting input_buffer_length bytes of data.

cecies_dev_urandom()

CECIES_API void cecies_dev_urandom	(	uint8_t *	output_buffer,
		size_t	output_buffer_size
	)

(Tries to) read from /dev/urandom (or Windows equivalent, yeah...) filling the given output_buffer with output_buffer_size random bytes.

Parameters

output_buffer	Where to write the random bytes into.
output_buffer_size	How many random bytes to write into output_buffer

cecies_disable_fprintf()

CECIES_API void cecies_disable_fprintf

(

)

Disables CECIES' use of fprintf().

cecies_enable_fprintf()

CECIES_API void cecies_enable_fprintf

(

)

Enables CECIES' use of fprintf().

cecies_free()

CECIES_API void cecies_free

(

void *

mem

)

Free memory that was allocated by CECIES.

Wraps the free() function (mainly useful for C# interop).

Parameters

mem	The pointer to the memory to free.

cecies_get_random_big_integer()

static unsigned long long int cecies_get_random_big_integer ( )

inlinestatic

Gets a random big integer. This only features very limited randomness due to usage of rand()!

DO NOT USE THIS FOR ANY TYPE OF KEY GENERATION!

Current usage is for adding some lightweight additional entropy to the MbedTLS mbedtls_ctr_drbg_seed() function, which only gives the advantage of having a slightly different per-app starting point for the seed (as stated in the MbedTLS documentation).

Returns

Random big number

cecies_get_version_nr()

CECIES_API uint64_t cecies_get_version_nr

(

)

Gets the current CECIES version number as an unsigned integer (e.g. version "2.1.2" would return 212).

Returns

The current CECIES version number.

cecies_get_version_str()

CECIES_API char * cecies_get_version_str

(

)

Gets the current CECIES version number as a human-readable string (e.g. "2.1.2").

Returns

The stringified current CECIES version number.

cecies_hexstr2bin()

CECIES_API int cecies_hexstr2bin	(	const char *	hexstr,
		size_t	hexstr_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Converts a hex string to binary array.

A NUL-terminator is appended at the end of the output buffer, so make sure to allocate at least (hexstr_length / 2) + 1 bytes!

Parameters

hexstr	The hex string to convert.
hexstr_length	Length of the hexstr
output	Where to write the converted binary data into.
output_size	Size of the output buffer (make sure to allocate at least (hexstr_length / 2) + 1 bytes!).
output_length	[OPTIONAL] Where to write the output array length into. This is always gonna be hexstr_length / 2, but you can still choose to write it out just to be sure. If you want to omit this: no problem.. just pass NULL!

Returns

0 if conversion succeeded. 1 if one or more required arguments were NULL or invalid. 2 if the hexadecimal string is in an invalid format (e.g. not divisible by 2). 3 if output buffer size was insufficient (needs to be at least (hexstr_length / 2) + 1 bytes).

cecies_is_fprintf_enabled()

CECIES_API int cecies_is_fprintf_enabled

(

)

Checks whether CECIES fprintf is enabled (whether errors are fprintfed into stderr).

Returns

Whether errors are fprintfed into stderr or not (1 for true ; 0 for false).

cecies_printvoid()

static int cecies_printvoid ( FILE *  stream, const char *  format,   ...  )

inlinestatic

Like fprintf() except it doesn't do anything. Like printing into /dev/null :D lots of fun!

Parameters

stream	[IGNORED]
format	[IGNORED]
...	[IGNORED]

Returns

0