Detailed Description

A collection of utility functions for cryptographic purposes.

============================================================================

#include <stdint.h>
#include <stdbool.h>
#include <string.h>

Include dependency graph for CryptoUtils.h:

Enumerations
enum	CryptoUtils_Endianess { CryptoUtils_ENDIANESS_BIG = 0u, CryptoUtils_ENDIANESS_LITTLE = 1u }
	Indicates the endianess (byte order) of a multi-byte value. More...

Functions
bool	CryptoUtils_buffersMatch (const volatile void volatile buffer0, const volatile void volatile buffer1, size_t bufferByteLength)
	Compares two buffers for equality without branching. More...

bool	CryptoUtils_buffersMatchWordAligned (const volatile uint32_t volatile buffer0, const volatile uint32_t volatile buffer1, size_t bufferByteLength)
	Compares two buffers for equality word-by-word without branching. More...

bool	CryptoUtils_isBufferAllZeros (const void *buffer, size_t bufferByteLength)
	Check whether the provided buffer only contains 0x00 bytes. More...

void	CryptoUtils_memset (void *dest, size_t destSize, uint8_t val, size_t count)
	Copies `val` into the first `count` bytes of the buffer pointed to by `dest`. More...

void	CryptoUtils_reverseBufferBytewise (void *buffer, size_t bufferByteLength)
	Reverses the byte order in a buffer of a given length. More...

void	CryptoUtils_copyPad (const void source, uint32_t destination, size_t sourceLength)
	Copies and pads an array of words. More...

void	CryptoUtils_reverseCopyPad (const void source, uint32_t destination, size_t sourceLength)
	Reverses, copies, and pads an array of words. More...

void	CryptoUtils_reverseCopy (const void source, void destination, size_t sourceLength)
	Reverses and copies an array of bytes. More...

bool	CryptoUtils_isNumberInRange (const void number, size_t bitLength, CryptoUtils_Endianess endianess, const void lowerLimit, const void *upperLimit)
	Checks if number is within the range [lowerLimit, upperLimit) More...

Variables
const uint8_t *	CryptoUtils_limitZero
	Limit value of 0. More...

const uint8_t *	CryptoUtils_limitOne
	Limit value of 1. More...

Enumeration Type Documentation

§ CryptoUtils_Endianess

enum CryptoUtils_Endianess

Indicates the endianess (byte order) of a multi-byte value.

Enumerator
CryptoUtils_ENDIANESS_BIG	MSB at lowest address.
CryptoUtils_ENDIANESS_LITTLE	LSB at highest address.

Function Documentation

§ CryptoUtils_buffersMatch()

bool CryptoUtils_buffersMatch	(	const volatile void *volatile	buffer0,
		const volatile void *volatile	buffer1,
		size_t	bufferByteLength
	)

Compares two buffers for equality without branching.

Note: This is not a drop-in replacement for memcmp!

Most memcmp implementations break out of their comparison loop immediately once a mismatch is detected to save execution time. For cryptographic purposes, this is a flaw.

This function compares two buffers without branching thus requiring a an amount of time that does not vary with the content of buffer0 and buffer1.

Parameters

buffer0	Buffer to compare against `buffer1`.
buffer1	Buffer tp compare against `buffer0`
bufferByteLength	Length in bytes of `buffer0` and `buffer1`.

Return values

true	The contents of the buffers match.
false	The contents of the buffers do not match.

§ CryptoUtils_buffersMatchWordAligned()

bool CryptoUtils_buffersMatchWordAligned	(	const volatile uint32_t *volatile	buffer0,
		const volatile uint32_t *volatile	buffer1,
		size_t	bufferByteLength
	)

Compares two buffers for equality word-by-word without branching.

Note: This is not a drop-in replacement for memcmp!

Most memcmp implementations break out of their comparison loop immediately once a mismatch is detected to save execution time. For cryptographic purposes, this is a flaw.

This function compares two buffers without branching thus requiring a an amount of time that does not vary with the content of buffer0 and buffer1.

Unlike CryptoUtils_buffersMatch(), this function expects buffer0 and buffer1 to be 32-bit aligned. It will only perform 32-bit aligned accesses to memory. This is needed to access the registers of certain peripherals.

Parameters

buffer0	Buffer to compare against `buffer1`.
buffer1	Buffer tp compare against `buffer0`
bufferByteLength	Length in bytes of `buffer0` and `buffer1`. Must be evenly divisible by sizeof(uint32_t). This function will return false if `bufferByteLength` is not evenly divisible by sizeof(uin32_t).

Return values

true	The contents of the buffers match.
false	The contents of the buffers do not match.

§ CryptoUtils_isBufferAllZeros()

bool CryptoUtils_isBufferAllZeros	(	const void *	buffer,
		size_t	bufferByteLength
	)

Check whether the provided buffer only contains 0x00 bytes.

Parameters

buffer	Buffer to search for non-zero bytes
bufferByteLength	Length of `buffer` in bytes

Return values

true	The buffer contained only bytes with value 0x00
false	The buffer contained at least on non-zero byte

§ CryptoUtils_memset()

void CryptoUtils_memset	(	void *	dest,
		size_t	destSize,
		uint8_t	val,
		size_t	count
	)

Copies val into the first count bytes of the buffer pointed to by dest.

Parameters

dest	Pointer to destination buffer
destSize	Size of destination buffer in bytes
val	Fill byte value
count	Number of bytes to fill

§ CryptoUtils_reverseBufferBytewise()

void CryptoUtils_reverseBufferBytewise	(	void *	buffer,
		size_t	bufferByteLength
	)

Reverses the byte order in a buffer of a given length.

The left-most byte will become the right-most byte and vice versa.

Parameters

buffer	Buffer containing the data to be reversed.
bufferByteLength	Length in bytes of `buffer`.

§ CryptoUtils_copyPad()

void CryptoUtils_copyPad	(	const void *	source,
		uint32_t *	destination,
		size_t	sourceLength
	)

Copies and pads an array of words.

The source array is copied into the destination array. Writes are done word-wise. If sourceLength is not a multiple of 4, any remaining bytes up to the next word boundary are padded with 0.

The length of the destination array must be a multiple of 4, rounded up to the padded sourceLength if required.

Parameters

source	Source array
destination	Destination array
sourceLength	Length of the source array

§ CryptoUtils_reverseCopyPad()

void CryptoUtils_reverseCopyPad	(	const void *	source,
		uint32_t *	destination,
		size_t	sourceLength
	)

Reverses, copies, and pads an array of words.

The source array is reversed byte-wise and copied into the destination array. Writes are done word-wise. If sourceLength is not a multiple of 4, any remaining bytes up to the next word boundary are padded with 0.

The length of the destination array must be a multiple of 4, rounded up to the padded sourceLength if required.

Parameters

source	Source array
destination	Destination array
sourceLength	Length of the source array

§ CryptoUtils_reverseCopy()

void CryptoUtils_reverseCopy	(	const void *	source,
		void *	destination,
		size_t	sourceLength
	)

Reverses and copies an array of bytes.

The source array is reversed byte-wise and copied into the destination array.

Parameters

source	Source array
destination	Destination array
sourceLength	Length of the source array

§ CryptoUtils_isNumberInRange()

bool CryptoUtils_isNumberInRange	(	const void *	number,
		size_t	bitLength,
		CryptoUtils_Endianess	endianess,
		const void *	lowerLimit,
		const void *	upperLimit
	)

Checks if number is within the range [lowerLimit, upperLimit)

Checks if the specified number is at greater than or equal to the lower limit and less than the upper limit. Note that the boundary set by the upper limit is not inclusive.

Note that the special values of CryptoUtils_limitZero and CryptoUtils_limitOne are available to pass in for the lowerLimit. (These values can also be used for the upperLimit but their use for the upperLimit has no practical use.)

If lowerLimit is NULL then the lower limit is taken as 0. If upperLimit is NULL then the upper limit is taken as 2^{(bitLength + 1)}.

The implemented algorithm is timing-constant when the following parameters are held constant: lowerLimit, upperLimit, bitLength, and endianess. Thus, the number being checked may change and timing will not leak its relation to the limits. However, timing may leak the bitLength, the endianess, and the use of CryptoUtils_limitZero, CryptoUtils_limitOne, and NULL for the limit values.

Parameters

number	Pointer to number to check
bitLength	Length in bits of `number`, `lowerLimit`, and `upperLimit`.
endianess	The endianess of `number`, `lowerLimit`, and `upperLimit`.
lowerLimit	Pointer to lower limit value.
upperLimit	Pointer to upper limit value.

Return values

true	The randomNumber is within [`lowerLimit`, `upperLimit`).
false	The randomNumber is not within [`lowerLimit`, `upperLimit`).

Variable Documentation

§ CryptoUtils_limitZero

const uint8_t* CryptoUtils_limitZero

Limit value of 0.

This is a value provided for convenience when checking a value against a range.

See also: CryptoUtils_limitOne; CryptoUtils_isNumberInRange

§ CryptoUtils_limitOne

const uint8_t* CryptoUtils_limitOne

Limit value of 1.

This is a value provided for convenience when checking a value against a range.

See also: CryptoUtils_limitZero; CryptoUtils_isNumberInRange

Detailed Description

Enumerations

Functions

Variables

Enumeration Type Documentation

§ CryptoUtils_Endianess

Function Documentation

§ CryptoUtils_buffersMatch()

§ CryptoUtils_buffersMatchWordAligned()

§ CryptoUtils_isBufferAllZeros()

§ CryptoUtils_memset()

§ CryptoUtils_reverseBufferBytewise()

§ CryptoUtils_copyPad()

§ CryptoUtils_reverseCopyPad()

§ CryptoUtils_reverseCopy()

§ CryptoUtils_isNumberInRange()

Variable Documentation

§ CryptoUtils_limitZero

§ CryptoUtils_limitOne