RSIP key-injection HAL – wrap raw key material into theRSIP installed-key blob format. More...

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

Include dependency graph for ra8_rsip_key_injection.h:

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

Enumerations
enum	ra8_rsip_wrapped_key_const_t : uint32_t { k_ra8_rsip_wrapped_type_bytes = 4U , k_ra8_rsip_wrapped_mgmt_info_bytes = 16U , k_ra8_rsip_wrapped_mac_bytes = 16U , k_ra8_rsip_wrapped_max_payload = 600U , k_ra8_rsip_wrapped_max_total = 636U }
	Sizing constants for RSIP wrapped-key blobs. More...
enum	ra8_rsip_wrapped_key_type_t : uint32_t { k_ra8_rsip_wrapped_type_aes = 0xD1D2D3D4UL , k_ra8_rsip_wrapped_type_rsa_pub = 0xE1E2E3E4UL , k_ra8_rsip_wrapped_type_rsa_priv = 0xE5E6E7E8UL , k_ra8_rsip_wrapped_type_ecc_pub = 0xF1F2F3F4UL , k_ra8_rsip_wrapped_type_ecc_priv = 0xF5F6F7F8UL }
	Type tag stored in the leading 4 bytes of a wrapped blob. More...
enum	ra8_rsip_aes_key_bits_t : uint16_t { k_ra8_rsip_aes_key_bits_128 = 128U , k_ra8_rsip_aes_key_bits_192 = 192U , k_ra8_rsip_aes_key_bits_256 = 256U }
	AES key-width selector accepted by ra8_rsip_key_inject_aes. More...

Functions
ra8_err_t	ra8_rsip_key_inject_aes (uint8_t installed_key_buf, const uint8_t raw_key, ra8_rsip_aes_key_bits_t key_bits)
	Wrap a raw AES key into the RSIP installed-key format.
ra8_err_t	ra8_rsip_key_inject_rsa (uint8_t installed_key_buf, const uint8_t raw_modulus, const uint8_t *raw_exponent, ra8_rsip_rsa_size_t size)
	Wrap a raw RSA key (modulus + exponent) into the installed-key format.
ra8_err_t	ra8_rsip_key_inject_ecc (uint8_t installed_key_buf, ra8_rsip_curve_t curve, const uint8_t raw_priv_or_pub, bool is_private)
	Wrap a raw ECC scalar (private or public) into the installed-key format.
ra8_err_t	ra8_rsip_key_validate (const uint8_t *installed_key_buf, ra8_rsip_wrapped_key_type_t expected_type)
	Validate that a wrapped-key blob has the expected structure and a matching trailing MAC.

Detailed Description

RSIP key-injection HAL – wrap raw key material into the

RSIP installed-key blob format.

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

The Renesas FSP r_rsip_key_injection driver bundles a raw key (AES, RSA modulus + exponent, ECC private or public scalar) with a key-injection envelope so the RSIP-E50D engine can accept key material without ever exposing the raw bytes to host software again. This HAL exposes the wrapping operation only – the wrapped blob is then consumed by ra8_rsip_protected_* calls.

The implementation in ra8_rsip_key_injection.c is a host-friendly software stub that lays out the wrapped buffer in the same shape the FSP layer would ([type | mgmt-info | key-bytes | footer-mac]) but uses a deterministic xorshift64* mixer to produce the embedded MAC. This mirrors the pattern used by ra8_sce_key_injection so the protected-op pipeline can round-trip in unit tests. A future drop-in real backend (sanctioned FSP integration) only has to honour the public API shape here.

Warning: Stub backend; NOT cryptographically secure. 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_protected.h Crypto operations driven by wrapped keys.

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

Definition in file ra8_rsip_key_injection.h.

Enumeration Type Documentation

◆ ra8_rsip_aes_key_bits_t

enum ra8_rsip_aes_key_bits_t : uint16_t

AES key-width selector accepted by ra8_rsip_key_inject_aes.

Since: 0.1.0

Enumerator
k_ra8_rsip_aes_key_bits_128	AES-128.
k_ra8_rsip_aes_key_bits_192	AES-192.
k_ra8_rsip_aes_key_bits_256	AES-256.

Definition at line 101 of file ra8_rsip_key_injection.h.

◆ ra8_rsip_wrapped_key_const_t

enum ra8_rsip_wrapped_key_const_t : uint32_t

Sizing constants for RSIP wrapped-key blobs.

Mirrors the FSP rsip_*_wrapped_key_t shape: a 4-byte type tag, a fixed-size key-injection envelope, the raw key bytes, and a 16-byte footer MAC. The sizes are picked to fit the largest supported key (RSA-4096 modulus + exponent) plus padding so the total blob fits in a single fixed-size buffer.

Invariant: k_ra8_rsip_wrapped_max_total == k_ra8_rsip_wrapped_type_bytes + k_ra8_rsip_wrapped_mgmt_info_bytes + k_ra8_rsip_wrapped_max_payload + k_ra8_rsip_wrapped_mac_bytes.

Since: 0.1.0

Enumerator
k_ra8_rsip_wrapped_type_bytes	Wrapped-blob type tag.
k_ra8_rsip_wrapped_mgmt_info_bytes	Key-injection envelope.
k_ra8_rsip_wrapped_mac_bytes	Trailing integrity MAC.
k_ra8_rsip_wrapped_max_payload	Largest key payload (RSA-4096).
k_ra8_rsip_wrapped_max_total	Largest wrapped blob in bytes.

Definition at line 69 of file ra8_rsip_key_injection.h.

◆ ra8_rsip_wrapped_key_type_t

enum ra8_rsip_wrapped_key_type_t : uint32_t

Type tag stored in the leading 4 bytes of a wrapped blob.

The tag lets the protected layer reject blobs created for the wrong algorithm before the engine even sees them.

Since: 0.1.0

Enumerator
k_ra8_rsip_wrapped_type_aes	AES key blob.
k_ra8_rsip_wrapped_type_rsa_pub	RSA public blob.
k_ra8_rsip_wrapped_type_rsa_priv	RSA private blob.
k_ra8_rsip_wrapped_type_ecc_pub	ECC public blob.
k_ra8_rsip_wrapped_type_ecc_priv	ECC private blob.

Definition at line 87 of file ra8_rsip_key_injection.h.

Function Documentation

◆ ra8_rsip_key_inject_aes()

ra8_err_t ra8_rsip_key_inject_aes	(	uint8_t *	installed_key_buf,
		const uint8_t *	raw_key,
		ra8_rsip_aes_key_bits_t	key_bits )

nodiscard

Wrap a raw AES key into the RSIP installed-key format.

Produces a self-describing blob the RSIP engine accepts as a "wrapped key": a leading type tag, the key-injection envelope, the AES key bytes, and a trailing MAC over the whole structure. The blob is the only artefact a caller may pass to ra8_rsip_protected_aes_init.

Warning: Stub: the wrapping is deterministic; not real key isolation. See file-level; .

Parameters

[out]	installed_key_buf	Destination buffer; must be k_ra8_rsip_wrapped_max_total bytes.
[in]	raw_key	Raw AES key bytes (key_bits / 8).
[in]	key_bits	AES key width.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Blob written.
k_ra8_err_null_ptr	installed_key_buf or raw_key was NULL.
k_ra8_err_invalid_arg	Unsupported key_bits.

Precondition: installed_key_buf is k_ra8_rsip_wrapped_max_total bytes.; raw_key is at least key_bits / 8 bytes.

Postcondition: On success, installed_key_buf holds a valid wrapped blob.; First 4 bytes of installed_key_buf equal k_ra8_rsip_wrapped_type_aes (little-endian).

Note: Thread safety: not thread-safe.

See also: ra8_rsip_protected_aes_init

Since: 0.1.0

Definition at line 555 of file ra8_rsip_key_injection.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_key_inject_ecc()

ra8_err_t ra8_rsip_key_inject_ecc	(	uint8_t *	installed_key_buf,
		ra8_rsip_curve_t	curve,
		const uint8_t *	raw_priv_or_pub,
		bool	is_private )

nodiscard

Wrap a raw ECC scalar (private or public) into the installed-key format.

For private keys the payload is the raw scalar bytes; for public keys the payload is X || Y (the uncompressed point coordinates). The byte counts come from curve.

Parameters

[out]	installed_key_buf	Destination buffer.
[in]	curve	Curve identifier.
[in]	raw_priv_or_pub	Raw scalar bytes; the buffer length is implied by curve.
[in]	is_private	true -> wrap a private scalar; false -> wrap a public point.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Blob written.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_invalid_arg	Unsupported curve.

Precondition: installed_key_buf is k_ra8_rsip_wrapped_max_total bytes.; raw_priv_or_pub is large enough for curve.

Postcondition: On success, installed_key_buf holds a valid wrapped blob.

Note: Thread safety: not thread-safe.

See also: ra8_rsip_protected_ecdsa_sign

Since: 0.1.0

Definition at line 577 of file ra8_rsip_key_injection.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_key_inject_rsa()

ra8_err_t ra8_rsip_key_inject_rsa	(	uint8_t *	installed_key_buf,
		const uint8_t *	raw_modulus,
		const uint8_t *	raw_exponent,
		ra8_rsip_rsa_size_t	size )

nodiscard

Wrap a raw RSA key (modulus + exponent) into the installed-key format.

The payload layout is [modulus | 4-byte exponent]. Both private and public RSA blobs share this representation and are differentiated only by the leading type tag (private blobs use k_ra8_rsip_wrapped_type_rsa_priv).

Parameters

[out]	installed_key_buf	Destination (k_ra8_rsip_wrapped_max_total).
[in]	raw_modulus	Big-endian modulus bytes (size / 8 long).
[in]	raw_exponent	Big-endian exponent bytes (4 bytes for public e; truncated to 4 for the stub).
[in]	size	RSA modulus width.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Blob written.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_invalid_arg	Unsupported size.

Precondition: installed_key_buf is k_ra8_rsip_wrapped_max_total bytes.; raw_modulus is size / 8 bytes.; raw_exponent is at least 4 bytes.

Postcondition: On success, installed_key_buf holds a valid wrapped blob.

Note: Thread safety: not thread-safe.

See also: ra8_rsip_protected_rsa_decrypt

Since: 0.1.0

Definition at line 565 of file ra8_rsip_key_injection.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_key_validate()

ra8_err_t ra8_rsip_key_validate	(	const uint8_t *	installed_key_buf,
		ra8_rsip_wrapped_key_type_t	expected_type )

nodiscard

Validate that a wrapped-key blob has the expected structure and a matching trailing MAC.

Parses the leading type tag, recomputes the MAC over [type | mgmt-info | payload] using the same xorshift mixer the inject path used, and returns k_ra8_ok only if it matches. Any single-byte tamper in the blob causes the recomputed MAC to diverge.

Parameters

[in]	installed_key_buf	Wrapped blob.
[in]	expected_type	Expected type tag.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Blob is well-formed and MAC matches.
k_ra8_err_null_ptr	installed_key_buf was NULL.
k_ra8_err_invalid_arg	Type tag mismatched.
k_ra8_err_hw_error	Trailing MAC mismatched.

Precondition: installed_key_buf is at least k_ra8_rsip_wrapped_max_total long.

Postcondition: No state changes.

Note: Thread safety: not thread-safe.

Since: 0.1.0

Definition at line 589 of file ra8_rsip_key_injection.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rsa_validate_wrapped(), ra8_rsip_protected_aes_init(), and ra8_rsip_protected_ecdsa_sign().

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ ra8_rsip_aes_key_bits_t

◆ ra8_rsip_wrapped_key_const_t

◆ ra8_rsip_wrapped_key_type_t

Function Documentation

◆ ra8_rsip_key_inject_aes()

◆ ra8_rsip_key_inject_ecc()

◆ ra8_rsip_key_inject_rsa()

◆ ra8_rsip_key_validate()