ra8_psa_crypto.h File Reference

Application-level PSA Crypto facade over tf-psa-crypto. More...

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

Include dependency graph for ra8_psa_crypto.h:

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

Go to the source code of this file.

Data Structures
struct	ra8_psa_key_attr

Typedefs
typedef struct ra8_psa_key_handle *	ra8_psa_key_t
	Opaque PSA key handle (typed pointer into the static pool).
typedef struct ra8_psa_key_attr	ra8_psa_key_attr_t

Enumerations
enum	ra8_psa_limits_t : uint8_t {   k_ra8_psa_max_keys = 16U ,   k_ra8_psa_max_key_bytes = 96U ,   k_ra8_psa_sha256_len = 32U ,   k_ra8_psa_gcm_nonce_len = 12U ,   k_ra8_psa_gcm_tag_len = 16U ,   k_ra8_psa_max_sig_bytes = 96U }
	Static-pool sizing constants for the PSA Crypto facade. More...
enum	ra8_psa_key_type_t : uint8_t {   k_ra8_psa_key_type_raw = 0U ,   k_ra8_psa_key_type_aes = 1U ,   k_ra8_psa_key_type_hmac = 2U ,   k_ra8_psa_key_type_ecc_p256_priv = 3U ,   k_ra8_psa_key_type_ecc_p256_pub = 4U }
	Project-local enum mirroring the PSA key-type families we care about. More...
enum	ra8_psa_alg_t : uint8_t {   k_ra8_psa_alg_none = 0U ,   k_ra8_psa_alg_sha_256 = 1U ,   k_ra8_psa_alg_aes_gcm = 2U ,   k_ra8_psa_alg_ecdsa_sha_256 = 3U }
	Algorithm selector passed to sign / verify / AEAD operations. More...
enum	ra8_psa_key_usage_t : uint32_t {   k_ra8_psa_usage_none = 0x00U ,   k_ra8_psa_usage_sign = 0x01U ,   k_ra8_psa_usage_verify = 0x02U ,   k_ra8_psa_usage_encrypt = 0x04U ,   k_ra8_psa_usage_decrypt = 0x08U ,   k_ra8_psa_usage_derive = 0x10U }
	Bitmask of allowed operations on an imported key. More...

Functions
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.
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.
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.
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[0..out_len-1] with cryptographically secure bytes.

Detailed Description

Application-level PSA Crypto facade over tf-psa-crypto.

Tag

[Ring 4 / PAL] {World: NS}

ra8_psa_crypto is a thin, project-shaped wrapper around the vendored TF-PSA-Crypto 1.x library at libs/third_party/tf-psa-crypto. Where ra8_tls provides session- oriented TLS, this module exposes the application-level PSA Crypto primitives (key import / destroy, signing, hashing, AEAD) behind a small ra8_psa_* API that returns ra8_err_t.

The facade has three jobs:

1. Hide PSA spelling: callers never include psa/crypto.h directly. A higher-level OTA verifier, secure-boot ledger, or BLE pairing flow asks ra8_psa_* for "sign this hash with key handle 3" and never touches a psa_key_id_t.
2. Enforce NASA Rule 3: key handles come from a fixed-size static pool of k_ra8_psa_max_keys slots. Application code cannot accidentally leak key material across boots or fragment the PSA key store – if the pool is full, ra8_psa_key_import returns k_ra8_err_no_mem.
3. Optional RSIP routing: where the silicon has a hardware crypto engine (ra8_rsip), the facade may transparently route AES-GCM, SHA-256, and ECDSA primitives through it. The public surface is identical regardless of whether the operation ran in software (TF-PSA-Crypto) or hardware (RSIP).

Layering

*   +---------------------------+ ra8_psa_sign_hash, ra8_psa_aead_encrypt
*   | App (OTA / boot / pairing)|
*   +-------------+-------------+
*                 |
*                 v
*   +---------------------------+ ra8_psa_crypto (this header)
*   | TF-PSA-Crypto 1.x         |
*   +-------------+-------------+
*                 |
*                 v (optional, when present)
*   +---------------------------+ ra8_rsip hardware accelerator
*   | Silicon AES / SHA / ECDSA |
*   +---------------------------+
* 

References

• PSA Crypto API specification, ARM IHI 0086 v1.1.0, Sections 9-12 (key management, hash, AEAD, asymmetric signature).

Copyright

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

Definition in file ra8_psa_crypto.h.

Typedef Documentation

ra8_psa_key_attr_t

typedef struct ra8_psa_key_attr ra8_psa_key_attr_t

ra8_psa_key_t

typedef struct ra8_psa_key_handle* ra8_psa_key_t

Opaque PSA key handle (typed pointer into the static pool).

NULL is the sentinel for "uninitialized handle". The only legal way to obtain a non-NULL value is ra8_psa_key_import; passing any other pointer to ra8_psa_* yields k_ra8_err_invalid_arg.

Since

0.1.0

Definition at line 211 of file ra8_psa_crypto.h.

Enumeration Type Documentation

ra8_psa_alg_t

enum ra8_psa_alg_t : uint8_t

Algorithm selector passed to sign / verify / AEAD operations.

See also

PSA Crypto API spec (ARM IHI 0086) Sec 10 "Algorithms".

Enumerator
k_ra8_psa_alg_none	Sentinel for "unset".
k_ra8_psa_alg_sha_256	SHA-256 hash (FIPS 180-4).
k_ra8_psa_alg_aes_gcm	AES-GCM AEAD (NIST SP 800-38D).
k_ra8_psa_alg_ecdsa_sha_256	ECDSA over SHA-256 (FIPS 186-4).

Definition at line 159 of file ra8_psa_crypto.h.

ra8_psa_key_type_t

enum ra8_psa_key_type_t : uint8_t

Project-local enum mirroring the PSA key-type families we care about.

Mirrors the subset of PSA_KEY_TYPE_* codes we actually use, mapped back to canonical PSA values inside ra8_psa_crypto.c. Keeping the tag in our own namespace lets callers avoid a transitive include of psa/crypto_values.h.

See also

PSA Crypto API spec (ARM IHI 0086) Sec 9.2 "Key types".

Enumerator
k_ra8_psa_key_type_raw	Raw octet string (HKDF input).
k_ra8_psa_key_type_aes	Symmetric AES key.
k_ra8_psa_key_type_hmac	HMAC key (any hash).
k_ra8_psa_key_type_ecc_p256_priv	ECDSA P-256 private key.
k_ra8_psa_key_type_ecc_p256_pub	ECDSA P-256 public key (uncompressed).

Definition at line 145 of file ra8_psa_crypto.h.

ra8_psa_key_usage_t

enum ra8_psa_key_usage_t : uint32_t

Bitmask of allowed operations on an imported key.

Equivalent to PSA's psa_key_usage_t flags, restricted to the subset this facade exposes.

See also

PSA Crypto API spec (ARM IHI 0086) Sec 9.4 "Key policies".

Enumerator
k_ra8_psa_usage_none	No usage allowed (placeholder).
k_ra8_psa_usage_sign	Allow ra8_psa_sign_hash.
k_ra8_psa_usage_verify	Allow ra8_psa_verify_hash.
k_ra8_psa_usage_encrypt	Allow ra8_psa_aead_encrypt.
k_ra8_psa_usage_decrypt	Allow ra8_psa_aead_decrypt.
k_ra8_psa_usage_derive	Allow KDF-style derivation (future).

Definition at line 176 of file ra8_psa_crypto.h.

ra8_psa_limits_t

enum ra8_psa_limits_t : uint8_t

Static-pool sizing constants for the PSA Crypto facade.

Sized to comfortably cover the worst-case number of long-lived keys we expect in a single boot: a device identity key, two OTA verify keys (current + rollover), a TLS client key, a BLE LTK, and a handful of ephemeral session keys. Increasing the bound only costs a few bytes of .bss per slot.

Invariant

k_ra8_psa_max_keys fits in a uint8_t.

See also

PSA Crypto API spec (ARM IHI 0086) Sec 9.1 "Key identifiers".

Enumerator
k_ra8_psa_max_keys	Maximum simultaneous key handles handed out by the pool. NASA Power of 10 Rule 3 cap: any further import returns k_ra8_err_no_mem.
k_ra8_psa_max_key_bytes	Maximum imported raw-key length in bytes (P-384 + AES-256).
k_ra8_psa_sha256_len	SHA-256 digest length (RFC 6234, Section 4.1).
k_ra8_psa_gcm_nonce_len	AES-GCM nonce length used by ra8_psa_aead_* (NIST SP 800-38D).
k_ra8_psa_gcm_tag_len	AES-GCM authentication tag length (16 octets).
k_ra8_psa_max_sig_bytes	Maximum ECDSA signature length we ever emit (P-384 raw r||s).

Definition at line 94 of file ra8_psa_crypto.h.

Function Documentation

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[0..out_len-1] with cryptographically secure bytes.

Wraps psa_generate_random (PSA Crypto API spec, ARM IHI 0086 v1.1.0, Section 10.4 "Random number generation"). On the target the underlying PSA implementation pulls entropy from the RSIP TRNG; in RA8_OFF_TARGET builds a deterministic xorshift32 stream seeded from the call index is used so host-side tests are reproducible.

Parameters

[out]	out	Destination buffer that receives out_len bytes.
[in]	out_len	Number of bytes to fill; must be > 0.

Returns

ra8_err_t Error code.

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 via ra8_psa_crypto_init.

out is non-NULL.

Postcondition

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

On any error, out is unchanged.

Note

Not thread-safe; caller must serialise with concurrent crypto calls.

Example:

uint8_t nonce[12] = {};
(void)ra8_psa_crypto_random(nonce, sizeof(nonce));

See also

PSA Crypto API spec (ARM IHI 0086) Sec 10.4 "psa_generate_random".

Since

0.1.0

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.