RSIP-E50D symmetric cipher + wrapped-key install path. More...

#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_internal.h"
#include "ra8_rsip_regs.h"

Include dependency graph for ra8_rsip_cipher.c:

Functions
uint32_t	priv_pack_le (const uint8_t *p)
	Pack 4 little-endian bytes into a uint32_t.
void	priv_unpack_le (uint32_t word, uint8_t *p)
	Unpack a uint32_t into 4 little-endian bytes.
uint32_t	priv_handle_words_for (ra8_rsip_oem_cmd_t cmd)
	Map an OEM opcode to the wrapped-key body word count.
ra8_err_t	priv_complete (uint32_t done_mask)
	Drive a single mailbox completion (DONE poll + ack).
void	priv_push_bytes_to_port (ra8_rsip_off_t off, const uint8_t *in, uint32_t len)
	Implementation of priv_push_bytes_to_port() – LE word stream + zero-padded tail.
void	priv_push_iv_lanes (ra8_rsip_off_t base, const uint8_t *iv, uint32_t iv_len)
	Implementation of priv_push_iv_lanes() – bounded 4-lane LE IV window writer.
void	priv_push_handle_body (const ra8_rsip_key_handle_t *handle)
	Implementation of priv_push_handle_body() – KEY_STAGE body word stream.
void	priv_load_handle (const ra8_rsip_key_handle_t *handle)
	Stream a wrapped-key body into the engine input FIFO.
uint8_t	priv_aes_alg_byte (uint32_t alg)
	Pick the AES algorithm byte that matches the wrapped key.
ra8_err_t	ra8_rsip_aes128_install_plain (const uint8_t key, ra8_rsip_key_handle_t out)
	Wrap a 16-byte AES-128 key for use by the engine.
ra8_err_t	ra8_rsip_aes192_install_plain (const uint8_t key, ra8_rsip_key_handle_t out)
	Wrap a 24-byte AES-192 key (see ra8_rsip_aes128_install_plain).
ra8_err_t	ra8_rsip_aes256_install_plain (const uint8_t key, ra8_rsip_key_handle_t out)
	Wrap a 32-byte AES-256 key (see ra8_rsip_aes128_install_plain).
ra8_err_t	ra8_rsip_chacha20_install_plain (const uint8_t key, ra8_rsip_key_handle_t out)
	Wrap a 32-byte ChaCha20 key.
ra8_err_t	ra8_rsip_hmac_install_plain (ra8_rsip_oem_cmd_t alg, const uint8_t key, uint32_t key_len, ra8_rsip_key_handle_t out)
	Wrap an HMAC key for use by the HMAC engine.
ra8_err_t	ra8_rsip_oem_install (ra8_rsip_oem_cmd_t cmd, const uint8_t iv, const uint8_t oem_blob, uint32_t blob_len, ra8_rsip_key_handle_t *out)
	Install an OEM-encrypted key blob into the wrapped vault.
ra8_err_t	ra8_rsip_aes_cipher (const ra8_rsip_key_handle_t key, ra8_rsip_aes_mode_t mode, ra8_rsip_aes_dir_t dir, const uint8_t iv, const uint8_t in, uint8_t out, uint32_t len)
	Encrypt or decrypt a buffer with AES in a non-AEAD mode.
ra8_err_t	ra8_rsip_aes_gcm (const ra8_rsip_key_handle_t key, ra8_rsip_aes_dir_t dir, const uint8_t iv, const uint8_t aad, uint32_t aad_len, const uint8_t in, uint8_t out, uint32_t in_len, uint8_t tag)
	AES-GCM encrypt or decrypt with associated data.
ra8_err_t	ra8_rsip_aes_ccm (const ra8_rsip_key_handle_t key, ra8_rsip_aes_dir_t dir, const uint8_t iv, const uint8_t aad, uint32_t aad_len, const uint8_t in, uint8_t out, uint32_t in_len, uint8_t tag)
	AES-CCM encrypt or decrypt with associated data.
ra8_err_t	ra8_rsip_chacha20 (const ra8_rsip_key_handle_t key, ra8_rsip_aes_dir_t dir, const uint8_t nonce, uint32_t counter, const uint8_t in, uint8_t out, uint32_t len)
	ChaCha20 stream encrypt or decrypt (RFC 7539, no AEAD).
ra8_err_t	ra8_rsip_chacha20_poly1305 (const ra8_rsip_key_handle_t key, ra8_rsip_aes_dir_t dir, const uint8_t nonce, const uint8_t aad, uint32_t aad_len, const uint8_t in, uint8_t out, uint32_t in_len, uint8_t tag)
	ChaCha20-Poly1305 AEAD encrypt or decrypt (RFC 7539).
ra8_err_t	ra8_rsip_poly1305 (const uint8_t one_time_key, const uint8_t msg, uint32_t msg_len, uint8_t *tag)
	Poly1305 MAC over a buffer using a 32-byte one-time key.

Variables
static const char *	s_tag = "RSIP"
	Logger tag used by every ra8_log_* call in this TU.

Detailed Description

RSIP-E50D symmetric cipher + wrapped-key install path.

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

Symmetric-cipher and key-install slice of the RA8D2 RSIP-E50D HAL driver, split out of ra8_rsip.c to keep every translation unit under the file-size budget. Covers HUM Ch 51 (Security Features p 3263-3301) + Ch 52 (RSIP-E50D mailbox p 3302-3307) for:

the round-3 little-endian byte-packing primitives and the mailbox completion driver shared with the asymmetric path;
wrapped-key install (plaintext + OEM (PE5/PE6) flows);
symmetric AES (ECB / CBC / CTR / GCM / CCM / XTS / CMAC / GMAC) for both encrypt and decrypt;
ChaCha20 + Poly1305 (stream + AEAD + standalone MAC).

The key-install and cipher / AEAD / MAC entry points are FAIL-CLOSED in production: HUM Ch 52 documents no symmetric command-register map for the RSIP-E50D, so the off-target-only command path is gated behind the stub-crypto guard and a production build returns k_ra8_err_not_supported. The shipping symmetric crypto is tf-psa-crypto on the M85. NetX Crypto is linked with its own built-in software AES / SHA-256 (there is no RSIP ALT shim), so no NetX consumer depends on this fail-closed path (issue #214).

Cross-TU primitives shared with ra8_rsip.c and ra8_rsip_asym.c are declared in ra8_rsip_internal.h and remain compiled in every build. The RSIP engine exposes no documented symmetric register interface (HUM Ch 52 is a feature overview, p 3302-3307), so the fake command path here is a modelled fiction, not a real hardware sequence.

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

Since: 0.1.0

Definition in file ra8_rsip_cipher.c.

Function Documentation

◆ priv_aes_alg_byte()

uint8_t priv_aes_alg_byte ( uint32_t alg )

Pick the AES algorithm byte that matches the wrapped key.

Defined in ra8_rsip_cipher.c; shared with the key wrap / unwrap entry points in ra8_rsip_asym.c (KEK validation).

Parameters

[in] alg Wrapped-key install opcode (ra8_rsip_oem_cmd_t value).

Returns: AES algorithm selector byte, or 0 for a non-AES key.

Return values

0	Key is not an AES key.

Precondition: alg is a ra8_rsip_oem_cmd_t value.; Caller treats 0 as "not an AES key".

Postcondition: No state modified.; Result selects the symmetric AES variant.

Note: Internal helper.

Since: 0.1.0

Definition at line 204 of file ra8_rsip_cipher.c.

References k_ra8_rsip_oem_cmd_aes128, k_ra8_rsip_oem_cmd_aes192, k_ra8_rsip_oem_cmd_aes256, k_ra8_rsip_sym_alg_aes128, k_ra8_rsip_sym_alg_aes192, and k_ra8_rsip_sym_alg_aes256.

◆ priv_complete()

ra8_err_t priv_complete ( uint32_t done_mask )

Drive a single mailbox completion (DONE poll + ack).

Pre-asserts the DONE bit so the host fake spin terminates, waits on it, reads MBOX_RET (non-zero indicates an engine-side error), then W1C-acks the completion bit. Defined in ra8_rsip_cipher.c; shared with the asymmetric / key-management entry points in ra8_rsip_asym.c.

Parameters

[in] done_mask Completion bit mask to poll and acknowledge.

Returns: k_ra8_ok on success; an error otherwise.

Return values

k_ra8_ok	Operation completed successfully.
k_ra8_err_hw_timeout	Completion bit never observed.
k_ra8_err_hw_error	MBOX_RET was non-zero.

Precondition: A mailbox command has been issued.; done_mask is non-zero.

Postcondition: On k_ra8_ok, done_mask has been acknowledged.; On error, the engine result is reported to the caller.

Note: Internal helper.

Since: 0.1.0

Definition at line 131 of file ra8_rsip_cipher.c.

References k_ra8_err_hw_error, k_ra8_ok, k_ra8_rsip_off_isr, k_ra8_rsip_off_mbox_ret, priv_wait_bit(), and ra8_rsip_reg32().

◆ priv_handle_words_for()

uint32_t priv_handle_words_for ( ra8_rsip_oem_cmd_t cmd )

Map an OEM opcode to the wrapped-key body word count.

Handle-body sizes mirror FSP r_rsip_key_injection.c. Defined in ra8_rsip_cipher.c; shared with the unwrap path in ra8_rsip_asym.c.

Parameters

[in] cmd OEM install / handle opcode.

Returns: Body word count, or 0 for an unsupported opcode.

Return values

0	Unsupported / invalid opcode.

Precondition: cmd is one of ra8_rsip_oem_cmd_t.; Caller treats 0 as "unsupported".

Postcondition: No state modified.; Result is the wrapped-body length for cmd.

Note: Internal helper.

Since: 0.1.0

Definition at line 83 of file ra8_rsip_cipher.c.

◆ priv_load_handle()

void priv_load_handle ( const ra8_rsip_key_handle_t * handle )

Stream a wrapped-key body into the engine input FIFO.

Publishes handle->alg to SYM_KEYH then streams the wrapped body via priv_push_handle_body. A NULL handle is a no-op. Defined in ra8_rsip_cipher.c; shared with every key-touching asymmetric entry point in ra8_rsip_asym.c.

Parameters

[in] handle Source handle, or NULL.

Precondition: Either handle is NULL or handle->body_words is valid.; The engine is idle and ready to latch a key handle.

Postcondition: On a non-NULL handle, SYM_KEYH carries handle->alg.; On a non-NULL handle, the body words have been streamed.

Note: Internal helper.

Since: 0.1.0

Definition at line 194 of file ra8_rsip_cipher.c.

References ra8_rsip_key_handle_t::alg, k_ra8_rsip_off_sym_keyh, priv_push_handle_body(), and ra8_rsip_reg32().

◆ priv_pack_le()

uint32_t priv_pack_le ( const uint8_t * p )

Pack 4 little-endian bytes into a uint32_t.

Used by the RSIP register-port writers when streaming key material, IVs, and message blocks into the engine. Defined in ra8_rsip_cipher.c; shared with ra8_rsip.c and ra8_rsip_asym.c.

Parameters

[in] p Source byte pointer.

Returns: Packed little-endian 32-bit word.

Return values

value Packed word built from p[0..3] in LE order.

Precondition: p is non-NULL and points to at least 4 readable bytes.; Caller has ensured p is correctly aligned for the architecture.

Postcondition: No caller-visible side effects beyond returning the packed word.; The 4 source bytes are unmodified.

Note: Internal helper.

Since: 0.1.0

Definition at line 68 of file ra8_rsip_cipher.c.

References k_ra8_rsip_byte_bits, k_ra8_rsip_byte_shift_2, and k_ra8_rsip_byte_shift_3.

Referenced by priv_push_bytes_to_port().

◆ priv_push_bytes_to_port()

void priv_push_bytes_to_port	(	ra8_rsip_off_t	off,
		const uint8_t *	in,
		uint32_t	len )

Implementation of priv_push_bytes_to_port() – LE word stream + zero-padded tail.

Stream a variable-length byte buffer into a single fixed MMIO port.

Definition at line 150 of file ra8_rsip_cipher.c.

References k_ra8_rsip_byte_bits, k_ra8_rsip_trng_word_bytes, priv_pack_le(), and ra8_rsip_reg32().

◆ priv_push_handle_body()

void priv_push_handle_body ( const ra8_rsip_key_handle_t * handle )

Implementation of priv_push_handle_body() – KEY_STAGE body word stream.

Stream a wrapped key body into the staging port.

Definition at line 187 of file ra8_rsip_cipher.c.

References ra8_rsip_key_handle_t::body, ra8_rsip_key_handle_t::body_words, k_ra8_rsip_off_key_stage, and ra8_rsip_reg32().

Referenced by priv_load_handle().

◆ priv_push_iv_lanes()

void priv_push_iv_lanes	(	ra8_rsip_off_t	base,
		const uint8_t *	iv,
		uint32_t	iv_len )

Implementation of priv_push_iv_lanes() – bounded 4-lane LE IV window writer.

Push a bounded IV / nonce into 4 consecutive 32-bit lanes.

Definition at line 168 of file ra8_rsip_cipher.c.

References k_ra8_rsip_byte_bits, k_ra8_rsip_iv_words, k_ra8_rsip_trng_word_bytes, k_ra8_rsip_word_shift, and ra8_rsip_reg32().

◆ priv_unpack_le()

void priv_unpack_le	(	uint32_t	word,
		uint8_t *	p )

Unpack a uint32_t into 4 little-endian bytes.

Inverse of priv_pack_le. Used by the RSIP digest / key-output port readers to materialise byte buffers from the engine's word-addressed result registers. Defined in ra8_rsip_cipher.c; shared with ra8_rsip.c and ra8_rsip_asym.c.

Parameters

[in]	word	Little-endian 32-bit word to split.
[out]	p	Destination 4-byte buffer.

Precondition: p is non-NULL and points to at least 4 writable bytes.; Caller owns the destination buffer for the duration of the call.

Postcondition: p[0..3] reflect word in little-endian byte order.; No state outside the destination buffer is modified.

Note: Internal helper.

Since: 0.1.0

Definition at line 75 of file ra8_rsip_cipher.c.

References k_ra8_rsip_byte_bits, k_ra8_rsip_byte_mask, k_ra8_rsip_byte_shift_2, and k_ra8_rsip_byte_shift_3.

◆ ra8_rsip_aes128_install_plain()

ra8_err_t ra8_rsip_aes128_install_plain	(	const uint8_t *	key,
		ra8_rsip_key_handle_t *	out )

nodiscard

Wrap a 16-byte AES-128 key for use by the engine.

Streams the plaintext key through the OEM key-install primitive (FSP R_RSIP_AES128_InitialKeyWrap p r_rsip_key_injection.c) and returns the wrapped handle. The plaintext bytes are pushed directly into the engine input FIFO and never copied into a static buffer.

Parameters

[in]	key	Plaintext AES-128 key (16 bytes).
[out]	out	Wrapped handle.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	key or out was nullptr.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: key is non-NULL and 16-byte readable.; out is non-NULL.

Postcondition: On success, out->alg == k_ra8_rsip_oem_cmd_aes128.; On success, out->body_words == k_ra8_rsip_handle_words_aes128.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

See also: ra8_rsip_aes192_install_plain

Since: 0.1.0

Definition at line 762 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_p_aes_install().

◆ ra8_rsip_aes192_install_plain()

ra8_err_t ra8_rsip_aes192_install_plain	(	const uint8_t *	key,
		ra8_rsip_key_handle_t *	out )

nodiscard

Wrap a 24-byte AES-192 key (see ra8_rsip_aes128_install_plain).

Parameters

[in]	key	Plaintext AES-192 key (24 bytes).
[out]	out	Wrapped handle.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	key or out was nullptr.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: key is non-NULL and 24-byte readable.; out is non-NULL.

Postcondition: out->alg == k_ra8_rsip_oem_cmd_aes192.; out->body_words == k_ra8_rsip_handle_words_aes192.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 769 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_p_aes_install().

◆ ra8_rsip_aes256_install_plain()

ra8_err_t ra8_rsip_aes256_install_plain	(	const uint8_t *	key,
		ra8_rsip_key_handle_t *	out )

nodiscard

Wrap a 32-byte AES-256 key (see ra8_rsip_aes128_install_plain).

Parameters

[in]	key	Plaintext AES-256 key (32 bytes).
[out]	out	Wrapped handle.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	key or out was nullptr.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: key is non-NULL and 32-byte readable.; out is non-NULL.

Postcondition: out->alg == k_ra8_rsip_oem_cmd_aes256.; out->body_words == k_ra8_rsip_handle_words_aes256.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 776 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_p_aes_install().

◆ ra8_rsip_aes_ccm()

ra8_err_t ra8_rsip_aes_ccm	(	const ra8_rsip_key_handle_t *	key,
		ra8_rsip_aes_dir_t	dir,
		const uint8_t *	iv,
		const uint8_t *	aad,
		uint32_t	aad_len,
		const uint8_t *	in,
		uint8_t *	out,
		uint32_t	in_len,
		uint8_t *	tag )

nodiscard

AES-CCM encrypt or decrypt with associated data.

NIST SP 800-38C. Same surface as ra8_rsip_aes_gcm – the engine handles the L / nonce concatenation internally; the caller supplies a 12-byte nonce for compatibility.

Parameters

[in]	key	Wrapped AES key handle.
[in]	dir	Encrypt / decrypt selector.
[in]	iv	12-byte nonce.
[in]	aad	Additional authenticated data; may be NULL.
[in]	aad_len	aad length.
[in]	in	Plaintext (encrypt) or ciphertext (decrypt).
[out]	out	Ciphertext (encrypt) or plaintext (decrypt).
[in]	in_len	Input length in bytes.
[in,out]	tag	16-byte tag buffer.

Returns: ra8_err_t error code (same set as ra8_rsip_aes_gcm).

Return values

k_ra8_err_not_supported Production build fail-closed; no RSIP backend, use tf-psa-crypto.

Precondition: key->alg is an AES install opcode.; iv is non-NULL.

Postcondition: On encrypt success, tag[0..15] is the authenticator.; On decrypt success, out[0..in_len-1] is plaintext.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 856 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_aes_cipher()

ra8_err_t ra8_rsip_aes_cipher	(	const ra8_rsip_key_handle_t *	key,
		ra8_rsip_aes_mode_t	mode,
		ra8_rsip_aes_dir_t	dir,
		const uint8_t *	iv,
		const uint8_t *	in,
		uint8_t *	out,
		uint32_t	len )

nodiscard

Encrypt or decrypt a buffer with AES in a non-AEAD mode.

Streams the input through DATA_IN0..3 16 bytes at a time and pulls the result from DATA_OUT0..3. The caller is responsible for padding to a 16-byte boundary in modes that require it (ECB, CBC, CMAC); CTR / XTS / GMAC accept partial trailing bytes.

Parameters

[in]	key	Wrapped AES key handle.
[in]	mode	Block / authenticated mode selector.
[in]	dir	Encrypt / decrypt selector.
[in]	iv	IV / counter / tweak (16 bytes); may be NULL for ECB / CMAC.
[in]	in	Input buffer.
[out]	out	Output buffer (>= len bytes).
[in]	len	Number of input bytes.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Buffer transformed.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	Any required pointer was NULL.
k_ra8_err_invalid_arg	mode is an AEAD mode, or len is not a multiple of the block size for ECB / CBC / CMAC.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: key is non-NULL and refers to a wrapped AES handle.; in and out are non-NULL.

Postcondition: On success, out[0..len-1] holds the transformed bytes.; Engine SYM_STATUS.DONE has been observed and acked.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

See also: ra8_rsip_aes_gcm

Since: 0.1.0

Definition at line 816 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_rsip_protected_aes_decrypt(), and ra8_rsip_protected_aes_encrypt().

◆ ra8_rsip_aes_gcm()

ra8_err_t ra8_rsip_aes_gcm	(	const ra8_rsip_key_handle_t *	key,
		ra8_rsip_aes_dir_t	dir,
		const uint8_t *	iv,
		const uint8_t *	aad,
		uint32_t	aad_len,
		const uint8_t *	in,
		uint8_t *	out,
		uint32_t	in_len,
		uint8_t *	tag )

nodiscard

AES-GCM encrypt or decrypt with associated data.

NIST SP 800-38D (HUM Ch 52.1 Table 52.1 "GCM" p 3302). On encrypt, tag is filled with the 16-byte authenticator; on decrypt, the tag passed in is compared and the routine returns k_ra8_err_hw_error if the comparison fails.

Parameters

[in]	key	Wrapped AES key handle.
[in]	dir	Encrypt / decrypt selector.
[in]	iv	12-byte nonce.
[in]	aad	Additional authenticated data; may be NULL.
[in]	aad_len	aad length.
[in]	in	Plaintext (encrypt) or ciphertext (decrypt).
[out]	out	Ciphertext (encrypt) or plaintext (decrypt).
[in]	in_len	Input length in bytes.
[in,out]	tag	16-byte tag buffer (output on encrypt, input on decrypt).

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	key, iv, in, out or tag was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Decrypt-side tag comparison failed.

Precondition: key->alg is an AES install opcode.; iv is non-NULL.

Postcondition: On encrypt success, tag[0..15] is the authenticator.; On decrypt success, out[0..in_len-1] is plaintext.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 834 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_chacha20()

ra8_err_t ra8_rsip_chacha20	(	const ra8_rsip_key_handle_t *	key,
		ra8_rsip_aes_dir_t	dir,
		const uint8_t *	nonce,
		uint32_t	counter,
		const uint8_t *	in,
		uint8_t *	out,
		uint32_t	len )

nodiscard

ChaCha20 stream encrypt or decrypt (RFC 7539, no AEAD).

Parameters

[in]	key	Wrapped ChaCha20 key handle.
[in]	dir	Encrypt / decrypt selector.
[in]	nonce	12-byte nonce.
[in]	counter	Initial 32-bit block counter.
[in]	in	Input buffer.
[out]	out	Output buffer (>= len bytes).
[in]	len	Input length in bytes.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: key->alg == k_ra8_rsip_oem_cmd_chacha20.; nonce is non-NULL.

Postcondition: On success, out[0..len-1] holds the transformed bytes.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 878 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_chacha20_install_plain()

ra8_err_t ra8_rsip_chacha20_install_plain	(	const uint8_t *	key,
		ra8_rsip_key_handle_t *	out )

nodiscard

Wrap a 32-byte ChaCha20 key.

Parameters

[in]	key	Plaintext ChaCha20 key (32 bytes).
[out]	out	Wrapped handle.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	key or out was nullptr.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: key is non-NULL and 32-byte readable.; out is non-NULL.

Postcondition: out->alg == k_ra8_rsip_oem_cmd_chacha20.; out->body_words == k_ra8_rsip_handle_words_chacha20.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 783 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_chacha20_poly1305()

ra8_err_t ra8_rsip_chacha20_poly1305	(	const ra8_rsip_key_handle_t *	key,
		ra8_rsip_aes_dir_t	dir,
		const uint8_t *	nonce,
		const uint8_t *	aad,
		uint32_t	aad_len,
		const uint8_t *	in,
		uint8_t *	out,
		uint32_t	in_len,
		uint8_t *	tag )

nodiscard

ChaCha20-Poly1305 AEAD encrypt or decrypt (RFC 7539).

Parameters

[in]	key	Wrapped ChaCha20 key handle.
[in]	dir	Encrypt / decrypt selector.
[in]	nonce	12-byte nonce.
[in]	aad	Additional authenticated data; may be NULL.
[in]	aad_len	aad length in bytes.
[in]	in	Plaintext (encrypt) or ciphertext (decrypt).
[out]	out	Ciphertext (encrypt) or plaintext (decrypt).
[in]	in_len	Input length in bytes.
[in,out]	tag	16-byte Poly1305 tag.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Operation succeeded.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	Any required pointer was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Decrypt-side tag check failed.

Precondition: key->alg == k_ra8_rsip_oem_cmd_chacha20.; nonce, in, out, tag are non-NULL.

Postcondition: On encrypt success, tag[0..15] is the Poly1305 MAC.; On decrypt success, out[0..in_len-1] is plaintext.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 896 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_hmac_install_plain()

ra8_err_t ra8_rsip_hmac_install_plain	(	ra8_rsip_oem_cmd_t	alg,
		const uint8_t *	key,
		uint32_t	key_len,
		ra8_rsip_key_handle_t *	out )

nodiscard

Wrap an HMAC key for use by the HMAC engine.

The wrapped-key body size depends on the underlying SHA flavour; the selector is derived from alg. HUM Ch 52 documents no HMAC key-wrap register map (issue #215); production is fail-closed.

Parameters

[in]	alg	One of k_ra8_rsip_oem_cmd_hmac_sha*.
[in]	key	Plaintext HMAC key.
[in]	key_len	key length in bytes.
[out]	out	Wrapped handle.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_invalid_arg	alg not in the HMAC range, or key_len is zero.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: alg is a HMAC opcode.; key is non-NULL and key_len bytes readable.

Postcondition: On success out->alg == alg.; On success out->body_words matches the algo's handle size.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 790 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

◆ ra8_rsip_oem_install()

ra8_err_t ra8_rsip_oem_install	(	ra8_rsip_oem_cmd_t	cmd,
		const uint8_t *	iv,
		const uint8_t *	oem_blob,
		uint32_t	blob_len,
		ra8_rsip_key_handle_t *	out )

nodiscard

Install an OEM-encrypted key blob into the wrapped vault.

Drives the OEM (PE5/PE6) install primitive used during factory provisioning: the plaintext key has already been encrypted under the OEM root key and is delivered as oem_blob; the engine unwraps it inside the secure boundary and returns a vault-wrapped handle (FSP r_rsip_key_injection.c – InitialKeyWrap family).

Parameters

[in]	cmd	OEM opcode (algorithm + key length selector).
[in]	iv	16-byte install IV.
[in]	oem_blob	OEM-encrypted body.
[in]	blob_len	oem_blob length in bytes.
[out]	out	Wrapped handle.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Handle filled.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_invalid_arg	Unknown cmd or blob_len zero.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Engine reported a verification fail.

Precondition: cmd != k_ra8_rsip_oem_cmd_invalid.; iv, oem_blob and out are non-NULL.

Postcondition: On success out->alg == cmd.; On success out->body_words matches the algo's handle size.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 802 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by internal_rsa_install_priv().

◆ ra8_rsip_poly1305()

ra8_err_t ra8_rsip_poly1305	(	const uint8_t *	one_time_key,
		const uint8_t *	msg,
		uint32_t	msg_len,
		uint8_t *	tag )

nodiscard

Poly1305 MAC over a buffer using a 32-byte one-time key.

Parameters

[in]	one_time_key	32-byte Poly1305 key (derived per message).
[in]	msg	Buffer to authenticate.
[in]	msg_len	Length of msg in bytes.
[out]	tag	16-byte tag output.

Returns: ra8_err_t error code.

Return values

k_ra8_ok	Tag computed.
k_ra8_err_not_supported	Production build fail-closed; no RSIP backend, use tf-psa-crypto.
k_ra8_err_null_ptr	Any pointer was NULL.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition: one_time_key is non-NULL and 32-byte readable.; tag is non-NULL.

Postcondition: On success, tag[0..15] is the Poly1305 MAC.

Note: Thread safety: not thread-safe.; Fail-closed in production (HUM Ch 52 documents no RSIP backend); the fake/stub command path never ships. Real crypto: tf-psa-crypto (issues #214 / #187 / #181).

Since: 0.1.0

Definition at line 919 of file ra8_rsip_cipher.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Variable Documentation

◆ s_tag

const char* s_tag = "RSIP"

static

Logger tag used by every ra8_log_* call in this TU.

Kept short ("RSIP") so it fits in the fixed-width log prefix without truncation. Each RSIP translation unit keeps its own private copy.

Note: Static, file-scope.

Since: 0.1.0

Definition at line 61 of file ra8_rsip_cipher.c.

Functions

Variables

Detailed Description

Function Documentation

◆ priv_aes_alg_byte()

◆ priv_complete()

◆ priv_handle_words_for()

◆ priv_load_handle()

◆ priv_pack_le()

◆ priv_push_bytes_to_port()

◆ priv_push_handle_body()

◆ priv_push_iv_lanes()

◆ priv_unpack_le()

◆ ra8_rsip_aes128_install_plain()

◆ ra8_rsip_aes192_install_plain()

◆ ra8_rsip_aes256_install_plain()

◆ ra8_rsip_aes_ccm()

◆ ra8_rsip_aes_cipher()

◆ ra8_rsip_aes_gcm()

◆ ra8_rsip_chacha20()

◆ ra8_rsip_chacha20_install_plain()

◆ ra8_rsip_chacha20_poly1305()

◆ ra8_rsip_hmac_install_plain()

◆ ra8_rsip_oem_install()

◆ ra8_rsip_poly1305()

Variable Documentation

◆ s_tag