ra8_psa_crypto.c File Reference

Implementation of the ra8_psa_crypto facade over TF-PSA-Crypto. More...

#include "ra8_psa_crypto.h"
#include <stddef.h>
#include <stdint.h>
#include <string.h>
#include "ra8_attributes.h"
#include "ra8_check.h"
#include "ra8_err.h"
#include "ra8_log.h"
#include "ra8_psa_crypto_internal.h"
#include "psa/crypto.h"

Include dependency graph for ra8_psa_crypto.c:

Go to the source code of this file.

Functions
static bool	internal_handle_valid (ra8_psa_key_t handle)
static struct ra8_psa_key_handle *	internal_alloc_slot (void)
	Locate the first free slot in the pool.
ra8_err_t	ra8_psa_crypto_init (void)
	One-shot facade initialisation.
ra8_err_t	ra8_psa_crypto_deinit (void)
	Symmetric tear-down for ra8_psa_crypto_init.
static psa_key_type_t	internal_map_key_type (ra8_psa_key_type_t type)
static psa_algorithm_t	internal_map_alg (ra8_psa_alg_t alg)
static psa_key_usage_t	internal_map_usage (ra8_psa_key_usage_t usage)
static ra8_err_t	internal_psa_import_into_slot (struct ra8_psa_key_handle *slot, const ra8_psa_key_attr_t *attr, const uint8_t *data, size_t data_len)
ra8_err_t	ra8_psa_key_import (ra8_psa_key_t *out_handle, const ra8_psa_key_attr_t *attr, const uint8_t *data, size_t data_len)
	Import a raw-byte key into the static pool.
ra8_err_t	ra8_psa_key_destroy (ra8_psa_key_t handle)
	Destroy a previously-imported key.
ra8_err_t	ra8_psa_hash_compute (ra8_psa_alg_t alg, const uint8_t *input, size_t input_len, uint8_t *out, size_t out_cap, size_t *out_len)
	Compute a one-shot SHA-256 digest.
ra8_err_t	ra8_psa_sign_hash (ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t *hash, size_t hash_len, uint8_t *sig, size_t sig_cap, size_t *sig_len)
	Sign a pre-computed hash with a private ECDSA key.
ra8_err_t	ra8_psa_verify_hash (ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t *hash, size_t hash_len, const uint8_t *sig, size_t sig_len)
	Verify an ECDSA signature over a pre-computed hash.
static ra8_err_t	internal_aead_encrypt_check (ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t *nonce, size_t nonce_len, const uint8_t *aad, size_t aad_len, const uint8_t *plain, size_t plain_len, const uint8_t *out, size_t out_cap, const size_t *out_len)
ra8_err_t	ra8_psa_aead_encrypt (ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t *nonce, size_t nonce_len, const uint8_t *aad, size_t aad_len, const uint8_t *plain, size_t plain_len, uint8_t *out, size_t out_cap, size_t *out_len)
	Encrypt + authenticate a buffer with AES-GCM.
static ra8_err_t	internal_aead_decrypt_check (ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t *nonce, size_t nonce_len, const uint8_t *aad, size_t aad_len, const uint8_t *cipher, size_t cipher_len, const uint8_t *out, size_t out_cap, const size_t *out_len, size_t *out_plain_len)
ra8_err_t	ra8_psa_aead_decrypt (ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t *nonce, size_t nonce_len, const uint8_t *aad, size_t aad_len, const uint8_t *cipher, size_t cipher_len, uint8_t *out, size_t out_cap, size_t *out_len)
	Decrypt + verify-tag an AES-GCM buffer.
ra8_err_t	ra8_psa_crypto_random (uint8_t *out, size_t out_len)
	Fill out with cryptographically secure bytes.

Variables
static const char *const	s_ra8_psa_tag = "ra8_psa_crypto"
	Logging tag prefix used by every ra8_psa_crypto log line.
static struct ra8_psa_key_handle	s_key_pool [k_ra8_psa_max_keys]
	Per-handle state pool sized at compile time.
static bool	s_initialized
	One-shot global init flag protecting the pool.

Detailed Description

Implementation of the ra8_psa_crypto facade over TF-PSA-Crypto.

Tag

[Ring 4 / PAL] {World: NS}

Hosts the static key-handle pool and the thin translation layer between PSA Crypto status codes (psa_status_t) and ra8_err_t.

TF-PSA-Crypto is only linked into the firmware build when RA8_USE_MBEDTLS=ON (the same option that pulls in Mbed TLS). The host unit-test build (tests/CMakeLists.txt) defines RA8_OFF_TARGET for every translation unit and intentionally does not link the heavy PSA object library; in that mode this file substitutes a tiny in-memory crypto stand-in:

• SHA-256 is implemented inline (FIPS 180-4 reference algorithm) so ra8_psa_hash_compute can produce real digests in the test suite.
• AES-GCM is replaced by a deterministic XOR-and-checksum cipher that exercises the AEAD contract (ciphertext + tag layout, tag tampering detection) without requiring the real AES core.
• ECDSA sign / verify is replaced by an HMAC-style "signature" that binds (key bytes, hash) and verifies by recomputation. This is not cryptographically secure – it exists only so the round-trip sign+verify test in test_ra8_psa_crypto.c can pass without pulling in P-256.

The public ra8_psa_* surface is identical in either build, so a caller migrating from off-target mode to a real firmware image only has to flip the build flag.

Copyright

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

Definition in file ra8_psa_crypto.c.

Function Documentation

internal_aead_decrypt_check()

ra8_err_t internal_aead_decrypt_check ( ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t * nonce, size_t nonce_len, const uint8_t * aad, size_t aad_len, const uint8_t * cipher, size_t cipher_len, const uint8_t * out, size_t out_cap, const size_t * out_len, size_t * out_plain_len )

static

Definition at line 560 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::attr, internal_handle_valid(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_psa_alg_aes_gcm, k_ra8_psa_gcm_nonce_len, k_ra8_psa_gcm_tag_len, k_ra8_psa_usage_decrypt, RA8_INTERNAL, and s_initialized.

Referenced by ra8_psa_aead_decrypt().

internal_aead_encrypt_check()

ra8_err_t internal_aead_encrypt_check ( ra8_psa_key_t handle, ra8_psa_alg_t alg, const uint8_t * nonce, size_t nonce_len, const uint8_t * aad, size_t aad_len, const uint8_t * plain, size_t plain_len, const uint8_t * out, size_t out_cap, const size_t * out_len )

static

Definition at line 461 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::attr, internal_handle_valid(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_psa_alg_aes_gcm, k_ra8_psa_gcm_nonce_len, k_ra8_psa_gcm_tag_len, k_ra8_psa_usage_encrypt, RA8_INTERNAL, and s_initialized.

Referenced by ra8_psa_aead_encrypt().

internal_alloc_slot()

struct ra8_psa_key_handle * internal_alloc_slot ( void )

static

Locate the first free slot in the pool.

Returns

Slot pointer or NULL when the pool is full.

< Nullptr.

Definition at line 101 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::in_use, k_ra8_psa_max_keys, RA8_INTERNAL, and s_key_pool.

Referenced by ra8_psa_key_import().

internal_handle_valid()

bool internal_handle_valid ( ra8_psa_key_t handle )

static

Definition at line 83 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::in_use, k_ra8_psa_max_keys, RA8_INTERNAL, and s_key_pool.

Referenced by internal_aead_decrypt_check(), internal_aead_encrypt_check(), ra8_psa_key_destroy(), ra8_psa_sign_hash(), and ra8_psa_verify_hash().

internal_map_alg()

psa_algorithm_t internal_map_alg ( ra8_psa_alg_t alg )

static

Definition at line 185 of file ra8_psa_crypto.c.

References k_ra8_psa_alg_aes_gcm, k_ra8_psa_alg_ecdsa_sha_256, k_ra8_psa_alg_none, k_ra8_psa_alg_sha_256, and RA8_INTERNAL.

Referenced by internal_psa_import_into_slot().

internal_map_key_type()

psa_key_type_t internal_map_key_type ( ra8_psa_key_type_t type )

static

Definition at line 167 of file ra8_psa_crypto.c.

References k_ra8_psa_key_type_aes, k_ra8_psa_key_type_ecc_p256_priv, k_ra8_psa_key_type_ecc_p256_pub, k_ra8_psa_key_type_hmac, k_ra8_psa_key_type_raw, and RA8_INTERNAL.

Referenced by internal_psa_import_into_slot().

internal_map_usage()

psa_key_usage_t internal_map_usage ( ra8_psa_key_usage_t usage )

static

Definition at line 201 of file ra8_psa_crypto.c.

References k_ra8_psa_usage_decrypt, k_ra8_psa_usage_derive, k_ra8_psa_usage_encrypt, k_ra8_psa_usage_sign, k_ra8_psa_usage_verify, and RA8_INTERNAL.

Referenced by internal_psa_import_into_slot().

internal_psa_import_into_slot()

ra8_err_t internal_psa_import_into_slot ( struct ra8_psa_key_handle * slot, const ra8_psa_key_attr_t * attr, const uint8_t * data, size_t data_len )

static

Definition at line 223 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::attr, internal_map_alg(), internal_map_key_type(), internal_map_usage(), k_ra8_err_hw_error, k_ra8_ok, ra8_psa_key_handle::psa_id, and RA8_INTERNAL.

Referenced by ra8_psa_key_import().

ra8_psa_aead_decrypt()

ra8_err_t ra8_psa_aead_decrypt	(	ra8_psa_key_t	handle,
		ra8_psa_alg_t	alg,
		const uint8_t *	nonce,
		size_t	nonce_len,
		const uint8_t *	aad,
		size_t	aad_len,
		const uint8_t *	cipher,
		size_t	cipher_len,
		uint8_t *	out,
		size_t	out_cap,
		size_t *	out_len )

Decrypt + verify-tag an AES-GCM buffer.

Wraps psa_aead_decrypt (PSA spec Sec 11.5). cipher must be ciphertext concatenated with the 16-octet authentication tag, as produced by ra8_psa_aead_encrypt.

Parameters

[in]	handle	Key with k_ra8_psa_usage_decrypt set.
[in]	alg	Must be k_ra8_psa_alg_aes_gcm.
[in]	nonce	12-byte nonce.
[in]	nonce_len	Length of nonce.
[in]	aad	Additional authenticated data.
[in]	aad_len	Length of aad.
[in]	cipher	Ciphertext || tag input.
[in]	cipher_len	Length of cipher (must be >= k_ra8_psa_gcm_tag_len).
[out]	out	Buffer for plaintext.
[in]	out_cap	Capacity of out.
[out]	out_len	Plaintext bytes written.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Plaintext recovered, tag valid.
k_ra8_err_invalid_arg	NULL pointer / alg mismatch.
k_ra8_err_invalid_size	Output buffer too small or input too short to contain a tag.
k_ra8_err_not_initialized	Facade not initialized.
k_ra8_err_crc_mismatch	Tag verification failed (ciphertext / aad / nonce / key was tampered with).
k_ra8_err_hw_error	Underlying AEAD reported a fault.

Precondition

Handle was imported with k_ra8_psa_usage_decrypt.

cipher_len >= k_ra8_psa_gcm_tag_len.

Postcondition

On k_ra8_ok, *out_len == cipher_len - k_ra8_psa_gcm_tag_len.

On any error, *out_len == 0.

See also

ra8_psa_aead_encrypt()

PSA Crypto API spec (ARM IHI 0086) Sec 11.5 "psa_aead_decrypt".

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 601 of file ra8_psa_crypto.c.

References internal_aead_decrypt_check(), k_ra8_err_crc_mismatch, k_ra8_err_hw_error, k_ra8_ok, and ra8_psa_key_handle::psa_id.

Referenced by internal_one_round_trip().

ra8_psa_aead_encrypt()

ra8_err_t ra8_psa_aead_encrypt	(	ra8_psa_key_t	handle,
		ra8_psa_alg_t	alg,
		const uint8_t *	nonce,
		size_t	nonce_len,
		const uint8_t *	aad,
		size_t	aad_len,
		const uint8_t *	plain,
		size_t	plain_len,
		uint8_t *	out,
		size_t	out_cap,
		size_t *	out_len )

Encrypt + authenticate a buffer with AES-GCM.

Wraps psa_aead_encrypt (PSA spec Sec 11.4). Output layout is ciphertext concatenated with the 16-octet authentication tag, so out_cap must be >= plain_len + k_ra8_psa_gcm_tag_len.

Parameters

[in]	handle	Key with k_ra8_psa_usage_encrypt set.
[in]	alg	Must be k_ra8_psa_alg_aes_gcm.
[in]	nonce	12-byte nonce (must be unique per key per call).
[in]	nonce_len	Length of nonce (k_ra8_psa_gcm_nonce_len).
[in]	aad	Additional authenticated data (may be NULL when aad_len == 0).
[in]	aad_len	Length of aad.
[in]	plain	Plaintext input.
[in]	plain_len	Length of plain.
[out]	out	Buffer for ciphertext || tag.
[in]	out_cap	Capacity of out.
[out]	out_len	Bytes written (== plain_len + k_ra8_psa_gcm_tag_len on success).

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Ciphertext + tag written.
k_ra8_err_invalid_arg	NULL pointer / alg mismatch.
k_ra8_err_invalid_size	Output buffer too small or nonce wrong length.
k_ra8_err_not_initialized	Facade not initialized.
k_ra8_err_hw_error	Underlying AEAD reported a fault.

Precondition

Handle was imported with k_ra8_psa_usage_encrypt.

nonce_len == k_ra8_psa_gcm_nonce_len.

Postcondition

On k_ra8_ok *out_len == plain_len + k_ra8_psa_gcm_tag_len.

On error *out_len == 0.

Warning

Reusing a (key, nonce) pair under AES-GCM catastrophically breaks confidentiality and integrity (NIST SP 800-38D 8.3).

See also

ra8_psa_aead_decrypt()

PSA Crypto API spec (ARM IHI 0086) Sec 11.4 "psa_aead_encrypt".

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 493 of file ra8_psa_crypto.c.

References internal_aead_encrypt_check(), k_ra8_err_hw_error, k_ra8_ok, and ra8_psa_key_handle::psa_id.

Referenced by internal_one_round_trip().

ra8_psa_crypto_deinit()

ra8_err_t ra8_psa_crypto_deinit

(

void

)

Symmetric tear-down for ra8_psa_crypto_init.

Destroys every still-imported key, calls mbedtls_psa_crypto_free (or the fake stand-in), and clears the initialized flag so a subsequent ra8_psa_crypto_init succeeds again.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Facade torn down.
k_ra8_err_not_initialized	ra8_psa_crypto_init was never called.

Precondition

Module was previously initialized.

Caller has guaranteed no other thread holds a key handle.

Postcondition

Pool is empty and module is not initialized.

All TF-PSA-Crypto resources released.

Note

Not re-entrant.

See also

ra8_psa_crypto_init()

Since

0.1.0

Definition at line 139 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::in_use, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_psa_max_keys, ra8_psa_key_handle::key, memset(), ra8_psa_key_handle::psa_id, s_initialized, and s_key_pool.

ra8_psa_crypto_init()

ra8_err_t ra8_psa_crypto_init

(

void

)

One-shot facade initialisation.

Calls psa_crypto_init (PSA Crypto API spec Sec 8.2), zeroes the key-handle pool, and marks the module ready. Safe to call exactly once per boot; subsequent calls without a matching ra8_psa_crypto_deinit return k_ra8_err_exists.

Algorithm:

1. If already initialized, return k_ra8_err_exists.
2. Invoke psa_crypto_init (or the fake stand-in).
3. Zero s_key_pool so close-without-import paths are well defined.
4. Mark the module initialized.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Facade ready.
k_ra8_err_exists	Already initialized this boot.
k_ra8_err_hw_error	TF-PSA-Crypto initialisation reported a fault.

Precondition

TF-PSA-Crypto has been built into the firmware image (RA8_USE_MBEDTLS=ON) OR RA8_OFF_TARGET is defined.

Caller is on the boot thread; not safe to interleave with other crypto calls.

Postcondition

Module is in the initialized state on success.

Key pool is fully reset (no slot held).

Note

Not re-entrant. Call from the boot path.

Warning

Do not invoke any ra8_psa_* function before this returns k_ra8_ok; doing so yields k_ra8_err_not_initialized.

Example:

ra8_err_t err = ra8_psa_crypto_init();
RA8_RETURN_ON_ERROR(err, "ra8_psa", "init failed");

See also

ra8_psa_crypto_deinit()

PSA Crypto API spec (ARM IHI 0086) Sec 8.2 "Library initialisation".

Since

0.1.0

Definition at line 116 of file ra8_psa_crypto.c.

References k_ra8_err_exists, k_ra8_err_hw_error, k_ra8_ok, k_ra8_psa_max_keys, ra8_log_error, s_initialized, s_key_pool, and s_ra8_psa_tag.

Referenced by blc_setup_or_halt(), internal_rng_demo_setup_or_halt(), internal_setup_or_halt(), main(), rot_setup_or_halt(), and sb_setup_or_halt().

ra8_psa_crypto_random()

ra8_err_t ra8_psa_crypto_random ( uint8_t * out, size_t out_len )

nodiscard

Fill out with cryptographically secure bytes.

Fill out[0..out_len-1] with cryptographically secure bytes.

See the matching header declaration for the full contract. On the target this delegates to psa_generate_random; in RA8_OFF_TARGET builds a deterministic xorshift32 stream is used so host-side tests are reproducible across runs.

Parameters

[out]	out	Destination buffer.
[in]	out_len	Number of bytes requested.

Returns

ra8_err_t error code per header.

Return values

k_ra8_ok	out filled with out_len bytes.
k_ra8_err_invalid_arg	out was NULL.
k_ra8_err_invalid_size	out_len was zero.
k_ra8_err_not_initialized	Facade not initialized.
k_ra8_err_hw_error	Underlying psa_generate_random failed.

Precondition

Facade has been initialized by ra8_psa_crypto_init.

out is non-NULL and out_len > 0.

Postcondition

On k_ra8_ok out[0..out_len-1] has been written.

On any error out is unchanged.

Note

Not thread-safe.

Since

0.1.0

Definition at line 696 of file ra8_psa_crypto.c.

References k_ra8_err_hw_error, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_ok, k_xs32_byte_m, k_xs32_seed, k_xs32_shl_a, k_xs32_shl_c, k_xs32_shr_b, ra8_log_error, s_initialized, s_ra8_psa_tag, and s_state.

Referenced by internal_rng_demo_emit_one_line().

ra8_psa_hash_compute()

ra8_err_t ra8_psa_hash_compute	(	ra8_psa_alg_t	alg,
		const uint8_t *	input,
		size_t	input_len,
		uint8_t *	out,
		size_t	out_cap,
		size_t *	out_len )

Compute a one-shot SHA-256 digest.

Wraps psa_hash_compute (PSA spec Sec 10.2.1). The output buffer must be at least k_ra8_psa_sha256_len bytes; *out_len is updated with the bytes actually written (always 32 on success).

Parameters

[in]	alg	Hash algorithm; must equal k_ra8_psa_alg_sha_256 for this revision of the facade.
[in]	input	Input message bytes.
[in]	input_len	Length of input in bytes.
[out]	out	Buffer that receives the digest.
[in]	out_cap	Capacity of out in bytes (>= k_ra8_psa_sha256_len).
[out]	out_len	Bytes actually written.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Digest written.
k_ra8_err_invalid_arg	Pointer NULL or wrong algorithm.
k_ra8_err_invalid_size	out_cap too small.
k_ra8_err_not_initialized	Facade not initialized.
k_ra8_err_hw_error	PSA reported a fatal error.

Precondition

Facade initialized.

out is non-NULL.

Postcondition

On k_ra8_ok, *out_len == k_ra8_psa_sha256_len.

On any error, *out_len == 0.

See also

PSA Crypto API spec (ARM IHI 0086) Sec 10.2 "Hash operations".

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 304 of file ra8_psa_crypto.c.

References k_ra8_err_hw_error, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_psa_alg_sha_256, k_ra8_psa_sha256_len, and s_initialized.

ra8_psa_key_destroy()

ra8_err_t ra8_psa_key_destroy

(

ra8_psa_key_t

handle

)

Destroy a previously-imported key.

Calls psa_destroy_key on the underlying PSA key id, zeroes the slot, and clears the in-use bit. Safe to call on any imported key.

Parameters

[in,out]

handle

Key handle previously returned by ra8_psa_key_import.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Key destroyed.
k_ra8_err_invalid_arg	Handle NULL or not from this pool.
k_ra8_err_not_initialized	Facade not initialized.

Precondition

Handle was returned by ra8_psa_key_import.

Module is initialized.

Postcondition

Slot is free and may be re-issued.

No further use of handle is permitted.

See also

ra8_psa_key_import()

PSA Crypto API spec (ARM IHI 0086) Sec 9.6 "psa_destroy_key".

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 286 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::in_use, internal_handle_valid(), k_ra8_err_invalid_arg, k_ra8_err_not_initialized, k_ra8_ok, ra8_psa_key_handle::key, ra8_psa_key_handle::key_len, memset(), ra8_psa_key_handle::psa_id, and s_initialized.

Referenced by internal_one_round_trip().

ra8_psa_key_import()

ra8_err_t ra8_psa_key_import	(	ra8_psa_key_t *	out_handle,
		const ra8_psa_key_attr_t *	attr,
		const uint8_t *	data,
		size_t	data_len )

Import a raw-byte key into the static pool.

Allocates the first free slot, copies data into the underlying PSA key store via psa_import_key (PSA spec Sec 9.5), and returns an opaque handle through out_handle.

Parameters

[out]	out_handle	Receives the new opaque handle on success. Set to NULL on any non-success return.
[in]	attr	Key attributes (type, algorithm, usage).
[in]	data	Raw key bytes; layout depends on attr->type.
[in]	data_len	Length of data in bytes; must be <= k_ra8_psa_max_key_bytes.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Key imported and handle valid.
k_ra8_err_invalid_arg	NULL pointer or malformed attributes.
k_ra8_err_invalid_size	data_len exceeds the static cap.
k_ra8_err_not_initialized	Facade was never initialized.
k_ra8_err_no_mem	Pool exhausted (k_ra8_psa_max_keys).
k_ra8_err_hw_error	Underlying psa_import_key rejected the key (bad key material).

Precondition

ra8_psa_crypto_init returned k_ra8_ok previously.

data_len > 0 and data is non-NULL.

Postcondition

On k_ra8_ok, *out_handle is non-NULL and lives until a matching ra8_psa_key_destroy.

On any error, *out_handle is set to NULL.

Note

Not thread-safe; serialise with concurrent destroys.

Example:

ra8_psa_key_attr_t attr = {
    .type  = k_ra8_psa_key_type_aes,
    .alg   = k_ra8_psa_alg_aes_gcm,
    .usage = (ra8_psa_key_usage_t)
             (k_ra8_psa_usage_encrypt | k_ra8_psa_usage_decrypt),
};
ra8_psa_key_t k = NULL;
(void)ra8_psa_key_import(&k, &attr, raw, sizeof(raw));

See also

ra8_psa_key_destroy()

PSA Crypto API spec (ARM IHI 0086) Sec 9.5 "Key import / export".

Since

0.1.0

Definition at line 244 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::attr, ra8_psa_key_handle::in_use, internal_alloc_slot(), internal_psa_import_into_slot(), k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_no_mem, k_ra8_err_not_initialized, k_ra8_ok, k_ra8_psa_max_key_bytes, k_ra8_psa_usage_none, ra8_psa_key_handle::key, ra8_psa_key_handle::key_len, memcpy(), and s_initialized.

Referenced by internal_one_round_trip().

ra8_psa_sign_hash()

ra8_err_t ra8_psa_sign_hash	(	ra8_psa_key_t	handle,
		ra8_psa_alg_t	alg,
		const uint8_t *	hash,
		size_t	hash_len,
		uint8_t *	sig,
		size_t	sig_cap,
		size_t *	sig_len )

Sign a pre-computed hash with a private ECDSA key.

Wraps psa_sign_hash (PSA spec Sec 12.6). Only ECDSA over SHA-256 is exercised; other algorithms return k_ra8_err_not_supported. The caller is responsible for hashing the message first – ra8_psa_sign_hash does not hash hash, it signs the bytes verbatim per the PSA contract.

Parameters

[in]	handle	Private-key handle with k_ra8_psa_usage_sign.
[in]	alg	Signature algorithm; must be k_ra8_psa_alg_ecdsa_sha_256.
[in]	hash	Pre-computed digest bytes.
[in]	hash_len	Length of hash (32 for SHA-256).
[out]	sig	Output buffer for the signature.
[in]	sig_cap	Capacity of sig (>= k_ra8_psa_max_sig_bytes).
[out]	sig_len	Bytes actually written.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Signature emitted.
k_ra8_err_invalid_arg	NULL pointer or alg mismatch.
k_ra8_err_invalid_size	Output buffer too small.
k_ra8_err_not_initialized	Facade not initialized.
k_ra8_err_not_supported	Key type / alg not implemented.
k_ra8_err_hw_error	Underlying psa_sign_hash failed.

Precondition

Handle was imported with k_ra8_psa_usage_sign.

hash_len == k_ra8_psa_sha256_len for SHA-256.

Postcondition

On k_ra8_ok, *sig_len > 0 and <= sig_cap.

On any error, *sig_len == 0.

See also

ra8_psa_verify_hash()

PSA Crypto API spec (ARM IHI 0086) Sec 12.6 "psa_sign_hash".

Since

0.1.0

Note

Not thread-safe unless documented otherwise.

Definition at line 346 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::attr, internal_handle_valid(), k_ra8_err_hw_error, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_ok, k_ra8_psa_alg_ecdsa_sha_256, k_ra8_psa_max_key_bytes, k_ra8_psa_sha256_len, k_ra8_psa_usage_sign, ra8_psa_key_handle::key, ra8_psa_key_handle::key_len, memcpy(), ra8_psa_key_handle::psa_id, and s_initialized.

ra8_psa_verify_hash()

ra8_err_t ra8_psa_verify_hash	(	ra8_psa_key_t	handle,
		ra8_psa_alg_t	alg,
		const uint8_t *	hash,
		size_t	hash_len,
		const uint8_t *	sig,
		size_t	sig_len )

Verify an ECDSA signature over a pre-computed hash.

Wraps psa_verify_hash (PSA spec Sec 12.7). Returns k_ra8_ok on a valid signature, k_ra8_err_crc_mismatch on a structurally well-formed but invalid signature, and an k_ra8_err_* value for other failures.

Parameters

[in]	handle	Public-key handle with k_ra8_psa_usage_verify.
[in]	alg	Signature algorithm; must be k_ra8_psa_alg_ecdsa_sha_256.
[in]	hash	Pre-computed digest bytes.
[in]	hash_len	Length of hash.
[in]	sig	Signature bytes.
[in]	sig_len	Length of sig.

Returns

ra8_err_t Error code.

Return values

k_ra8_ok	Signature is valid.
k_ra8_err_crc_mismatch	Signature is invalid.
k_ra8_err_invalid_arg	Pointer NULL or alg mismatch.
k_ra8_err_not_initialized	Facade not initialized.
k_ra8_err_not_supported	Algorithm not implemented.
k_ra8_err_hw_error	Underlying PSA call reported a fault.

Precondition

Handle was imported with k_ra8_psa_usage_verify.

hash_len == k_ra8_psa_sha256_len.

Postcondition

No state modified on failure.

See also

ra8_psa_sign_hash()

PSA Crypto API spec (ARM IHI 0086) Sec 12.7 "psa_verify_hash".

Since

0.1.0

Postcondition

Side effects bounded to documented state.

Note

Not thread-safe unless documented otherwise.

Definition at line 406 of file ra8_psa_crypto.c.

References ra8_psa_key_handle::attr, internal_handle_valid(), k_ra8_err_crc_mismatch, k_ra8_err_hw_error, k_ra8_err_invalid_arg, k_ra8_err_invalid_size, k_ra8_err_not_initialized, k_ra8_err_not_supported, k_ra8_ok, k_ra8_psa_alg_ecdsa_sha_256, k_ra8_psa_max_key_bytes, k_ra8_psa_sha256_len, k_ra8_psa_usage_verify, ra8_psa_key_handle::key, ra8_psa_key_handle::key_len, memcpy(), ra8_psa_key_handle::psa_id, and s_initialized.

Variable Documentation

s_initialized

bool s_initialized

static

One-shot global init flag protecting the pool.

Definition at line 75 of file ra8_psa_crypto.c.

s_key_pool

struct ra8_psa_key_handle s_key_pool[k_ra8_psa_max_keys]

static

Per-handle state pool sized at compile time.

Definition at line 72 of file ra8_psa_crypto.c.

Referenced by internal_alloc_slot(), internal_handle_valid(), ra8_psa_crypto_deinit(), and ra8_psa_crypto_init().

s_ra8_psa_tag

const char* const s_ra8_psa_tag = "ra8_psa_crypto"

static

Logging tag prefix used by every ra8_psa_crypto log line.

Definition at line 60 of file ra8_psa_crypto.c.

Referenced by ra8_psa_crypto_init(), and ra8_psa_crypto_random().