RSIP protected-key HAL – crypto operations driven by wrappedkey blobs (the RSIP engine never sees the raw key). More...

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

Include dependency graph for ra8_rsip_protected.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_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.
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.
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.

Detailed Description

RSIP protected-key HAL – crypto operations driven by wrapped

key blobs (the RSIP engine never sees the raw key).

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

Mirrors the FSP r_rsip_protected shape: every entry point takes a wrapped-key buffer (produced by ra8_rsip_key_inject_*) instead of a raw key. The wrapper carries the key-injection envelope and an integrity MAC so the protected-op path can refuse forged or corrupted blobs before they reach the engine.

Internally the stub validates the blob via ra8_rsip_key_validate, unwraps the payload into a private scratch buffer, drives the underlying ra8_rsip_*_install_plain call to obtain a wrapped ra8_rsip_key_handle_t, dispatches the crypto op, and scrubs the scratch buffer. A future drop-in real backend (sanctioned FSP integration) replaces the unwrap step with a hardware key-handle dispatch.

Warning: Stub backend; NOT cryptographically secure. The wrapper is symmetric (no real key isolation). Do not ship key-bearing firmware against this header until a real backend is wired up.

See also: ra8_rsip.h Underlying RSIP HAL surface.; ra8_rsip_key_injection.h Producer of wrapped-key blobs.

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

Definition in file ra8_rsip_protected.h.

Function Documentation

◆ 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.

Functions

Detailed Description

Function Documentation

◆ 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()