A collection of utility functions for cryptographic purposes.
============================================================================
#include <stdint.h>
#include <stdbool.h>
#include <string.h>
Go to the source code of this file.
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... | |
bool CryptoUtils_buffersMatch | ( | const volatile void *volatile | buffer0, |
const volatile void *volatile | buffer1, | ||
size_t | bufferByteLength | ||
) |
Compares two buffers for equality without branching.
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
.
buffer0 | Buffer to compare against buffer1 . |
buffer1 | Buffer tp compare against buffer0 |
bufferByteLength | Length in bytes of buffer0 and buffer1 . |
true | The contents of the buffers match. |
false | The contents of the buffers do not match. |
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.
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.
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). |
true | The contents of the buffers match. |
false | The contents of the buffers do not match. |
bool CryptoUtils_isBufferAllZeros | ( | const void * | buffer, |
size_t | bufferByteLength | ||
) |
Check whether the provided buffer only contains 0x00 bytes.
buffer | Buffer to search for non-zero bytes |
bufferByteLength | Length of buffer in bytes |
true | The buffer contained only bytes with value 0x00 |
false | The buffer contained at least one non-zero byte |
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
.
dest | Pointer to destination buffer |
destSize | Size of destination buffer in bytes |
val | Fill byte value |
count | Number of bytes to fill |
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.
buffer | Buffer containing the data to be reversed. |
bufferByteLength | Length in bytes of buffer . |
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.
source | Source array |
destination | Destination array |
sourceLength | Length of the source array |
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.
source | Source array |
destination | Destination array |
sourceLength | Length of the source array |
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.
source | Source array |
destination | Destination array |
sourceLength | Length of the source array |
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.
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. |
true | The randomNumber is within [lowerLimit , upperLimit ). |
false | The randomNumber is not within [lowerLimit , upperLimit ). |
const uint8_t* CryptoUtils_limitZero |
Limit value of 0.
This is a value provided for convenience when checking a value against a range.
const uint8_t* CryptoUtils_limitOne |
Limit value of 1.
This is a value provided for convenience when checking a value against a range.