ra8_nsc_key_vault.c File Reference

NSC veneer: secure key vault challenge-response. More...

#include "key_vault.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_nsc.h"
#include "ra8_nsc_veneer.h"

Include dependency graph for ra8_nsc_key_vault.c:

Go to the source code of this file.

Functions
ra8_err_t	ra8_nsc_key_vault_challenge (uint16_t slot, const uint8_t *ns_chal, uint8_t *ns_digest)
	NSC veneer: SHA-256(slot_key XOR challenge) for a stored slot.

Variables
static const char *	s_tag = "NSCKV"

Detailed Description

NSC veneer: secure key vault challenge-response.

Tag

[Ring 4 / NSC] {World: NSC}

deliverable. Wraps ra8_key_vault_sha256_xor_challenge for Non-Secure callers. The raw key never leaves the secure world; only the 32-byte SHA-256 digest crosses the boundary.

Copyright

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

Definition in file ra8_nsc_key_vault.c.

Function Documentation

ra8_nsc_key_vault_challenge()

ra8_err_t ra8_nsc_key_vault_challenge ( uint16_t slot, const uint8_t * ns_chal, uint8_t * ns_digest )

nodiscard

NSC veneer: SHA-256(slot_key XOR challenge) for a stored slot.

NSC veneer: SHA-256(key XOR challenge) for a stored slot.

Validates that the NS challenge buffer (read) and the NS digest buffer (read/write) lie inside the Non-Secure region, then forwards to ra8_key_vault_sha256_xor_challenge. The raw key never leaves the secure world; only the 32-byte SHA-256 digest crosses the boundary back to NS.

The 32-byte slot bound is published by k_ra8_key_vault_chal_bytes and k_ra8_key_vault_digest_bytes; the veneer enforces it on both buffers before calling into the secure key vault.

Parameters

[in]	slot	Vault slot index.
[in]	ns_chal	NS challenge buffer (k_ra8_key_vault_chal_bytes).
[out]	ns_digest	NS destination for the SHA-256 digest (k_ra8_key_vault_digest_bytes).

Returns

ra8_err_t outcome.

Return values

k_ra8_ok	Digest copied to ns_digest.
k_ra8_err_null_ptr	A pointer argument was NULL.
k_ra8_err_invalid_arg	Buffer outside NS region or bad slot.

Precondition

TrustZone substrate up.

Both buffers lie entirely within the NS data region.

Postcondition

On success ns_digest holds the SHA-256(key XOR challenge).

On failure ns_digest content is undefined and no key bytes are exposed.

TrustZone:

NS->S boundary via cmse_nonsecure_entry. Both NS pointers are cmse_check_address_range-validated. The raw slot key is read only inside the secure world; it is XORed with the challenge and hashed before any byte crosses back to NS, so a malicious NS caller cannot recover the key from the digest without breaking SHA-256.

Note

Thread-safe: serialised by the secure key-vault lock.

Since

0.1.0

Definition at line 65 of file ra8_nsc_key_vault.c.

References k_ra8_key_vault_chal_bytes, k_ra8_key_vault_digest_bytes, RA8_CHECK_NULL_PTR, ra8_key_vault_sha256_xor_challenge(), RA8_NSC_CHECK_NS_RANGE_R, RA8_NSC_CHECK_NS_RANGE_RW, RA8_NSC_VENEER, and s_tag.

Variable Documentation

s_tag

const char* s_tag = "NSCKV"

static

Definition at line 23 of file ra8_nsc_key_vault.c.