Function declarations for PSA Crypto. More...

Detailed Description

Function declarations for PSA Crypto.

Author: Lena Boeckmann lena..nosp@m.boec.nosp@m.kmann.nosp@m.@haw.nosp@m.-hamb.nosp@m.urg..nosp@m.de

See also: https://armmbed.github.io/mbed-crypto/html/index.html

Definition in file crypto.h.

#include <stdlib.h>
#include <string.h>
#include "kernel_defines.h"
#include "crypto_sizes.h"
#include "crypto_struct.h"
#include "crypto_values.h"
#include "crypto_types.h"

Include dependency graph for crypto.h:

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

Go to the source code of this file.

#define	PSA_CRYPTO_API_VERSION_MAJOR 1
	The major version of this implementation of the PSA Crypto API.

#define	PSA_CRYPTO_API_VERSION_MINOR 1
	The minor version of this implementation of the PSA Crypto API.

const char *	psa_status_to_humanly_readable (psa_status_t status)
	Helper function to convert PSA status values humanly readable.

psa_status_t	psa_crypto_init (void)
	Library initialization.

psa_status_t	psa_aead_encrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t nonce, size_t nonce_length, const uint8_t additional_data, size_t additional_data_length, const uint8_t plaintext, size_t plaintext_length, uint8_t ciphertext, size_t ciphertext_size, size_t *ciphertext_length)
	Process an authenticated encryption operation.

psa_status_t	psa_aead_decrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t nonce, size_t nonce_length, const uint8_t additional_data, size_t additional_data_length, const uint8_t ciphertext, size_t ciphertext_length, uint8_t plaintext, size_t plaintext_size, size_t *plaintext_length)
	Process an authenticated decryption operation.

psa_status_t	psa_aead_encrypt_setup (psa_aead_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
	Set the key for a multi-part authenticated encryption operation.

psa_status_t	psa_aead_decrypt_setup (psa_aead_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
	Set the key for a multi-part authenticated decryption operation.

psa_status_t	psa_aead_set_lengths (psa_aead_operation_t *operation, size_t ad_length, size_t plaintext_length)
	Declare the lengths of the message and additional data for AEAD.

psa_status_t	psa_aead_generate_nonce (psa_aead_operation_t operation, uint8_t nonce, size_t nonce_size, size_t *nonce_length)
	Generate a random nonce for an authenticated encryption operation.

psa_status_t	psa_aead_set_nonce (psa_aead_operation_t operation, const uint8_t nonce, size_t nonce_length)
	Set the nonce for an authenticated encryption or decryption operation.

psa_status_t	psa_aead_update_ad (psa_aead_operation_t operation, const uint8_t input, size_t input_length)
	Pass additional data to an active AEAD operation.

psa_status_t	psa_aead_update (psa_aead_operation_t operation, const uint8_t input, size_t input_length, uint8_t output, size_t output_size, size_t output_length)
	Encrypt or decrypt a message fragment in an active AEAD operation.

psa_status_t	psa_aead_finish (psa_aead_operation_t operation, uint8_t ciphertext, size_t ciphertext_size, size_t ciphertext_length, uint8_t tag, size_t tag_size, size_t *tag_length)
	Finish encrypting a message in an AEAD operation.

psa_status_t	psa_aead_verify (psa_aead_operation_t operation, uint8_t plaintext, size_t plaintext_size, size_t plaintext_length, const uint8_t tag, size_t tag_length)
	Finish authenticating and decrypting a message in an AEAD operation.

psa_status_t	psa_aead_abort (psa_aead_operation_t *operation)
	Abort an AEAD operation.

psa_status_t	psa_asymmetric_encrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, const uint8_t salt, size_t salt_length, uint8_t output, size_t output_size, size_t output_length)
	Encrypt a short message with a public key.

psa_status_t	psa_asymmetric_decrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, const uint8_t salt, size_t salt_length, uint8_t output, size_t output_size, size_t output_length)
	Decrypt a short message with a private key.

psa_status_t	psa_cipher_abort (psa_cipher_operation_t *operation)
	Abort a cipher operation.

psa_status_t	psa_cipher_decrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, uint8_t output, size_t output_size, size_t *output_length)
	Decrypt a message using a symmetric cipher.

psa_status_t	psa_cipher_decrypt_setup (psa_cipher_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
	Set the key for a multi-part symmetric decryption operation.

psa_status_t	psa_cipher_encrypt (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, uint8_t output, size_t output_size, size_t *output_length)
	Encrypt a message using a symmetric cipher.

psa_status_t	psa_cipher_encrypt_setup (psa_cipher_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
	Set the key for a multi-part symmetric encryption operation.

psa_status_t	psa_cipher_finish (psa_cipher_operation_t operation, uint8_t output, size_t output_size, size_t *output_length)
	Finish encrypting or decrypting a message in a cipher operation.

psa_status_t	psa_cipher_generate_iv (psa_cipher_operation_t operation, uint8_t iv, size_t iv_size, size_t *iv_length)
	Generate an initialization vector (IV) for a symmetric encryption operation.

psa_status_t	psa_cipher_set_iv (psa_cipher_operation_t operation, const uint8_t iv, size_t iv_length)
	Set the initialization vector (IV) for a symmetric encryption or decryption operation.

psa_status_t	psa_cipher_update (psa_cipher_operation_t operation, const uint8_t input, size_t input_length, uint8_t output, size_t output_size, size_t output_length)
	Encrypt or decrypt a message fragment in an active cipher operation.

psa_status_t	psa_copy_key (psa_key_id_t source_key, const psa_key_attributes_t attributes, psa_key_id_t target_key)
	Make a copy of a key.

psa_status_t	psa_destroy_key (psa_key_id_t key)
	Destroy a key.

psa_status_t	psa_export_key (psa_key_id_t key, uint8_t data, size_t data_size, size_t data_length)
	Export a key in binary format.

psa_status_t	psa_export_public_key (psa_key_id_t key, uint8_t data, size_t data_size, size_t data_length)
	Export a public key or the public part of a key pair in binary format.

psa_status_t	psa_builtin_generate_key (const psa_key_attributes_t attributes, uint8_t key_buffer, size_t key_buffer_size, size_t *key_buffer_length)
	Built-in key generation function.

psa_status_t	psa_generate_key (const psa_key_attributes_t attributes, psa_key_id_t key)
	Generate a key or key pair.

psa_status_t	psa_builtin_generate_random (uint8_t *output, size_t output_size)
	Built-in function for random number generation.

psa_status_t	psa_generate_random (uint8_t *output, size_t output_size)
	Generate random bytes.

static void	psa_set_key_algorithm (psa_key_attributes_t *attributes, psa_algorithm_t alg)
	Declare the permitted algorithm policy for a key.

static psa_algorithm_t	psa_get_key_algorithm (const psa_key_attributes_t *attributes)
	Retrieve the permitted algorithm policy from key attributes.

static void	psa_set_key_bits (psa_key_attributes_t *attributes, size_t bits)
	Declare the size of a key.

static size_t	psa_get_key_bits (const psa_key_attributes_t *attributes)
	Retrieve the key size from key attributes.

static void	psa_set_key_id (psa_key_attributes_t *attributes, psa_key_id_t id)
	Declare a key as persistent and set its key identifier.

static psa_key_id_t	psa_get_key_id (const psa_key_attributes_t *attributes)
	Retrieve the key identifier from key attributes.

static void	psa_set_key_lifetime (psa_key_attributes_t *attributes, psa_key_lifetime_t lifetime)
	Set the location of a persistent key.

static psa_key_lifetime_t	psa_get_key_lifetime (const psa_key_attributes_t *attributes)
	Retrieve the lifetime from key attributes.

static void	psa_set_key_type (psa_key_attributes_t *attributes, psa_key_type_t type)
	Declare the type of a key.

static psa_key_type_t	psa_get_key_type (const psa_key_attributes_t *attributes)
	Retrieve the key type from key attributes.

static void	psa_set_key_usage_flags (psa_key_attributes_t *attributes, psa_key_usage_t usage_flags)
	Declare usage flags for a key.

static psa_key_usage_t	psa_get_key_usage_flags (const psa_key_attributes_t *attributes)
	Retrieve the usage flags from key attributes.

static void	psa_reset_key_attributes (psa_key_attributes_t *attributes)
	Reset a key attribute object to a freshly initialized state.

psa_status_t	psa_get_key_attributes (psa_key_id_t key, psa_key_attributes_t *attributes)
	Retrieve the attributes of a key.

psa_status_t	psa_hash_abort (psa_hash_operation_t *operation)
	Abort a hash operation.

psa_status_t	psa_hash_clone (const psa_hash_operation_t source_operation, psa_hash_operation_t target_operation)
	Clone a hash operation.

psa_status_t	psa_hash_compare (psa_algorithm_t alg, const uint8_t input, size_t input_length, const uint8_t hash, size_t hash_length)
	Calculate the hash (digest) of a message and compare it with a reference value.

psa_status_t	psa_hash_compute (psa_algorithm_t alg, const uint8_t input, size_t input_length, uint8_t hash, size_t hash_size, size_t *hash_length)
	Calculate the hash (digest) of a message.

psa_status_t	psa_hash_finish (psa_hash_operation_t operation, uint8_t hash, size_t hash_size, size_t *hash_length)
	Finish the calculation of the hash of a message.

psa_status_t	psa_hash_resume (psa_hash_operation_t operation, const uint8_t hash_state, size_t hash_state_length)
	Set up a multi-part hash operation using the hash suspend state from a previously suspended hash operation.

psa_status_t	psa_hash_setup (psa_hash_operation_t *operation, psa_algorithm_t alg)
	Set up a multipart hash operation.

psa_status_t	psa_hash_suspend (psa_hash_operation_t operation, uint8_t hash_state, size_t hash_state_size, size_t *hash_state_length)
	Halt the hash operation and extract the intermediate state of the hash computation.

psa_status_t	psa_hash_update (psa_hash_operation_t operation, const uint8_t input, size_t input_length)
	Add a message fragment to a multi-part hash operation.

psa_status_t	psa_hash_verify (psa_hash_operation_t operation, const uint8_t hash, size_t hash_length)
	Finish the calculation of the hash of a message and compare it with an expected value.

psa_status_t	psa_builtin_import_key (const psa_key_attributes_t attributes, const uint8_t data, size_t data_length, uint8_t key_buffer, size_t key_buffer_size, size_t key_buffer_length, size_t *bits)
	Built-in key import function.

psa_status_t	psa_import_key (const psa_key_attributes_t attributes, const uint8_t data, size_t data_length, psa_key_id_t *key)
	Import a key in binary format.

psa_status_t	psa_key_derivation_abort (psa_key_derivation_operation_t *operation)
	Abort a key derivation operation.

psa_status_t	psa_key_derivation_get_capacity (const psa_key_derivation_operation_t operation, size_t capacity)
	Retrieve the current capacity of a key derivation operation.

psa_status_t	psa_key_derivation_input_bytes (psa_key_derivation_operation_t operation, psa_key_derivation_step_t step, const uint8_t data, size_t data_length)
	Provide an input for key derivation or key agreement.

psa_status_t	psa_key_derivation_input_integer (psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, uint64_t value)
	Provide a numeric input for key derivation or key agreement.

psa_status_t	psa_key_derivation_input_key (psa_key_derivation_operation_t *operation, psa_key_derivation_step_t step, psa_key_id_t key)
	Provide an input for key derivation in the form of a key.

psa_status_t	psa_key_derivation_key_agreement (psa_key_derivation_operation_t operation, psa_key_derivation_step_t step, psa_key_id_t private_key, const uint8_t peer_key, size_t peer_key_length)
	Perform a key agreement and use the shared secret as input to a key derivation.

psa_status_t	psa_key_derivation_output_bytes (psa_key_derivation_operation_t operation, uint8_t output, size_t output_length)
	Read some data from a key derivation operation.

psa_status_t	psa_key_derivation_output_key (const psa_key_attributes_t attributes, psa_key_derivation_operation_t operation, psa_key_id_t *key)
	Derive a key from an ongoing key derivation operation.

psa_status_t	psa_key_derivation_set_capacity (psa_key_derivation_operation_t *operation, size_t capacity)
	Set the maximum capacity of a key derivation operation.

psa_status_t	psa_key_derivation_setup (psa_key_derivation_operation_t *operation, psa_algorithm_t alg)
	Set up a key derivation operation.

psa_status_t	psa_key_derivation_verify_bytes (psa_key_derivation_operation_t operation, const uint8_t expected_output, size_t output_length)
	Compare output data from a key derivation operation to an expected value.

psa_status_t	psa_key_derivation_verify_key (psa_key_derivation_operation_t *operation, psa_key_id_t expected)
	Compare output data from a key derivation operation to an expected value stored in a key.

psa_status_t	psa_mac_abort (psa_mac_operation_t *operation)
	Abort a MAC operation.

psa_status_t	psa_mac_compute (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, uint8_t mac, size_t mac_size, size_t *mac_length)
	Calculate the message authentication code (MAC) of a message.

psa_status_t	psa_mac_sign_finish (psa_mac_operation_t operation, uint8_t mac, size_t mac_size, size_t *mac_length)
	Finish the calculation of the MAC of a message.

psa_status_t	psa_mac_sign_setup (psa_mac_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
	Set up a multi-part MAC calculation operation.

psa_status_t	psa_mac_update (psa_mac_operation_t operation, const uint8_t input, size_t input_length)
	Add a message fragment to a multi-part MAC operation.

psa_status_t	psa_mac_verify (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, const uint8_t mac, size_t mac_length)
	Calculate the MAC of a message and compare it with a reference value.

psa_status_t	psa_mac_verify_finish (psa_mac_operation_t operation, const uint8_t mac, size_t mac_length)
	Finish the calculation of the MAC of a message and compare it with an expected value.

psa_status_t	psa_mac_verify_setup (psa_mac_operation_t *operation, psa_key_id_t key, psa_algorithm_t alg)
	Set up a multi-part MAC verification operation.

psa_status_t	psa_purge_key (psa_key_id_t key)
	Remove non-essential copies of key material from memory.

psa_status_t	psa_raw_key_agreement (psa_algorithm_t alg, psa_key_id_t private_key, const uint8_t peer_key, size_t peer_key_length, uint8_t output, size_t output_size, size_t *output_length)
	Perform a key agreement and return the raw shared secret.

psa_status_t	psa_sign_hash (psa_key_id_t key, psa_algorithm_t alg, const uint8_t hash, size_t hash_length, uint8_t signature, size_t signature_size, size_t *signature_length)
	Sign an already-calculated hash with a private key.

psa_status_t	psa_sign_message (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, uint8_t signature, size_t signature_size, size_t *signature_length)
	Sign a message with a private key.

psa_status_t	psa_verify_hash (psa_key_id_t key, psa_algorithm_t alg, const uint8_t hash, size_t hash_length, const uint8_t signature, size_t signature_length)
	Verify the signature of a hash or short message using a public key.

psa_status_t	psa_verify_message (psa_key_id_t key, psa_algorithm_t alg, const uint8_t input, size_t input_length, const uint8_t signature, size_t signature_length)
	Verify the signature of a message with a public key.

Macro Definition Documentation

◆ PSA_CRYPTO_API_VERSION_MAJOR

#define PSA_CRYPTO_API_VERSION_MAJOR 1

The major version of this implementation of the PSA Crypto API.

Definition at line 46 of file crypto.h.

◆ PSA_CRYPTO_API_VERSION_MINOR

#define PSA_CRYPTO_API_VERSION_MINOR 1

The minor version of this implementation of the PSA Crypto API.

Definition at line 51 of file crypto.h.

Function Documentation

◆ psa_aead_abort()

psa_status_t psa_aead_abort ( psa_aead_operation_t * operation )

Abort an AEAD operation.

Aborting an operation frees all associated resources except for the operation object itself. Once aborted, the operation object can be reused for another operation by calling psa_aead_encrypt_setup() or psa_aead_decrypt_setup() again.

This function can be called any time after the operation object has been initialized as described in psa_aead_operation_t.

In particular, calling psa_aead_abort() after the operation has been terminated by a call to psa_aead_abort(), psa_aead_finish() or psa_aead_verify() is safe and has no effect.

Parameters

operation Initialized AEAD operation.

Returns: PSA_SUCCESS Success.; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_decrypt()

psa_status_t psa_aead_decrypt	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	nonce,
		size_t	nonce_length,
		const uint8_t *	additional_data,
		size_t	additional_data_length,
		const uint8_t *	ciphertext,
		size_t	ciphertext_length,
		uint8_t *	plaintext,
		size_t	plaintext_size,
		size_t *	plaintext_length
	)

Process an authenticated decryption operation.

Parameters

key	Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg	The AEAD algorithm to compute (`PSA_ALG_XXX` value such that PSA_ALG_IS_AEAD(`alg`) is true).
nonce	Nonce or IV to use.
nonce_length	Size of the nonce buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(`key_type`, `alg`) where `key_type` is the type of `key`.
additional_data	Additional data that will be authenticated but not encrypted.
additional_data_length	Size of `additional_data` in bytes.
ciphertext	Data that has been authenticated and encrypted. For algorithms where the encrypted data and the authentication tag are defined as separate inputs, the buffer must contain the encrypted data followed by the authentication tag.
ciphertext_length	Size of `ciphertext` in bytes.
plaintext	Output buffer for the decrypted data.
plaintext_size	Size of the plaintext buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_AEAD_DECRYPT_OUTPUT_SIZE(`key_type`, `alg`, `ciphertext_length`) where `key_type` is the type of key. PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE(`ciphertext_length`) evaluates to the maximum ciphertext size of any supported AEAD decryption.
plaintext_length	On success, the size of the output in the plaintext buffer.

Returns: PSA_SUCCESS Success.; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_INVALID_SIGNATURE The ciphertext is not authentic.; PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not permit the requested algorithm.; PSA_ERROR_INVALID_ARGUMENT key is not compatible with alg.; PSA_ERROR_NOT_SUPPORTED alg is not supported or is not an AEAD algorithm.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_BUFFER_TOO_SMALL plaintext_size is too small. PSA_AEAD_DECRYPT_OUTPUT_SIZE() or PSA_AEAD_DECRYPT_OUTPUT_MAX_SIZE() can be used to determine the required buffer size.; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_decrypt_setup()

psa_status_t psa_aead_decrypt_setup	(	psa_aead_operation_t *	operation,
		psa_key_id_t	key,
		psa_algorithm_t	alg
	)

Set the key for a multi-part authenticated decryption operation.

The sequence of operations to decrypt a message with authentication is as follows:

Allocate an operation object which will be passed to all the functions listed here
Initialize the operation object with one of the methods described in the documentation for psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
Call psa_aead_decrypt_setup() to specify the algorithm and key.
If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details.
Call psa_aead_set_nonce() with the nonce for the decryption.
Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
Call psa_aead_update() zero, one or more times, passing a fragment of the message to encrypt each time.
Call psa_aead_verify().

If an error occurs at any step after a call to psa_aead_decrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application can call psa_aead_abort() at any time after the operation has been initialized.

After a successful call to psa_aead_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_aead_verify().
A call to psa_aead_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_aead_operation_t and not yet in use.
key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg	The AEAD algorithm to compute (`PSA_ALG_XXX` value such that PSA_ALG_IS_AEAD(`alg`) is true).

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be inactive.; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not permit the requested algorithm.; PSA_ERROR_INVALID_ARGUMENT key is not compatible with alg.; PSA_ERROR_NOT_SUPPORTED alg is not supported or is not an AEAD algorithm.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_encrypt()

psa_status_t psa_aead_encrypt	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	nonce,
		size_t	nonce_length,
		const uint8_t *	additional_data,
		size_t	additional_data_length,
		const uint8_t *	plaintext,
		size_t	plaintext_length,
		uint8_t *	ciphertext,
		size_t	ciphertext_size,
		size_t *	ciphertext_length
	)

Process an authenticated encryption operation.

Parameters

key	Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg	The AEAD algorithm to compute (`PSA_ALG_XXX` value such that PSA_ALG_IS_AEAD(`alg`) is true).
nonce	Nonce or IV to use.
nonce_length	Size of the nonce buffer in bytes. This must be appropriate for the selected algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH(`key_type`, `alg`) where `key_type` is the type of key.
additional_data	Additional data that will be authenticated but not encrypted.
additional_data_length	Size of additional_data in bytes.
plaintext	Data that will be authenticated and encrypted.
plaintext_length	Size of plaintext in bytes.
ciphertext	Output buffer for the authenticated and encrypted data. The additional data is not part of this output. For algorithms where the encrypted data and the authentication tag are defined as separate outputs, the authentication tag is appended to the encrypted data.
ciphertext_size	Size of the ciphertext buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_AEAD_ENCRYPT_OUTPUT_SIZE(`key_type`, `alg`, `plaintext_length`) where key_type is the type of key. PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE(`plaintext_length`) evaluates to the maximum ciphertext size of any supported AEAD encryption.
ciphertext_length	On success, the size of the output in the ciphertext buffer.

Returns: PSA_SUCCESS Success.; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not permit the requested algorithm.; PSA_ERROR_INVALID_ARGUMENT key is not compatible with alg.; PSA_ERROR_NOT_SUPPORTED alg is not supported or is not an AEAD algorithm.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_BUFFER_TOO_SMALL ciphertext_size is too small. PSA_AEAD_ENCRYPT_OUTPUT_SIZE() or PSA_AEAD_ENCRYPT_OUTPUT_MAX_SIZE() can be used to determine the required buffer size.; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_encrypt_setup()

psa_status_t psa_aead_encrypt_setup	(	psa_aead_operation_t *	operation,
		psa_key_id_t	key,
		psa_algorithm_t	alg
	)

Set the key for a multi-part authenticated encryption operation.

The sequence of operations to encrypt a message with authentication is as follows:

Allocate an operation object which will be passed to all the functions listed here
Initialize the operation object with one of the methods described in the documentation for psa_aead_operation_t, e.g. PSA_AEAD_OPERATION_INIT.
Call psa_aead_encrypt_setup() to specify the algorithm and key.
If needed, call psa_aead_set_lengths() to specify the length of the inputs to the subsequent calls to psa_aead_update_ad() and psa_aead_update(). See the documentation of psa_aead_set_lengths() for details.
Call either psa_aead_generate_nonce() or psa_aead_set_nonce() to generate or set the nonce. It is recommended to use psa_aead_generate_nonce() unless the protocol being implemented requires a specific nonce value.
Call psa_aead_update_ad() zero, one or more times, passing a fragment of the non-encrypted additional authenticated data each time.
Call psa_aead_update() zero, one or more times, passing a fragment of the message to encrypt each time.
Call psa_aead_finish().

If an error occurs at any step after a call to psa_aead_encrypt_setup(), the operation will need to be reset by a call to psa_aead_abort(). The application can call psa_aead_abort() at any time after the operation has been initialized.

After a successful call to psa_aead_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_aead_finish().
A call to psa_aead_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_aead_operation_t and not yet in use.
key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg	The AEAD algorithm to compute (`PSA_ALG_XXX` value such that PSA_ALG_IS_AEAD(`alg`) is true).

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be inactive.; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not permit the requested algorithm.; PSA_ERROR_INVALID_ARGUMENT key is not compatible with alg.; PSA_ERROR_NOT_SUPPORTED alg is not supported or is not an AEAD algorithm.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_finish()

psa_status_t psa_aead_finish	(	psa_aead_operation_t *	operation,
		uint8_t *	ciphertext,
		size_t	ciphertext_size,
		size_t *	ciphertext_length,
		uint8_t *	tag,
		size_t	tag_size,
		size_t *	tag_length
	)

Finish encrypting a message in an AEAD operation.

The operation must have been set up with psa_aead_encrypt_setup(). This function finishes the authentication of the additional data formed by concatenating the inputs passed to preceding calls to psa_aead_update_ad() with the plaintext formed by concatenating the inputs passed to preceding calls to psa_aead_update(). This function has two output buffers:

ciphertext contains trailing ciphertext that was buffered from preceding calls to psa_aead_update().
tag contains the authentication tag.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Parameters

operation	Active AEAD operation.
ciphertext	Buffer where the last part of the ciphertext is to be written.
ciphertext_size	Size of the ciphertext buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_AEAD_FINISH_OUTPUT_SIZE( `key_type`, `alg`) where `key_type` is the type of key and `alg` is the algorithm that were used to set up the operation PSA_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.
ciphertext_length	On success, the number of bytes of returned ciphertext.
tag	Buffer where the authentication tag is to be written.
tag_size	Size of the tag buffer in bytes. This must be appropriate for the selected algorithm and key: The exact tag size is PSA_AEAD_TAG_LENGTH(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size of the key, and `alg` is the algorithm that were used in the call to psa_aead_encrypt_setup(). PSA_AEAD_TAG_MAX_SIZE evaluates to the maximum tag size of any supported AEAD algorithm.
tag_length	On success, the number of bytes that make up the returned tag.

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be an active encryption operation with a nonce set.; PSA_ERROR_BUFFER_TOO_SMALL The size of the ciphertext or tag buffer is too small. PSA_AEAD_FINISH_OUTPUT_SIZE() or PSA_AEAD_FINISH_OUTPUT_MAX_SIZE can be used to determine the required ciphertext buffer size. PSA_AEAD_TAG_LENGTH() or PSA_AEAD_TAG_MAX_SIZE can be used to determine the required tag buffer size.; PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(); PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update() so far is less than the plaintext length that was previously specified with psa_aead_set_lengths().; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_generate_nonce()

psa_status_t psa_aead_generate_nonce	(	psa_aead_operation_t *	operation,
		uint8_t *	nonce,
		size_t	nonce_size,
		size_t *	nonce_length
	)

Generate a random nonce for an authenticated encryption operation.

This function generates a random nonce for the authenticated encryption operation with an appropriate size for the chosen algorithm, key type and key size.

The application must call psa_aead_encrypt_setup() before calling this function. If applicable for the algorithm, the application must call psa_aead_set_lengths() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Parameters

operation	Active AEAD operation.
nonce	Buffer where the generated nonce is to be written.
nonce_size	Size of the nonce buffer in bytes. This must be at least PSA_AEAD_NONCE_LENGTH(`key_type`, `alg`) where `key_type` and `alg` are type of key and the algorithm respectively that were used to set up the AEAD operation.
nonce_length	On success, the number of bytes of the generated nonce.

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be an active AEAD encryption operation, with no nonce set.; PSA_ERROR_BAD_STATE The operation state is not valid: this is an algorithm which requires psa_aead_set_lengths() to be called before setting the nonce.; PSA_ERROR_BUFFER_TOO_SMALL The size of the nonce buffer is too small. PSA_AEAD_NONCE_LENGTH() or PSA_AEAD_NONCE_MAX_SIZE can be used to determine the required buffer size.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_set_lengths()

psa_status_t psa_aead_set_lengths	(	psa_aead_operation_t *	operation,
		size_t	ad_length,
		size_t	plaintext_length
	)

Declare the lengths of the message and additional data for AEAD.

The application must call this function before calling psa_aead_set_nonce() or psa_aead_generate_nonce(), if the algorithm for the operation requires it. If the algorithm does not require it, calling this function is optional, but if this function is called then the implementation must enforce the lengths.

For PSA_ALG_CCM, calling this function is required.
For the other AEAD algorithms defined in this specification, calling this function is not required.
For vendor-defined algorithm, refer to the vendor documentation.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Parameters

operation	Active AEAD operation.
ad_length	Size of the non-encrypted additional authenticated data in bytes.
plaintext_length	Size of the plaintext to encrypt in bytes.

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be active, and psa_aead_set_nonce() and psa_aead_generate_nonce() must not have been called yet.; PSA_ERROR_INVALID_ARGUMENT At least one of the lengths is not acceptable for the chosen algorithm.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_set_nonce()

psa_status_t psa_aead_set_nonce	(	psa_aead_operation_t *	operation,
		const uint8_t *	nonce,
		size_t	nonce_length
	)

Set the nonce for an authenticated encryption or decryption operation.

This function sets the nonce for the authenticated encryption or decryption operation. The application must call psa_aead_encrypt_setup() or psa_aead_decrypt_setup() before calling this function. If applicable for the algorithm, the application must call psa_aead_set_lengths() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Note: When encrypting, psa_aead_generate_nonce() is recommended instead of using this function, unless implementing a protocol that requires a non-random IV.

Parameters

operation	Active AEAD operation.
nonce	Buffer containing the nonce to use.
nonce_length	Size of the nonce in bytes. This must be a valid nonce size for the chosen algorithm. The default nonce size is PSA_AEAD_NONCE_LENGTH (`key_type`, `alg`) where `key_type` and `alg` are type of key and the algorithm respectively that were used to set up the AEAD operation.

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be an active AEAD encryption operation, with no nonce set.; PSA_ERROR_BAD_STATE The operation state is not valid: this is an algorithm which requires psa_aead_set_lengths() to be called before setting the nonce.; PSA_ERROR_INVALID_ARGUMENT The size of nonce is not acceptable for the chosen algorithm.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_update()

psa_status_t psa_aead_update	(	psa_aead_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Encrypt or decrypt a message fragment in an active AEAD operation.

The following must occur before calling this function:

Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().
Call psa_aead_update_ad() to pass all the additional data.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

This function does not require the input to be aligned to any particular block boundary. If the implementation can only process a whole block at a time, it must consume all the input provided, but it might delay the end of the corresponding output until a subsequent call to psa_aead_update(), psa_aead_finish() or psa_aead_verify() provides sufficient input. The amount of data that can be delayed in this way is bounded by PSA_AEAD_UPDATE_OUTPUT_SIZE().

Warning: When decrypting, do not trust the input until psa_aead_verify() succeeds. See the detailed warning.

Parameters

operation	Active AEAD operation.
input	Buffer containing the message fragment to encrypt or decrypt.
input_length	Size of the input buffer in bytes.
output	Buffer where the output is to be written.
output_size	Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_AEAD_UPDATE_OUTPUT_SIZE( `key_type`, `alg`, `input_length`) where `key_type` is the type of key and `alg` is the algorithm that were used to set up the operation. PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE(`input_length`) evaluates to the maximum output size of any supported AEAD algorithm.
output_length	On success, the number of bytes that make up the returned output.

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be active, have a nonce set, and have lengths set if required by the algorithm.; PSA_ERROR_BUFFER_TOO_SMALL The size of the output buffer is too small. PSA_AEAD_UPDATE_OUTPUT_SIZE() or PSA_AEAD_UPDATE_OUTPUT_MAX_SIZE() can be used to determine the required buffer size.; PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(); PSA_ERROR_INVALID_ARGUMENT The total input length overflows the plaintext length that was previously specified with psa_aead_set_lengths().; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_update_ad()

psa_status_t psa_aead_update_ad	(	psa_aead_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length
	)

Pass additional data to an active AEAD operation.

Additional data is authenticated, but not encrypted. This function can be called multiple times to pass successive fragments of the additional data. This function must not be called after passing data to encrypt or decrypt with psa_aead_update().

The following must occur before calling this function:

Call either psa_aead_encrypt_setup() or psa_aead_decrypt_setup().
Set the nonce with psa_aead_generate_nonce() or psa_aead_set_nonce().

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Warning: When decrypting, do not trust the input until psa_aead_verify() succeeds. See the detailed warning.

Parameters

operation	Active AEAD operation.
input	Buffer containing the fragment of additional data.
input_length	Size of the input buffer in bytes.

Returns: PSA_SUCCESS Success.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be active, have a nonce set, have lengths set if required by the algorithm, and psa_aead_update() must not have been called yet.; PSA_ERROR_INVALID_ARGUMENT The total input length overflows the additional data length that was previously specified with psa_aead_set_lengths().; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_aead_verify()

psa_status_t psa_aead_verify	(	psa_aead_operation_t *	operation,
		uint8_t *	plaintext,
		size_t	plaintext_size,
		size_t *	plaintext_length,
		const uint8_t *	tag,
		size_t	tag_length
	)

Finish authenticating and decrypting a message in an AEAD operation.

The operation must have been set up with psa_aead_decrypt_setup(). This function finishes the authenticated decryption of the message components:

The additional data consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update_ad().
The ciphertext consisting of the concatenation of the inputs passed to preceding calls to psa_aead_update().
The tag passed to this function call.

If the authentication tag is correct, this function outputs any remaining plaintext and reports success. If the authentication tag is not correct, this function returns PSA_ERROR_INVALID_SIGNATURE.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_aead_abort().

Note: Implementations must make the best effort to ensure that the comparison between the actual tag and the expected tag is performed in constant time.

Parameters

operation	Active AEAD operation.
plaintext	Buffer where the last part of the plaintext is to be written. This is the remaining data from previous calls to psa_aead_update() that could not be processed until the end of the input.
plaintext_size	Size of the plaintext buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_AEAD_FINISH_OUTPUT_SIZE( `key_type`, `alg`) where `key_type` is the type of key and `alg` is the algorithm that were used to set up the operation PSA_AEAD_FINISH_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported AEAD algorithm.
plaintext_length	On success, the number of bytes of returned plaintext.
tag	Buffer containing the authentication tag.
tag_length	Size of the tag buffer in bytes.

Returns: PSA_SUCCESS Success.; PSA_ERROR_INVALID_SIGNATURE The calculations were successful, but the authentication tag is not correct.; PSA_ERROR_BAD_STATE The operation state is not valid: it must be an active encryption operation with a nonce set.; PSA_ERROR_BUFFER_TOO_SMALL The size of the plaintext buffer is too small. PSA_AEAD_VERIFY_OUTPUT_SIZE() or PSA_AEAD_VERIFY_OUTPUT_MAX_SIZE can be used to determine the required buffer size.; PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update_ad() so far is less than the additional data length that was previously specified with psa_aead_set_lengths(); PSA_ERROR_INVALID_ARGUMENT The total length of input to psa_aead_update() so far is less than the plaintext length that was previously specified with psa_aead_set_lengths().; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_asymmetric_decrypt()

psa_status_t psa_asymmetric_decrypt	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		const uint8_t *	salt,
		size_t	salt_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Decrypt a short message with a private key.

For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

Parameters

key	Identifier of the key to use for the operation. It must be an asymmetric key pair. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg	An asymmetric encryption algorithm that is compatible with the type of key.
input	The message to decrypt.
input_length	Size of the input buffer in bytes.
salt	A salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass `NULL`. If the algorithm supports an optional salt, pass `NULL` to indicate that there is no salt.
salt_length	Size of the salt buffer in bytes. If salt is `NULL`, pass 0.
output	Buffer where the decrypted message is to be written.
output_size	Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key: The required output size is PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE (`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of key. PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported asymmetric decryption.
output_length	On success, the number of bytes that make up the returned output.

Returns: PSA_SUCCESS; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not permit the requested algorithm.; PSA_ERROR_BUFFER_TOO_SMALL The size of the output buffer is too small. PSA_ASYMMETRIC_DECRYPT_OUTPUT_SIZE() or PSA_ASYMMETRIC_DECRYPT_OUTPUT_MAX_SIZE can be used to determine the required buffer size.; PSA_ERROR_NOT_SUPPORTED; PSA_ERROR_INVALID_ARGUMENT; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_INSUFFICIENT_ENTROPY; PSA_ERROR_INVALID_PADDING; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_asymmetric_encrypt()

psa_status_t psa_asymmetric_encrypt	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		const uint8_t *	salt,
		size_t	salt_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Encrypt a short message with a public key.

For PSA_ALG_RSA_PKCS1V15_CRYPT, no salt is supported.

Parameters

key	Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg	An asymmetric encryption algorithm that is compatible with the type of key.
input	The message to encrypt.
input_length	Size of the input buffer in bytes.
salt	A salt or label, if supported by the encryption algorithm. If the algorithm does not support a salt, pass `NULL`. If the algorithm supports an optional salt, pass `NULL` to indicate that there is no salt.
salt_length	Size of the salt buffer in bytes. If salt is `NULL`, pass 0.
output	Buffer where the encrypted message is to be written.
output_size	Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key: The required output size is PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE (`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of key PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported asymmetric encryption.
output_length	On success, the number of bytes that make up the returned output.

Returns: PSA_SUCCESS; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not permit the requested algorithm.; PSA_ERROR_BUFFER_TOO_SMALL The size of the output buffer is too small. PSA_ASYMMETRIC_ENCRYPT_OUTPUT_SIZE() or PSA_ASYMMETRIC_ENCRYPT_OUTPUT_MAX_SIZE can be used to determine the required buffer size.; PSA_ERROR_NOT_SUPPORTED; PSA_ERROR_INVALID_ARGUMENT; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_INSUFFICIENT_ENTROPY; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_builtin_generate_key()

psa_status_t psa_builtin_generate_key	(	const psa_key_attributes_t *	attributes,
		uint8_t *	key_buffer,
		size_t	key_buffer_size,
		size_t *	key_buffer_length
	)

Built-in key generation function.

This function generates a random symmetric key. As of yet it does not implement asymmetric key generation.

Parameters

attributes
key_buffer
key_buffer_size
key_buffer_length

Returns: psa_status_t

◆ psa_builtin_generate_random()

psa_status_t psa_builtin_generate_random	(	uint8_t *	output,
		size_t	output_size
	)

Built-in function for random number generation.

This function is being used to generate a random number if no other driver for random number generation is present. It uses the RIOT RNG module as a default backend.

Parameters

output	Output buffer of the size of the random number to be generated.
output_size	Size of `output` in bytes

Returns: PSA_SUCCESS; PSA_ERROR_INVALID_ARGUMENT output is NULL

◆ psa_builtin_import_key()

psa_status_t psa_builtin_import_key	(	const psa_key_attributes_t *	attributes,
		const uint8_t *	data,
		size_t	data_length,
		uint8_t *	key_buffer,
		size_t	key_buffer_size,
		size_t *	key_buffer_length,
		size_t *	bits
	)

Built-in key import function.

Copies a plain key into local memory. This function is used by the implementation, when an imported key is stored only in local memory.

Parameters

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type is required, and determines how the data buffer is interpreted.
The key size is always determined from the data buffer. If the key size in attributes is nonzero, it must be equal to the size determined from data.
The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.
The key usage flags define what operations are permitted with the key, see Key usage flags.
The key lifetime and identifier are required for a persistent key.

Note: This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

Parameters

data	Buffer containing the key data. The content of this buffer is interpreted according to the type declared in attributes. All implementations must support at least the format described in the documentation of psa_export_key() or psa_export_public_key() for the chosen type. Implementations can support other formats, but be conservative in interpreting the key data: it is recommended that implementations reject content if it might be erroneous, for example, if it is the wrong type or is truncated.
data_length	Size of the data buffer in bytes.
key_buffer	Pointer to buffer containing the plain text key material
key_buffer_size	Size of `key_buffer` in bytes
key_buffer_length	Size of the key buffer
bits	Size of the key in bits

Returns

PSA_SUCCESS Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

The key size is nonzero, and is incompatible with the key data in data.

PSA_ERROR_NOT_SUPPORTED The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.

◆ psa_cipher_abort()

psa_status_t psa_cipher_abort ( psa_cipher_operation_t * operation )

Abort a cipher operation.

Aborting an operation frees all associated resources except for the operation object itself. Once aborted, the operation object can be reused for another operation by calling psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() again.

This function can be called any time after the operation object has been initialized as described in psa_cipher_operation_t.

In particular, calling psa_cipher_abort() after the operation has been terminated by a call to psa_cipher_abort() or psa_cipher_finish() is safe and has no effect.

Parameters

operation Initialized cipher operation.

Returns: PSA_SUCCESS Success. The operation object can now be discarded or reused.; PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_CORRUPTION_DETECTED

◆ psa_cipher_decrypt()

psa_status_t psa_cipher_decrypt	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Decrypt a message using a symmetric cipher.

This function decrypts a message encrypted with a symmetric cipher. * The input to this function must contain the IV followed by the ciphertext, as output by psa_cipher_encrypt(). The IV must be PSA_CIPHER_IV_LENGTH(key_type, alg) bytes in length, where key_type is the type of key.

Use the multi-part operation interface with a psa_cipher_operation_t object to decrypt data which is not in the expected input format.

Parameters

key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg	The cipher algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_CIPHER(`alg`) is true.
input	Buffer containing the message to decrypt. This consists of the IV followed by the ciphertext proper.
input_length	Size of the input buffer in bytes.
output	Buffer where the plaintext is to be written.
output_size	Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_CIPHER_DECRYPT_OUTPUT_SIZE( `key_type`, `alg`, `input_length`) where `key_type` is the type of key. PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE(`input_length`) evaluates to the maximum output size of any supported cipher decryption.
output_length	On success, the number of bytes that make up the output.

Returns

PSA_SUCCESS Success. The first (*output_length) bytes of output contain the plaintext.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL The size of the output buffer is too small. PSA_CIPHER_DECRYPT_OUTPUT_SIZE() or PSA_CIPHER_DECRYPT_OUTPUT_MAX_SIZE() can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_PADDING The algorithm uses padding, and the input does not contain valid padding.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a cipher algorithm.
key is not compatible with alg.
The input_length is not valid for the algorithm and key type. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a cipher algorithm.
key is not supported for use with alg.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_cipher_decrypt_setup()

psa_status_t psa_cipher_decrypt_setup	(	psa_cipher_operation_t *	operation,
		psa_key_id_t	key,
		psa_algorithm_t	alg
	)

Set the key for a multi-part symmetric decryption operation.

The sequence of operations to decrypt a message with a symmetric cipher is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
Call psa_cipher_decrypt_setup() to specify the algorithm and key.
Call psa_cipher_set_iv() with the initialization vector (IV) for the decryption, if the algorithm requires one. This must match the IV used for the encryption.
Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
Call psa_cipher_finish().

If an error occurs at any step after a call to psa_cipher_decrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application can call psa_cipher_abort() at any time after the operation has been initialized.

After a successful call to psa_cipher_decrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_cipher_finish().
A call to psa_cipher_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_cipher_operation_t and not yet in use.
key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_DECRYPT.
alg	The cipher algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_CIPHER(`alg`) is true.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_DECRYPT flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a cipher algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a cipher algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_cipher_encrypt()

psa_status_t psa_cipher_encrypt	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Encrypt a message using a symmetric cipher.

This function encrypts a message with a random initialization vector (IV). The length of the IV is PSA_CIPHER_IV_LENGTH(key_type, alg) where key_type is the type of key. The output of psa_cipher_encrypt() is the IV followed by the ciphertext.

Use the multi-part operation interface with a psa_cipher_operation_t object to provide other forms of IV or to manage the IV and ciphertext independently.

Parameters

key	Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg	The cipher algorithm to compute (`PSA_ALG_XXX` value such that PSA_ALG_IS_CIPHER(`alg`) is true).
input	Buffer containing the message to encrypt.
input_length	Size of the input buffer in bytes.
output	Buffer where the output is to be written. The output contains the IV followed by the ciphertext proper.
output_size	Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_CIPHER_ENCRYPT_OUTPUT_SIZE( `key_type`, `alg`, `input_length`) where `key_type` is the type of key PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE(`input_length`) evaluates to the maximum output size of any supported cipher encryption.
output_length	On success, the number of bytes that make up the output.

Returns: PSA_SUCCESS Success.; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not permit the requested algorithm.; PSA_ERROR_INVALID_ARGUMENT key is not compatible with alg.; PSA_ERROR_INVALID_ARGUMENT The input_length is not valid for the algorithm and key type. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.; PSA_ERROR_NOT_SUPPORTED alg is not supported or is not a cipher algorithm.; PSA_ERROR_BUFFER_TOO_SMALL output_size is too small. PSA_CIPHER_ENCRYPT_OUTPUT_SIZE() or PSA_CIPHER_ENCRYPT_OUTPUT_MAX_SIZE() can be used to determine the required buffer size.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_cipher_encrypt_setup()

psa_status_t psa_cipher_encrypt_setup	(	psa_cipher_operation_t *	operation,
		psa_key_id_t	key,
		psa_algorithm_t	alg
	)

Set the key for a multi-part symmetric encryption operation.

The sequence of operations to encrypt a message with a symmetric cipher is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_cipher_operation_t, e.g. PSA_CIPHER_OPERATION_INIT.
Call psa_cipher_encrypt_setup() to specify the algorithm and key.
Call either psa_cipher_generate_iv() or psa_cipher_set_iv() to generate or set the initialization vector (IV), if the algorithm requires one. It is recommended to use psa_cipher_generate_iv() unless the protocol being implemented requires a specific IV value.
Call psa_cipher_update() zero, one or more times, passing a fragment of the message each time.
Call psa_cipher_finish().

If an error occurs at any step after a call to psa_cipher_encrypt_setup(), the operation will need to be reset by a call to psa_cipher_abort(). The application can call psa_cipher_abort() at any time after the operation has been initialized.

After a successful call to psa_cipher_encrypt_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_cipher_finish().
A call to psa_cipher_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_cipher_operation_t and not yet in use.
key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_ENCRYPT.
alg	The cipher algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_CIPHER(`alg`) is true.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_ENCRYPT flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a cipher algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a cipher algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_cipher_finish()

psa_status_t psa_cipher_finish	(	psa_cipher_operation_t *	operation,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Finish encrypting or decrypting a message in a cipher operation.

The application must call psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() before calling this function. The choice of setup function determines whether this function encrypts or decrypts its input.

This function finishes the encryption or decryption of the message formed by concatenating the inputs passed to preceding calls to psa_cipher_update().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters

operation	Active cipher operation.
output	Buffer where the output is to be written.
output_size	Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_CIPHER_FINISH_OUTPUT_SIZE( `key_type`, `alg`) where `key_type` is the type of key and `alg` is the algorithm that were used to set up the operation. PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported cipher algorithm.
output_length	On success, the number of bytes that make up the returned output.

Returns

PSA_SUCCESS Success. The first (*output_length) bytes of output contain the final output.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active, with an IV set if required for the algorithm.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL The size of the output buffer is too small. PSA_CIPHER_FINISH_OUTPUT_SIZE() or PSA_CIPHER_FINISH_OUTPUT_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_PADDING This is a decryption operation for an algorithm that includes padding, and the ciphertext does not contain valid padding.

PSA_ERROR_INVALID_ARGUMENT The total input size passed to this operation is not valid for this particular algorithm. For example, the algorithm is a based on block cipher and requires a whole number of blocks, but the total input size is not a multiple of the block size.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_cipher_generate_iv()

psa_status_t psa_cipher_generate_iv	(	psa_cipher_operation_t *	operation,
		uint8_t *	iv,
		size_t	iv_size,
		size_t *	iv_length
	)

Generate an initialization vector (IV) for a symmetric encryption operation.

This function generates a random IV, nonce or initial counter value for the encryption operation as appropriate for the chosen algorithm, key type and key size.

The generated IV is always the default length for the key and algorithm: PSA_CIPHER_IV_LENGTH(key_type, alg), where key_type is the type of key and alg is the algorithm that were used to set up the operation. To generate different lengths of IV, use psa_generate_random() and psa_cipher_set_iv().

If the cipher algorithm does not use an IV, calling this function returns a PSA_ERROR_BAD_STATE error. For these algorithms, PSA_CIPHER_IV_LENGTH( key_type, alg) will be zero.

The application must call psa_cipher_encrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters

operation	Active cipher operation.
iv	Buffer where the generated IV is to be written.
iv_size	Size of the iv buffer in bytes. This must be at least PSA_CIPHER_IV_LENGTH(`key_type`, `alg`) where `key_type` and `alg` are type of key and the algorithm respectively that were used to set up the cipher operation.
iv_length	On success, the number of bytes of the generated IV.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE Either:

The cipher algorithm does not use an IV.
The operation state is not valid: it must be active, with no IV set.

PSA_ERROR_BUFFER_TOO_SMALL The size of the iv buffer is too small. PSA_CIPHER_IV_LENGTH() or PSA_CIPHER_IV_MAX_SIZE can be used to determine the required buffer size.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_HARDWARE_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_cipher_set_iv()

psa_status_t psa_cipher_set_iv	(	psa_cipher_operation_t *	operation,
		const uint8_t *	iv,
		size_t	iv_length
	)

Set the initialization vector (IV) for a symmetric encryption or decryption operation.

This function sets the IV, nonce or initial counter value for the encryption or decryption operation.

If the cipher algorithm does not use an IV, calling this function returns a PSA_ERROR_BAD_STATE error. For these algorithms, PSA_CIPHER_IV_LENGTH(key_type, alg) will be zero.

The application must call psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Note: When encrypting, psa_cipher_generate_iv() is recommended instead of using this function, unless implementing a protocol that requires a non-random IV.

Parameters

operation	Active cipher operation.
iv	Buffer containing the IV to use.
iv_length	Size of the IV in bytes.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The cipher algorithm does not use an IV.
The operation state is not valid: it must be an active cipher encrypt operation, with no IV set.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

The chosen algorithm does not use an IV.
iv_length is not valid for the chosen algorithm.

PSA_ERROR_NOT_SUPPORTED iv_length is not supported for use with the operation’s algorithm and key.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_cipher_update()

psa_status_t psa_cipher_update	(	psa_cipher_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Encrypt or decrypt a message fragment in an active cipher operation.

The following must occur before calling this function:

Call either psa_cipher_encrypt_setup() or psa_cipher_decrypt_setup(). The choice of setup function determines whether this function encrypts or decrypts its input.
If the algorithm requires an IV, call psa_cipher_generate_iv() or psa_cipher_set_iv(). psa_cipher_generate_iv() is recommended when encrypting.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_cipher_abort().

Parameters

operation	Active cipher operation.
input	Buffer containing the message fragment to encrypt or decrypt.
input_length	Size of the `input` buffer in bytes.
output	Buffer where the output is to be written.
output_size	Size of the output buffer in bytes. This must be appropriate for the selected algorithm and key: A sufficient output size is PSA_CIPHER_UPDATE_OUTPUT_SIZE( `key_type`, `alg`, `input_length`) where `key_type` is the type of key and `alg` is the algorithm that were used to set up the operation. PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE(`input_length`) evaluates to the maximum output size of any supported cipher algorithm.
output_length	On success, the number of bytes that make up the returned output.

Returns

PSA_SUCCESS Success. The first (*output_length) bytes of output contain the output data.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active, with an IV set if required for the algorithm.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL The size of the output buffer is too small. PSA_CIPHER_UPDATE_OUTPUT_SIZE() or PSA_CIPHER_UPDATE_OUTPUT_MAX_SIZE() can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT The total input size passed to this operation is too large for this particular algorithm.

PSA_ERROR_NOT_SUPPORTED The total input size passed to this operation is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_copy_key()

psa_status_t psa_copy_key	(	psa_key_id_t	source_key,
		const psa_key_attributes_t *	attributes,
		psa_key_id_t *	target_key
	)

Make a copy of a key.

Copy key material from one location to another. * This function is primarily useful to copy a key from one location to another, as it populates a key using the material from another key which can have a different lifetime.

This function can be used to share a key with a different party, subject to implementation-defined restrictions on key sharing.

The policy on the source key must have the usage flag PSA_KEY_USAGE_COPY set. This flag is sufficient to permit the copy if the key has the lifetime PSA_KEY_LIFETIME_VOLATILE or PSA_KEY_LIFETIME_PERSISTENT. Some secure elements do not provide a way to copy a key without making it extractable from the secure element. If a key is located in such a secure element, then the key must have both usage flags PSA_KEY_USAGE_COPY and PSA_KEY_USAGE_EXPORT in order to make a copy of the key outside the secure element.

The resulting key can only be used in a way that conforms to both the policy of the original key and the policy specified in the attributes parameter:

The usage flags on the resulting key are the bitwise-and of the usage flags on the source policy and the usage flags in attributes.
If both permit the same algorithm or wildcard-based algorithm, the resulting key has the same permitted algorithm.
If either of the policies permits an algorithm and the other policy allows a wildcard-based permitted algorithm that includes this algorithm, the resulting key uses this permitted algorithm.
If the policies do not permit any algorithm in common, this function fails with the status PSA_ERROR_INVALID_ARGUMENT.

The effect of this function on implementation-defined attributes is implementation-defined.

Parameters

source_key The key to copy. It must allow the usage PSA_KEY_USAGE_COPY. If a private or secret key is being copied outside of a secure element it must also allow PSA_KEY_USAGE_EXPORT.

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type and size can be 0. If either is nonzero, it must match the corresponding attribute of the source key.
The key location (the lifetime and, for persistent keys, the key identifier) is used directly.
The key policy (usage flags and permitted algorithm) are combined from the source key and attributes so that both sets of restrictions apply, as described in the documentation of this function.

Note: This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

Parameters

target_key On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns

PSA_SUCCESS Success. If the new key is persistent, the key material and the key’s metadata have been saved to persistent storage.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE source_key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The following conditions can result in this error:

source_key does not have the PSA_KEY_USAGE_COPY usage flag.
source_key does not have the PSA_KEY_USAGE_EXPORT usage flag, and its storage location does not allow copying it to the target key’s storage location.
The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.

PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

attributes specifies a key type or key size which does not match the attributes of source_key.
The lifetime or identifier in attributes are invalid.
The key policies from source_key and those specified in attributes are incompatible.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

The source_key storage location does not support copying to the target key’s storage location.
The key attributes, as a whole, are not supported in the target key’s storage location.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_crypto_init()

psa_status_t psa_crypto_init ( void )

Library initialization.

Applications must call this function before calling any other function in this module. Applications are permitted to call this function more than once. Once a call succeeds, subsequent calls are guaranteed to succeed.

If the application calls other functions before calling psa_crypto_init(), the behavior is undefined. In this situation:

Implementations are encouraged to either perform the operation as if the library had been initialized or to return PSA_ERROR_BAD_STATE or some other applicable error.
Implementations must not return a success status if the lack of initialization might have security implications, for example due to improper seeding of the random number generator.

Returns: PSA_SUCCESS; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_INSUFFICIENT_ENTROPY

◆ psa_destroy_key()

psa_status_t psa_destroy_key ( psa_key_id_t key )

Destroy a key.

This function destroys a key from both volatile memory and, if applicable, non-volatile storage. Implementations must make a best effort to ensure that that the key material cannot be recovered.

This function also erases any metadata such as policies and frees resources associated with the key. Destroying the key makes the key identifier invalid, and the key identifier must not be used again by the application.

If a key is currently in use in a multi-part operation, then destroying the key will cause the multi-part operation to fail.

Warning: This implementation uses a virtual file system for storing and reading persistent keys to and from flash. Destroying a key only unlinks the file and does not erase the actual key data from flash. Anyone with hardware access can still recover the key material.

Parameters

key	Identifier of the key to erase. If this is PSA_KEY_ID_NULL, do nothing and return PSA_SUCCESS.

Returns: PSA_SUCCESS Success. If key was a valid key identifier, then the key material that it referred to has been erased. Alternatively, key was PSA_KEY_ID_NULL.; PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().; PSA_ERROR_INVALID_HANDLE key is neither a valid key identifier, nor PSA_KEY_ID_NULL.; PSA_ERROR_NOT_PERMITTED The key cannot be erased because it is read-only, either due to a policy or due to physical restrictions.; PSA_ERROR_COMMUNICATION_FAILURE There was an failure in communication with the cryptoprocessor. The key material might still be present in the cryptoprocessor.; PSA_ERROR_CORRUPTION_DETECTED An unexpected condition which is not a storage corruption or a communication failure occurred. The cryptoprocessor might have been compromised.; PSA_ERROR_STORAGE_FAILURE The storage operation failed. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.; PSA_ERROR_DATA_CORRUPT The storage is corrupted. Implementations must make a best effort to erase key material even in this situation, however, it might be impossible to guarantee that the key material is not recoverable in such cases.; PSA_ERROR_DATA_INVALID

◆ psa_export_key()

psa_status_t psa_export_key	(	psa_key_id_t	key,
		uint8_t *	data,
		size_t	data_size,
		size_t *	data_length
	)

Export a key in binary format.

The output of this function can be passed to psa_import_key() to create an equivalent object.

If the implementation of psa_import_key() supports other formats beyond the format specified here, the output from psa_export_key() must use the representation specified here, not the original representation.

For standard key types, the output format is as follows:

For symmetric keys, excluding HMAC keys, the format is the raw bytes of the key.
For HMAC keys that are shorter than, or equal in size to, the underlying hash algorithm block size, the format is the raw bytes of the key.
For HMAC keys that are longer than the underlying hash algorithm block size, the format is an implementation defined choice between the following formats:
- The raw bytes of the key.
- The raw bytes of the hash of the key, using the underlying hash algorithm. See also PSA_KEY_TYPE_HMAC.
For DES, the key data consists of 8 bytes. The parity bits must be correct.
For Triple-DES, the format is the concatenation of the two or three DES keys.
For RSA key pairs, with key type PSA_KEY_TYPE_RSA_KEY_PAIR, the format is the non-encrypted DER encoding of the representation defined by in PKCS #1: RSA Cryptography Specifications Version 2.2 [RFC8017] as RSAPrivateKey, version 0.
RSAPrivateKey ::= SEQUENCE {

version INTEGER, -- must be 0

modulus INTEGER, -- n

publicExponent INTEGER, -- e

privateExponent INTEGER, -- d

prime1 INTEGER, -- p

prime2 INTEGER, -- q

exponent1 INTEGER, -- d mod (p-1)

exponent2 INTEGER, -- d mod (q-1)

coefficient INTEGER, -- (inverse of q) mod p

}

Note
Although it is possible to define an RSA key pair or private key using a subset of these elements, the output from psa_export_key() for an RSA key pair must include all of these elements.
For elliptic curve key pairs, with key types for which PSA_KEY_TYPE_IS_ECC_KEY_PAIR () is true, the format is a representation of the private value.
- For Weierstrass curve families PSA_ECC_FAMILY_SECT_XX, PSA_ECC_FAMILY_SECP_XX, PSA_ECC_FAMILY_FRP and PSA_ECC_FAMILY_BRAINPOOL_P_R1, the content of the privateKey field of the ECPrivateKey format defined by Elliptic Curve Private Key Structure [RFC5915]. This is a ceiling(m/8)-byte string in big-endian order where m is the key size in bits.
- For curve family PSA_ECC_FAMILY_MONTGOMERY, the scalar value of the ‘private key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. The value must have the forced bits set to zero or one as specified by decodeScalar25519() and decodeScalar448() in [RFC7748] §5. This is a ceiling(m/8)-byte string where m is the key size in bits. This is 32 bytes for Curve25519, and 56 bytes for Curve448.
- For the Twisted Edwards curve family PSA_ECC_FAMILY_TWISTED_EDWARDS, the private key is defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]. This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.
For Diffie-Hellman key exchange key pairs, with key types for which PSA_KEY_TYPE_IS_DH_KEY_PAIR() is true, the format is the representation of the private key x as a big-endian byte string. The length of the byte string is the private key size in bytes, and leading zeroes are not stripped.
For public keys, with key types for which PSA_KEY_TYPE_IS_PUBLIC_KEY() is true, the format is the same as for psa_export_public_key().

The policy on the key must have the usage flag PSA_KEY_USAGE_EXPORT set.

Parameters

key	Identifier of the key to export. It must allow the usage PSA_KEY_USAGE_EXPORT, unless it is a public key.
data	Buffer where the key data is to be written.
data_size	Size of the data buffer in bytes. This must be appropriate for the key: The required output size is PSA_EXPORT_KEY_OUTPUT_SIZE(`type`, `bits`) where `type` is the key type and `bits` is the key size in bits. PSA_EXPORT_KEY_PAIR_MAX_SIZE evaluates to the maximum output size of any supported key pair. PSA_EXPORT_PUBLIC_KEY_MAX_SIZE evaluates to the maximum output size of any supported public key. This API defines no maximum size for symmetric keys. Arbitrarily large data items can be stored in the key store, for example certificates that correspond to a stored private key or input material for key derivation.
data_length	On success, the number of bytes that make up the key data.

Returns

PSA_SUCCESS Success. The first (*data_length) bytes of data contain the exported key

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_EXPORT flag.

PSA_ERROR_BUFFER_TOO_SMALL The size of the data buffer is too small. PSA_EXPORT_KEY_OUTPUT_SIZE() or PSA_EXPORT_KEY_PAIR_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

The key’s storage location does not support export of the key
The implementation does not support export of keys with this key type.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_export_public_key()

psa_status_t psa_export_public_key	(	psa_key_id_t	key,
		uint8_t *	data,
		size_t	data_size,
		size_t *	data_length
	)

Export a public key or the public part of a key pair in binary format.

The output of this function can be passed to psa_import_key() to create an object that is equivalent to the public key.

If the implementation of psa_import_key() supports other formats beyond the format specified here, the output from psa_export_public_key() must use the representation specified here, not the original representation.

For standard key types, the output format is as follows:

For RSA public keys, with key type PSA_KEY_TYPE_RSA_PUBLIC_KEY, the DER encoding of the representation defined by Algorithms and Identifiers for the Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile [RFC3279] §2.3.1 as RSAPublicKey.
RSAPublicKey ::= SEQUENCE {

modulus INTEGER, -- n

publicExponent INTEGER } -- e
For elliptic curve key pairs, with key types for which PSA_KEY_TYPE_IS_ECC_PUBLIC_KEY() is true, the format depends on the key family:
- For Weierstrass curve families PSA_ECC_FAMILY_SECT_XX, PSA_ECC_FAMILY_SECP_XX, PSA_ECC_FAMILY_FRP and PSA_ECC_FAMILY_BRAINPOOL_P_R1, the uncompressed representation of an elliptic curve point as an octet string defined in SEC 1: Elliptic Curve Cryptography [SEC1] §2.3.3. If m is the bit size associated with the curve, i.e. the bit size of q for a curve over F_q. The representation consists of:
  - The byte 0x04;
  - x_P as a ceiling(m/8)-byte string, big-endian;
  - y_P as a ceiling(m/8)-byte string, big-endian.
- For curve family PSA_ECC_FAMILY_MONTGOMERY, the scalar value of the ‘public key’ in little-endian order as defined by Elliptic Curves for Security [RFC7748] §6. This is a ceiling(m/8)-byte string where m is the key size in bits.
  - This is 32 bytes for Curve25519, computed as X25519(private_key, 9).
  - This is 56 bytes for Curve448, computed as X448(private_key, 5).
- For curve family PSA_ECC_FAMILY_TWISTED_EDWARDS, the public key is defined by Edwards-Curve Digital Signature Algorithm (EdDSA) [RFC8032]. This is a 32-byte string for Edwards25519, and a 57-byte string for Edwards448.
For Diffie-Hellman key exchange public keys, with key types for which PSA_KEY_TYPE_IS_DH_PUBLIC_KEY is true, the format is the representation of the public key y = g^x mod p as a big-endian byte string. The length of the byte string is the length of the base prime p in bytes. Exporting a public key object or the public part of a key pair is always permitted, regardless of the key’s usage flags.

Parameters

key	Identifier of the key to export.
data	Buffer where the key data is to be written.
data_size	Size of the `data` buffer in bytes. This must be appropriate for the key: The required output size is PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE( `type`, `bits`) where `type` is the key type and `bits` is the key size in bits. PSA_EXPORT_PUBLIC_KEY_MAX_SIZE evaluates to the maximum output size of any supported public key or public part of a key pair.
data_length	On success, the number of bytes that make up the key data.

Returns

PSA_SUCCESS Success. The first (*data_length) bytes of data contain the exported public key.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_BUFFER_TOO_SMALL The size of the data buffer is too small. PSA_EXPORT_PUBLIC_KEY_OUTPUT_SIZE() or PSA_EXPORT_PUBLIC_KEY_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT The key is neither a public key nor a key pair.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

The key’s storage location does not support export of the key.
The implementation does not support export of keys with this key type.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_generate_key()

psa_status_t psa_generate_key	(	const psa_key_attributes_t *	attributes,
		psa_key_id_t *	key
	)

Generate a key or key pair.

The key is generated randomly. Its location, policy, type and size are taken from attributes.

Implementations must reject an attempt to generate a key of size 0.

The following type-specific considerations apply:

For RSA keys (PSA_KEY_TYPE_RSA_KEY_PAIR), the public exponent is 65537. The modulus is a product of two probabilistic primes between 2^{n-1} and 2^n where n is the bit size specified in the attributes.

Parameters

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type is required. It cannot be an asymmetric public key.
The key size is required. It must be a valid size for the key type.
The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.
The key usage flags define what operations are permitted with the key, see Key usage flags.
The key lifetime and identifier are required for a persistent key.

Note: This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

Parameters

key	On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns: PSA_SUCCESS Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.; PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.; PSA_ERROR_NOT_SUPPORTED The key type or key size is not supported, either by the implementation in general or in this particular persistent location.; PSA_ERROR_INVALID_ARGUMENT The key attributes, as a whole, are invalid.; PSA_ERROR_INVALID_ARGUMENT The key type is an asymmetric public key type.; PSA_ERROR_INVALID_ARGUMENT The key size is not a valid size for the key type.; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_INSUFFICIENT_ENTROPY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_INSUFFICIENT_STORAGE; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_generate_random()

psa_status_t psa_generate_random	(	uint8_t *	output,
		size_t	output_size
	)

Generate random bytes.

Warning: This function can fail! Callers MUST check the return status and MUST NOT use the content of the output buffer if the return status is not PSA_SUCCESS.

Note: To generate a key, use psa_generate_key() instead.

Parameters

output	Output buffer for the generated data.
output_size	Number of bytes to generate and output.

Returns: PSA_SUCCESS Success. output contains output_size bytes of generated random data.; PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().; PSA_ERROR_INVALID_ARGUMENT output is NULL; PSA_ERROR_NOT_SUPPORTED; PSA_ERROR_INSUFFICIENT_ENTROPY; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_CORRUPTION_DETECTED

◆ psa_get_key_algorithm()

static psa_algorithm_t psa_get_key_algorithm ( const psa_key_attributes_t * attributes )

inlinestatic

Retrieve the permitted algorithm policy from key attributes.

Parameters

attributes The key attribute object to query.

Returns: psa_algorithm_t The algorithm stored in the attribute object.

Definition at line 1880 of file crypto.h.

◆ psa_get_key_attributes()

psa_status_t psa_get_key_attributes	(	psa_key_id_t	key,
		psa_key_attributes_t *	attributes
	)

Retrieve the attributes of a key.

This function first resets the attribute object as with psa_reset_key_attributes(). It then copies the attributes of the given key into the given attribute object.

Note: This function clears any previous content from the attribute object and therefore expects it to be in a valid state. In particular, if this function is called on a newly allocated attribute object, the attribute object must be initialized before calling this function.

Parameters

key	Identifier of the key to query.
attributes	On entry, `*attributes` must be in a valid state. On successful return, it contains the attributes of the key. On failure, it is equivalent to a freshly-initialized attribute object.

Returns: PSA_SUCCESS; PSA_ERROR_INVALID_HANDLE; PSA_ERROR_INSUFFICIENT_MEMORY; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_get_key_bits()

static size_t psa_get_key_bits ( const psa_key_attributes_t * attributes )

inlinestatic

Retrieve the key size from key attributes.

Parameters

attributes The key attribute object to query.

Returns: size_t The key size stored in the attribute object, in bits.

Definition at line 1908 of file crypto.h.

◆ psa_get_key_id()

static psa_key_id_t psa_get_key_id ( const psa_key_attributes_t * attributes )

inlinestatic

Retrieve the key identifier from key attributes.

Parameters

attributes The key attribute object to query.

Returns: psa_key_id_t The persistent identifier stored in the attribute object. This value is unspecified if the attribute object declares the key as volatile.

Definition at line 1943 of file crypto.h.

◆ psa_get_key_lifetime()

static psa_key_lifetime_t psa_get_key_lifetime ( const psa_key_attributes_t * attributes )

inlinestatic

Retrieve the lifetime from key attributes.

Parameters

attributes The key attribute object to query.

Returns: psa_key_lifetime_t The lifetime value stored in the attribute object.

Definition at line 1979 of file crypto.h.

◆ psa_get_key_type()

static psa_key_type_t psa_get_key_type ( const psa_key_attributes_t * attributes )

inlinestatic

Retrieve the key type from key attributes.

Parameters

attributes The key attribute object to query.

Returns: psa_key_type_t The key type stored in the attribute object.

Definition at line 2006 of file crypto.h.

◆ psa_get_key_usage_flags()

static psa_key_usage_t psa_get_key_usage_flags ( const psa_key_attributes_t * attributes )

inlinestatic

Retrieve the usage flags from key attributes.

Parameters

attributes The key attribute object to query.

Returns: psa_key_usage_t The usage flags stored in the attribute object.

Definition at line 2035 of file crypto.h.

◆ psa_hash_abort()

psa_status_t psa_hash_abort ( psa_hash_operation_t * operation )

Abort a hash operation.

Aborting an operation frees all associated resources except for the operation structure itself. Once aborted, the operation object can be reused for another operation by calling psa_hash_setup() again.

You may call this function any time after the operation object has been initialized by one of the methods described in psa_hash_operation_t.

In particular, calling psa_hash_abort() after the operation has been terminated by a call to psa_hash_abort(), psa_hash_finish() or psa_hash_verify() is safe and has no effect.

Parameters

operation Initialized hash operation.

Returns: PSA_SUCCESS; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_HARDWARE_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_BAD_STATE The library has not been previously initialized by psa_crypto_init(). It is implementation-dependent whether a failure to initialize results in this error code.

◆ psa_hash_clone()

psa_status_t psa_hash_clone	(	const psa_hash_operation_t *	source_operation,
		psa_hash_operation_t *	target_operation
	)

Clone a hash operation.

This function copies the state of an ongoing hash operation to a new operation object. In other words, this function is equivalent to calling psa_hash_setup() on target_operation with the same algorithm that source_operation was set up for, then psa_hash_update() on target_operation with the same input that that was passed to source_operation. After this function returns, the two objects are independent, i.e. subsequent calls involving one of the objects do not affect the other object.

Parameters

source_operation	The active hash operation to clone.
target_operation	The operation object to set up. It must be initialized but not active.

Returns

PSA_SUCCESS

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The source_operation state is not valid: it must be active.
The target_operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_HARDWARE_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_INSUFFICIENT_MEMORY

◆ psa_hash_compare()

psa_status_t psa_hash_compare	(	psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		const uint8_t *	hash,
		size_t	hash_length
	)

Calculate the hash (digest) of a message and compare it with a reference value.

Parameters

alg	The hash algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(`alg`) is true.
input	Buffer containing the message to hash.
input_length	Size of the input buffer in bytes.
hash	Buffer containing the expected hash value.
hash_length	Size of the hash buffer in bytes.

Returns

PSA_SUCCESS Success. The expected hash is identical to the actual hash of the input.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_SIGNATURE The calculated hash of the message does not match the value in hash.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a hash algorithm.
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a hash algorithm.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_hash_compute()

psa_status_t psa_hash_compute	(	psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	hash,
		size_t	hash_size,
		size_t *	hash_length
	)

Calculate the hash (digest) of a message.

Note: To verify the hash of a message against an expected value, use psa_hash_compare() instead.

Parameters

alg	The hash algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(`alg`) is true.
input	Buffer containing the message to hash.
input_length	Size of the `input` buffer in bytes.
hash	Buffer where the hash is to be written.
hash_size	Size of the `hash` buffer in bytes. This must be at least PSA_HASH_LENGTH(`alg`).
hash_length	On success, the number of bytes that make up the hash value. This is always PSA_HASH_LENGTH(`alg`).

Returns

PSA_SUCCESS Success. The first (*hash_length) bytes of hash contain the hash value.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL The size of the hash buffer is too small. PSA_HASH_LENGTH() can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a hash algorithm
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a hash algorithm.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_hash_finish()

psa_status_t psa_hash_finish	(	psa_hash_operation_t *	operation,
		uint8_t *	hash,
		size_t	hash_size,
		size_t *	hash_length
	)

Finish the calculation of the hash of a message.

The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Warning: Applications should not call this function if they expect a specific value for the hash. Call psa_hash_verify() instead. Beware that comparing integrity or authenticity data such as hash values with a function such as memcmp is risky because the time taken by the comparison may leak information about the hashed data which could allow an attacker to guess a valid hash and thereby bypass security controls.

Parameters

operation	Active hash operation.
hash	Buffer where the hash is to be written.
hash_size	Size of the `hash` buffer in bytes. This must be at least PSA_HASH_LENGTH(`alg`) where `alg` is the algorithm that the operation performs.
hash_length	On success, the number of bytes that make up the hash value. This is always PSA_HASH_LENGTH(`alg`) where `alg` is the hash algorithm that is calculated.

Returns

PSA_SUCCESS Success. The first (*hash_length) bytes of hash contain the hash value.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL The size of the hash buffer is too small. PSA_HASH_LENGTH() can be used to determine a sufficient buffer size.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_hash_resume()

psa_status_t psa_hash_resume	(	psa_hash_operation_t *	operation,
		const uint8_t *	hash_state,
		size_t	hash_state_length
	)

Set up a multi-part hash operation using the hash suspend state from a previously suspended hash operation.

See psa_hash_suspend() for an example of how to use this function to suspend and resume a hash operation.

After a successful call to psa_hash_resume(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_hash_finish(), psa_hash_verify() or psa_hash_suspend().
A call to psa_hash_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_hash_operation_t and not yet in use.
hash_state	A buffer containing the suspended hash state which is to be resumed. This must be in the format output by psa_hash_suspend().
hash_state_length	Length of hash_state in bytes.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT hash_state does not correspond to a valid hash suspend state. See Hash suspend state format for the definition.

PSA_ERROR_NOT_SUPPORTED The provided hash suspend state is for an algorithm that is not supported.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_hash_setup()

psa_status_t psa_hash_setup	(	psa_hash_operation_t *	operation,
		psa_algorithm_t	alg
	)

Set up a multipart hash operation.

The sequence of operations to calculate a hash (message digest) is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_hash_operation_t, e.g. PSA_HASH_OPERATION_INIT.
Call psa_hash_setup() to specify the algorithm.
Call psa_hash_update() zero, one or more times, passing a fragment of the message each time. The hash that is calculated is the hash of the concatenation of these messages in order.
To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call psa_hash_verify().

If an error occurs at any step after a call to psa_hash_setup(), the operation will need to be reset by a call to psa_hash_abort(). The application may call psa_hash_abort() at any time after the operation has been initialized.

After a successful call to psa_hash_setup(), the application must eventually terminate the operation. The following events terminate an operation:

A successful call to psa_hash_finish() or psa_hash_verify().
A call to psa_hash_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_hash_operation_t and not yet in use.
alg	The hash algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_HASH(`alg`) is true.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT alg is not a hash algorithm.

PSA_ERROR_NOT_SUPPORTED alg is not supported or is not a hash algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_hash_suspend()

psa_status_t psa_hash_suspend	(	psa_hash_operation_t *	operation,
		uint8_t *	hash_state,
		size_t	hash_state_size,
		size_t *	hash_state_length
	)

Halt the hash operation and extract the intermediate state of the hash computation.

The application must call psa_hash_setup() or psa_hash_resume() before calling this function. This function extracts an intermediate state of the hash computation of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update().

This function can be used to halt a hash operation, and then resume the hash operation at a later time, or in another application, by transferring the extracted hash suspend state to a call to psa_hash_resume().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Hash suspend and resume is not defined for the SHA3 family of hash algorithms. Hash suspend state defines the format of the output from psa_hash_suspend().

Warning: Applications must not use any of the hash suspend state as if it was a hash output. Instead, the suspend state must only be used to resume a hash operation, and psa_hash_finish() or psa_hash_verify() can then calculate or verify the final hash value.

Usage

The sequence of operations to suspend and resume a hash operation is as follows:

Compute the first part of the hash.
1. Allocate an operation object and initialize it as described in the documentation for psa_hash_operation_t.
2. Call psa_hash_setup() to specify the algorithm.
3. Call psa_hash_update() zero, one or more times, passing a fragment of the message each time.
4. Call psa_hash_suspend() to extract the hash suspend state into a buffer.
Pass the hash state buffer to the application which will resume the operation.
Compute the rest of the hash.
1. Allocate an operation object and initialize it as described in the documentation for psa_hash_operation_t.
2. Call psa_hash_resume() with the extracted hash state.
3. Call psa_hash_update() zero, one or more times, passing a fragment of the message each time.
4. To calculate the hash, call psa_hash_finish(). To compare the hash with an expected value, call psa_hash_verify().

If an error occurs at any step after a call to psa_hash_setup() or psa_hash_resume(), the operation will need to be reset by a call to psa_hash_abort(). The application can call psa_hash_abort() at any time after the operation has been initialized.

Parameters

operation	Active hash operation.
hash_state	Buffer where the hash suspend state is to be written.
hash_state_size	Size of the hash_state buffer in bytes. This must be appropriate for the selected algorithm: A sufficient output size is PSA_HASH_SUSPEND_OUTPUT_SIZE(`alg`) where alg is the algorithm that was used to set up the operation. PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported hash algorithm.
hash_state_length	On success, the number of bytes that make up the hash suspend state.

Returns

PSA_SUCCESS Success. The first (*hash_state_length) bytes of hash_state contain the intermediate hash state.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL The size of the hash_state buffer is too small. PSA_HASH_SUSPEND_OUTPUT_SIZE() or PSA_HASH_SUSPEND_OUTPUT_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_NOT_SUPPORTED The hash algorithm being computed does not support suspend and resume.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_hash_update()

psa_status_t psa_hash_update	(	psa_hash_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length
	)

Add a message fragment to a multi-part hash operation.

The application must call psa_hash_setup() before calling this function. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Parameters

operation	Active hash operation.
input	Buffer containing the message fragment to hash.
input_length	Size of the `input` buffer in bytes.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT The total input for the operation is too large for the hash algorithm.

PSA_ERROR_NOT_SUPPORTED The total input for the operation is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_hash_verify()

psa_status_t psa_hash_verify	(	psa_hash_operation_t *	operation,
		const uint8_t *	hash,
		size_t	hash_length
	)

Finish the calculation of the hash of a message and compare it with an expected value.

The application must call psa_hash_setup() before calling this function. This function calculates the hash of the message formed by concatenating the inputs passed to preceding calls to psa_hash_update(). It then compares the calculated hash with the expected hash passed as a parameter to this function.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_hash_abort().

Note: Implementations shall make the best effort to ensure that the comparison between the actual hash and the expected hash is performed in constant time.

Parameters

operation	Active hash operation.
hash	Buffer containing the expected hash value.
hash_length	Size of the `hash` buffer in bytes.

Returns

PSA_SUCCESS Success. The expected hash is identical to the actual hash of the message.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_SIGNATURE The calculated hash of the message does not match the value in hash.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_import_key()

psa_status_t psa_import_key	(	const psa_key_attributes_t *	attributes,
		const uint8_t *	data,
		size_t	data_length,
		psa_key_id_t *	key
	)

Import a key in binary format.

This function supports any output from psa_export_key(). Refer to the documentation of psa_export_public_key() for the format of public keys and to the documentation of psa_export_key() for the format for other key types.

The key data determines the key size. The attributes can optionally specify a key size; in this case it must match the size determined from the key data. A key size of 0 in attributes indicates that the key size is solely determined by the key data.

Implementations must reject an attempt to import a key of size 0.

This specification defines a single format for each key type. Implementations can optionally support other formats in addition to the standard format. It is recommended that implementations that support other formats ensure that the formats are clearly unambiguous, to minimize the risk that an invalid input is accidentally interpreted according to a different format.

Note: The PSA Crypto API does not support asymmetric private key objects outside of a key pair. To import a private key, the attributes must specify the corresponding key pair type. Depending on the key type, either the import format contains the public key data or the implementation will reconstruct the public key from the private key as needed.

Parameters

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type is required, and determines how the data buffer is interpreted.
The key size is always determined from the data buffer. If the key size in attributes is nonzero, it must be equal to the size determined from data.
The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation, see Permitted algorithms.
The key usage flags define what operations are permitted with the key, see Key usage flags.
The key lifetime and identifier are required for a persistent key.

Note: This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

Parameters

data	Buffer containing the key data. The content of this buffer is interpreted according to the type declared in attributes. All implementations must support at least the format described in the documentation of psa_export_key() or psa_export_public_key() for the chosen type. Implementations can support other formats, but be conservative in interpreting the key data: it is recommended that implementations reject content if it might be erroneous, for example, if it is the wrong type or is truncated.
data_length	Size of the data buffer in bytes.
key	On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns

PSA_SUCCESS Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.

PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

The key type is invalid.
The key size is nonzero, and is incompatible with the key data in data.
The key lifetime is invalid.
The key identifier is not valid for the key lifetime.
The key usage flags include invalid values.
The key’s permitted-usage algorithm is invalid.
The key attributes, as a whole, are invalid.
The key data is not correctly formatted for the key type.

PSA_ERROR_NOT_SUPPORTED The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_abort()

psa_status_t psa_key_derivation_abort ( psa_key_derivation_operation_t * operation )

Abort a key derivation operation.

Aborting an operation frees all associated resources except for the operation object itself. Once aborted, the operation object can be reused for another operation by calling psa_key_derivation_setup() again.

This function can be called at any time after the operation object has been initialized as described in psa_key_derivation_operation_t.

In particular, it is valid to call psa_key_derivation_abort() twice, or to call psa_key_derivation_abort() on an operation that has not been set up.

Parameters

operation The operation to abort.

Returns: PSA_SUCCESS Success. The operation object can now be discarded or reused.; PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_CORRUPTION_DETECTED

◆ psa_key_derivation_get_capacity()

psa_status_t psa_key_derivation_get_capacity	(	const psa_key_derivation_operation_t *	operation,
		size_t *	capacity
	)

Retrieve the current capacity of a key derivation operation.

The capacity of a key derivation is the maximum number of bytes that it can return. Reading N bytes of output from a key derivation operation reduces its capacity by at least N. The capacity can be reduced by more than N in the following situations:

Calling psa_key_derivation_output_key() can reduce the capacity by more than the key size, depending on the type of key being generated. See psa_key_derivation_output_key() for details of the key derivation process.
When the psa_key_derivation_operation_t object is operating as a deterministic random bit generator (DBRG), which reduces capacity in whole blocks, even when less than a block is read.

Parameters

operation	The operation to query.
capacity	On success, the capacity of the operation.

Returns

PSA_SUCCESS Success. The maximum number of bytes that this key derivation can return is (*capacity).

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_key_derivation_input_bytes()

psa_status_t psa_key_derivation_input_bytes	(	psa_key_derivation_operation_t *	operation,
		psa_key_derivation_step_t	step,
		const uint8_t *	data,
		size_t	data_length
	)

Provide an input for key derivation or key agreement.

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function passes direct inputs, which is usually correct for non-secret inputs. To pass a secret input, which is normally in a key object, call psa_key_derivation_input_key() instead of this function. Refer to the documentation of individual step types (PSA_KEY_DERIVATION_INPUT_xxx values of type psa_key_derivation_step_t) for more information.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation	The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
step	Which step the input data is for.
data	Input data to use.
data_length	Size of the data buffer in bytes.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid for this input step. This can happen if the application provides a step out of order or repeats a step that may not be repeated.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

step is not compatible with the operation’s algorithm.
step does not allow direct inputs.
data_length is too small or too large for step in this particular algorithm.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

step is not supported with the operation’s algorithm.
data_length is is not supported for step in this particular algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_input_integer()

psa_status_t psa_key_derivation_input_integer	(	psa_key_derivation_operation_t *	operation,
		psa_key_derivation_step_t	step,
		uint64_t	value
	)

Provide a numeric input for key derivation or key agreement.

Which inputs are required and in what order depends on the algorithm. However, when an algorithm requires a particular order, numeric inputs usually come first as they tend to be configuration parameters. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function is used for inputs which are fixed-size non-negative integers.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation	The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
step	Which step the input data is for.
value	The value of the numeric input.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid for this input step. This can happen if the application provides a step out of order or repeats a step that may not be repeated.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

step is not compatible with the operation’s algorithm.
step does not allow numerical inputs.
value is not valid for step in the operation’s algorithm.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

step is not supported with the operation’s algorithm.
value is not supported for step in the operation’s algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_input_key()

psa_status_t psa_key_derivation_input_key	(	psa_key_derivation_operation_t *	operation,
		psa_key_derivation_step_t	step,
		psa_key_id_t	key
	)

Provide an input for key derivation in the form of a key.

Which inputs are required and in what order depends on the algorithm. Refer to the documentation of each key derivation or key agreement algorithm for information.

This function obtains input from a key object, which is usually correct for secret inputs or for non-secret personalization strings kept in the key store. To pass a non-secret parameter which is not in the key store, call psa_key_derivation_input_bytes() instead of this function. Refer to the documentation of individual step types (PSA_KEY_DERIVATION_INPUT_xxx values of type psa_key_derivation_step_t) for more information.

Note

Once all inputs steps are completed, the following operations are permitted:

psa_key_derivation_output_bytes() — if each input was either a direct input or a key with usage flag PSA_KEY_USAGE_DERIVE.
psa_key_derivation_output_key() — if the input for step PSA_KEY_DERIVATION_INPUT_SECRET or PSA_KEY_DERIVATION_INPUT_PASSWORD was a key with usage flag PSA_KEY_USAGE_DERIVE, and every other input was either a direct input or a key with usage flag PSA_KEY_USAGE_DERIVE.
psa_key_derivation_verify_bytes() — if each input was either a direct input or a key with usage flag PSA_KEY_USAGE_VERIFY_DERIVATION.
psa_key_derivation_verify_key() — under the same conditions as psa_key_derivation_verify_bytes().

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation	The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() and must not have produced any output yet.
step	Which step the input data is for.
key	Identifier of the key. The key must have an appropriate type for step, it must allow the usage PSA_KEY_USAGE_DERIVE or PSA_KEY_USAGE_VERIFY_DERIVATION (see note), and it must permit the algorithm used by the operation.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid for this input step. This can happen if the application provides a step out of order or repeats a step that may not be repeated.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key has neither the PSA_KEY_USAGE_DERIVE nor the PSA_KEY_USAGE_VERIFY_DERIVATION usage flag, or it does not permit the operation’s algorithm.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

step is not compatible with the operation’s algorithm.
step does not allow key inputs of the given type, or does not allow key inputs at all.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

step is not supported with the operation’s algorithm.
Key inputs of the given type are not supported for step in the operation’s algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_key_agreement()

psa_status_t psa_key_derivation_key_agreement	(	psa_key_derivation_operation_t *	operation,
		psa_key_derivation_step_t	step,
		psa_key_id_t	private_key,
		const uint8_t *	peer_key,
		size_t	peer_key_length
	)

Perform a key agreement and use the shared secret as input to a key derivation.

A key agreement algorithm takes two inputs: a private key private_key, and a public key peer_key. The result of this function is passed as input to the key derivation operation. The output of this key derivation can be extracted by reading from the resulting operation to produce keys and other cryptographic material.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation	The key derivation operation object to use. It must have been set up with psa_key_derivation_setup() with a key agreement and derivation algorithm alg: a value of type psa_algorithm_t such that PSA_ALG_IS_KEY_AGREEMENT(`alg`) is true and PSA_ALG_IS_RAW_KEY_AGREEMENT(`alg`) is false. The operation must be ready for an input of the type given by step.
step	Which step the input data is for.
private_key	Identifier of the private key to use. It must allow the usage PSA_KEY_USAGE_DERIVE.
peer_key	Public key of the peer. The peer key must be in the same format that psa_import_key() accepts for the public key type corresponding to the type of `private_key`. That is, this function performs the equivalent of psa_import_key(..., `peer_key`, `peer_key_length`), with key attributes indicating the public key type corresponding to the type of `private_key`. For example, for ECC keys, this means that `peer_key` is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of psa_export_public_key().
peer_key_length	Size of `peer_key` in bytes.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid for this key agreement step.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE private_key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED private_key does not have the PSA_KEY_USAGE_DERIVE flag, or it does not permit the operation’s algorithm.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

The operation’s algorithm is not a key agreement algorithm.
step does not allow an input resulting from a key agreement.
private_key is not compatible with the operation’s algorithm.
peer_key is not a valid public key corresponding to private_key.

PSA_ERROR_NOT_SUPPORTED private_key is not supported for use with the operation’s algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_output_bytes()

psa_status_t psa_key_derivation_output_bytes	(	psa_key_derivation_operation_t *	operation,
		uint8_t *	output,
		size_t	output_length
	)

Read some data from a key derivation operation.

This function calculates output bytes from a key derivation algorithm and returns those bytes. If the key derivation’s output is viewed as a stream of bytes, this function consumes the requested number of bytes from the stream and returns them to the caller. The operation’s capacity decreases by the number of bytes read.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Parameters

operation	The key derivation operation object to read from.
output	Buffer where the output will be written.
output_length	Number of bytes to output.

Returns

PSA_SUCCESS Success. The first output_length bytes of output contain the derived data.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active, with all required input steps complete.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED One of the inputs was a key whose policy did not allow PSA_KEY_USAGE_DERIVE.

PSA_ERROR_INSUFFICIENT_DATA The operation’s capacity was less than output_length bytes. In this case, the following occurs:

No output is written to the output buffer.
The operation’s capacity is set to zero — subsequent calls to this function will not succeed, even with a smaller output buffer.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_output_key()

psa_status_t psa_key_derivation_output_key	(	const psa_key_attributes_t *	attributes,
		psa_key_derivation_operation_t *	operation,
		psa_key_id_t *	key
	)

Derive a key from an ongoing key derivation operation.

This function calculates output bytes from a key derivation algorithm and uses those bytes to generate a key deterministically. The key’s location, policy, type and size are taken from attributes.

If the key derivation’s output is viewed as a stream of bytes, this function consumes the required number of bytes from the stream. The operation’s capacity decreases by the number of bytes used to derive the key.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

How much output is produced and consumed from the operation, and how the key is derived, depends on the key type.

For key types for which the key is an arbitrary sequence of bytes of a given size, this function is functionally equivalent to calling psa_key_derivation_output_bytes() and passing the resulting output to psa_import_key(). However, this function has a security benefit: if the implementation provides an isolation boundary then the key material is not exposed outside the isolation boundary. As a consequence, for these key types, this function always consumes exactly (bits/8) bytes from the operation. The following key types defined in this specification follow this scheme:
- PSA_KEY_TYPE_AES
- PSA_KEY_TYPE_ARC4
- PSA_KEY_TYPE_ARIA
- PSA_KEY_TYPE_CAMELLIA
- PSA_KEY_TYPE_CHACHA20
- PSA_KEY_TYPE_SM4
- PSA_KEY_TYPE_DERIVE
- PSA_KEY_TYPE_HMAC
- PSA_KEY_TYPE_PASSWORD_HASH
- PSA_KEY_TYPE_DES, 64 bits This function generates a key using the following process:
  1. Draw an 8-byte string.
  2. Set/clear the parity bits in each byte.
  3. If the result is a forbidden weak key, discard the result and return to step 1.
  4. Output the string.
- PSA_KEY_TYPE_DES, 192 bits
- PSA_KEY_TYPE_DES, 128 bits The two or three keys are generated by repeated application of the process used to generate a DES key. For example, for 3-key 3DES, if the first 8 bytes specify a weak key and the next 8 bytes do not, discard the first 8 bytes, use the next 8 bytes as the first key, and continue reading output from the operation to derive the other two keys.
For Finite-field Diffie-Hellman keys PSA_KEY_TYPE_DH_KEY_PAIR(dh_family) where dh_family designates any Diffie-Hellman family.
ECC keys on a Weierstrass elliptic curve (PSA_KEY_TYPE_ECC_KEY_PAIR( ecc_family) where ecc_family designates a Weierstrass curve family.) require the generation of a private key which is an integer in the range [1, N - 1], where N is the boundary of the private key domain: N is the prime p for Diffie-Hellman, or the order of the curve’s base point for ECC. Let m be the bit size of N, such that 2^m > N >= 2^(m-1). This function generates the private key using the following process:
1. Draw a byte string of length ceiling(m/8) bytes.
2. If m is not a multiple of 8, set the most significant (8 * ceiling(m/8) - m) bits of the first byte in the string to zero.
3. Convert the string to integer k by decoding it as a big-endian byte string.
4. If k > N - 2, discard the result and return to step 1.
5. Output k + 1 as the private key. This method allows compliance to NIST standards, specifically the methods titled Key-Pair Generation by Testing Candidates in the following publications:
- NIST Special Publication 800-56A: Recommendation for Pair-Wise Key-Establishment Schemes Using Discrete Logarithm Cryptography SP800-56A §5.6.1.1.4 for Diffie-Hellman keys.
- SP800-56A §5.6.1.2.2 or FIPS Publication 186-4: Digital Signature Standard (DSS) FIPS186-4 §B.4.2 for elliptic curve keys.
For ECC keys on a Montgomery elliptic curve (where PSA_KEY_TYPE_ECC_KEY_PAIR (PSA_ECC_FAMILY_MONTGOMERY)) this function always draws a byte string whose length is determined by the curve, and sets the mandatory bits accordingly. That is:
- Curve25519 (PSA_ECC_FAMILY_MONTGOMERY, 255 bits): draw a 32-byte string and process it as specified in Elliptic Curves for Security RFC7748 §5.
- Curve448 (PSA_ECC_FAMILY_MONTGOMERY, 448 bits): draw a 56-byte string and process it as specified in RFC7748 §5.

In all cases, the data that is read is discarded from the operation. The operation’s capacity is decreased by the number of bytes read.

For algorithms that take an input step PSA_KEY_DERIVATION_INPUT_SECRET, the input to that step must be provided with psa_key_derivation_input_key(). Future versions of this specification might include additional restrictions on the derived key based on the attributes and strength of the secret key.

Parameters

attributes

The attributes for the new key. This function uses the attributes as follows:

The key type is required. It cannot be an asymmetric public key.
The key size is required. It must be a valid size for the key type.
The key permitted-algorithm policy is required for keys that will be used for a cryptographic operation.
If the key type to be created is PSA_KEY_TYPE_PASSWORD_HASH, then the permitted-algorithm policy must be the same as the current operation’s algorithm.
The key usage flags define what operations are permitted with the key.
The key lifetime and identifier are required for a persistent key.

Note: This is an input parameter: it is not updated with the final key attributes. The final attributes of the new key can be queried by calling psa_get_key_attributes() with the key’s identifier.

Parameters

operation	The key derivation operation object to read from.
key	On success, an identifier for the newly created key. PSA_KEY_ID_NULL on failure.

Returns

PSA_SUCCESS Success. If the key is persistent, the key material and the key’s metadata have been saved to persistent storage.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active, with all required input steps complete.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED The following conditions can result in this error:

The PSA_KEY_DERIVATION_INPUT_SECRET input step was neither provided through a key, nor the result of a key agreement.
One of the inputs was a key whose policy did not allow PSA_KEY_USAGE_DERIVE.
The implementation does not permit creating a key with the specified attributes due to some implementation-specific policy.

PSA_ERROR_ALREADY_EXISTS This is an attempt to create a persistent key, and there is already a persistent key with the given identifier.

PSA_ERROR_INSUFFICIENT_DATA There was not enough data to create the desired key. In this case, the following occurs:

No key is generated.
The operation’s capacity is set to zero — subsequent calls to this function will not succeed, even if they require less data.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

The key type is invalid, or is an asymmetric public key type.
The key type is PSA_KEY_TYPE_PASSWORD_HASH, and the permitted-algorithm policy is not the same as the current operation’s algorithm.
The key size is not valid for the key type.
The key lifetime is invalid.
The key identifier is not valid for the key lifetime.
The key usage flags include invalid values.
The key’s permitted-usage algorithm is invalid.
The key attributes, as a whole, are invalid.

PSA_ERROR_NOT_SUPPORTED The key attributes, as a whole, are not supported, either by the implementation in general or in the specified storage location.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_INSUFFICIENT_STORAGE

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_set_capacity()

psa_status_t psa_key_derivation_set_capacity	(	psa_key_derivation_operation_t *	operation,
		size_t	capacity
	)

Set the maximum capacity of a key derivation operation.

The capacity of a key derivation operation is the maximum number of bytes that the key derivation operation can return from this point onwards.

Parameters

operation	The key derivation operation object to modify.
capacity	The new capacity of the operation. It must be less or equal to the operation’s current capacity.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT capacity is larger than the operation’s current capacity. In this case, the operation object remains valid and its capacity remains unchanged.

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_key_derivation_setup()

psa_status_t psa_key_derivation_setup	(	psa_key_derivation_operation_t *	operation,
		psa_algorithm_t	alg
	)

Set up a key derivation operation.

A key derivation algorithm takes some inputs and uses them to generate a byte stream in a deterministic way. This byte stream can be used to produce keys and other cryptographic material.

A key agreement and derivation algorithm uses a key agreement protocol to provide a shared secret which is used for the key derivation. See psa_key_derivation_key_agreement().

To derive a key:

Start with an initialized object of type psa_key_derivation_operation_t.
Call psa_key_derivation_setup() to select the algorithm.
Provide the inputs for the key derivation by calling psa_key_derivation_input_bytes() or psa_key_derivation_input_key() as appropriate. Which inputs are needed, in what order, whether keys are permitted, and what type of keys depends on the algorithm.
Optionally set the operation’s maximum capacity with psa_key_derivation_set_capacity(). This can be done before, in the middle of, or after providing inputs. For some algorithms, this step is mandatory because the output depends on the maximum capacity.
To derive a key, call psa_key_derivation_output_key(). To derive a byte string for a different purpose, call psa_key_derivation_output_bytes(). Successive calls to these functions use successive output bytes calculated by the key derivation algorithm.
Clean up the key derivation operation object with psa_key_derivation_abort().

If this function returns an error, the key derivation operation object is not changed.

If an error occurs at any step after a call to psa_key_derivation_setup(), the operation will need to be reset by a call to psa_key_derivation_abort().

Implementations must reject an attempt to derive a key of size 0.

Parameters

operation	The key derivation operation object to set up. It must have been initialized but not set up yet.
alg	The algorithm to compute. This must be one of the following: A key derivation algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_KEY_DERIVATION(`alg`) is true. A key agreement and derivation algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_KEY_AGREEMENT(`alg`) is true and PSA_ALG_IS_RAW_KEY_AGREEMENT(`alg`) is false.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT alg is neither a key derivation algorithm, nor a key agreement and derivation algorithm.

PSA_ERROR_NOT_SUPPORTED alg is not supported or is not a key derivation algorithm, or a key agreement and derivation algorithm.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

◆ psa_key_derivation_verify_bytes()

psa_status_t psa_key_derivation_verify_bytes	(	psa_key_derivation_operation_t *	operation,
		const uint8_t *	expected_output,
		size_t	output_length
	)

Compare output data from a key derivation operation to an expected value.

This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value. If the key derivation’s output is viewed as a stream of bytes, this function destructively reads output_length bytes from the stream before comparing them with expected_output. The operation’s capacity decreases by the number of bytes read.

This is functionally equivalent to the following code:

uint8_t tmp[output_length];
psa_key_derivation_output_bytes(operation, tmp, output_length);
if (memcmp(expected_output, tmp, output_length) != 0)
     return PSA_ERROR_INVALID_SIGNATURE;

However, calling psa_key_derivation_verify_bytes() works even if the key’s policy does not allow output of the bytes.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Note: Implementations must make the best effort to ensure that the comparison between the actual key derivation output and the expected output is performed in constant time.

Parameters

operation	The key derivation operation object to read from.
expected_output	Buffer containing the expected derivation output.
output_length	Length ot the expected output. This is also the number of bytes that will be read.

Returns

PSA_SUCCESS Success. The output of the key derivation operation matches expected_output.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active, with all required input steps complete.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_NOT_PERMITTED One of the inputs is a key whose policy does not permit PSA_KEY_USAGE_VERIFY_DERIVATION.

PSA_ERROR_INVALID_SIGNATURE The output of the key derivation operation does not match the value in expected_output.

PSA_ERROR_INSUFFICIENT_DATA The operation’s capacity was less than output_length bytes. In this case, the operation’s capacity is set to zero — subsequent calls to this function will not succeed, even with a smaller expected output length.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_key_derivation_verify_key()

psa_status_t psa_key_derivation_verify_key	(	psa_key_derivation_operation_t *	operation,
		psa_key_id_t	expected
	)

Compare output data from a key derivation operation to an expected value stored in a key.

This function calculates output bytes from a key derivation algorithm and compares those bytes to an expected value, provided as key of type PSA_KEY_TYPE_PASSWORD_HASH. If the key derivation’s output is viewed as a stream of bytes, this function destructively reads the number of bytes corresponding to the length of the expected key from the stream before comparing them with the key value. The operation’s capacity decreases by the number of bytes read.

This is functionally equivalent to exporting the expected key and calling psa_key_derivation_verify_bytes() on the result, except that it works when the key cannot be exported.

If this function returns an error status other than PSA_ERROR_INSUFFICIENT_DATA or PSA_ERROR_INVALID_SIGNATURE, the operation enters an error state and must be aborted by calling psa_key_derivation_abort().

Note: Implementations must make the best effort to ensure that the comparison between the actual key derivation output and the expected output is performed in constant time.

Parameters

operation	The key derivation operation object to read from.
expected	A key of type PSA_KEY_TYPE_PASSWORD_HASH containing the expected output. The key must allow the usage PSA_KEY_USAGE_VERIFY_DERIVATION, and the permitted algorithm must match the operation’s algorithm. The value of this key is typically computed by a previous call to psa_key_derivation_output_key().

Returns

PSA_SUCCESS Success. The output of the key derivation operation matches the expected key value.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active, with all required input steps complete.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE expected is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The following conditions can result in this error:

The key does not have the PSA_KEY_USAGE_VERIFY_DERIVATION flag, or it does not permit the requested algorithm.
One of the inputs is a key whose policy does not permit PSA_KEY_USAGE_VERIFY_DERIVATION.

PSA_ERROR_INVALID_SIGNATURE The output of the key derivation operation does not match the value of the expected key.

PSA_ERROR_INSUFFICIENT_DATA The operation’s capacity was less than the length of the expected key. In this case, the operation’s capacity is set to zero — subsequent calls to this function will not succeed, even with a smaller expected key length.

PSA_ERROR_INVALID_ARGUMENT The key type is not PSA_KEY_TYPE_PASSWORD_HASH.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_mac_abort()

psa_status_t psa_mac_abort ( psa_mac_operation_t * operation )

Abort a MAC operation.

Aborting an operation frees all associated resources except for the operation object itself. Once aborted, the operation object can be reused for another operation by calling psa_mac_sign_setup() or psa_mac_verify_setup() again.

This function can be called any time after the operation object has been initialized by one of the methods described in psa_mac_operation_t.

In particular, calling psa_mac_abort() after the operation has been terminated by a call to psa_mac_abort(), psa_mac_sign_finish() or psa_mac_verify_finish() is safe and has no effect.

Parameters

operation Initialized MAC operation.

Returns: PSA_SUCCESS Success. The operation object can now be discarded or reused.; PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_CORRUPTION_DETECTED

◆ psa_mac_compute()

psa_status_t psa_mac_compute	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	mac,
		size_t	mac_size,
		size_t *	mac_length
	)

Calculate the message authentication code (MAC) of a message.

Note: To verify the MAC of a message against an expected value, use psa_mac_verify() instead. Beware that comparing integrity or authenticity data such as MAC values with a function such as memcmp() is risky because the time taken by the comparison might leak information about the MAC value which could allow an attacker to guess a valid MAC and thereby bypass security controls.

Parameters

key	Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg	The MAC algorithm to compute (PSA_ALG_XXX value such that PSA_ALG_IS_MAC(`alg`) is true).
input	Buffer containing the input message.
input_length	Size of the input buffer in bytes.
mac	Buffer where the MAC value is to be written.
mac_size	Size of the mac buffer in bytes. This must be appropriate for the selected algorithm and key: The exact MAC size is PSA_MAC_LENGTH(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are attributes of the key used to compute the MAC. PSA_MAC_MAX_SIZE evaluates to the maximum MAC size of any supported MAC algorithm.
mac_length	On success, the number of bytes that make up the MAC value.

Returns

PSA_SUCCESS Success. The first (*mac_length) bytes of mac contain the MAC value.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL The size of the mac buffer is too small. PSA_MAC_LENGTH() or PSA_MAC_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a MAC algorithm.
key is not compatible with alg.
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_mac_sign_finish()

psa_status_t psa_mac_sign_finish	(	psa_mac_operation_t *	operation,
		uint8_t *	mac,
		size_t	mac_size,
		size_t *	mac_length
	)

Finish the calculation of the MAC of a message.

The application must call psa_mac_sign_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update().

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Warning: It is not recommended to use this function when a specific value is expected for the MAC. Call psa_mac_verify_finish() instead with the expected MAC value. Comparing integrity or authenticity data such as MAC values with a function such as memcmp() is risky because the time taken by the comparison might leak information about the hashed data which could allow an attacker to guess a valid MAC and thereby bypass security controls.

Parameters

operation	Active MAC operation.
mac	Buffer where the MAC value is to be written.
mac_size	Size of the mac buffer in bytes. This must be appropriate for the selected algorithm and key: The exact MAC size is PSA_MAC_LENGTH(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are attributes of the key, and `alg` is the algorithm used to compute the MAC. PSA_MAC_MAX_SIZE evaluates to the maximum MAC size of any supported MAC algorithm.
mac_length	On success, the number of bytes that make up the MAC value. This is always PSA_MAC_LENGTH(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are attributes of the key, and `alg` is the algorithm used to compute the MAC.

Returns

PSA_SUCCESS Success. The first (*mac_length) bytes of mac contain the MAC value.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be an active mac sign operation.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_BUFFER_TOO_SMALL The size of the mac buffer is too small. PSA_MAC_LENGTH() or PSA_MAC_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_mac_sign_setup()

psa_status_t psa_mac_sign_setup	(	psa_mac_operation_t *	operation,
		psa_key_id_t	key,
		psa_algorithm_t	alg
	)

Set up a multi-part MAC calculation operation.

This function sets up the calculation of the message authentication code (MAC) of a byte string. To verify the MAC of a message against an expected value, use psa_mac_verify_setup() instead.

The sequence of operations to calculate a MAC is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Call psa_mac_sign_setup() to specify the algorithm and key.
Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
At the end of the message, call psa_mac_sign_finish() to finish calculating the MAC value and retrieve it.

If an error occurs at any step after a call to psa_mac_sign_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application can call psa_mac_abort() at any time after the operation has been initialized.

After a successful call to psa_mac_sign_setup(), the application must eventually terminate the operation through one of the following methods:

A successful call to psa_mac_sign_finish().
A call to psa_mac_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg	The MAC algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(`alg`) is true.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a MAC algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_mac_update()

psa_status_t psa_mac_update	(	psa_mac_operation_t *	operation,
		const uint8_t *	input,
		size_t	input_length
	)

Add a message fragment to a multi-part MAC operation.

The application must call psa_mac_sign_setup() or psa_mac_verify_setup() before calling this function.

If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Parameters

operation	Active MAC operation.
input	Buffer containing the message fragment to add to the MAC calculation.
input_length	Size of the `input` buffer in bytes.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be active.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_ARGUMENT The total input for the operation is too large for the MAC algorithm.

PSA_ERROR_NOT_SUPPORTED The total input for the operation is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_mac_verify()

psa_status_t psa_mac_verify	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		const uint8_t *	mac,
		size_t	mac_length
	)

Calculate the MAC of a message and compare it with a reference value.

Parameters

key	Identifier of the key to use for the operation. It must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg	The MAC algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(`alg`) is true.
input	Buffer containing the input message.
input_length	Size of the `input` buffer in bytes.
mac	Buffer containing the expected MAC value.
mac_length	Size of the `mac` buffer in bytes.

Returns

PSA_SUCCESS Success. The expected MAC is identical to the actual MAC of the input.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_VERIFY_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_SIGNATURE The calculated MAC of the message does not match the value in mac.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a MAC algorithm.
key is not compatible with alg.
input_length is too large for alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_mac_verify_finish()

psa_status_t psa_mac_verify_finish	(	psa_mac_operation_t *	operation,
		const uint8_t *	mac,
		size_t	mac_length
	)

Finish the calculation of the MAC of a message and compare it with an expected value.

The application must call psa_mac_verify_setup() before calling this function. This function calculates the MAC of the message formed by concatenating the inputs passed to preceding calls to psa_mac_update(). It then compares the calculated MAC with the expected MAC passed as a parameter to this function.

When this function returns successfully, the operation becomes inactive. If this function returns an error status, the operation enters an error state and must be aborted by calling psa_mac_abort().

Note: Implementations must make the best effort to ensure that the comparison between the actual MAC and the expected MAC is performed in constant time.

Parameters

operation	Active MAC operation.
mac	Buffer containing the expected MAC value.
mac_length	Size of the `mac` buffer in bytes.

Returns

PSA_SUCCESS Success. The expected MAC is identical to the actual MAC of the message.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be an active mac verify operation.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_SIGNATURE The calculated MAC of the message does not match the value in mac.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_mac_verify_setup()

psa_status_t psa_mac_verify_setup	(	psa_mac_operation_t *	operation,
		psa_key_id_t	key,
		psa_algorithm_t	alg
	)

Set up a multi-part MAC verification operation.

This function sets up the verification of the message authentication code (MAC) of a byte string against an expected value.

The sequence of operations to verify a MAC is as follows:

Allocate an operation object which will be passed to all the functions listed here.
Initialize the operation object with one of the methods described in the documentation for psa_mac_operation_t, e.g. PSA_MAC_OPERATION_INIT.
Call psa_mac_verify_setup() to specify the algorithm and key.
Call psa_mac_update() zero, one or more times, passing a fragment of the message each time. The MAC that is calculated is the MAC of the concatenation of these messages in order.
At the end of the message, call psa_mac_verify_finish() to finish calculating the actual MAC of the message and verify it against the expected value.

If an error occurs at any step after a call to psa_mac_verify_setup(), the operation will need to be reset by a call to psa_mac_abort(). The application can call psa_mac_abort() at any time after the operation has been initialized.

After a successful call to psa_mac_verify_setup(), the application must eventually terminate the operation through one of the following methods:

A successful call to psa_mac_verify_finish().
A call to psa_mac_abort().

Parameters

operation	The operation object to set up. It must have been initialized as per the documentation for psa_mac_operation_t and not yet in use.
key	Identifier of the key to use for the operation. It must remain valid until the operation terminates. It must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg	The MAC algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_MAC(`alg`) is true.

Returns

PSA_SUCCESS Success.

PSA_ERROR_BAD_STATE The following conditions can result in this error:

The operation state is not valid: it must be inactive.
The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_VERIFY_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a MAC algorithm.
key is not compatible with alg.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a MAC algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_purge_key()

psa_status_t psa_purge_key ( psa_key_id_t key )

Remove non-essential copies of key material from memory.

For keys that have been created with the PSA_KEY_USAGE_CACHE usage flag, an implementation is permitted to make additional copies of the key material that are not in storage and not for the purpose of ongoing operations.

This function will remove these extra copies of the key material from memory.

This function is not required to remove key material from memory in any of the following situations:

The key is currently in use in a cryptographic operation.
The key is volatile.

Parameters

key	Identifier of the key to purge.

Returns: PSA_SUCCESS Success. The key material has been removed from memory, if the key material is not currently required.; PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().; PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.; PSA_ERROR_COMMUNICATION_FAILURE; PSA_ERROR_CORRUPTION_DETECTED; PSA_ERROR_STORAGE_FAILURE; PSA_ERROR_DATA_CORRUPT; PSA_ERROR_DATA_INVALID

◆ psa_raw_key_agreement()

psa_status_t psa_raw_key_agreement	(	psa_algorithm_t	alg,
		psa_key_id_t	private_key,
		const uint8_t *	peer_key,
		size_t	peer_key_length,
		uint8_t *	output,
		size_t	output_size,
		size_t *	output_length
	)

Perform a key agreement and return the raw shared secret.

Warning: The raw result of a key agreement algorithm such as finite-field Diffie-Hellman or elliptic curve Diffie-Hellman has biases, and is not suitable for use as key material. Instead it is recommended that the result is used as input to a key derivation algorithm. To chain a key agreement with a key derivation, use psa_key_derivation_key_agreement() and other functions from the key derivation interface.

Parameters

alg	The key agreement algorithm to compute: a value of type psa_algorithm_t such that PSA_ALG_IS_RAW_KEY_AGREEMENT(`alg`) is true.
private_key	Identifier of the private key to use. It must allow the usage PSA_KEY_USAGE_DERIVE.
peer_key	Public key of the peer. The peer key must be in the same format that psa_import_key() accepts for the public key type corresponding to the type of private_key. That is, this function performs the equivalent of psa_import_key(..., `peer_key`, `peer_key_length`), with key attributes indicating the public key type corresponding to the type of `private_key`. For example, for ECC keys, this means that `peer_key` is interpreted as a point on the curve that the private key is on. The standard formats for public keys are documented in the documentation of psa_export_public_key().
peer_key_length	Size of peer_key in bytes.
output	Buffer where the raw shared secret is to be written.
output_size	Size of the output buffer in bytes. This must be appropriate for the keys: The required output size is PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE (`type`, `bits`) where type is the type of `private_key` and `bits` is the bit-size of either `private_key` or the `peer_key`. PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE evaluates to the maximum output size of any supported raw key agreement algorithm.
output_length	On success, the number of bytes that make up the returned output.

Returns

PSA_SUCCESS Success. The first (*output_length) bytes of output contain the raw shared secret.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE private_key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED private_key does not have the PSA_KEY_USAGE_DERIVE flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL The size of the output buffer is too small. PSA_RAW_KEY_AGREEMENT_OUTPUT_SIZE() or PSA_RAW_KEY_AGREEMENT_OUTPUT_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not a key agreement algorithm.
private_key is not compatible with alg.
peer_key is not a valid public key corresponding to private_key.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not a key agreement algorithm.
private_key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_reset_key_attributes()

static void psa_reset_key_attributes ( psa_key_attributes_t * attributes )

inlinestatic

Reset a key attribute object to a freshly initialized state.

The attribute object must be initialized as described in the documentation of the type psa_key_attributes_t before calling this function. Once the object has been initialized, this function can be called at any time.

This function frees any auxiliary resources that the object might contain.

Parameters

attributes The attribute object to reset.

Definition at line 2051 of file crypto.h.

◆ psa_set_key_algorithm()

static void psa_set_key_algorithm	(	psa_key_attributes_t *	attributes,
		psa_algorithm_t	alg
	)

inlinestatic

Declare the permitted algorithm policy for a key.

The permitted algorithm policy of a key encodes which algorithm or algorithms are permitted to be used with this key. This function overwrites any permitted algorithm policy previously set in attributes.

Parameters

attributes	The attribute object to write to.
alg	The permitted algorithm to write.

Definition at line 1867 of file crypto.h.

◆ psa_set_key_bits()

static void psa_set_key_bits	(	psa_key_attributes_t *	attributes,
		size_t	bits
	)

inlinestatic

Declare the size of a key.

This function overwrites any key size previously set in attributes.

Parameters

attributes	The attribute object to write to.
bits	The key size in bits. If this is 0, the key size in attributes becomes unspecified. Keys of size 0 are not supported.

Definition at line 1895 of file crypto.h.

◆ psa_set_key_id()

static void psa_set_key_id	(	psa_key_attributes_t *	attributes,
		psa_key_id_t	id
	)

inlinestatic

Declare a key as persistent and set its key identifier.

The application must choose a value for id between PSA_KEY_ID_USER_MIN and PSA_KEY_ID_USER_MAX. If the attribute object currently declares the key as volatile, which is the default lifetime of an attribute object, this function sets the lifetime attribute to PSA_KEY_LIFETIME_PERSISTENT.

This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key().

Parameters

attributes	The attribute object to write to.
id	The persistent identifier for the key.

Definition at line 1929 of file crypto.h.

◆ psa_set_key_lifetime()

static void psa_set_key_lifetime	(	psa_key_attributes_t *	attributes,
		psa_key_lifetime_t	lifetime
	)

inlinestatic

Set the location of a persistent key.

To make a key persistent, give it a persistent key identifier by using psa_set_key_id(). By default, a key that has a persistent identifier is stored in the default storage area identifier by PSA_KEY_LIFETIME_PERSISTENT. Call this function to choose a storage area, or to explicitly declare the key as volatile.

This function does not access storage, it merely stores the given value in the attribute object. The persistent key will be written to storage when the attribute object is passed to a key creation function such as psa_import_key(), psa_generate_key(), psa_key_derivation_output_key() or psa_copy_key().

Parameters

attributes	The attribute object to write to.
lifetime	The lifetime for the key. If this is PSA_KEY_LIFETIME_VOLATILE, the key will be volatile, and the key identifier attribute is reset to PSA_KEY_ID_NULL.

Definition at line 1966 of file crypto.h.

◆ psa_set_key_type()

static void psa_set_key_type	(	psa_key_attributes_t *	attributes,
		psa_key_type_t	type
	)

inlinestatic

Declare the type of a key.

This function overwrites any key type previously set in attributes.

Parameters

attributes	The attribute object to write to.
type	The key type to write. If this is PSA_KEY_TYPE_NONE, the key type in attributes becomes unspecified.

Definition at line 1993 of file crypto.h.

◆ psa_set_key_usage_flags()

static void psa_set_key_usage_flags	(	psa_key_attributes_t *	attributes,
		psa_key_usage_t	usage_flags
	)

inlinestatic

Declare usage flags for a key.

Usage flags are part of a key’s policy. They encode what kind of operations are permitted on the key. For more details, see Key policies.

This function overwrites any usage flags previously set in attributes.

Parameters

attributes	The attribute object to write to.
usage_flags	The usage flags to write.

Definition at line 2022 of file crypto.h.

◆ psa_sign_hash()

psa_status_t psa_sign_hash	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	hash,
		size_t	hash_length,
		uint8_t *	signature,
		size_t	signature_size,
		size_t *	signature_length
	)

Sign an already-calculated hash with a private key.

With most signature mechanisms that follow the hash-and-sign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.

Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

Note: To perform a hash-and-sign signature algorithm, the hash must be calculated before passing it to this function. This can be done by calling psa_hash_compute() or with a multi-part hash operation. The correct hash algorithm to use can be determined using PSA_ALG_GET_HASH().

Alternatively, to hash and sign a message in a single call, use psa_sign_message().

Parameters

key	Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_HASH.
alg	An asymmetric signature algorithm that separates the hash and sign operations: a value of type psa_algorithm_t such that PSA_ALG_IS_SIGN_HASH(`alg`) is true.
hash	The input to sign. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.
hash_length	Size of the hash buffer in bytes.
signature	Buffer where the signature is to be written.
signature_size	Size of the signature buffer in bytes. This must be appropriate for the selected algorithm and key: The required signature size is PSA_SIGN_OUTPUT_SIZE(`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of `key`. PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.
signature_length	On success, the number of bytes that make up the returned signature value.

Returns

PSA_SUCCESS Success. The first (*signature_length) bytes of signature contain the signature value.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_SIGN_HASH flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL The size of the signature buffer is too small. PSA_SIGN_OUTPUT_SIZE() or PSA_SIGNATURE_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not an asymmetric signature algorithm.
key is not an asymmetric key pair, that is compatible with alg.
hash_length is not valid for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not an asymmetric signature algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_ENTROPY

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_sign_message()

psa_status_t psa_sign_message	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		uint8_t *	signature,
		size_t	signature_size,
		size_t *	signature_length
	)

Sign a message with a private key.

For hash-and-sign algorithms, this includes the hashing step.

Note: To perform a multi-part hash-and-sign signature algorithm, first use a multi-part hash operation and then pass the resulting hash to psa_sign_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.

Parameters

key	Identifier of the key to use for the operation. It must be an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_SIGN_MESSAGE.
alg	An asymmetric signature algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_SIGN_MESSAGE(`alg`) is true.
input	The input message to sign.
input_length	Size of the input buffer in bytes.
signature	Buffer where the signature is to be written.
signature_size	Size of the signature buffer in bytes. This must be appropriate for the selected algorithm and key: The required signature size is PSA_SIGN_OUTPUT_SIZE (`key_type`, `key_bits`, `alg`) where `key_type` and `key_bits` are the type and bit-size respectively of `key`. PSA_SIGNATURE_MAX_SIZE evaluates to the maximum signature size of any supported signature algorithm.
signature_length	On success, the number of bytes that make up the returned signature value.

Returns

PSA_SUCCESS Success. The first (*signature_length) bytes of signature contain the signature value.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_SIGN_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_BUFFER_TOO_SMALL The size of the signature buffer is too small. PSA_SIGN_OUTPUT_SIZE() or PSA_SIGNATURE_MAX_SIZE can be used to determine a sufficient buffer size.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not an asymmetric signature algorithm.
key is not an asymmetric key pair, that is compatible with alg.
input_length is too large for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not an asymmetric signature algorithm.
key is not supported for use with alg.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_ENTROPY

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_status_to_humanly_readable()

const char * psa_status_to_humanly_readable ( psa_status_t status )

Helper function to convert PSA status values humanly readable.

Parameters

status PSA status value

Returns: Pointer to string

◆ psa_verify_hash()

psa_status_t psa_verify_hash	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	hash,
		size_t	hash_length,
		const uint8_t *	signature,
		size_t	signature_length
	)

Verify the signature of a hash or short message using a public key.

With most signature mechanisms that follow the hash-and-sign paradigm, the hash input to this function is the hash of the message to sign. The hash algorithm is encoded in the signature algorithm.

Some hash-and-sign mechanisms apply a padding or encoding to the hash. In such cases, the encoded hash must be passed to this function. The current version of this specification defines one such signature algorithm: PSA_ALG_RSA_PKCS1V15_SIGN_RAW.

Note: To perform a hash-and-sign verification algorithm, the hash must be calculated before passing it to this function. This can be done by calling psa_hash_compute() or with a multi-part hash operation. Alternatively, to hash and verify a message signature in a single call, use psa_verify_message().; When using secure elements as backends in this implementation, the key type can only be of type PSA_KEY_TYPE_ECC_PUBLIC_KEY(curve) and must be stored on a secure element. To use the public key of a previously generated key pair, please export the public key first and then import it as a separate key with its own attributes and identifier.

Parameters

key	Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_HASH.
alg	An asymmetric signature algorithm that separates the hash and sign operations (PSA_ALG_XXX value such that PSA_ALG_IS_SIGN_HASH(`alg`) is true), that is compatible with the type of key.
hash	The input whose signature is to be verified. This is usually the hash of a message. See the detailed description of this function and the description of individual signature algorithms for a detailed description of acceptable inputs.
hash_length	Size of the hash buffer in bytes.
signature	Buffer containing the signature to verify.
signature_length	Size of the signature buffer in bytes.

Returns

PSA_SUCCESS Success. The signature is valid.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_VERIFY_HASH flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_SIGNATURE signature is not the result of signing hash with algorithm alg using the private key corresponding to key.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not an asymmetric signature algorithm.
key is not a public key or an asymmetric key pair, that is compatible with alg.
hash_length is not valid for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not an asymmetric signature algorithm.
key is not supported for use with alg.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID

◆ psa_verify_message()

psa_status_t psa_verify_message	(	psa_key_id_t	key,
		psa_algorithm_t	alg,
		const uint8_t *	input,
		size_t	input_length,
		const uint8_t *	signature,
		size_t	signature_length
	)

Verify the signature of a message with a public key.

For hash-and-sign algorithms, this includes the hashing step.

Note: To perform a multi-part hash-and-sign signature verification algorithm, first use a multi-part hash operation to hash the message and then pass the resulting hash to psa_verify_hash(). PSA_ALG_GET_HASH(alg) can be used to determine the hash algorithm to use.

Parameters

key	Identifier of the key to use for the operation. It must be a public key or an asymmetric key pair. The key must allow the usage PSA_KEY_USAGE_VERIFY_MESSAGE.
alg	An asymmetric signature algorithm: a value of type psa_algorithm_t such that PSA_ALG_IS_SIGN_MESSAGE(`alg`) is true.
input	The message whose signature is to be verified.
input_length	Size of the `input` buffer in bytes.
signature	Buffer containing the signature to verify.
signature_length	Size of the `signature` buffer in bytes.

Returns

PSA_SUCCESS Success. The signature is valid.

PSA_ERROR_BAD_STATE The library requires initializing by a call to psa_crypto_init().

PSA_ERROR_INVALID_HANDLE key is not a valid key identifier.

PSA_ERROR_NOT_PERMITTED The key does not have the PSA_KEY_USAGE_VERIFY_MESSAGE flag, or it does not permit the requested algorithm.

PSA_ERROR_INVALID_SIGNATURE signature is not the result of signing the input message with algorithm alg using the private key corresponding to key.

PSA_ERROR_INVALID_ARGUMENT The following conditions can result in this error:

alg is not an asymmetric signature algorithm.
key is not a public key or an asymmetric key pair, that is compatible with alg.
input_length is too large for the algorithm and key type.

PSA_ERROR_NOT_SUPPORTED The following conditions can result in this error:

alg is not supported or is not an asymmetric signature algorithm.
key is not supported for use with alg.
input_length is too large for the implementation.

PSA_ERROR_INSUFFICIENT_MEMORY

PSA_ERROR_COMMUNICATION_FAILURE

PSA_ERROR_CORRUPTION_DETECTED

PSA_ERROR_STORAGE_FAILURE

PSA_ERROR_DATA_CORRUPT

PSA_ERROR_DATA_INVALID