Hardened memory operations for constant power buffer manipulation. More...

#include <stddef.h>
#include <stdint.h>
#include "sw/device/lib/base/hardened.h"
#include "sw/device/lib/base/macros.h"
#include "sw/device/lib/crypto/impl/status.h"

Functions
uint32_t	hardened_memshred_random_word (void)
	Expects some external implementation of randomness to be linked.

status_t	hardened_memcpy (uint32_t OT_RESTRICT dest, const uint32_t OT_RESTRICT src, size_t word_len)
	Copies 32-bit words between non-overlapping regions.

status_t	hardened_memshred (uint32_t *dest, size_t word_len)
	Fills a 32-bit aligned region of memory with random data.

hardened_bool_t	hardened_memeq (const uint32_t lhs, const uint32_t rhs, size_t word_len)
	Compare two potentially-overlapping 32-bit aligned regions of memory for equality.

hardened_bool_t	consttime_memeq_byte (const void lhs, const void rhs, size_t len)
	Constant time memeq implementation that can also handle non 32-bit aligned buffers.

status_t	hardened_xor (const uint32_t OT_RESTRICT x, const uint32_t OT_RESTRICT y, size_t word_len, uint32_t *OT_RESTRICT dest)
	Combines two word buffers with XOR and store the result in the dest.

status_t	hardened_xor_in_place (uint32_t OT_RESTRICT x, const uint32_t OT_RESTRICT y, size_t word_len)
	Combines two word buffers with XOR in-place.

status_t	randomized_bytecopy (void OT_RESTRICT dest, const void OT_RESTRICT src, size_t byte_len)
	Copy memory between non-overlapping regions with a randomized byte traversal.

status_t	randomized_bytexor_in_place (void OT_RESTRICT x, const void OT_RESTRICT y, size_t byte_len)
	In-place XOR of two non-overlapping memory regions with a randomized byte traversal.

status_t	hardened_add (const uint32_t OT_RESTRICT x, const uint32_t OT_RESTRICT y, size_t word_len, uint32_t *OT_RESTRICT dest)
	Combines two word buffers with ADD and store the result in the dest.

status_t	hardened_sub (const uint32_t OT_RESTRICT x, const uint32_t OT_RESTRICT y, size_t word_len, uint32_t *OT_RESTRICT dest)
	Combines two word buffers with SUB and store the result in the dest.

status_t	hardened_sub_mod (const uint32_t OT_RESTRICT x, const uint32_t OT_RESTRICT y, const uint32_t OT_RESTRICT n, size_t word_len, uint32_t OT_RESTRICT dest)
	Perform a modular subtraction of two multi-word values.

status_t	hardened_add_mod (const uint32_t OT_RESTRICT x, const uint32_t OT_RESTRICT y, const uint32_t OT_RESTRICT n, size_t word_len, uint32_t OT_RESTRICT dest)
	Perform a modular addition of two multi-word values.

status_t	hardened_range_check (const uint32_t value, const uint32_t N, size_t word_len)
	Perform a range check whether the value is larger than zero and smaller than N.

status_t	hardened_mod_reduce (const uint32_t value, const uint32_t n, size_t word_len, uint32_t *result)
	Perform a modular reduction of a multi-word value by a multi-word modulus.

Detailed Description

Hardened memory operations for constant power buffer manipulation.

Definition in file hardened_memory.h.

Function Documentation

◆ consttime_memeq_byte()

hardened_bool_t consttime_memeq_byte	(	const void *	lhs,
		const void *	rhs,
		size_t	len )

Constant time memeq implementation that can also handle non 32-bit aligned buffers.

SCA protection is provided by choosing a random start index for the comparison.

CAUTION! This function is not considered as secure as hardened_memeq due to the byte-sized memory accesses vs. 32b word accesses.

Parameters

lhs	The first buffer to compare.
rhs	The second buffer to compare.
word_len	The number of bytes to compare.

Definition at line 127 of file hardened_memory.c.

◆ hardened_add()

status_t hardened_add	(	const uint32_t *OT_RESTRICT	x,
		const uint32_t *OT_RESTRICT	y,
		size_t	word_len,
		uint32_t *OT_RESTRICT	dest )

Combines two word buffers with ADD and store the result in the dest.

buffer.

Warning: Only limited SCA hardening measures are applied due to the nature of arithmetic operations. guaranteed. The function is hardened against fault injections.

This mimics the OTBN add.

Parameters

x	Pointer to the first operand.
y	Pointer to the second operand.
word_len	Length in words of each operand.
dest[out]	Pointer to the output buffer.

Returns: OK or error.

◆ hardened_add_mod()

status_t hardened_add_mod	(	const uint32_t *OT_RESTRICT	x,
		const uint32_t *OT_RESTRICT	y,
		const uint32_t *OT_RESTRICT	n,
		size_t	word_len,
		uint32_t *OT_RESTRICT	dest )

Perform a modular addition of two multi-word values.

It computes (x + y) mod n. The values are expected to follow a little-endian layout.

Warning: the side-channel protection of this function call can not be guaranteed. The function is hardened against fault injections and is constant time in the value being reduced.

In order to have this function constant time, it conditionally subtracts n only once. This function mimics OTBN's addm.

Parameters

	x	Pointer to the first operand.
	y	Pointer to the second operand.
	n	Pointer to the multi-word modulus.
	word_len	Length in words of each operand and the modulus.
[out]	dest	Pointer to the multi-word result.

Returns: OK or error.

◆ hardened_memcpy()

status_t hardened_memcpy	(	uint32_t *OT_RESTRICT	dest,
		const uint32_t *OT_RESTRICT	src,
		size_t	word_len )

Copies 32-bit words between non-overlapping regions.

Unlike memcpy(), this function has important differences:

It is significantly slower, since it mitigates power-analysis attacks.
It performs operations on 32-bit words, rather than bytes.
It returns a status.

Input pointers MUST be 32-bit aligned, although they do not need to actually point to memory declared as uint32_t per the C aliasing rules. Internally, this function is careful to not dereference its operands directly, and instead uses dedicated load/store intrinsics.

Parameters

dest	The destination of the copy.
src	The source of the copy.
word_len	The number of words to copy.

Returns: OK or error.

◆ hardened_memeq()

hardened_bool_t hardened_memeq	(	const uint32_t *	lhs,
		const uint32_t *	rhs,
		size_t	word_len )

Compare two potentially-overlapping 32-bit aligned regions of memory for equality.

Unlike memcmp(), this function has important differences:

It is significantly slower, since it mitigates power-analysis attacks.
It performs operations on 32-bit words, rather than bytes.
It only computes equality, not lexicographic ordering, which would be even slower.
It returns a hardened_bool_t.
It is constant-time.

Input pointers MUST be 32-bit aligned, although they do not need to actually point to memory declared as uint32_t per the C aliasing rules. Internally, this function is careful to not dereference its operands directly, and instead uses dedicated load/store intrinsics.

Parameters

lhs	The first buffer to compare.
rhs	The second buffer to compare.
word_len	The number of words to compare.

Definition at line 78 of file hardened_memory.c.

◆ hardened_memshred()

status_t hardened_memshred	(	uint32_t *	dest,
		size_t	word_len )

Fills a 32-bit aligned region of memory with random data.

Unlike memset(), this function has important differences:

It is significantly slower, since it mitigates power-analysis attacks.
It performs operations on 32-bit words, rather than bytes.
A fill value cannot be specified.
It returns a status.

Input pointers MUST be 32-bit aligned, although they do not need to actually point to memory declared as uint32_t per the C aliasing rules. Internally, this function is careful to not dereference its operands directly, and instead uses dedicated load/store intrinsics.

Parameters

dest	The destination of the set.
word_len	The number of words to write.

Returns: OK or error.

Definition at line 53 of file hardened_memory.c.

◆ hardened_memshred_random_word()

uint32_t hardened_memshred_random_word ( void )

extern

Expects some external implementation of randomness to be linked.

Returns: A fresh random word.

Definition at line 141 of file rnd.c.

◆ hardened_mod_reduce()

status_t hardened_mod_reduce	(	const uint32_t *	value,
		const uint32_t *	n,
		size_t	word_len,
		uint32_t *	result )

Perform a modular reduction of a multi-word value by a multi-word modulus.

It checks whether value % n. The value is expected to follow a little-endian layout.

Warning: the side-channel protection of this function call can not be guaranteed. The function is hardened against fault injections and is constant time in the value being reduced.

Parameters

	value	Pointer to the value to check.
	n	Pointer to the multi-word modulus.
	word_len	Length in words of value.
[out]	result	Pointer to the multi-word result.

Returns: OK or error.

Definition at line 608 of file hardened_memory.c.

◆ hardened_range_check()

status_t hardened_range_check	(	const uint32_t *	value,
		const uint32_t *	N,
		size_t	word_len )

Perform a range check whether the value is larger than zero and smaller than N.

Namely, it checks whether 0 < value < N. Values are expected to follow little-endian layout.

Warning: the side-channel protection of this function call can not be guaranteed. The function is hardened against fault injections and is constant time.

Parameters

value	Pointer to the value to check.
N	Pointer to the upper limit of the range.
word_len	Length in words of value and N.

Returns: OK or error.

Definition at line 569 of file hardened_memory.c.

◆ hardened_sub()

status_t hardened_sub	(	const uint32_t *OT_RESTRICT	x,
		const uint32_t *OT_RESTRICT	y,
		size_t	word_len,
		uint32_t *OT_RESTRICT	dest )

Combines two word buffers with SUB and store the result in the dest.

buffer.

Warning: the side-channel protection of this function call can not be guaranteed. The function is hardened against fault injections.

This mimics the OTBN sub.

Parameters

x	Pointer to the first operand.
y	Pointer to the second operand.
word_len	Length in words of each operand.
dest[out]	Pointer to the output buffer.

Returns: OK or error.

◆ hardened_sub_mod()

status_t hardened_sub_mod	(	const uint32_t *OT_RESTRICT	x,
		const uint32_t *OT_RESTRICT	y,
		const uint32_t *OT_RESTRICT	n,
		size_t	word_len,
		uint32_t *OT_RESTRICT	dest )

Perform a modular subtraction of two multi-word values.

It computes (x - y) mod n. The values are expected to follow a little-endian layout.

Warning: the side-channel protection of this function call can not be guaranteed. The function is hardened against fault injections and is constant time in the value being reduced.

In order to have this function constant time, it conditionally adds n only once. This function mimics OTBN's subm.

Parameters

	x	Pointer to the first operand.
	y	Pointer to the second operand.
	n	Pointer to the multi-word modulus.
	word_len	Length in words of each operand and the modulus.
[out]	dest	Pointer to the multi-word result.

Returns: OK or error.

◆ hardened_xor()

status_t hardened_xor	(	const uint32_t *OT_RESTRICT	x,
		const uint32_t *OT_RESTRICT	y,
		size_t	word_len,
		uint32_t *OT_RESTRICT	dest )

Combines two word buffers with XOR and store the result in the dest.

buffer.

Performs dest = ((rand ^ x) ^ y) ^ rand

Callers should ensure the entropy complex is up before calling this function. The implementation uses random-order hardening primitives for side-channel defense. Moreover, calles should ensure that the dest. buffer is different from the source buffers.

Parameters

x	Pointer to the first operand.
y	Pointer to the second operand.
word_len	Length in words of each operand.
dest[out]	Pointer to the output buffer.

Returns: OK or error.

◆ hardened_xor_in_place()

status_t hardened_xor_in_place	(	uint32_t *OT_RESTRICT	x,
		const uint32_t *OT_RESTRICT	y,
		size_t	word_len )

Combines two word buffers with XOR in-place.

Callers should ensure the entropy complex is up before calling this function. The implementation uses random-order hardening primitives for side-channel defense.

Parameters

[in,out]	x	Pointer to the first operand (modified in-place).
	y	Pointer to the second operand.
	word_len	Length in words of each operand.

Returns: OK or error.

◆ randomized_bytecopy()

status_t randomized_bytecopy	(	void *OT_RESTRICT	dest,
		const void *OT_RESTRICT	src,
		size_t	byte_len )

Copy memory between non-overlapping regions with a randomized byte traversal.

CAUTION! This function is not considered as secure as hardened_memcpy due to the byte-sized memory accesses vs. 32b word accesses. After this function, a consttime_memeq_byte(src, dest, byte_len) should follow to check if the bytecopy was successful (see lowRISC/opentitan#8815). Switch the function arguments as shown in the example to also cover faults directly on the pointers.

Parameters

dest	the region to copy to.
src	the region to copy from.
byte_len,the	number of bytes to copy.

Returns: Result of the operation (OK or error).

◆ randomized_bytexor_in_place()

status_t randomized_bytexor_in_place	(	void *OT_RESTRICT	x,
		const void *OT_RESTRICT	y,
		size_t	byte_len )

In-place XOR of two non-overlapping memory regions with a randomized byte traversal.

CAUTION! This function is not considered as secure as hardened_xor_in_place due to the byte-sized memory accesses vs. 32b word accesses.

Parameters

x	Pointer to the first operand (modified in-place).
y	Pointer to the second operand.
byte_len,the	number of bytes to XOR.

Returns: Result of the operation (OK or error).

Functions

Detailed Description

Function Documentation

◆ consttime_memeq_byte()

◆ hardened_add()

◆ hardened_add_mod()

◆ hardened_memcpy()

◆ hardened_memeq()

◆ hardened_memshred()

◆ hardened_memshred_random_word()

◆ hardened_mod_reduce()

◆ hardened_range_check()

◆ hardened_sub()

◆ hardened_sub_mod()

◆ hardened_xor()

◆ hardened_xor_in_place()

◆ randomized_bytecopy()

◆ randomized_bytexor_in_place()