RSIP key-injection HAL implementation. More...

#include "ra8_rsip_key_injection.h"
#include <stdint.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_secure.h"

Include dependency graph for ra8_rsip_key_injection.c:

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.

Variables
static const char *	s_tag = "RSIP_KI"
	Logger tag for this TU.

Detailed Description

RSIP key-injection HAL implementation.

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

Software-stub backend for the public API in libs/ra8_hal/inc/ra8_rsip_key_injection.h. Wrapped key blobs are laid out as [type | mgmt-info | payload | mac] and the MAC is computed with the same xorshift mixer ra8_sce_key_injection uses so the round-trip property is preserved across the inject -> protected-op pipeline. Round-tripping under unit tests is the only guarantee made; the wrapping is not cryptographically meaningful and a real backend will replace this entirely.

Warning: Stub backend; NOT cryptographically secure.

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

Definition in file ra8_rsip_key_injection.c.

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

Variable Documentation

◆ s_tag

const char* s_tag = "RSIP_KI"

static

Logger tag for this TU.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 41 of file ra8_rsip_key_injection.c.

Functions

Variables

Detailed Description

Function Documentation

◆ ra8_rsip_key_inject_aes()

◆ ra8_rsip_key_inject_ecc()

◆ ra8_rsip_key_inject_rsa()

◆ ra8_rsip_key_validate()

Variable Documentation

◆ s_tag