NCBI C++ ToolKit
Macros | Functions
psa_crypto_storage.h File Reference

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

#include "psa/crypto.h"
#include "psa/crypto_se_driver.h"
#include <stdint.h>
#include <string.h>
+ Include dependency graph for psa_crypto_storage.h:

Go to the source code of this file.

Go to the SVN repository for this file.

Macros

#define PSA_CRYPTO_MAX_STORAGE_SIZE   (PSA_BITS_TO_BYTES(PSA_MAX_KEY_BITS))
 
#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_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_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_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_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_CRYPTO_MAX_STORAGE_SIZE

#define PSA_CRYPTO_MAX_STORAGE_SIZE   (PSA_BITS_TO_BYTES(PSA_MAX_KEY_BITS))

Definition at line 26 of file psa_crypto_storage.h.

◆ 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 MBEDTLS_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 48 of file psa_crypto_storage.h.

Function Documentation

◆ 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
keyPersistent identifier of the key to remove from persistent storage.
Return values
PSA_SUCCESSThe key was successfully removed, or the key did not exist.
PSA_ERROR_DATA_INVALID\emptydescription

◆ psa_format_key_data_for_storage()

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

Formats key data and metadata for persistent storage.

Parameters
[in]dataBuffer containing the key data.
data_lengthLength of the key data buffer.
[in]attrThe core attributes of the key.
[out]storage_dataOutput buffer for the formatted data.

◆ 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_dataBuffer for the key data.
key_data_lengthSize of the key data buffer.

◆ 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
keyPersistent identifier to check.
Return values
0No persistent data present for slot number
1Persistent data present for slot number

◆ psa_load_persistent_key()

psa_status_t psa_load_persistent_key ( psa_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. On successful return, the pointer is guaranteed to be valid and the buffer contains at least one byte of data. psa_free_persistent_key_data() must be called on the data buffer afterwards to zeroize and free this buffer.

Parameters
[in,out]attrOn 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]dataPointer to an allocated key data buffer on return.
[out]data_lengthThe number of bytes that make up the key data.
Return values
PSA_SUCCESS\emptydescription
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_DATA_INVALID\emptydescription
PSA_ERROR_DATA_CORRUPT\emptydescription
PSA_ERROR_DOES_NOT_EXIST\emptydescription

◆ 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_key_attributes_t attr 
)

Parses persistent storage data into key data and metadata.

Parameters
[in]storage_dataBuffer for the storage data.
storage_data_lengthLength of the storage data buffer
[out]key_dataOn output, pointer to a newly allocated buffer containing the key data. This must be freed using psa_free_persistent_key_data()
[out]key_data_lengthLength of the key data buffer
[out]attrOn success, the attribute structure is filled with the loaded key metadata.
Return values
PSA_SUCCESS\emptydescription
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_DATA_INVALID\emptydescription

◆ psa_save_persistent_key()

psa_status_t psa_save_persistent_key ( const psa_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.

Note: This function will only succeed for key buffers which are not empty. If passed a NULL pointer or zero-length, the function will fail with PSA_ERROR_INVALID_ARGUMENT.

Parameters
[in]attrThe attributes of the key to save. The key identifier field in the attributes determines the key's location.
[in]dataBuffer containing the key data.
data_lengthThe number of bytes that make up the key data.
Return values
PSA_SUCCESS\emptydescription
PSA_ERROR_INVALID_ARGUMENT\emptydescription
PSA_ERROR_INSUFFICIENT_MEMORY\emptydescription
PSA_ERROR_INSUFFICIENT_STORAGE\emptydescription
PSA_ERROR_STORAGE_FAILURE\emptydescription
PSA_ERROR_ALREADY_EXISTS\emptydescription
PSA_ERROR_DATA_INVALID\emptydescription
PSA_ERROR_DATA_CORRUPT\emptydescription
Modified on Wed Jul 17 13:16:55 2024 by modify_doxy.py rev. 669887