Secure-only symmetric key store. More...

#include <stdint.h>
#include "ra8_err.h"

Include dependency graph for key_vault.h:

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

Enumerations
enum	ra8_key_vault_limits_t : uint16_t { k_ra8_key_vault_slots = 8U , k_ra8_key_vault_key_bytes = 32U , k_ra8_key_vault_chal_bytes = 32U , k_ra8_key_vault_digest_bytes = 32U , k_ra8_key_vault_mac_key_bytes = 32U }
	Sizing constants for the vault. More...

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.

Detailed Description

Secure-only symmetric key store.

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

deliverable. Stores up to k_ra8_key_vault_slots 256-bit symmetric keys in a Secure-side static array that is unreachable from the Non-Secure world after the SAU partition is enabled.

ships the in-memory vault. The hardened storage path (MRAM-backed Secure region or SCE7 hardware key wrap) is a future deliverable that depends on the SCE driver gaining key-injection support.

The vault is intentionally minimal:

key_vault_init zeroes every slot.
key_vault_store(slot, key) copies a 256-bit key into a slot. Only callable from the secure world (no NSC veneer).
key_vault_sha256_xor_challenge(slot, challenge, out) computes SHA-256(key XOR challenge) and returns the 32-byte digest. This is the only operation the NS world can reach via the NSC veneer ra8_nsc_key_vault_challenge; the raw key never leaves the secure world.

TrustZone Safety:

Validates: slot index is in range; output pointer length matches expected digest size.
Trusts: the SAU partition keeps the static key array inaccessible from NS. The veneer is the only NS->S path.
Denies: raw key reads from any code path. Only the SHA-256-of-XOR digest crosses the boundary.

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

Definition in file key_vault.h.

Enumeration Type Documentation

◆ ra8_key_vault_limits_t

enum ra8_key_vault_limits_t : uint16_t

Sizing constants for the vault.

Enumerator
k_ra8_key_vault_slots	Number of stored keys.
k_ra8_key_vault_key_bytes	256-bit symmetric key.
k_ra8_key_vault_chal_bytes	Challenge length.
k_ra8_key_vault_digest_bytes	SHA-256 output size.
k_ra8_key_vault_mac_key_bytes	Max key-authentication key.

Definition at line 56 of file key_vault.h.

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().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_key_vault_limits_t

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()