PSA cryptography module: Mbed TLS key storage. More...

#include "psa/crypto.h"
#include "psa/crypto_se_driver.h"
#include <stdint.h>
#include <string.h>

Macros
#define	PSA_MAX_PERSISTENT_KEY_IDENTIFIER PSA_KEY_ID_VENDOR_MAX
	The maximum permitted persistent slot number. More...

Functions
int	psa_is_key_present_in_storage (const mbedtls_svc_key_id_t key)
	Checks if persistent data is stored for the given key slot number. More...

psa_status_t	psa_save_persistent_key (const psa_core_key_attributes_t attr, const uint8_t data, const size_t data_length)
	Format key data and metadata and save to a location for given key slot. More...

psa_status_t	psa_load_persistent_key (psa_core_key_attributes_t attr, uint8_t data, size_t data_length)
	Parses key data and metadata and load persistent key for given key slot number. More...

psa_status_t	psa_destroy_persistent_key (const mbedtls_svc_key_id_t key)
	Remove persistent data for the given key slot number. More...

void	psa_free_persistent_key_data (uint8_t *key_data, size_t key_data_length)
	Free the temporary buffer allocated by psa_load_persistent_key(). More...

void	psa_format_key_data_for_storage (const uint8_t data, const size_t data_length, const psa_core_key_attributes_t attr, uint8_t *storage_data)
	Formats key data and metadata for persistent storage. More...

psa_status_t	psa_parse_key_data_from_storage (const uint8_t storage_data, size_t storage_data_length, uint8_t key_data, size_t key_data_length, psa_core_key_attributes_t *attr)
	Parses persistent storage data into key data and metadata. More...

Detailed Description

PSA cryptography module: Mbed TLS key storage.

Definition in file psa_crypto_storage.h.

Macro Definition Documentation

◆ PSA_MAX_PERSISTENT_KEY_IDENTIFIER

#define PSA_MAX_PERSISTENT_KEY_IDENTIFIER PSA_KEY_ID_VENDOR_MAX

The maximum permitted persistent slot number.

In Mbed Crypto 0.1.0b:

Using the file backend, all key ids are ok except 0.
Using the ITS backend, all key ids are ok except 0xFFFFFF52 (PSA_CRYPTO_ITS_RANDOM_SEED_UID) for which the file contains the device's random seed (if this feature is enabled).
Only key ids from 1 to PSA_KEY_SLOT_COUNT are actually used.

Since we need to preserve the random seed, avoid using that key slot. Reserve a whole range of key slots just in case something else comes up.

This limitation will probably become moot when we implement client separation for key storage.

Definition at line 60 of file psa_crypto_storage.h.

Function Documentation

◆ psa_is_key_present_in_storage()

int psa_is_key_present_in_storage ( const mbedtls_svc_key_id_t key )

Checks if persistent data is stored for the given key slot number.

This function checks if any key data or metadata exists for the key slot in the persistent storage.

Parameters

key	Persistent identifier to check.

Return values

0	No persistent data present for slot number
1	Persistent data present for slot number

◆ psa_save_persistent_key()

psa_status_t psa_save_persistent_key	(	const psa_core_key_attributes_t *	attr,
		const uint8_t *	data,
		const size_t	data_length
	)

Format key data and metadata and save to a location for given key slot.

This function formats the key data and metadata and saves it to a persistent storage backend. The storage location corresponding to the key slot must be empty, otherwise this function will fail. This function should be called after loading the key into an internal slot to ensure the persistent key is not saved into a storage location corresponding to an already occupied non-persistent key, as well as ensuring the key data is validated.

Parameters

[in]	attr	The attributes of the key to save. The key identifier field in the attributes determines the key's location.
[in]	data	Buffer containing the key data.
	data_length	The number of bytes that make up the key data.

Return values

PSA_SUCCESS
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_ALREADY_EXISTS

◆ psa_load_persistent_key()

psa_status_t psa_load_persistent_key	(	psa_core_key_attributes_t *	attr,
		uint8_t **	data,
		size_t *	data_length
	)

Parses key data and metadata and load persistent key for given key slot number.

This function reads from a storage backend, parses the key data and metadata and writes them to the appropriate output parameters.

Note: This function allocates a buffer and returns a pointer to it through the data parameter. psa_free_persistent_key_data() must be called after this function to zeroize and free this buffer, regardless of whether this function succeeds or fails.

Parameters

[in,out]	attr	On input, the key identifier field identifies the key to load. Other fields are ignored. On success, the attribute structure contains the key metadata that was loaded from storage.
[out]	data	Pointer to an allocated key data buffer on return.
[out]	data_length	The number of bytes that make up the key data.

Return values

PSA_SUCCESS
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_STORAGE_FAILURE
PSA_ERROR_DOES_NOT_EXIST

◆ psa_destroy_persistent_key()

psa_status_t psa_destroy_persistent_key ( const mbedtls_svc_key_id_t key )

Remove persistent data for the given key slot number.

Parameters

key	Persistent identifier of the key to remove from persistent storage.

Return values

PSA_SUCCESS	The key was successfully removed, or the key did not exist.
PSA_ERROR_STORAGE_FAILURE

◆ psa_free_persistent_key_data()

void psa_free_persistent_key_data	(	uint8_t *	key_data,
		size_t	key_data_length
	)

Free the temporary buffer allocated by psa_load_persistent_key().

This function must be called at some point after psa_load_persistent_key() to zeroize and free the memory allocated to the buffer in that function.

Parameters

key_data	Buffer for the key data.
key_data_length	Size of the key data buffer.

◆ psa_format_key_data_for_storage()

void psa_format_key_data_for_storage	(	const uint8_t *	data,
		const size_t	data_length,
		const psa_core_key_attributes_t *	attr,
		uint8_t *	storage_data
	)

Formats key data and metadata for persistent storage.

Parameters

[in]	data	Buffer containing the key data.
	data_length	Length of the key data buffer.
[in]	attr	The core attributes of the key.
[out]	storage_data	Output buffer for the formatted data.

◆ psa_parse_key_data_from_storage()

psa_status_t psa_parse_key_data_from_storage	(	const uint8_t *	storage_data,
		size_t	storage_data_length,
		uint8_t **	key_data,
		size_t *	key_data_length,
		psa_core_key_attributes_t *	attr
	)

Parses persistent storage data into key data and metadata.

Parameters

[in]	storage_data	Buffer for the storage data.
	storage_data_length	Length of the storage data buffer
[out]	key_data	On output, pointer to a newly allocated buffer containing the key data. This must be freed using psa_free_persistent_key_data()
[out]	key_data_length	Length of the key data buffer
[out]	attr	On success, the attribute structure is filled with the loaded key metadata.

Return values

PSA_SUCCESS
PSA_ERROR_INSUFFICIENT_STORAGE
PSA_ERROR_INSUFFICIENT_MEMORY
PSA_ERROR_STORAGE_FAILURE

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ PSA_MAX_PERSISTENT_KEY_IDENTIFIER

Function Documentation

◆ psa_is_key_present_in_storage()

◆ psa_save_persistent_key()

◆ psa_load_persistent_key()

◆ psa_destroy_persistent_key()

◆ psa_free_persistent_key_data()

◆ psa_format_key_data_for_storage()

◆ psa_parse_key_data_from_storage()