Secure-side TRNG read API (RSIP-backed entropy). More...

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

Include dependency graph for secure_trng_internal.h:

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

Enumerations
enum	ra8_secure_trng_limits_t : uint16_t { k_ra8_secure_trng_max_bytes = 256U }
	Sizing constants for priv_ra8_secure_trng_read. More...

Functions
ra8_err_t	priv_ra8_secure_trng_reset (void)
	Reset the TRNG seed (test-only; production reseeds from RSIP).
ra8_err_t	priv_ra8_secure_trng_read (uint8_t *out, uint32_t len)
	Fill [out, out+len) with TRNG-quality entropy.

Detailed Description

Secure-side TRNG read API (RSIP-backed entropy).

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

The RSIP TRNG output registers live in the secure region and cannot be reached directly from Non-Secure code. The veneer ra8_nsc_trng_read lets NS request entropy without ever seeing an RSIP register; this header is the secure-side bridge.

The host implementation is a deterministic-but-decorrelated xorshift64* PRNG. On the real chip the call drops through to ra8_rsip_trng_read. The split keeps the veneer code unaware of which entropy source is wired in.

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

Definition in file secure_trng_internal.h.

Enumeration Type Documentation

◆ ra8_secure_trng_limits_t

enum ra8_secure_trng_limits_t : uint16_t

Sizing constants for priv_ra8_secure_trng_read.

Enumerator
k_ra8_secure_trng_max_bytes	Max bytes per call.

Definition at line 38 of file secure_trng_internal.h.

Function Documentation

◆ priv_ra8_secure_trng_read()

ra8_err_t priv_ra8_secure_trng_read	(	uint8_t *	out,
		uint32_t	len )

nodiscard

Fill [out, out+len) with TRNG-quality entropy.

Pulls 8 bytes at a time from the entropy core and copies the needed prefix into out. The caller must ensure out is already a secure buffer – the NSC veneer copies bytes from here back to the NS destination, so the secure-side function itself never touches NS memory.

Parameters

[out]	out	Destination buffer (secure scratch).
[in]	len	Bytes to fill, 1..k_ra8_secure_trng_max_bytes.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Bytes written.
k_ra8_err_null_ptr	out was NULL.
k_ra8_err_invalid_arg	len zero or above the cap.

Precondition: out non-NULL and points to len bytes of secure RAM.

Postcondition: out[0..len-1] contains entropy bytes.

Note: Thread safety: not thread-safe; the seed is a single static.

Since: 0.1.0

Definition at line 179 of file secure_trng.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ priv_ra8_secure_trng_reset()

ra8_err_t priv_ra8_secure_trng_reset ( void )

nodiscard

Reset the TRNG seed (test-only; production reseeds from RSIP).

Returns: ra8_err_t error code (currently always k_ra8_ok).

Precondition: Called from secure boot before any veneer can fire.

Postcondition: Subsequent reads produce a deterministic stream rooted at the new seed.

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

Since: 0.1.0

Definition at line 174 of file secure_trng.c.

References k_ra8_err_not_supported.