ra8_rsip_mgmt.h File Reference

Renesas Secure IP (RSIP-E50D) HAL – vault / KDF / lifecycle / tamper. More...

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

Include dependency graph for ra8_rsip_mgmt.h:

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

Go to the source code of this file.

Functions
ra8_err_t	ra8_rsip_oem_bl_version_get (uint32_t *out)
	Read the latched OEM boot loader version counter.
ra8_err_t	ra8_rsip_oem_bl_version_increment (void)
	Increment the OEM boot loader version (anti-rollback step).
ra8_err_t	ra8_rsip_oem_bl_version_lock (void)
	Latch the OEM_BL_LOCK so further increments are rejected.
ra8_err_t	ra8_rsip_kv_read (uint8_t slot, uint8_t *out)
	Read a wrapped-key blob from a vault slot.
ra8_err_t	ra8_rsip_kv_write (uint8_t slot, const uint8_t *in)
	Write a wrapped-key blob into a vault slot.
ra8_err_t	ra8_rsip_kv_erase (uint8_t slot)
	Zeroise a vault slot.
ra8_err_t	ra8_rsip_kv_count (uint32_t *out)
	Snapshot the populated-slot count.
ra8_err_t	ra8_rsip_key_wrap (const ra8_rsip_key_handle_t *kek, const uint8_t *iv, const ra8_rsip_key_handle_t *src, uint8_t *blob)
	Wrap a key handle into a transportable blob using a KEK.
ra8_err_t	ra8_rsip_key_unwrap (const ra8_rsip_key_handle_t *kek, const uint8_t *iv, const uint8_t *blob, ra8_rsip_key_handle_t *dest)
	Unwrap a transportable blob into a key handle.
ra8_err_t	ra8_rsip_kdf (ra8_rsip_kdf_op_t op, const ra8_rsip_key_handle_t *ikm, const uint8_t *label, uint32_t label_len, const uint8_t *salt, uint32_t salt_len, uint32_t out_len, ra8_rsip_key_handle_t *out)
	Derive a key from input keying material + label/salt/info.
ra8_err_t	ra8_rsip_life_get (ra8_rsip_life_state_t *out)
	Read the device-lifecycle state.
ra8_err_t	ra8_rsip_life_advance (ra8_rsip_life_state_t state)
	Advance the device lifecycle to a new state.
ra8_err_t	ra8_rsip_debug_level_get (ra8_rsip_debug_level_t *out)
	Read the current debug authorisation level.
ra8_err_t	ra8_rsip_debug_level_set (ra8_rsip_debug_level_t level)
	Set the debug authorisation level.
ra8_err_t	ra8_rsip_tamper_enable (uint32_t sources)
	Enable or disable a set of tamper sources.
ra8_err_t	ra8_rsip_tamper_status (uint32_t *out)
	Read latched tamper-source flags.
ra8_err_t	ra8_rsip_tamper_ack (uint32_t mask)
	Acknowledge tamper-source flags (write-1-to-clear).
ra8_err_t	ra8_rsip_dpa_arm (bool enable)
	Arm or disarm SPA / DPA countermeasures.
ra8_err_t	ra8_rsip_dotf_route (uint8_t which, uint8_t slot, bool on)
	Route a wrapped-key vault slot to one of the DOTF instances.

Detailed Description

Renesas Secure IP (RSIP-E50D) HAL – vault / KDF / lifecycle / tamper.

Tag

[Ring 3 / HAL] {World: S}

Device-management surface of the RA8D2 RSIP-E50D HAL split out of the ra8_rsip.h umbrella. This sub-header owns the OEM boot loader version anti-rollback counter, the wrapped-key vault slots, the KEK-backed key wrap / unwrap engine, the HKDF / HUK-UID key derivation function, the device lifecycle + debug-authorisation helpers, the tamper subsystem, and the DOTF key-delivery routing.

Wrap / unwrap and KDF consume the opaque ra8_rsip_key_handle_t type defined in ra8_rsip_keys.h, which this sub-header includes.

Warning

This entire surface FAILS CLOSED in a production build. The RSIP-E50D has no documented command / security-state register map: HUM Ch 52 "Renesas Secure IP (RSIP-E50D)" (p 3302-3307) is a six-page conceptual overview and HUM Ch 51 "Security Features" (p 3263-3301) is a prose feature index, neither a register map. The key-management and hash surface (ra8_rsip_asym.c, issues #214 / #215) and the device- security surface – lifecycle, debug authorisation, tamper, DPA arm (ra8_rsip_devsec.c, issue #216) – therefore return k_ra8_err_not_supported outside the insecure off-target build rather than fabricate a digest, key, or security-state answer. The k_ra8_ok / @post contracts below describe the guarded fake command path only; real key management runs on tf-psa-crypto (M85) and real device-security state lives in the DLM / option-setting memory / SAU, not an RSIP MMIO read.

Copyright

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

Since

0.1.0

Definition in file ra8_rsip_mgmt.h.

Function Documentation

ra8_rsip_debug_level_get()

ra8_err_t ra8_rsip_debug_level_get ( ra8_rsip_debug_level_t * out )

nodiscard

Read the current debug authorisation level.

Parameters

[out]

out

Receives the level (AL0/AL1/AL2).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out was NULL.

Precondition

out is non-NULL.

ra8_rsip_init has been called.

Postcondition

*out is one of AL0/AL1/AL2.

No engine state is modified.

Note

Thread safety: read-only.

Since

0.1.0

Definition at line 199 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_debug_level_set()

ra8_err_t ra8_rsip_debug_level_set ( ra8_rsip_debug_level_t level )

nodiscard

Set the debug authorisation level.

Parameters

[in]

level

Target level.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Level applied.
k_ra8_err_invalid_arg	level out of range.

Precondition

level is one of ra8_rsip_debug_level_t.

Lifecycle state allows the requested level.

Postcondition

Subsequent ra8_rsip_debug_level_get returns level.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 205 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported.

ra8_rsip_dotf_route()

ra8_err_t ra8_rsip_dotf_route ( uint8_t which, uint8_t slot, bool on )

nodiscard

Route a wrapped-key vault slot to one of the DOTF instances.

Parameters

[in]	which	DOTF instance (0 or 1).
[in]	slot	Vault slot to feed (must contain an AES key).
[in]	on	true to enable the route, false to disable.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Route applied.
k_ra8_err_invalid_arg	which not 0/1 or slot out of range.

Precondition

which < 2.

If on is true, slot < k_ra8_rsip_kv_slot_count.

Postcondition

DOTFn_CTRL reflects the requested route.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 747 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported.

ra8_rsip_dpa_arm()

ra8_err_t ra8_rsip_dpa_arm ( bool enable )

nodiscard

Arm or disarm SPA / DPA countermeasures.

Parameters

[in]

enable

true to arm, false to disarm.

Returns

ra8_err_t error code.

Return values

k_ra8_ok

Done.

Precondition

ra8_rsip_init has been called.

Engine is idle.

Postcondition

CTRL.DPA_ARM matches enable.

Subsequent crypto ops run with countermeasures as requested.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 229 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported.

ra8_rsip_kdf()

ra8_err_t ra8_rsip_kdf ( ra8_rsip_kdf_op_t op, const ra8_rsip_key_handle_t * ikm, const uint8_t * label, uint32_t label_len, const uint8_t * salt, uint32_t salt_len, uint32_t out_len, ra8_rsip_key_handle_t * out )

nodiscard

Derive a key from input keying material + label/salt/info.

Implements:

• HKDF-SHA-256 / 384 / 512 – op selects the hash flavour; ikm is consumed as the IKM.
• HUK / UID bound – op selects the source root, ikm is NULL, and the engine binds the device-unique value.

Parameters

[in]	op	KDF mode selector.
[in]	ikm	Input keying material handle (may be NULL for HUK / UID modes).
[in]	label	Label / context bytes.
[in]	label_len	Label length in bytes.
[in]	salt	Salt bytes (may be NULL).
[in]	salt_len	Salt length in bytes.
[in]	out_len	Bytes of derived material requested.
[out]	out	Wrapped derived-key handle.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_null_ptr	out was NULL or label/ikm missing where required.
k_ra8_err_invalid_arg	out_len zero or larger than the hash's max XOF length.
k_ra8_err_hw_timeout	Engine never signalled KDF_DONE.

Precondition

op is one of k_ra8_rsip_kdf_op_*.

out is non-NULL.

Postcondition

On success out carries a wrapped HMAC-SHA-256 handle.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 727 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_key_unwrap()

ra8_err_t ra8_rsip_key_unwrap ( const ra8_rsip_key_handle_t * kek, const uint8_t * iv, const uint8_t * blob, ra8_rsip_key_handle_t * dest )

nodiscard

Unwrap a transportable blob into a key handle.

Parameters

[in]	kek	Key-encryption-key handle.
[in]	iv	16-byte wrap IV used at wrap time.
[in]	blob	Wrapped blob (64 bytes).
[out]	dest	Destination key handle.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Blob authenticity check failed.

Precondition

kek->alg is an AES install opcode.

iv, blob, dest are non-NULL.

Postcondition

On success, dest carries the unwrapped algorithm + body.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 715 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_key_wrap()

ra8_err_t ra8_rsip_key_wrap ( const ra8_rsip_key_handle_t * kek, const uint8_t * iv, const ra8_rsip_key_handle_t * src, uint8_t * blob )

nodiscard

Wrap a key handle into a transportable blob using a KEK.

Parameters

[in]	kek	Key-encryption-key handle.
[in]	iv	16-byte wrap IV.
[in]	src	Source key handle to wrap.
[out]	blob	Wrapped blob output (64 bytes).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Blob produced.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

kek->alg is an AES install opcode.

iv is non-NULL.

Postcondition

On success, blob[0..63] is the wrapped blob.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 703 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_kv_count()

ra8_err_t ra8_rsip_kv_count ( uint32_t * out )

nodiscard

Snapshot the populated-slot count.

Parameters

[out]

out

Receives the count (0..16); never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Count returned.
k_ra8_err_null_ptr	out was NULL.

Precondition

out is non-NULL.

ra8_rsip_init has been called.

Postcondition

*out is in [0..k_ra8_rsip_kv_slot_count].

No engine state is modified.

Note

Thread safety: read-only, safe to call concurrently.

Since

0.1.0

Definition at line 697 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_kv_erase()

ra8_err_t ra8_rsip_kv_erase ( uint8_t slot )

nodiscard

Zeroise a vault slot.

Parameters

[in]

slot

Slot index.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Slot erased.
k_ra8_err_invalid_arg	slot out of range.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

slot < k_ra8_rsip_kv_slot_count.

ra8_rsip_init has been called.

Postcondition

Slot reads back as zero.

Populated-slot count decremented if the slot was non-empty.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 691 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported.

ra8_rsip_kv_read()

ra8_err_t ra8_rsip_kv_read ( uint8_t slot, uint8_t * out )

nodiscard

Read a wrapped-key blob from a vault slot.

Parameters

[in]	slot	Slot index (0..k_ra8_rsip_kv_slot_count-1).
[out]	out	64-byte buffer to receive the wrapped blob.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Blob returned.
k_ra8_err_invalid_arg	slot out of range.
k_ra8_err_null_ptr	out was NULL.
k_ra8_err_not_found	Slot is empty.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

slot < k_ra8_rsip_kv_slot_count.

out is non-NULL.

Postcondition

On success, out[0..63] holds the slot blob.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 677 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_kv_write()

ra8_err_t ra8_rsip_kv_write ( uint8_t slot, const uint8_t * in )

nodiscard

Write a wrapped-key blob into a vault slot.

Parameters

[in]	slot	Slot index.
[in]	in	64-byte wrapped blob.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Slot written.
k_ra8_err_invalid_arg	slot out of range.
k_ra8_err_null_ptr	in was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

slot < k_ra8_rsip_kv_slot_count.

in is non-NULL.

Postcondition

Slot now reads back as in.

Populated-slot count incremented if the slot was empty.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 684 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_life_advance()

ra8_err_t ra8_rsip_life_advance ( ra8_rsip_life_state_t state )

nodiscard

Advance the device lifecycle to a new state.

Lifecycle transitions are one-way (HUM Ch 51.1 p 3263). The engine rejects backward moves with k_ra8_err_invalid_state.

Parameters

[in]

state

Target lifecycle state.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Transition complete.
k_ra8_err_invalid_arg	Unknown state.
k_ra8_err_invalid_state	Transition would move backward.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

state is one of ra8_rsip_life_state_t.

state is forward of the current state.

Postcondition

Subsequent ra8_rsip_life_get returns state.

Note

Thread safety: not thread-safe.

Warning

Lifecycle transitions are irreversible.

Since

0.1.0

Definition at line 193 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported.

ra8_rsip_life_get()

ra8_err_t ra8_rsip_life_get ( ra8_rsip_life_state_t * out )

nodiscard

Read the device-lifecycle state.

Parameters

[out]

out

Receives the lifecycle word.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out was NULL.

Precondition

out is non-NULL.

ra8_rsip_init has been called.

Postcondition

*out reflects LIFE_STATE.

No engine state is modified.

Note

Thread safety: read-only.

Since

0.1.0

Definition at line 187 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_oem_bl_version_get()

ra8_err_t ra8_rsip_oem_bl_version_get ( uint32_t * out )

nodiscard

Read the latched OEM boot loader version counter.

Parameters

[out]

out

Receives the 32-bit counter; never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out was NULL.

Precondition

out is non-NULL.

ra8_rsip_init has been called.

Postcondition

*out reflects the OEM_BL_VER cell.

No engine state is modified.

Note

Thread safety: read-only, safe to call concurrently.

Since

0.1.0

Definition at line 661 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_oem_bl_version_increment()

ra8_err_t ra8_rsip_oem_bl_version_increment ( void )

nodiscard

Increment the OEM boot loader version (anti-rollback step).

Writes the inc-trigger word; the engine increments the counter monotonically. The lock register MUST be set after a successful boot to prevent further increments mid-flight.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Counter advanced.
k_ra8_err_invalid_state	OEM_BL_LOCK already latched.

Precondition

ra8_rsip_init has been called.

OEM_BL_LOCK is clear.

Postcondition

Counter has incremented by 1.

Counter value is observable via ra8_rsip_oem_bl_version_get.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 667 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported.

ra8_rsip_oem_bl_version_lock()

ra8_err_t ra8_rsip_oem_bl_version_lock ( void )

nodiscard

Latch the OEM_BL_LOCK so further increments are rejected.

Returns

ra8_err_t error code.

Return values

k_ra8_ok

Lock latched.

Precondition

ra8_rsip_init has been called.

Caller has finished any anti-rollback steps for this boot.

Postcondition

OEM_BL_LOCK reads as 1.

Subsequent ra8_rsip_oem_bl_version_increment returns k_ra8_err_invalid_state.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 672 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported.

ra8_rsip_tamper_ack()

ra8_err_t ra8_rsip_tamper_ack ( uint32_t mask )

nodiscard

Acknowledge tamper-source flags (write-1-to-clear).

Parameters

[in]

mask

Bits to clear.

Returns

ra8_err_t error code.

Return values

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

Precondition

mask AND-clean against k_ra8_rsip_tamper_src_all.

mask is non-zero.

Postcondition

Requested bits read as zero.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 223 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported.

ra8_rsip_tamper_enable()

ra8_err_t ra8_rsip_tamper_enable ( uint32_t sources )

nodiscard

Enable or disable a set of tamper sources.

Parameters

[in]

sources

OR of k_ra8_rsip_tamper_src_* bits to enable.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Mask applied.
k_ra8_err_invalid_arg	sources has bits outside the documented mask.

Precondition

sources AND-clean against k_ra8_rsip_tamper_src_all.

ra8_rsip_init has been called.

Postcondition

TAMPER_CTRL reads as sources.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 211 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported.

ra8_rsip_tamper_status()

ra8_err_t ra8_rsip_tamper_status ( uint32_t * out )

nodiscard

Read latched tamper-source flags.

Parameters

[out]

out

Receives the flag word.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Snapshot returned.
k_ra8_err_null_ptr	out was NULL.

Precondition

out is non-NULL.

ra8_rsip_init has been called.

Postcondition

*out reflects TAMPER_STATUS.

No engine state is modified.

Note

Thread safety: read-only.

Since

0.1.0

Definition at line 217 of file ra8_rsip_devsec.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.