ra8_rsip_keys.h File Reference

Renesas Secure IP (RSIP-E50D) HAL – key install + cipher / hash API. More...

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

Include dependency graph for ra8_rsip_keys.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_rsip_key_handle_t
	Opaque wrapped-key handle. More...

Functions
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.
ra8_err_t	ra8_rsip_hash (ra8_rsip_hash_alg_t alg, const uint8_t *msg, uint32_t msg_len, uint8_t *digest, uint32_t digest_len)
	Compute a hash of an in-memory buffer using the selected algorithm.
ra8_err_t	ra8_rsip_hmac (const ra8_rsip_key_handle_t *key, const uint8_t *msg, uint32_t msg_len, uint8_t *mac, uint32_t mac_len)
	HMAC-SHA-2 / HMAC-SHA-3 over a buffer using a wrapped key.
ra8_err_t	ra8_rsip_rsa_sign (const ra8_rsip_key_handle_t *key, ra8_rsip_rsa_size_t size, const uint8_t *digest, uint32_t digest_len, uint8_t *signature)
	RSA sign a digest with a wrapped private key.
ra8_err_t	ra8_rsip_rsa_verify (const ra8_rsip_key_handle_t *key, ra8_rsip_rsa_size_t size, const uint8_t *digest, uint32_t digest_len, const uint8_t *signature)
	RSA verify a signature against a digest using a wrapped pubkey.
ra8_err_t	ra8_rsip_rsa_encrypt (const ra8_rsip_key_handle_t *key, ra8_rsip_rsa_size_t size, ra8_rsip_rsa_pad_t pad, const uint8_t *plaintext, uint32_t plaintext_len, uint8_t *ciphertext)
	RSA public-key encrypt a short message (RSAES-OAEP / PKCS1).
ra8_err_t	ra8_rsip_rsa_decrypt (const ra8_rsip_key_handle_t *key, ra8_rsip_rsa_size_t size, ra8_rsip_rsa_pad_t pad, const uint8_t *ciphertext, uint8_t *plaintext, uint32_t plaintext_cap, uint32_t *recovered_len)
	RSA private-key decrypt a ciphertext (RSAES-OAEP / PKCS1).
ra8_err_t	ra8_rsip_ecdsa_sign (const ra8_rsip_key_handle_t *key, ra8_rsip_curve_t curve, const uint8_t *digest, uint32_t digest_len, uint8_t *signature)
	ECDSA sign a digest with a wrapped private key.
ra8_err_t	ra8_rsip_ecdsa_verify (const ra8_rsip_key_handle_t *key, ra8_rsip_curve_t curve, const uint8_t *digest, uint32_t digest_len, const uint8_t *signature)
	ECDSA verify a signature with a peer public key.
ra8_err_t	ra8_rsip_eddsa_sign (const ra8_rsip_key_handle_t *key, const uint8_t *msg, uint32_t msg_len, uint8_t *signature)
	Ed25519 PureEdDSA sign a message (RFC 8032).
ra8_err_t	ra8_rsip_eddsa_verify (const ra8_rsip_key_handle_t *key, const uint8_t *msg, uint32_t msg_len, const uint8_t *signature)
	Ed25519 PureEdDSA verify a signature (RFC 8032).
ra8_err_t	ra8_rsip_ecdh_compute (const ra8_rsip_key_handle_t *key, ra8_rsip_curve_t curve, const uint8_t *peer_x, const uint8_t *peer_y, ra8_rsip_key_handle_t *out)
	ECDH shared-secret derivation.

Detailed Description

Renesas Secure IP (RSIP-E50D) HAL – key install + cipher / hash API.

Tag

[Ring 3 / HAL] {World: S}

Key-touching surface of the RA8D2 RSIP-E50D HAL split out of the ra8_rsip.h umbrella. This sub-header owns the opaque wrapped-key handle type, the plaintext + OEM key-install flows, the AES block / authenticated cipher modes, ChaCha20 + Poly1305, the generic SHA-2 / SHA-3 / SHAKE hash family + HMAC, and the asymmetric RSA / ECDSA / ECDH primitives.

Every key-touching API takes opaque ra8_rsip_key_handle_t blobs – raw key bytes never leave secure RAM. The mailbox-driven peripheral is documented in HUM Ch 52 "Renesas Secure IP (RSIP-E50D)" p 3302-3307; cross-references to the broader security feature set live in HUM Ch 51 "Security Features" p 3263-3301.

Copyright

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

Since

0.1.0

Definition in file ra8_rsip_keys.h.

Function Documentation

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

ra8_err_t ra8_rsip_ecdh_compute ( const ra8_rsip_key_handle_t * key, ra8_rsip_curve_t curve, const uint8_t * peer_x, const uint8_t * peer_y, ra8_rsip_key_handle_t * out )

nodiscard

ECDH shared-secret derivation.

The peer public key is supplied as the uncompressed (X || Y) coordinate pair. The shared secret stays inside the wrapped vault and out receives a wrapped handle suitable for ra8_rsip_kdf.

Parameters

[in]	key	Wrapped ECC private-key handle (own).
[in]	curve	Curve selector.
[in]	peer_x	Peer X coordinate (curve byte length).
[in]	peer_y	Peer Y coordinate (curve byte length).
[out]	out	Wrapped shared-secret handle.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Shared secret derived.
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	Bad curve.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Peer point off-curve.

Precondition

key->alg is an ECC private install opcode.

peer_x and peer_y are non-NULL.

Postcondition

On success out->alg matches the curve's HMAC opcode.

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 392 of file ra8_rsip_ecc.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_ecdsa_sign()

ra8_err_t ra8_rsip_ecdsa_sign ( const ra8_rsip_key_handle_t * key, ra8_rsip_curve_t curve, const uint8_t * digest, uint32_t digest_len, uint8_t * signature )

nodiscard

ECDSA sign a digest with a wrapped private key.

Parameters

[in]	key	Wrapped ECC private-key handle.
[in]	curve	Curve selector.
[in]	digest	Pre-computed message digest.
[in]	digest_len	Digest length.
[out]	signature	Output (r || s); 64 bytes for P-256, 96 for P-384, 132 for P-521.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Signature produced.
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	Bad curve, or curve is k_ra8_rsip_curve_ed25519 (use ra8_rsip_eddsa_sign – Ed25519 is PureEdDSA, not ECDSA).
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

key->alg is an ECC (Weierstrass-curve) install opcode.

digest and signature are non-NULL.

Postcondition

On success, signature holds (r || s).

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

Ed25519 is rejected here; route it through ra8_rsip_eddsa_sign.

See also

ra8_rsip_eddsa_sign

Since

0.1.0

Definition at line 340 of file ra8_rsip_ecc.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_rsip_protected_ecdsa_sign().

ra8_rsip_ecdsa_verify()

ra8_err_t ra8_rsip_ecdsa_verify ( const ra8_rsip_key_handle_t * key, ra8_rsip_curve_t curve, const uint8_t * digest, uint32_t digest_len, const uint8_t * signature )

nodiscard

ECDSA verify a signature with a peer public key.

Parameters

[in]	key	Wrapped ECC public-key handle (or the peer's raw uncompressed point staged through ASYM_PUB_X/ASYM_PUB_Y).
[in]	curve	Curve selector.
[in]	digest	Pre-computed digest.
[in]	digest_len	Digest length.
[in]	signature	Signature (r || s).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Signature valid.
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	Bad curve, or curve is k_ra8_rsip_curve_ed25519 (use ra8_rsip_eddsa_verify).
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Signature did not verify.

Precondition

key->alg is an ECC (Weierstrass-curve) install opcode.

digest and signature are non-NULL.

Postcondition

On success, the engine has validated the signature.

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

Ed25519 is rejected here; route it through ra8_rsip_eddsa_verify.

See also

ra8_rsip_eddsa_verify

Since

0.1.0

Definition at line 354 of file ra8_rsip_ecc.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_eddsa_sign()

ra8_err_t ra8_rsip_eddsa_sign ( const ra8_rsip_key_handle_t * key, const uint8_t * msg, uint32_t msg_len, uint8_t * signature )

nodiscard

Ed25519 PureEdDSA sign a message (RFC 8032).

Ed25519 PureEdDSA (RFC 8032) is NOT backed by a documented RSIP register interface on this silicon – HUM Ch 52 "Renesas Secure IP (RSIP-E50D)" is a feature overview, not a command-register map, and the vendor engine is driven through an encrypted firmware mailbox. A production build (neither RA8_INSECURE_STUB_CRYPTO nor RA8_OFF_TARGET) is therefore FAIL-CLOSED: this entry point returns k_ra8_err_not_supported rather than hand back bytes that no RFC 8032 verifier would accept. The real Ed25519 signer is tf-psa-crypto (PSA_ALG_PURE_EDDSA) on the M85. Only the insecure-stub / off-target build drives a placeholder EdDSA command path (host command-path testing only); PureEdDSA signs the raw message, NOT a pre-computed digest, and the 64-byte output is the R || S encoding.

Parameters

[in]	key	Wrapped Ed25519 private-key handle (k_ra8_rsip_oem_cmd_ecc_ed25519_priv).
[in]	msg	Message to sign; may be NULL only if msg_len is 0.
[in]	msg_len	Message length in bytes.
[out]	signature	64-byte output (R || S); never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Signature produced (stub / off-target build only).
k_ra8_err_not_supported	Production build – Ed25519 has no RSIP backend; use tf-psa-crypto instead.
k_ra8_err_null_ptr	key / signature was NULL, or msg was NULL with non-zero msg_len.
k_ra8_err_invalid_arg	key->alg is not the Ed25519 opcode.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

key->alg == k_ra8_rsip_oem_cmd_ecc_ed25519_priv.

signature is at least 64 bytes wide.

Postcondition

On success, signature[0..63] holds (R || S).

No engine key state persists beyond the call.

Note

Thread safety: not thread-safe.

Fail-closed in production; Ed25519 is provided by tf-psa-crypto.

See also

ra8_rsip_eddsa_verify

Since

0.1.0

Definition at line 368 of file ra8_rsip_ecc.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_eddsa_verify()

ra8_err_t ra8_rsip_eddsa_verify ( const ra8_rsip_key_handle_t * key, const uint8_t * msg, uint32_t msg_len, const uint8_t * signature )

nodiscard

Ed25519 PureEdDSA verify a signature (RFC 8032).

The verify counterpart to ra8_rsip_eddsa_sign and subject to the same constraint: the RSIP-E50D exposes no documented Ed25519 register interface on this silicon, so a production build (neither RA8_INSECURE_STUB_CRYPTO nor RA8_OFF_TARGET) is FAIL-CLOSED and returns k_ra8_err_not_supported. Ed25519 verification is provided by tf-psa-crypto (PSA_ALG_PURE_EDDSA) on the M85. Only the insecure-stub / off-target build drives a placeholder EdDSA command path: the raw message is presented and the 64-byte signature is the R || S encoding.

Parameters

[in]	key	Wrapped Ed25519 public-key handle (tagged with the Ed25519 opcode).
[in]	msg	Message that was signed; may be NULL only if msg_len is 0.
[in]	msg_len	Message length in bytes.
[in]	signature	64-byte signature (R || S); never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Signature valid (stub / off-target build only).
k_ra8_err_not_supported	Production build – Ed25519 has no RSIP backend; use tf-psa-crypto instead.
k_ra8_err_null_ptr	key / signature was NULL, or msg was NULL with non-zero msg_len.
k_ra8_err_invalid_arg	key->alg is not the Ed25519 opcode.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Signature did not verify.

Precondition

key->alg == k_ra8_rsip_oem_cmd_ecc_ed25519_priv.

signature is at least 64 bytes wide.

Postcondition

On success, the engine has validated the signature.

Note

Thread safety: not thread-safe.

Fail-closed in production; Ed25519 is provided by tf-psa-crypto.

See also

ra8_rsip_eddsa_sign

Since

0.1.0

Definition at line 380 of file ra8_rsip_ecc.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_hash()

ra8_err_t ra8_rsip_hash ( ra8_rsip_hash_alg_t alg, const uint8_t * msg, uint32_t msg_len, uint8_t * digest, uint32_t digest_len )

nodiscard

Compute a hash of an in-memory buffer using the selected algorithm.

Generalisation of ra8_rsip_sha256 to every algorithm in ra8_rsip_hash_alg_t. out_len must be at least the digest size for the selected algorithm; for SHAKE-128/256 out_len is the requested XOF length and may be any positive value.

Parameters

[in]	alg	Algorithm selector.
[in]	msg	Message to hash; may be NULL only if msg_len is zero.
[in]	msg_len	Message length in bytes.
[out]	digest	Output buffer.
[in]	digest_len	Output buffer length.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Digest written.
k_ra8_err_null_ptr	digest was NULL, or msg was NULL with non-zero msg_len.
k_ra8_err_invalid_arg	digest_len too small for alg.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

alg is one of k_ra8_rsip_hash_*.

If msg_len > 0, msg is non-NULL.

Postcondition

On success, digest[0..N-1] is the digest where N is the algorithm's natural output size (or digest_len for SHAKE).

HASH_STATUS.DONE has been acked.

Note

Thread safety: not thread-safe.

See also

ra8_rsip_sha256

Since

0.1.0

Definition at line 633 of file ra8_rsip_asym.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_hmac()

ra8_err_t ra8_rsip_hmac ( const ra8_rsip_key_handle_t * key, const uint8_t * msg, uint32_t msg_len, uint8_t * mac, uint32_t mac_len )

nodiscard

HMAC-SHA-2 / HMAC-SHA-3 over a buffer using a wrapped key.

Parameters

[in]	key	Wrapped HMAC key handle.
[in]	msg	Buffer to authenticate.
[in]	msg_len	Length of msg in bytes.
[out]	mac	Output MAC buffer (>= digest size of HMAC's underlying hash).
[in]	mac_len	mac buffer length.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	MAC written.
k_ra8_err_null_ptr	Any required pointer was NULL.
k_ra8_err_invalid_arg	mac_len too small for the algo.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

key->alg is a HMAC opcode.

mac is non-NULL.

Postcondition

On success, mac[0..N-1] is the HMAC.

Note

Thread safety: not thread-safe.

Since

0.1.0

Definition at line 647 of file ra8_rsip_asym.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.

ra8_rsip_rsa_decrypt()

ra8_err_t ra8_rsip_rsa_decrypt ( const ra8_rsip_key_handle_t * key, ra8_rsip_rsa_size_t size, ra8_rsip_rsa_pad_t pad, const uint8_t * ciphertext, uint8_t * plaintext, uint32_t plaintext_cap, uint32_t * recovered_len )

nodiscard

RSA private-key decrypt a ciphertext (RSAES-OAEP / PKCS1).

Drives the RSIP asymmetric engine's private-decrypt opcode (k_ra8_rsip_asym_op_rsa_decrypt): the modulus-width ciphertext is raised to the private exponent and the pad padding is removed inside the secure boundary, leaving the recovered message. The recovered length (shorter than the modulus for OAEP / PKCS1) is reported through recovered_len.

Parameters

[in]	key	Wrapped RSA private-key handle.
[in]	size	RSA modulus selector (1024 / 2048 / 3072 / 4096).
[in]	pad	Padding scheme (OAEP or PKCS1).
[in]	ciphertext	Ciphertext to decrypt (modulus / 8 bytes); never NULL.
[out]	plaintext	Recovered-message buffer; never NULL.
[in]	plaintext_cap	Capacity of plaintext in bytes.
[out]	recovered_len	Receives the recovered-message length; never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Message recovered.
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	Bad size / pad, or recovered message exceeds plaintext_cap.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Padding check failed (corrupt ciphertext).

Precondition

key->alg is an RSA private install opcode.

ciphertext, plaintext and recovered_len are non-NULL.

Postcondition

On success, plaintext[0..*recovered_len-1] is the message.

On success, *recovered_len <= plaintext_cap.

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_rsa_encrypt

Since

0.1.0

Definition at line 408 of file ra8_rsip_rsa.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_rsa_encrypt()

ra8_err_t ra8_rsip_rsa_encrypt ( const ra8_rsip_key_handle_t * key, ra8_rsip_rsa_size_t size, ra8_rsip_rsa_pad_t pad, const uint8_t * plaintext, uint32_t plaintext_len, uint8_t * ciphertext )

nodiscard

RSA public-key encrypt a short message (RSAES-OAEP / PKCS1).

Drives the RSIP asymmetric engine's public-encrypt opcode (k_ra8_rsip_asym_op_rsa_encrypt) so RSA-OAEP key transport works: the plaintext (typically a wrapped content-encryption key) is padded per pad and raised to the public exponent, yielding a modulus-width ciphertext. The engine performs the padding inside the secure boundary; the caller supplies only the raw message bytes.

Parameters

[in]	key	Wrapped RSA public-key handle.
[in]	size	RSA modulus selector (1024 / 2048 / 3072 / 4096).
[in]	pad	Padding scheme (OAEP or PKCS1).
[in]	plaintext	Message to encrypt; never NULL.
[in]	plaintext_len	Message length in bytes; 1 .. modulus / 8.
[out]	ciphertext	Output ciphertext (modulus / 8 bytes); never NULL.

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Ciphertext produced.
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	Bad size / pad, or plaintext_len out of range.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Message too long for the padding scheme.

Precondition

key->alg is an RSA install opcode.

plaintext and ciphertext are non-NULL.

Postcondition

On success, ciphertext[0..modulus_bytes-1] is the RSAES blob.

No engine key state persists beyond the call.

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_rsa_decrypt

Since

0.1.0

Definition at line 392 of file ra8_rsip_rsa.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

ra8_rsip_rsa_sign()

ra8_err_t ra8_rsip_rsa_sign ( const ra8_rsip_key_handle_t * key, ra8_rsip_rsa_size_t size, const uint8_t * digest, uint32_t digest_len, uint8_t * signature )

nodiscard

RSA sign a digest with a wrapped private key.

Parameters

[in]	key	Wrapped RSA private-key handle.
[in]	size	RSA modulus selector (1024 / 2048 / 3072 / 4096).
[in]	digest	Pre-computed message digest.
[in]	digest_len	Digest length in bytes.
[out]	signature	Output signature (modulus / 8 bytes).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Signature produced.
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	Bad size.
k_ra8_err_hw_timeout	Engine never signalled DONE.

Precondition

key->alg is an RSA install opcode.

digest and signature are non-NULL.

Postcondition

On success, signature[0..modulus_bytes-1] is the RSA sig.

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 364 of file ra8_rsip_rsa.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.

Referenced by ra8_rsip_protected_rsa_decrypt().

ra8_rsip_rsa_verify()

ra8_err_t ra8_rsip_rsa_verify ( const ra8_rsip_key_handle_t * key, ra8_rsip_rsa_size_t size, const uint8_t * digest, uint32_t digest_len, const uint8_t * signature )

nodiscard

RSA verify a signature against a digest using a wrapped pubkey.

Parameters

[in]	key	Wrapped RSA public-key handle.
[in]	size	RSA modulus selector.
[in]	digest	Pre-computed message digest.
[in]	digest_len	Digest length.
[in]	signature	Signature (modulus / 8 bytes).

Returns

ra8_err_t error code.

Return values

k_ra8_ok	Signature valid.
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	Bad size.
k_ra8_err_hw_timeout	Engine never signalled DONE.
k_ra8_err_hw_error	Signature did not verify.

Precondition

key->alg is an RSA install opcode.

digest and signature are non-NULL.

Postcondition

On success, the signature has been validated by the engine.

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 378 of file ra8_rsip_rsa.c.

References k_ra8_err_not_supported, RA8_CHECK_NULL_PTR, and s_tag.