Secure-only symmetric key store implementation. More...

#include "key_vault.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_secure.h"

Include dependency graph for key_vault.c:

Functions
ra8_err_t	ra8_key_vault_init (void)
	Initialise the vault (zero every slot).
ra8_err_t	ra8_key_vault_store (uint16_t slot, const uint8_t *key)
	Programme a 256-bit symmetric key into a vault slot.
ra8_err_t	ra8_key_vault_sha256_xor_challenge (uint16_t slot, const uint8_t challenge, uint8_t out)
	Compute SHA-256(key XOR challenge) for slot.
ra8_err_t	ra8_key_vault_set_mac_key (const uint8_t *key, uint16_t key_len)
	Provision the key-authentication key (KAK) used to MAC key imports.
ra8_err_t	ra8_key_vault_load_mac_key (uint8_t out, uint16_t out_cap, uint16_t out_len)
	Copy the provisioned key-authentication key for a secure caller.

Variables
static const char *	s_tag = "KEYV"

Detailed Description

Secure-only symmetric key store implementation.

Tag: [Ring 5 / SECAPP] {World: S}

implementation. Stores 8 symmetric keys in a static array that lives in the secure SRAM partition. Provides three operations:

ra8_key_vault_init zero every slot.
ra8_key_vault_store copy a 32-byte key into a slot.
ra8_key_vault_sha256_xor_challenge compute SHA-256(key XOR challenge) – the only operation the NS world can reach via the NSC veneer.

The SHA-256 implementation is a small fixed-iteration sponge baked into this file – no external libraries, no heap. It is NIST FIPS 180-4 compliant for the single-block case used here (32-byte input, 32-byte output, single padding block).

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

Definition in file key_vault.c.

Function Documentation

◆ ra8_key_vault_init()

ra8_err_t ra8_key_vault_init ( void )

nodiscard

Initialise the vault (zero every slot).

Returns: ra8_err_t error code (currently always k_ra8_ok).

Precondition: Called once from secure-world boot.

Postcondition: Every slot reads as all-zeros.

Note: Thread safety: secure-world only, single-threaded init.

Since: 0.1.0

Definition at line 562 of file key_vault.c.

References k_ra8_err_not_supported.

◆ ra8_key_vault_load_mac_key()

ra8_err_t ra8_key_vault_load_mac_key	(	uint8_t *	out,
		uint16_t	out_cap,
		uint16_t *	out_len )

nodiscard

Copy the provisioned key-authentication key for a secure caller.

Secure-world-only accessor used by key_import.c to key the AES-CMAC. It copies the KAK into a caller-supplied secure buffer; the material never crosses to Non-Secure code (no NSC veneer exposes it). The caller wipes the copy after use.

Parameters

[out]	out	Destination for the KAK (secure scratch).
[in]	out_cap	Capacity of out in bytes (>= key_len).
[out]	out_len	Receives the KAK length actually copied.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	KAK copied and *out_len set.
k_ra8_err_null_ptr	out or out_len was NULL.
k_ra8_err_not_found	No KAK has been provisioned yet.
k_ra8_err_invalid_size	out_cap was smaller than the KAK.

Precondition: out and out_len are non-NULL.; A KAK was provisioned via ra8_key_vault_set_mac_key.

Postcondition: On success, out[0..*out_len-1] holds the KAK.; On error, no KAK bytes are copied.

Note: Thread safety: not thread-safe; secure-world only.

Warning: The caller must ra8_secure_memzero the copy after use.

See also: ra8_key_vault_set_mac_key()

Since: 0.1.0

Definition at line 589 of file key_vault.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_verify_cmac(), and priv_ra8_key_import_build_blob().

◆ ra8_key_vault_set_mac_key()

ra8_err_t ra8_key_vault_set_mac_key	(	const uint8_t *	key,
		uint16_t	key_len )

nodiscard

Provision the key-authentication key (KAK) used to MAC key imports.

The KAK is the secret that keys the AES-CMAC over a wrapped-key blob in priv_ra8_key_import_seal. It is stored in dedicated secure-side storage that is separate from the NS-importable slot array, so it can never be overwritten or read through the ra8_key_import_* / NSC path a Non-Secure caller reaches. Secure boot (or the host test harness) provisions it once before any import can occur. This is the single answer to "where does the CMAC key come from": the secure key vault, never NS.

Parameters

[in]	key	Raw AES-CMAC key material.
[in]	key_len	Key length: 16 (AES-128) or 32 (AES-256) bytes.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	KAK stored.
k_ra8_err_null_ptr	key was NULL.
k_ra8_err_invalid_arg	key_len was neither 16 nor 32.

Precondition: Called from secure world only, during provisioning.; key points to key_len bytes of secure RAM.

Postcondition: The KAK store holds the key and records key_len.

Note: Thread safety: secure-world only, single-threaded provisioning.

See also: ra8_key_vault_load_mac_key()

Since: 0.1.0

Definition at line 582 of file key_vault.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_key_vault_sha256_xor_challenge()

ra8_err_t ra8_key_vault_sha256_xor_challenge	(	uint16_t	slot,
		const uint8_t *	challenge,
		uint8_t *	out )

nodiscard

Compute SHA-256(key XOR challenge) for slot.

This is the only operation the Non-Secure world can reach via the ra8_nsc_key_vault_challenge veneer. The raw key never leaves the secure world; what crosses the boundary is the 32-byte SHA-256 digest of (key XOR challenge), which depends on both the key and the challenge but reveals neither.

Parameters

[in]	slot	Slot index 0..k_ra8_key_vault_slots-1.
[in]	challenge	32-byte challenge from the NS caller.
[out]	out	32-byte digest destination.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Digest computed.
k_ra8_err_invalid_arg	slot out of range.
k_ra8_err_null_ptr	challenge or out was NULL.

Precondition: Called from secure world (or via NSC veneer).; challenge and out point to k_ra8_key_vault_*_bytes.

Postcondition: out[0..31] holds the digest.

Note: Thread safety: not thread-safe; the SHA-256 sponge is single-instance.

Since: 0.1.0

Definition at line 574 of file key_vault.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_nsc_key_vault_challenge().

◆ ra8_key_vault_store()

ra8_err_t ra8_key_vault_store	(	uint16_t	slot,
		const uint8_t *	key )

nodiscard

Programme a 256-bit symmetric key into a vault slot.

Parameters

[in]	slot	Slot index 0..k_ra8_key_vault_slots-1.
[in]	key	32-byte symmetric key.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Key stored.
k_ra8_err_invalid_arg	slot out of range.
k_ra8_err_null_ptr	key was NULL.

Precondition: Called from secure world only.; key points to k_ra8_key_vault_key_bytes of secure RAM.

Postcondition: The slot contains the key.

Note: Thread safety: secure-world only.

Since: 0.1.0

Definition at line 567 of file key_vault.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by priv_ra8_key_import_seal().

Variable Documentation

◆ s_tag

const char* s_tag = "KEYV"

static

Definition at line 37 of file key_vault.c.

Functions

Variables

Detailed Description

Function Documentation

◆ ra8_key_vault_init()

◆ ra8_key_vault_load_mac_key()

◆ ra8_key_vault_set_mac_key()

◆ ra8_key_vault_sha256_xor_challenge()

◆ ra8_key_vault_store()

Variable Documentation

◆ s_tag