ra8_secure.h File Reference

Secure-comparison primitives for the crypto / secure-boot paths. More...

#include <stddef.h>

Include dependency graph for ra8_secure.h:

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

Go to the source code of this file.

Functions
bool	ra8_ct_equal (const void *a, const void *b, size_t len)
	Constant-time equality of two byte buffers.
void	ra8_secure_memzero (void *ptr, size_t len)
	Securely zero a buffer such that the write cannot be optimised away.

Detailed Description

Secure-comparison primitives for the crypto / secure-boot paths.

Tag

[Ring 1 / Core] {World: S}

Data-dependent early-out in a byte comparison of a MAC, authentication tag, or image digest leaks – through timing – how many leading bytes matched, which an attacker turns into a byte-at-a-time forgery of the compared value. The plain library memcmp returns as soon as it finds a mismatch and is therefore unsafe on any security-verdict comparison. ra8_ct_equal compares the full length unconditionally so its execution time does not depend on where (or whether) the buffers differ.

Route every MAC / tag / digest / key equality check through ra8_ct_equal; keep plain memcmp only for non-secret, non-verdict comparisons.

Copyright

Copyright (c) 2026 Brighton Sikarskie SPDX-License-Identifier: MIT

Definition in file ra8_secure.h.

Function Documentation

ra8_ct_equal()

bool ra8_ct_equal ( const void * a, const void * b, size_t len )

nodiscard

Constant-time equality of two byte buffers.

OR-accumulates the per-byte XOR difference across all len bytes with no early-out, then reports equality from the accumulator. The number of byte comparisons – and thus the timing – depends only on len, never on the contents, so a caller comparing a secret (MAC / tag / digest / key) against an attacker-supplied value does not leak how many leading bytes matched.

Parameters

[in]	a	First buffer. Must be non-NULL.
[in]	b	Second buffer. Must be non-NULL.
[in]	len	Number of bytes to compare.

Returns

Whether the two buffers are byte-for-byte equal over len bytes.

Return values

true	All len bytes are equal (vacuously true when len == 0).
false	The buffers differ, or either pointer is NULL.

Precondition

a is non-NULL.

b is non-NULL.

Postcondition

Neither buffer is modified.

Execution time is independent of the buffer contents (constant-time).

Note

Use this – never plain memcmp – for any comparison whose result is a security verdict or whose operands are secret.

Thread-safe: reads only, no shared state.

Since

0.1.0

NASA Power of 10 Compliance:

• Rule 2: the compare loop is bounded by the caller-supplied len.
• Rule 5: 2 preconditions (both pointers non-NULL), 2 postconditions.

Definition at line 20 of file ra8_secure.c.

Referenced by priv_ra8_sec_cmac_verify(), and ra8_ota_verify_signature().

ra8_secure_memzero()

void ra8_secure_memzero	(	void *	ptr,
		size_t	len )

Securely zero a buffer such that the write cannot be optimised away.

Overwrites len bytes at ptr with zero through a volatile pointer. A plain memset immediately before a buffer leaves scope is a dead store the optimiser is free to delete, leaving secret key / MAC / digest material in stack or static memory; the volatile access is an observable side effect the compiler must preserve. Use this to scrub any transient that held a secret.

Parameters

[out]	ptr	Buffer to zero. A NULL pointer is a no-op.
[in]	len	Number of bytes to zero. Zero length is a no-op.

Returns

void.

Precondition

ptr is NULL or addresses at least len writable bytes.

len is the size of the secret region, in bytes.

Postcondition

On return, the first len bytes at a non-NULL ptr are zero.

The zeroing store is not elided even if ptr is never read again.

Note

Not a timing-safe operation itself; it exists to erase, not compare.

Thread-safe only with respect to distinct buffers.

Since

0.1.0

NASA Power of 10 Compliance:

• Rule 2: the zeroing loop is bounded by the caller-supplied len.
• Rule 5: 2 preconditions (NULL guard, zero-length guard), 2 postconditions.

Definition at line 37 of file ra8_secure.c.

Referenced by c6_join_phase_associate(), internal_c6_cam_associate(), internal_c6link_op_join(), internal_c6link_sta_set_config(), internal_cmac_subkeys(), internal_cmac_tag(), internal_open_and_join(), internal_run(), internal_verify_cmac(), priv_c6link_rpc_call(), priv_ra8_key_import_build_blob(), priv_ra8_sec_cmac_verify(), ra8_c6link_sta_cfg_set(), ra8_net_provision_clear(), and ra8_net_provision_receive().