ra8_rsip_core.h File Reference

Renesas Secure IP (RSIP-E50D) HAL – core lifecycle / TRNG / hash API. More...

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

Include dependency graph for ra8_rsip_core.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_rsip_config_t
	Initial configuration for ra8_rsip_init. More...
struct	ra8_rsip_sha256_ctx_t
	Streaming state for incremental SHA-256. More...
struct	ra8_rsip_hmac_sha256_ctx_t
	Streaming state for incremental HMAC-SHA-256. More...

Typedefs
typedef void(*	ra8_rsip_event_fn_t) (void *ctx, uint32_t isr)
	RSIP interrupt callback.

Enumerations
enum	ra8_rsip_sha_buf_t : uint16_t {   k_ra8_rsip_sha256_state_words = 8U ,   k_ra8_rsip_sha256_block = 64U ,   k_ra8_rsip_hmac_inner_pad = 0x36U ,   k_ra8_rsip_hmac_outer_pad = 0x5CU }
	Fixed geometry for the incremental SHA / HMAC state. More...

Functions
ra8_err_t	ra8_rsip_init (const ra8_rsip_config_t *cfg)
	Power on the RSIP engine and (optionally) run BIST.
ra8_err_t	ra8_rsip_deinit (void)
	Power off the RSIP engine.
ra8_err_t	ra8_rsip_get_status (uint32_t *out)
	Snapshot the STATUS mailbox word.
ra8_err_t	ra8_rsip_clear_status (uint32_t mask)
	Acknowledge ISR bits via write-1-to-clear.
ra8_err_t	ra8_rsip_attach_handler (ra8_rsip_event_fn_t fn, void *ctx)
	Attach a single shared interrupt callback.
void	ra8_rsip_dispatch (void)
	Run the attached callback with the current ISR snapshot.
ra8_err_t	ra8_rsip_trng_read (uint8_t *buf, uint32_t len)
	Drain len bytes from the RSIP true RNG – fail-closed, no backend.
ra8_err_t	ra8_rsip_sha256 (const uint8_t *msg, uint32_t msg_len, uint8_t *digest)
	Compute SHA-256 of an in-memory buffer.
ra8_err_t	ra8_rsip_sha256_init (ra8_rsip_sha256_ctx_t *ctx)
	Initialise a streaming SHA-256 context.
ra8_err_t	ra8_rsip_sha256_update (ra8_rsip_sha256_ctx_t *ctx, const uint8_t *data, uint32_t len)
	Absorb additional bytes into a streaming SHA-256 context.
ra8_err_t	ra8_rsip_sha256_final (ra8_rsip_sha256_ctx_t *ctx, uint8_t *digest_out)
	Emit the digest of a streaming SHA-256 context.
ra8_err_t	ra8_rsip_hmac_sha256_init (ra8_rsip_hmac_sha256_ctx_t *ctx, const uint8_t *key, uint32_t key_len)
	Initialise a streaming HMAC-SHA-256 context.
ra8_err_t	ra8_rsip_hmac_sha256_update (ra8_rsip_hmac_sha256_ctx_t *ctx, const uint8_t *data, uint32_t len)
	Absorb additional bytes into a streaming HMAC-SHA-256 context.
ra8_err_t	ra8_rsip_hmac_sha256_final (ra8_rsip_hmac_sha256_ctx_t *ctx, uint8_t *mac_out)
	Emit the MAC of a streaming HMAC-SHA-256 context.
ra8_err_t	ra8_rsip_enter_stop (void)
	Park the engine for software-standby entry.
ra8_err_t	ra8_rsip_exit_stop (void)
	Re-enable the engine after software-standby exit.

Detailed Description

Renesas Secure IP (RSIP-E50D) HAL – core lifecycle / TRNG / hash API.

Tag

[Ring 3 / HAL] {World: S}

Core surface of the RA8D2 RSIP-E50D HAL split out of the ra8_rsip.h umbrella. This sub-header owns the engine lifecycle (init / deinit / power transition), the status / IRQ mailbox plumbing, the 128-bit TRNG drain, the one-shot SHA-256 primitive, and the incremental SHA-256 / HMAC-SHA-256 streaming contexts.

The mailbox-driven peripheral is documented in HUM Ch 52 "Renesas Secure IP (RSIP-E50D)" p 3302-3307; cross-references to the broader security feature set live in HUM Ch 51 "Security Features" p 3263-3301.

Copyright

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

Since

0.1.0

Definition in file ra8_rsip_core.h.

Typedef Documentation

ra8_rsip_event_fn_t

typedef void(* ra8_rsip_event_fn_t) (void *ctx, uint32_t isr)

RSIP interrupt callback.

Parameters

[in]	ctx	Caller-provided context pointer.
[in]	isr	Snapshot of the k_ra8_rsip_off_isr word at the moment the interrupt fired (see k_ra8_rsip_mask_isr_*).

Definition at line 64 of file ra8_rsip_core.h.

Enumeration Type Documentation

ra8_rsip_sha_buf_t

enum ra8_rsip_sha_buf_t : uint16_t

Fixed geometry for the incremental SHA / HMAC state.

The software backend compresses complete SHA-256 blocks as they arrive and retains only one partial block. Input length is therefore independent of context size; the 64-bit byte count enforces the FIPS 180-4 bit-length encoding bound at update time.

Enumerator
k_ra8_rsip_sha256_state_words	SHA-256 chaining-state words.
k_ra8_rsip_sha256_block	SHA-256 message-block byte length.
k_ra8_rsip_hmac_inner_pad	RFC 2104 inner-pad fill byte.
k_ra8_rsip_hmac_outer_pad	RFC 2104 outer-pad fill byte.

Definition at line 367 of file ra8_rsip_core.h.

Function Documentation

ra8_rsip_attach_handler()

ra8_err_t ra8_rsip_attach_handler ( ra8_rsip_event_fn_t fn, void * ctx )

nodiscard

Attach a single shared interrupt callback.

The RSIP routes a small number of edge-triggered events (DONE / RND / HASH / TAMPER) into one peripheral IRQ line. The driver fans them out by passing the live ISR snapshot to a single callback.

Parameters

[in]	fn	Callback fired by ra8_rsip_dispatch; may be NULL to detach.
[in]	ctx	Opaque context forwarded to fn.

Returns

ra8_err_t error code.

Return values

k_ra8_ok

Callback installed.

Precondition

IRQs masked while swapping callbacks.

Caller owns the lifetime of ctx.

Postcondition

fn / ctx are visible to ra8_rsip_dispatch.

Previous callback (if any) is no longer invoked.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_dispatch

Since

0.1.0

Definition at line 307 of file ra8_rsip.c.

References k_ra8_ok, s_rsip_ctx, and s_rsip_fn.

ra8_rsip_clear_status()

ra8_err_t ra8_rsip_clear_status ( uint32_t mask )

nodiscard

Acknowledge ISR bits via write-1-to-clear.

Writes mask to the ISR register; only the bits listed in k_ra8_rsip_mask_isr_* are valid. The write masks unrelated bits before issuing.

Parameters

[in]

mask

OR of k_ra8_rsip_mask_isr_* values.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Bits cleared.
k_ra8_err_invalid_arg	mask had bits outside the ISR field.

Precondition

ra8_rsip_init has been called.

mask has at least one valid bit set.

Postcondition

Requested ISR bits read as 0.

No CTRL bits are touched.

Note

Thread safety: not thread-safe with concurrent dispatch.

See also

ra8_rsip_attach_handler

Since

0.1.0

Definition at line 293 of file ra8_rsip.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_rsip_mask_isr_all, k_ra8_rsip_off_isr, and ra8_rsip_reg32().

ra8_rsip_deinit()

ra8_err_t ra8_rsip_deinit ( void )

nodiscard

Power off the RSIP engine.

Clears CTRL.ENABLE, scrubs any pending ISR bits, releases the shared callback slot, and asks ra8_mstp to gate MSTPC31.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Engine gated.
k_ra8_err_invalid_state	ra8_mstp had no matching enable.
k_ra8_err_hw_timeout	MSTP read-back loop expired.

Precondition

Engine is idle (STATUS.BUSY = 0); the HAL does not enforce this – callers must drain in-flight commands.

ra8_rsip_init has been called at least once since reset.

Postcondition

Engine is gated and the shared callback / context are cleared.

MSTPC31 ref count is decremented.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_init

Since

0.1.0

Definition at line 267 of file ra8_rsip.c.

References k_ra8_mstp_rsip, k_ra8_rsip_mask_isr_all, k_ra8_rsip_off_ctrl, k_ra8_rsip_off_isr, ra8_mstp_disable(), ra8_rsip_reg32(), s_rsip_ctx, and s_rsip_fn.

ra8_rsip_dispatch()

void ra8_rsip_dispatch

(

void

)

Run the attached callback with the current ISR snapshot.

Called from the secure-world ICU dispatch when the RSIP IRQ fires. Reads the live ISR word, fires the registered callback (if any), and acks the bits the callback observed via ra8_rsip_clear_status.

Precondition

Caller is the IRQ glue layer; runs in IRQ context.

ra8_rsip_init has been called at least once since reset.

Postcondition

Pending ISR bits that were visible to the callback are cleared.

No CTRL bits are modified.

Note

Thread safety: must run with IRQ priority above the RSIP line (default for ICU dispatch). See HUM Ch 39 "Renesas Secure IP (RSIP-E51A)" pp 1839-1859.

See also

ra8_rsip_attach_handler

Since

0.1.0

Definition at line 315 of file ra8_rsip.c.

References k_ra8_rsip_off_isr, ra8_rsip_reg32(), s_rsip_ctx, and s_rsip_fn.

ra8_rsip_enter_stop()

ra8_err_t ra8_rsip_enter_stop ( void )

nodiscard

Park the engine for software-standby entry.

HUM Ch 52.3.1 p 3307 ("Software Standby Mode") requires the engine to be idle before software-standby; this helper clears CTRL.ENABLE then gates MSTPC31.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Engine parked.
k_ra8_err_invalid_state	ra8_mstp had no matching enable.
k_ra8_err_hw_timeout	MSTP read-back loop expired.

Precondition

Engine is idle (caller's responsibility; HUM 52.3.1).

ra8_rsip_init has been called.

Postcondition

CTRL.ENABLE = 0.

MSTPC31 ref count is decremented.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_exit_stop

Since

0.1.0

Definition at line 947 of file ra8_rsip.c.

References k_ra8_mstp_rsip, k_ra8_rsip_off_ctrl, ra8_mstp_disable(), and ra8_rsip_reg32().

ra8_rsip_exit_stop()

ra8_err_t ra8_rsip_exit_stop ( void )

nodiscard

Re-enable the engine after software-standby exit.

Calls ra8_mstp_enable to clock the block, sets CTRL.ENABLE, and re-runs BIST so a side-channel injection during standby does not silently leak.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Engine ready, BIST passed.
k_ra8_err_hw_init_failed	BIST did not pass.
k_ra8_err_hw_timeout	MSTP read-back loop expired.

Precondition

ra8_rsip_enter_stop was the previous transition.

IRQs masked.

Postcondition

CTRL.ENABLE = 1 and STATUS.BIST_OK = 1.

MSTPC31 ref count is incremented.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_enter_stop

Since

0.1.0

Definition at line 955 of file ra8_rsip.c.

References internal_run_bist(), k_ra8_mstp_rsip, k_ra8_ok, k_ra8_rsip_mask_ctrl_enable, k_ra8_rsip_off_ctrl, ra8_mstp_disable(), ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_rsip_reg32(), and s_tag.

ra8_rsip_get_status()

ra8_err_t ra8_rsip_get_status ( uint32_t * out )

nodiscard

Snapshot the STATUS mailbox word.

Parameters

[out]

out

Receives the raw STATUS word; never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out was nullptr.

Precondition

out is non-NULL.

ra8_rsip_init has been called.

Postcondition

*out reflects the live STATUS word.

No engine state is modified.

Note

Thread safety: read-only, safe to call concurrently with data-path operations.

See also

ra8_rsip_clear_status

Since

0.1.0

Definition at line 284 of file ra8_rsip.c.

References k_ra8_ok, k_ra8_rsip_off_status, RA8_CHECK_NULL_PTR, ra8_rsip_reg32(), and s_tag.

ra8_rsip_hmac_sha256_final()

ra8_err_t ra8_rsip_hmac_sha256_final ( ra8_rsip_hmac_sha256_ctx_t * ctx, uint8_t * mac_out )

nodiscard

Emit the MAC of a streaming HMAC-SHA-256 context.

Parameters

[in,out]	ctx	Context populated by prior update() calls.
[out]	mac_out	32-byte MAC output buffer; never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	MAC written.
k_ra8_err_null_ptr	ctx or mac_out was nullptr.
k_ra8_err_invalid_state	ctx was not initialized.
k_ra8_err_hw_timeout	Either SHA pass timed out.

Precondition

ctx->initialized == 1.

mac_out is non-NULL.

Postcondition

On success mac_out[0..31] is the HMAC-SHA-256.

On any return ctx->initialized == 0.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_hmac_sha256_init

Since

0.1.0

Definition at line 927 of file ra8_rsip.c.

References ra8_rsip_hmac_sha256_ctx_t::initialized, ra8_rsip_hmac_sha256_ctx_t::inner, internal_hmac_outer(), k_ra8_err_invalid_state, k_ra8_ok, k_ra8_rsip_sha256_block, k_ra8_rsip_sha256_digest_bytes, ra8_rsip_hmac_sha256_ctx_t::key_block, RA8_CHECK_NULL_PTR, ra8_rsip_sha256_final(), and s_tag.

ra8_rsip_hmac_sha256_init()

ra8_err_t ra8_rsip_hmac_sha256_init ( ra8_rsip_hmac_sha256_ctx_t * ctx, const uint8_t * key, uint32_t key_len )

nodiscard

Initialise a streaming HMAC-SHA-256 context.

Parameters

[out]	ctx	Streaming HMAC state; never NULL.
[in]	key	HMAC key bytes; never NULL when key_len > 0.
[in]	key_len	Length of key in bytes (may be 0).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Context ready.
k_ra8_err_null_ptr	ctx was nullptr or key was NULL with non-zero key_len.
k_ra8_err_hw_timeout	Internal SHA collapse of an oversized key timed out.

Precondition

ra8_rsip_init has been called.

ctx is non-NULL.

Postcondition

ctx->initialized == 1.

No engine state is modified beyond the optional key-collapse.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_hmac_sha256_update

Since

0.1.0

Definition at line 846 of file ra8_rsip.c.

References ra8_rsip_hmac_sha256_ctx_t::initialized, ra8_rsip_sha256_ctx_t::initialized, ra8_rsip_hmac_sha256_ctx_t::inner, internal_hmac_prep_key(), k_ra8_err_null_ptr, k_ra8_ok, k_ra8_rsip_hmac_inner_pad, k_ra8_rsip_sha256_block, ra8_rsip_hmac_sha256_ctx_t::key_block, RA8_CHECK_NULL_PTR, ra8_rsip_sha256_init(), ra8_rsip_sha256_update(), and s_tag.

ra8_rsip_hmac_sha256_update()

ra8_err_t ra8_rsip_hmac_sha256_update ( ra8_rsip_hmac_sha256_ctx_t * ctx, const uint8_t * data, uint32_t len )

nodiscard

Absorb additional bytes into a streaming HMAC-SHA-256 context.

Parameters

[in,out]	ctx	Context primed by ra8_rsip_hmac_sha256_init.
[in]	data	Bytes to absorb; may be NULL only if len is 0.
[in]	len	Number of bytes in data.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Bytes accumulated.
k_ra8_err_null_ptr	ctx was nullptr or data NULL with non-zero len.
k_ra8_err_invalid_state	ctx was not initialized.
k_ra8_err_invalid_size	Cumulative input exceeds SHA-256's encoded length range.

Precondition

ctx->initialized == 1.

Either len == 0 or data is non-NULL.

Postcondition

On success ctx->inner.total_bytes grew by len.

On failure ctx is unchanged.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_hmac_sha256_init

Since

0.1.0

Definition at line 874 of file ra8_rsip.c.

References ra8_rsip_hmac_sha256_ctx_t::initialized, ra8_rsip_hmac_sha256_ctx_t::inner, k_ra8_err_invalid_state, RA8_CHECK_NULL_PTR, ra8_rsip_sha256_update(), and s_tag.

ra8_rsip_init()

ra8_err_t ra8_rsip_init ( const ra8_rsip_config_t * cfg )

nodiscard

Power on the RSIP engine and (optionally) run BIST.

Sequence:

1. Release MSTPC31 via ra8_mstp_enable(k_ra8_mstp_rsip). HUM Ch 11.2.8 "MSTPCRC: Module Stop Control Register C" p 446 + HUM Ch 52.3.2 "Module-Stop Function Setting" p 3307.
2. Soft-reset the engine via CTRL.RESET pulse.
3. Set CTRL.ENABLE so the access-management circuit clocks the internal subsystem.
4. If cfg->run_bist is true, set CTRL.BIST and spin on STATUS.BIST_OK. Returns k_ra8_err_hw_init_failed if the spin exhausts its budget (BIST failure is a fatal condition – the engine MUST NOT be used).
5. Clear pending ISR bits.

Parameters

[in]

cfg

Non-NULL configuration descriptor.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Engine ready, BIST passed.
k_ra8_err_null_ptr	cfg was nullptr.
k_ra8_err_hw_init_failed	BIST did not pass within budget.

Precondition

IRQs masked or single-threaded init context.

ra8_mstp_init has been called.

Postcondition

On success, the engine is clocked, BIST_OK is set, and no spurious ISR bits are pending.

On success, MSTPC31 ref count is at least 1.

Warning

See file-level

– TRNG output is invalid until BIST passes. Do not call ra8_rsip_trng_read if this function returned anything other than k_ra8_ok.

Note

Thread safety: not thread-safe.

const ra8_rsip_config_t cfg = {.run_bist = true };
if (ra8_rsip_init(&cfg) != k_ra8_ok) { panic; }

See also

ra8_rsip_deinit

ra8_rsip_trng_read

Since

0.1.0

Definition at line 234 of file ra8_rsip.c.

References internal_run_bist(), k_ra8_mstp_rsip, k_ra8_ok, k_ra8_rsip_mask_ctrl_enable, k_ra8_rsip_mask_ctrl_reset, k_ra8_rsip_mask_isr_all, k_ra8_rsip_off_ctrl, k_ra8_rsip_off_isr, RA8_CHECK_NULL_PTR, ra8_log_info, ra8_mstp_disable(), ra8_mstp_enable(), RA8_RETURN_ON_ERROR, ra8_rsip_reg32(), ra8_rsip_config_t::run_bist, and s_tag.

Referenced by demo_setup_or_halt(), internal_demo_setup_or_halt(), and internal_run().

ra8_rsip_sha256()

ra8_err_t ra8_rsip_sha256 ( const uint8_t * msg, uint32_t msg_len, uint8_t * digest )

nodiscard

Compute SHA-256 of an in-memory buffer.

Streams msg through the HASH engine 32 bits at a time, then reads back the 8-word (32-byte) digest from HASH_DIGEST. Algorithm select is hard-wired to k_ra8_rsip_hash_sha256. Suitable for short messages; incremental update / final API is deferred to a future revision.

Parameters

[in]	msg	Pointer to the input buffer; never NULL.
[in]	msg_len	Length of msg in bytes; may be 0.
[out]	digest	32-byte output buffer; never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Digest written.
k_ra8_err_null_ptr	msg or digest was nullptr.
k_ra8_err_hw_timeout	HASH engine did not signal done.

Precondition

ra8_rsip_init has been called.

digest is at least k_ra8_rsip_sha256_digest_bytes wide.

Postcondition

On success, digest[0..31] holds the SHA-256 of msg.

HASH_STATUS.DONE has been observed and acked.

Note

Thread safety: not thread-safe.

uint8_t out[k_ra8_rsip_sha256_digest_bytes];
(void)ra8_rsip_sha256(buf, len, out);

Since

0.1.0

Definition at line 397 of file ra8_rsip.c.

References internal_sw_sha256(), k_ra8_ok, k_ra8_rsip_hash_sha256, k_ra8_rsip_mask_status_ready, k_ra8_rsip_off_hash_ctrl, k_ra8_rsip_off_hash_status, priv_hash_wait_done(), priv_wait_bit(), RA8_CHECK_NULL_PTR, RA8_RETURN_ON_ERROR, ra8_rsip_reg32(), and s_tag.

Referenced by app_stage_images(), internal_demo_verify_cert_pin(), internal_kat_one(), and internal_sha256_dispatch().

ra8_rsip_sha256_final()

ra8_err_t ra8_rsip_sha256_final ( ra8_rsip_sha256_ctx_t * ctx, uint8_t * digest_out )

nodiscard

Emit the digest of a streaming SHA-256 context.

Parameters

[in,out]	ctx	Context populated by prior update() calls.
[out]	digest_out	32-byte digest output buffer; never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Digest written.
k_ra8_err_null_ptr	ctx or digest_out was nullptr.
k_ra8_err_invalid_state	ctx was not initialized.

Precondition

ctx->initialized == 1.

digest_out is non-NULL.

Postcondition

On success digest_out[0..31] holds the SHA-256.

On success ctx is cleared and no message bytes remain resident.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_sha256_init

Since

0.1.0

Definition at line 794 of file ra8_rsip.c.

References ra8_rsip_sha256_ctx_t::block, ra8_rsip_sha256_ctx_t::initialized, internal_sw_sha256_emit(), internal_sw_sha256_finalize(), k_ra8_err_invalid_state, k_ra8_ok, k_ra8_rsip_sha256_block, k_ra8_rsip_sha256_state_words, RA8_CHECK_NULL_PTR, s_tag, ra8_rsip_sha256_ctx_t::state, ra8_rsip_sha256_ctx_t::total_bytes, and ra8_rsip_sha256_ctx_t::used.

Referenced by app_sha_final(), internal_sha_final(), internal_sw_sha256(), and ra8_rsip_hmac_sha256_final().

ra8_rsip_sha256_init()

ra8_err_t ra8_rsip_sha256_init ( ra8_rsip_sha256_ctx_t * ctx )

nodiscard

Initialise a streaming SHA-256 context.

Parameters

[out]

ctx

Streaming state; never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Context ready for update().
k_ra8_err_null_ptr	ctx was nullptr.

Precondition

ra8_rsip_init has been called at least once since reset.

ctx is non-NULL.

Postcondition

ctx->used == 0, ctx->total_bytes == 0 and ctx->initialized == 1.

No engine state is modified.

Note

Thread safety: not thread-safe.

ra8_rsip_sha256_ctx_t ctx;
(void)ra8_rsip_sha256_init(&ctx);
(void)ra8_rsip_sha256_update(&ctx, hello, hello_len);
uint8_t transcript[k_ra8_rsip_sha256_digest_bytes];
(void)ra8_rsip_sha256_final(&ctx, transcript);

See also

ra8_rsip_sha256_update

ra8_rsip_sha256_final

Since

0.1.0

Definition at line 747 of file ra8_rsip.c.

References ra8_rsip_sha256_ctx_t::initialized, k_ra8_ok, k_ra8_rsip_sha256_state_words, RA8_CHECK_NULL_PTR, s_sw_sha256_h0, s_tag, ra8_rsip_sha256_ctx_t::state, ra8_rsip_sha256_ctx_t::total_bytes, and ra8_rsip_sha256_ctx_t::used.

Referenced by app_sha_init(), internal_sha_init(), internal_sw_sha256(), and ra8_rsip_hmac_sha256_init().

ra8_rsip_sha256_update()

ra8_err_t ra8_rsip_sha256_update ( ra8_rsip_sha256_ctx_t * ctx, const uint8_t * data, uint32_t len )

nodiscard

Absorb additional bytes into a streaming SHA-256 context.

Parameters

[in,out]	ctx	Context primed by ra8_rsip_sha256_init.
[in]	data	Bytes to absorb; may be NULL only if len is 0.
[in]	len	Number of bytes in data.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Bytes compressed or retained.
k_ra8_err_null_ptr	ctx was nullptr or data was NULL with non-zero len.
k_ra8_err_invalid_state	ctx was not initialized.
k_ra8_err_invalid_size	Cumulative input cannot be represented by SHA-256's 64-bit bit-length field.

Precondition

ctx->initialized == 1.

Either len == 0 or data is non-NULL.

Postcondition

On success ctx->total_bytes grew by len and ctx->used identifies only the retained partial block.

On failure ctx is unchanged.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_sha256_init

Since

0.1.0

Definition at line 759 of file ra8_rsip.c.

References ra8_rsip_sha256_ctx_t::block, ra8_rsip_sha256_ctx_t::initialized, internal_sw_sha256_compress(), k_ra8_err_invalid_size, k_ra8_err_invalid_state, k_ra8_err_null_ptr, k_ra8_ok, k_ra8_rsip_byte_bits, k_ra8_rsip_sha256_block, RA8_CHECK_NULL_PTR, s_tag, ra8_rsip_sha256_ctx_t::state, ra8_rsip_sha256_ctx_t::total_bytes, and ra8_rsip_sha256_ctx_t::used.

Referenced by app_sha_update(), internal_sha_update(), internal_sw_sha256(), ra8_rsip_hmac_sha256_init(), and ra8_rsip_hmac_sha256_update().

ra8_rsip_trng_read()

ra8_err_t ra8_rsip_trng_read ( uint8_t * buf, uint32_t len )

nodiscard

Drain len bytes from the RSIP true RNG – fail-closed, no backend.

The RSIP-E50D TRNG has no documented register interface (HUM Ch 52 is a 6-page feature overview with no register map), so the hand-written RND_* access is invented and non-functional on silicon: RND_STATUS.READY never asserts. This routine therefore fails closed with k_ra8_err_not_supported rather than spin to a timeout or hand back a deterministic / all-zero value – predictable "entropy" is far more dangerous than an honest error. A working TRNG needs an FSP-derived RSIP primitive sequence; the register path is retained behind RA8_RSIP_TRNG_HARDWARE (never defined) for a future port. A software PRNG is NOT a substitute here.

Parameters

[out]	buf	Destination buffer (>= len bytes); never NULL.
[in]	len	Bytes to fetch; must be a non-zero multiple of 4.

Returns

ra8_err_t error code.

Return values

k_ra8_err_not_supported	No working RSIP TRNG register interface exists (the shipped, fail-closed path).
k_ra8_err_null_ptr	buf was nullptr.
k_ra8_err_invalid_arg	len is zero or not a multiple of k_ra8_rsip_trng_word_bytes.

Precondition

buf is non-NULL.

len is a non-zero multiple of k_ra8_rsip_trng_word_bytes.

Postcondition

buf is left untouched; the caller must treat it as uninitialized.

No RSIP register is mutated in the fail-closed build.

Warning

Returns no entropy on this silicon. Do NOT use for key or nonce generation until a real TRNG backend exists.

Note

Thread safety: not thread-safe.

uint8_t  seed[32];
ra8_err_t e = ra8_rsip_trng_read(seed, sizeof(seed)); // e == k_ra8_err_not_supported

Since

0.1.0

Definition at line 338 of file ra8_rsip.c.

References k_ra8_err_invalid_arg, k_ra8_err_not_supported, k_ra8_ok, k_ra8_rsip_byte_bits, k_ra8_rsip_byte_mask, k_ra8_rsip_byte_shift_2, k_ra8_rsip_byte_shift_3, k_ra8_rsip_mask_ctrl_enable, k_ra8_rsip_mask_status_ready, k_ra8_rsip_off_rnd_ctrl, k_ra8_rsip_off_rnd_data, k_ra8_rsip_off_rnd_status, k_ra8_rsip_trng_word_bytes, k_ra8_rsip_word_shift, priv_wait_bit(), RA8_CHECK_NULL_PTR, ra8_rsip_reg32(), and s_tag.

Referenced by internal_demo_entropy_source(), and mbedtls_psa_external_get_random().