RSIP protected-key HAL implementation. More...

#include "ra8_rsip_protected.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_rsip.h"
#include "ra8_rsip_key_injection.h"
#include "ra8_rsip_regs.h"
#include "ra8_stack_budget.h"

Include dependency graph for ra8_rsip_protected.c:

Enumerations
enum	rsip_prot_size_t : uint16_t { k_rsa_1024_mod_bytes = 128U , k_rsa_2048_mod_bytes = 256U , k_rsa_3072_mod_bytes = 384U , k_rsa_4096_mod_bytes = 512U , k_ecc_secp256_priv_bytes = 32U , k_ecc_secp384r1_priv_bytes = 48U , k_ecc_secp521r1_priv_bytes = 66U }
	RSA modulus / ECC private-scalar byte counts. More...
enum	rsip_prot_stack_t : uint16_t { k_unwrap_key_stack_bytes = 1128U , k_rsa4096_priv_stack_bytes = 1720U , k_ecc_priv_stack_bytes = 1104U }
	Measured worst-case stack frames (bytes), scrubbed on unwind. More...
enum	ra8_rsip_p_layout_t : uint32_t { k_ra8_rsip_p_off_payload = 20U }
	Local copy of the wrapped-key blob layout. More...
enum	ra8_rsip_p_const_t : uint32_t { k_ra8_rsip_p_aes_max_bytes = 32U , k_ra8_rsip_p_iv_bytes = 16U , k_ra8_rsip_p_bits_per_byte = 8U , k_ra8_rsip_p_aes128_bytes = 16U , k_ra8_rsip_p_aes192_bytes = 24U , k_ra8_rsip_p_aes256_bytes = 32U , k_ra8_rsip_p_rsa_e_bytes = 4U }
	Sizing constants used by the protected layer. More...

Functions
static void	internal_p_scrub (uint8_t *buf, uint32_t n)
	Bytewise scrub of a buffer.
static ra8_err_t	internal_p_aes_install (const uint8_t raw_key, ra8_rsip_aes_key_bits_t key_bits, ra8_rsip_key_handle_t out)
	Drive the right ra8_rsip_aes*_install_plain for the width.
ra8_err_t	ra8_rsip_protected_aes_init (const uint8_t wrapped_key, ra8_rsip_aes_key_bits_t key_bits, ra8_rsip_aes_mode_t mode, const uint8_t iv)
	Initialise an AES context using a wrapped key blob.
ra8_err_t	ra8_rsip_protected_aes_encrypt (const uint8_t plaintext, uint8_t ciphertext, uint32_t len)
	Encrypt with the latched protected AES context.
ra8_err_t	ra8_rsip_protected_aes_decrypt (const uint8_t ciphertext, uint8_t plaintext, uint32_t len)
	Decrypt with the latched protected AES context.
ra8_err_t	ra8_rsip_protected_aes_finish (void)
	Finalise the protected AES context.
static ra8_err_t	internal_rsa_mod_bytes (ra8_rsip_rsa_size_t size, uint32_t *out_bytes)
	Map an ra8_rsip_rsa_size_t to its modulus byte count.
static ra8_rsip_oem_cmd_t	internal_rsa_install_cmd (ra8_rsip_rsa_size_t size)
	Resolve the OEM install opcode for an RSA private key size.
static ra8_err_t	internal_rsa_validate_wrapped (const uint8_t *wrapped_priv)
	Accept a wrapped RSA blob tagged with either RSA type tag.
static ra8_err_t	internal_rsa_install_priv (const uint8_t wrapped_priv, ra8_rsip_rsa_size_t size, uint32_t mod_bytes, ra8_rsip_key_handle_t out_handle)
	Recover the modulus from a wrapped blob and OEM-install it.
ra8_err_t	ra8_rsip_protected_rsa_decrypt (const uint8_t wrapped_priv, ra8_rsip_rsa_size_t size, const uint8_t ciphertext, uint32_t ciphertext_len, uint8_t *plaintext_out, uint32_t plaintext_cap)
	RSA-private decrypt using a wrapped private key.
static ra8_err_t	internal_ecc_priv_params (ra8_rsip_curve_t curve, uint32_t out_alg, uint32_t out_priv_bytes)
	Map an ra8_rsip_curve_t to its OEM opcode and scalar size.
ra8_err_t	ra8_rsip_protected_ecdsa_sign (const uint8_t wrapped_priv, ra8_rsip_curve_t curve, const uint8_t hash, uint32_t hash_len, uint8_t *sig_out)
	ECDSA sign using a wrapped private key.

Variables
static const char *	s_tag = "RSIP_P"
	Logger tag for this TU.
static ra8_rsip_key_handle_t	s_p_aes_handle
	Latched AES handle for the protected-AES path.
static uint8_t	s_p_aes_iv [k_ra8_rsip_p_iv_bytes]
	Latched IV used by the protected-AES path.
static bool	s_p_aes_iv_set
	Whether s_p_aes_iv was populated by the caller.
static ra8_rsip_aes_mode_t	s_p_aes_mode
	Latched block-cipher mode for the protected-AES path.
static bool	s_p_aes_active
	Whether ra8_rsip_protected_aes_init has run since the last finish.

Detailed Description

RSIP protected-key HAL implementation.

Tag: [Ring 3 / HAL] {World: S}

Software-stub backend for the public API in libs/ra8_hal/inc/ra8_rsip_protected.h. Each entry point validates the wrapped-key blob via ra8_rsip_key_validate, unwraps the payload into a private scratch buffer, dispatches the underlying unprotected ra8_rsip_* operation, and scrubs the scratch buffer.

Warning: Stub backend; NOT cryptographically secure.

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

Definition in file ra8_rsip_protected.c.

Enumeration Type Documentation

◆ ra8_rsip_p_const_t

enum ra8_rsip_p_const_t : uint32_t

Sizing constants used by the protected layer.

Since: 0.1.0

Enumerator
k_ra8_rsip_p_aes_max_bytes	AES-256 key length.
k_ra8_rsip_p_iv_bytes	AES IV length.
k_ra8_rsip_p_bits_per_byte	Width of a byte.
k_ra8_rsip_p_aes128_bytes	AES-128 raw-key bytes.
k_ra8_rsip_p_aes192_bytes	AES-192 raw-key bytes.
k_ra8_rsip_p_aes256_bytes	AES-256 raw-key bytes.
k_ra8_rsip_p_rsa_e_bytes	RSA exponent bytes (stub).

Definition at line 82 of file ra8_rsip_protected.c.

◆ ra8_rsip_p_layout_t

enum ra8_rsip_p_layout_t : uint32_t

Local copy of the wrapped-key blob layout.

Mirrors ra8_rsip_ki_layout_t from ra8_rsip_key_injection.c; duplicated here so this TU does not depend on private internals of the injection driver.

Since: 0.1.0

Enumerator
k_ra8_rsip_p_off_payload	Payload offset inside a wrapped blob.

Definition at line 72 of file ra8_rsip_protected.c.

◆ rsip_prot_size_t

enum rsip_prot_size_t : uint16_t

RSA modulus / ECC private-scalar byte counts.

Enumerator
k_rsa_1024_mod_bytes	RSA 1024 mod bytes.
k_rsa_2048_mod_bytes	RSA 2048 mod bytes.
k_rsa_3072_mod_bytes	RSA 3072 mod bytes.
k_rsa_4096_mod_bytes	RSA 4096 mod bytes.
k_ecc_secp256_priv_bytes	ECC secp256 priv bytes.
k_ecc_secp384r1_priv_bytes	ECC secp384r1 priv bytes.
k_ecc_secp521r1_priv_bytes	ECC secp521r1 priv bytes.

Definition at line 44 of file ra8_rsip_protected.c.

◆ rsip_prot_stack_t

enum rsip_prot_stack_t : uint16_t

Measured worst-case stack frames (bytes), scrubbed on unwind.

Enumerator
k_unwrap_key_stack_bytes	Unwrap key stack bytes.
k_rsa4096_priv_stack_bytes	Rsa4096 priv stack bytes.
k_ecc_priv_stack_bytes	ECC priv stack bytes.

Definition at line 55 of file ra8_rsip_protected.c.

Function Documentation

◆ internal_ecc_priv_params()

ra8_err_t internal_ecc_priv_params	(	ra8_rsip_curve_t	curve,
		uint32_t *	out_alg,
		uint32_t *	out_priv_bytes )

static

Map an ra8_rsip_curve_t to its OEM opcode and scalar size.

Lookup helper for the protected ECDSA path: resolves the engine algorithm tag (k_ra8_rsip_oem_cmd_ecc_*_priv) and the private scalar byte count for each supported curve. Unknown curve values are rejected so the caller never builds a handle from them.

Parameters

[in]	curve	ECC curve selector.
[out]	out_alg	Receives the OEM install opcode value.
[out]	out_priv_bytes	Receives the private scalar byte count.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Curve mapped; both outputs written.
k_ra8_err_invalid_arg	Unknown curve enum value.

Precondition: out_alg and out_priv_bytes are non-NULL.; curve is a value of ra8_rsip_curve_t.

Postcondition: On success both outputs describe the selected curve.; On error neither output has been written.

Note: Pure function; reentrant and ISR-safe.

Since: 0.1.0

Definition at line 525 of file ra8_rsip_protected.c.

References k_ecc_secp256_priv_bytes, k_ecc_secp384r1_priv_bytes, k_ecc_secp521r1_priv_bytes, k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_rsip_curve_secp256k1, k_ra8_rsip_curve_secp256r1, k_ra8_rsip_curve_secp384r1, k_ra8_rsip_curve_secp521r1, k_ra8_rsip_oem_cmd_ecc_secp256k1_priv, k_ra8_rsip_oem_cmd_ecc_secp256r1_priv, k_ra8_rsip_oem_cmd_ecc_secp384r1_priv, and k_ra8_rsip_oem_cmd_ecc_secp521r1_priv.

Referenced by ra8_rsip_protected_ecdsa_sign().

◆ internal_p_aes_install()

ra8_err_t internal_p_aes_install	(	const uint8_t *	raw_key,
		ra8_rsip_aes_key_bits_t	key_bits,
		ra8_rsip_key_handle_t *	out )

static

Drive the right ra8_rsip_aes*_install_plain for the width.

Parameters

[in]	raw_key	Raw key bytes.
[in]	key_bits	Width selector.
[out]	out	Wrapped handle.

Returns: ra8_err_t.

Precondition: raw_key and out non-NULL.; raw_key is at least key_bits / 8 bytes long.

Postcondition: On success, out->alg matches the install opcode.

Since: 0.1.0

See implementation.

Return values

k_ra8_ok Operation succeeded.

Postcondition: Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Definition at line 189 of file ra8_rsip_protected.c.

References k_ra8_err_invalid_arg, k_ra8_rsip_aes_key_bits_128, k_ra8_rsip_aes_key_bits_192, k_ra8_rsip_aes_key_bits_256, RA8_INTERNAL, ra8_rsip_aes128_install_plain(), ra8_rsip_aes192_install_plain(), and ra8_rsip_aes256_install_plain().

Referenced by ra8_rsip_protected_aes_init().

◆ internal_p_scrub()

void internal_p_scrub	(	uint8_t *	buf,
		uint32_t	n )

static

Bytewise scrub of a buffer.

Parameters

[out]	buf	Buffer to zero.
[in]	n	Length of buf.

Precondition: buf non-NULL when n > 0.

Postcondition: buf[0..n-1] is zero.

Since: 0.1.0

See implementation.

Precondition: Module state is consistent.

Postcondition: Caller-visible state matches the documented contract.

Note: Not thread-safe unless documented otherwise.

Definition at line 162 of file ra8_rsip_protected.c.

References RA8_INTERNAL.

Referenced by internal_rsa_install_priv(), ra8_rsip_protected_aes_finish(), ra8_rsip_protected_aes_init(), and ra8_rsip_protected_ecdsa_sign().

◆ internal_rsa_install_cmd()

ra8_rsip_oem_cmd_t internal_rsa_install_cmd ( ra8_rsip_rsa_size_t size )

static

Resolve the OEM install opcode for an RSA private key size.

The stub install table is keyed by ra8_rsip_oem_cmd_t; this helper collapses the size-to-opcode mapping so the public entry point does not have to repeat the switch in line.

Parameters

[in] size RSA key-size enum.

Returns: ra8_rsip_oem_cmd_t value; k_ra8_rsip_oem_cmd_invalid for sizes not represented in the OEM install path (RSA-1024).

Return values

k_ra8_rsip_oem_cmd_rsa2048_priv	size == k_ra8_rsip_rsa_2048.
k_ra8_rsip_oem_cmd_rsa3072_priv	size == k_ra8_rsip_rsa_3072.
k_ra8_rsip_oem_cmd_rsa4096_priv	size == k_ra8_rsip_rsa_4096.
k_ra8_rsip_oem_cmd_invalid	size is RSA-1024 or unknown.

Precondition: Caller has validated size via internal_rsa_mod_bytes().; size is a value of ra8_rsip_rsa_size_t.

Postcondition: Return value is one of the documented opcodes or _invalid.; No global or module-private state is mutated.

Note: Pure function; reentrant and ISR-safe.

Since: 0.1.0

Definition at line 365 of file ra8_rsip_protected.c.

References k_ra8_rsip_oem_cmd_invalid, k_ra8_rsip_oem_cmd_rsa2048_priv, k_ra8_rsip_oem_cmd_rsa3072_priv, k_ra8_rsip_oem_cmd_rsa4096_priv, k_ra8_rsip_rsa_2048, k_ra8_rsip_rsa_3072, and k_ra8_rsip_rsa_4096.

Referenced by internal_rsa_install_priv().

◆ internal_rsa_install_priv()

ra8_err_t internal_rsa_install_priv	(	const uint8_t *	wrapped_priv,
		ra8_rsip_rsa_size_t	size,
		uint32_t	mod_bytes,
		ra8_rsip_key_handle_t *	out_handle )

static

Recover the modulus from a wrapped blob and OEM-install it.

Re-installs the wrapped key under the RSA OEM opcode so the downstream ra8_rsip_rsa_sign accepts it (the stub recognises k_ra8_rsip_oem_cmd_rsa* algorithm tags). The raw modulus is recovered from the payload and pushed through the OEM install path just like the unprotected install entry points would; the stack scratch copy is scrubbed before returning.

Parameters

[in]	wrapped_priv	Wrapped RSA private-key blob.
[in]	size	RSA key-size enum (already validated).
[in]	mod_bytes	Modulus byte count for size.
[out]	out_handle	Receives the installed key handle.

Returns: ra8_err_t error code from ra8_rsip_oem_install.

Return values

k_ra8_ok Key installed; *out_handle is live.

Precondition: wrapped_priv passed internal_rsa_validate_wrapped.; mod_bytes came from internal_rsa_mod_bytes for size.

Postcondition: The modulus stack scratch has been scrubbed.; On error *out_handle holds no usable key material.

Note: Not thread-safe; single secure-dispatch context.

Since: 0.1.0

Definition at line 438 of file ra8_rsip_protected.c.

References internal_p_scrub(), internal_rsa_install_cmd(), k_ra8_rsip_p_iv_bytes, k_ra8_rsip_p_off_payload, k_ra8_rsip_wrapped_max_payload, and ra8_rsip_oem_install().

Referenced by ra8_rsip_protected_rsa_decrypt().

◆ internal_rsa_mod_bytes()

ra8_err_t internal_rsa_mod_bytes	(	ra8_rsip_rsa_size_t	size,
		uint32_t *	out_bytes )

static

Map an ra8_rsip_rsa_size_t to its modulus byte count.

Lookup helper used by the protected RSA path; the engine's modular-exponentiation surface accepts only the four canonical key sizes. Anything else is rejected.

Parameters

[in]	size	RSA key-size enum.
[out]	out_bytes	Receives 128/256/384/512 on success.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Valid size mapped.
k_ra8_err_invalid_arg	Unknown enum value.

Precondition: out_bytes non-NULL.; Caller has validated the wrapped key blob.

Postcondition: On success *out_bytes holds the modulus length in bytes.; On error *out_bytes is unchanged.

Note: Pure function; no side effects.

Since: 0.1.0

Definition at line 319 of file ra8_rsip_protected.c.

References k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_rsip_rsa_1024, k_ra8_rsip_rsa_2048, k_ra8_rsip_rsa_3072, k_ra8_rsip_rsa_4096, k_rsa_1024_mod_bytes, k_rsa_2048_mod_bytes, k_rsa_3072_mod_bytes, and k_rsa_4096_mod_bytes.

Referenced by ra8_rsip_protected_rsa_decrypt().

◆ internal_rsa_validate_wrapped()

ra8_err_t internal_rsa_validate_wrapped ( const uint8_t * wrapped_priv )

static

Accept a wrapped RSA blob tagged with either RSA type tag.

The injection layer tags both private and public RSA blobs with the public type tag (single-tag stub); this helper accepts either tag so the protected entry points do not repeat the two-step validate.

Parameters

[in] wrapped_priv Wrapped RSA key blob.

Returns: ra8_err_t error code from ra8_rsip_key_validate.

Return values

k_ra8_ok Blob carries a valid RSA public or private tag.

Precondition: wrapped_priv is non-NULL (checked by the caller).; The injection driver is initialized.

Postcondition: No state is mutated.; Return value depends only on the blob contents.

Note: Pure validation helper; safe from any context.

Since: 0.1.0

Definition at line 401 of file ra8_rsip_protected.c.

References k_ra8_ok, k_ra8_rsip_wrapped_type_rsa_priv, k_ra8_rsip_wrapped_type_rsa_pub, and ra8_rsip_key_validate().

Referenced by ra8_rsip_protected_rsa_decrypt().

◆ ra8_rsip_protected_aes_decrypt()

ra8_err_t ra8_rsip_protected_aes_decrypt	(	const uint8_t *	ciphertext,
		uint8_t *	plaintext,
		uint32_t	len )

nodiscard

Decrypt with the latched protected AES context.

Parameters

[in]	ciphertext	Source bytes.
[out]	plaintext	Destination bytes.
[in]	len	Number of bytes.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Buffer transformed.
k_ra8_err_invalid_state	Protected AES context not latched.
k_ra8_err_null_ptr	Either pointer was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: ra8_rsip_protected_aes_init returned k_ra8_ok.

Postcondition: On success, plaintext is populated.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 266 of file ra8_rsip_protected.c.

References k_ra8_err_invalid_state, k_ra8_rsip_dir_decrypt, RA8_CHECK_NULL_PTR, ra8_rsip_aes_cipher(), s_p_aes_active, s_p_aes_handle, s_p_aes_iv, s_p_aes_iv_set, s_p_aes_mode, and s_tag.

◆ ra8_rsip_protected_aes_encrypt()

ra8_err_t ra8_rsip_protected_aes_encrypt	(	const uint8_t *	plaintext,
		uint8_t *	ciphertext,
		uint32_t	len )

nodiscard

Encrypt with the latched protected AES context.

Parameters

[in]	plaintext	Source bytes.
[out]	ciphertext	Destination bytes.
[in]	len	Number of bytes.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Buffer transformed.
k_ra8_err_invalid_state	Protected AES context not latched.
k_ra8_err_null_ptr	Either pointer was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: ra8_rsip_protected_aes_init returned k_ra8_ok.

Postcondition: On success, ciphertext is populated.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 249 of file ra8_rsip_protected.c.

References k_ra8_err_invalid_state, k_ra8_rsip_dir_encrypt, RA8_CHECK_NULL_PTR, ra8_rsip_aes_cipher(), s_p_aes_active, s_p_aes_handle, s_p_aes_iv, s_p_aes_iv_set, s_p_aes_mode, and s_tag.

◆ ra8_rsip_protected_aes_finish()

ra8_err_t ra8_rsip_protected_aes_finish ( void )

nodiscard

Finalise the protected AES context.

Scrubs the latched key handle and IV. Must be called after the last encrypt / decrypt and before another ra8_rsip_protected_aes_init cycle so a stale handle cannot be reused.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Context cleared.
k_ra8_err_invalid_state	..._aes_init had not run.

Precondition: ra8_rsip_protected_aes_init returned k_ra8_ok.

Postcondition: Cached AES context is wiped.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 282 of file ra8_rsip_protected.c.

References internal_p_scrub(), k_ra8_err_invalid_state, k_ra8_ok, k_ra8_rsip_p_iv_bytes, s_p_aes_active, s_p_aes_handle, s_p_aes_iv, and s_p_aes_iv_set.

◆ ra8_rsip_protected_aes_init()

ra8_err_t ra8_rsip_protected_aes_init	(	const uint8_t *	wrapped_key,
		ra8_rsip_aes_key_bits_t	key_bits,
		ra8_rsip_aes_mode_t	mode,
		const uint8_t *	iv )

nodiscard

Initialise an AES context using a wrapped key blob.

Validates the wrapper, materialises the underlying ra8_rsip_key_handle_t via the install-plain path, and latches it along with the requested mode and IV. Subsequent calls to ra8_rsip_protected_aes_encrypt / ..._decrypt use the latched state without re-presenting the raw key.

Parameters

[in]	wrapped_key	Wrapped-key buffer produced by ra8_rsip_key_inject_aes.
[in]	key_bits	Width of the wrapped key.
[in]	mode	Block-cipher mode (ECB / CBC / CTR).
[in]	iv	16-byte IV (NULL only for ECB).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Context initialized.
k_ra8_err_null_ptr	wrapped_key was NULL.
k_ra8_err_invalid_arg	Wrapper type tag mismatched, mode or key-bits unsupported.
k_ra8_err_hw_error	Wrapper integrity MAC failed.
k_ra8_err_hw_timeout	RSIP install primitive timed out.

Precondition: Wrapper was produced by ra8_rsip_key_inject_aes.; ra8_rsip_init returned k_ra8_ok on the live engine (or ra8_fake_mmap is wired up under test).

Postcondition: On success, AES context is latched.

Note: Thread safety: not thread-safe.

See also: ra8_rsip_aes_cipher

Since: 0.1.0

Definition at line 205 of file ra8_rsip_protected.c.

References internal_p_aes_install(), internal_p_scrub(), k_ra8_err_invalid_arg, k_ra8_ok, k_ra8_rsip_p_aes_max_bytes, k_ra8_rsip_p_bits_per_byte, k_ra8_rsip_p_iv_bytes, k_ra8_rsip_p_off_payload, k_ra8_rsip_wrapped_type_aes, k_unwrap_key_stack_bytes, RA8_CHECK_NULL_PTR, ra8_rsip_key_validate(), RA8_STACK_BUDGET, s_p_aes_active, s_p_aes_handle, s_p_aes_iv, s_p_aes_iv_set, s_p_aes_mode, and s_tag.

◆ ra8_rsip_protected_ecdsa_sign()

ra8_err_t ra8_rsip_protected_ecdsa_sign	(	const uint8_t *	wrapped_priv,
		ra8_rsip_curve_t	curve,
		const uint8_t *	hash,
		uint32_t	hash_len,
		uint8_t *	sig_out )

nodiscard

ECDSA sign using a wrapped private key.

Parameters

[in]	wrapped_priv	Wrapped-key buffer.
[in]	curve	Curve identifier.
[in]	hash	Message digest.
[in]	hash_len	Length of hash.
[out]	sig_out	Signature destination (r \|\| s).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Signature written.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_invalid_arg	Wrapper malformed; curve unsupported.
k_ra8_err_hw_error	Wrapper integrity MAC failed.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: Wrapper was produced by ra8_rsip_key_inject_ecc(..., true).; ra8_rsip_init returned k_ra8_ok on the live engine.

Postcondition: On success, sig_out is populated.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 549 of file ra8_rsip_protected.c.

References ra8_rsip_key_handle_t::alg, ra8_rsip_key_handle_t::body, ra8_rsip_key_handle_t::body_words, internal_ecc_priv_params(), internal_p_scrub(), k_ecc_priv_stack_bytes, k_ra8_ok, k_ra8_rsip_p_off_payload, k_ra8_rsip_wrapped_type_ecc_priv, RA8_CHECK_NULL_PTR, ra8_rsip_ecdsa_sign(), ra8_rsip_key_validate(), RA8_STACK_BUDGET, and s_tag.

◆ ra8_rsip_protected_rsa_decrypt()

ra8_err_t ra8_rsip_protected_rsa_decrypt	(	const uint8_t *	wrapped_priv,
		ra8_rsip_rsa_size_t	size,
		const uint8_t *	ciphertext,
		uint32_t	ciphertext_len,
		uint8_t *	plaintext_out,
		uint32_t	plaintext_cap )

nodiscard

RSA-private decrypt using a wrapped private key.

The stub treats RSA-decrypt as RSA-sign with a swapped semantic: the wrapper is presented to ra8_rsip_rsa_sign so the engine exercises the same modular-exponentiation path that a real "private op" would follow. The output is the engine's raw exponentiation result – callers wrap their own padding scheme (PKCS#1 v1.5 / OAEP) on top.

Parameters

[in]	wrapped_priv	Wrapped-key buffer.
[in]	size	RSA modulus width.
[in]	ciphertext	Big-endian ciphertext (modulus / 8 bytes).
[in]	ciphertext_len	Length of ciphertext.
[out]	plaintext_out	Destination (modulus / 8 bytes).
[in]	plaintext_cap	Capacity of plaintext_out.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Plaintext written.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_invalid_arg	Wrapper malformed; lengths unsupported.
k_ra8_err_hw_error	Wrapper integrity MAC failed.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: Wrapper was produced by ra8_rsip_key_inject_rsa.; ra8_rsip_init returned k_ra8_ok on the live engine.

Postcondition: On success, plaintext_out is populated.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 458 of file ra8_rsip_protected.c.

References internal_rsa_install_priv(), internal_rsa_mod_bytes(), internal_rsa_validate_wrapped(), k_ra8_err_invalid_arg, k_ra8_ok, k_rsa4096_priv_stack_bytes, RA8_CHECK_NULL_PTR, ra8_rsip_rsa_sign(), RA8_STACK_BUDGET, and s_tag.

Variable Documentation

◆ s_p_aes_active

bool s_p_aes_active

static

Whether ra8_rsip_protected_aes_init has run since the last finish.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 143 of file ra8_rsip_protected.c.

Referenced by ra8_rsip_protected_aes_decrypt(), ra8_rsip_protected_aes_encrypt(), ra8_rsip_protected_aes_finish(), and ra8_rsip_protected_aes_init().

◆ s_p_aes_handle

ra8_rsip_key_handle_t s_p_aes_handle

static

Latched AES handle for the protected-AES path.

Populated by ra8_rsip_protected_aes_init and consumed by ra8_rsip_protected_aes_encrypt / ..._decrypt.

Warning: Direct modification is forbidden; the protected entry points are the only legitimate writers.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 106 of file ra8_rsip_protected.c.

Referenced by ra8_rsip_protected_aes_decrypt(), ra8_rsip_protected_aes_encrypt(), ra8_rsip_protected_aes_finish(), and ra8_rsip_protected_aes_init().

◆ s_p_aes_iv

uint8_t s_p_aes_iv[k_ra8_rsip_p_iv_bytes]

static

Latched IV used by the protected-AES path.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 115 of file ra8_rsip_protected.c.

Referenced by ra8_rsip_protected_aes_decrypt(), ra8_rsip_protected_aes_encrypt(), ra8_rsip_protected_aes_finish(), and ra8_rsip_protected_aes_init().

◆ s_p_aes_iv_set

bool s_p_aes_iv_set

static

Whether s_p_aes_iv was populated by the caller.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 124 of file ra8_rsip_protected.c.

Referenced by ra8_rsip_protected_aes_decrypt(), ra8_rsip_protected_aes_encrypt(), ra8_rsip_protected_aes_finish(), and ra8_rsip_protected_aes_init().

◆ s_p_aes_mode

ra8_rsip_aes_mode_t s_p_aes_mode

static

Latched block-cipher mode for the protected-AES path.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 133 of file ra8_rsip_protected.c.

Referenced by ra8_rsip_protected_aes_decrypt(), ra8_rsip_protected_aes_encrypt(), and ra8_rsip_protected_aes_init().

◆ s_tag

const char* s_tag = "RSIP_P"

static

Logger tag for this TU.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 41 of file ra8_rsip_protected.c.

Enumerations

Functions

Variables

Detailed Description

Enumeration Type Documentation

◆ ra8_rsip_p_const_t

◆ ra8_rsip_p_layout_t

◆ rsip_prot_size_t

◆ rsip_prot_stack_t

Function Documentation

◆ internal_ecc_priv_params()

◆ internal_p_aes_install()

◆ internal_p_scrub()

◆ internal_rsa_install_cmd()

◆ internal_rsa_install_priv()

◆ internal_rsa_mod_bytes()

◆ internal_rsa_validate_wrapped()

◆ ra8_rsip_protected_aes_decrypt()

◆ ra8_rsip_protected_aes_encrypt()

◆ ra8_rsip_protected_aes_finish()

◆ ra8_rsip_protected_aes_init()

◆ ra8_rsip_protected_ecdsa_sign()

◆ ra8_rsip_protected_rsa_decrypt()

Variable Documentation

◆ s_p_aes_active

◆ s_p_aes_handle

◆ s_p_aes_iv

◆ s_p_aes_iv_set

◆ s_p_aes_mode

◆ s_tag