This document specifies how Mbed Crypto uses storage.
Mbed Crypto may be upgraded on an existing device with the storage preserved. Therefore:
Tags: mbedcrypto-0.1.0b, mbedcrypto-0.1.0b2
Released in November 2018.
Integrated in Mbed OS 5.11.
Supported backends:
Supported features:
This is a beta release, and we do not promise backward compatibility, with one exception:
On Mbed OS, if a device has a nonvolatile random seed file produced with Mbed OS 5.11.x and is upgraded to a later version of Mbed OS, the nonvolatile random seed file is preserved or upgraded.
We do not make any promises regarding key storage, or regarding the nonvolatile random seed file on other platforms.
Information about each key is stored in a dedicated file whose name is constructed from the key identifier. The way in which the file name is constructed depends on the storage backend. The content of the file is described below.
The valid values for a key identifier are the range from 1 to 0xfffeffff. This limitation on the range is not documented in user-facing documentation: according to the user-facing documentation, arbitrary 32-bit values are valid.
The code uses the following constant in an internal header (note that despite the name, this value is actually one plus the maximum permitted value):
#define PSA_MAX_PERSISTENT_KEY_IDENTIFIER 0xffff0000
There is a shared namespace for all callers.
All integers are encoded in little-endian order in 8-bit bytes.
The layout of a key file is:
"PSA\0KEY\0"psa_key_type_t valuepsa_key_usage_t valuepsa_algorithm_t valuepsa_export_keyThe nonvolatile random seed file contains a seed for the random generator. If present, it is rewritten at each boot as part of the random generator initialization.
The file format is just the seed as a byte string with no metadata or encoding of any kind.
Assumption: ITS provides a 32-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
PSA_CRYPTO_ITS_RANDOM_SEED_UID): nonvolatile random seed.Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
An undocumented build-time configuration value CRYPTO_STORAGE_FILE_LOCATION allows storing the key files in a directory other than the current directory. This value is simply prepended to the file name (so it must end with a directory separator to put the keys in a different directory).
CRYPTO_STORAGE_FILE_LOCATION "psa_key_slot_0": used as a temporary file. Must be writable. May be overwritten or deleted if present.sprintf(CRYPTO_STORAGE_FILE_LOCATION "psa_key_slot_%lu", key_id) content of the key whose identifier is key_id.Tags: mbedcrypto-1.0.0d4, mbedcrypto-1.0.0
Released in February 2019.
Integrated in Mbed OS 5.12.
Supported integrations:
Supported features:
Backward compatibility commitments: TBD
Information about each key is stored in a dedicated file designated by the key identifier. In integrations where there is no concept of key owner (in particular, in library integrations), the key identifier is exactly the key identifier as defined in the PSA Cryptography API specification (psa_key_id_t). In integrations where there is a concept of key owner (integration into a service for example), the key identifier is made of an owner identifier (its semantics and type are integration specific) and of the key identifier (psa_key_id_t) from the key owner point of view.
The way in which the file name is constructed from the key identifier depends on the storage backend. The content of the file is described below.
(uint32_t)owner_uid << 32 | key_id where key_id is the key identifier from the owner point of view and owner_uid (of type int32_t) is the calling partition identifier provided to the server by the partition manager. This is a 64-bit value.The layout is identical to 0.1.0 so far. However note that the encoding of key types, algorithms and key material has changed, therefore the storage format is not compatible (despite using the same value in the version field so far).
Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
Assumption: the owner identifier is a nonzero value of type int32_t.
PSA_CRYPTO_ITS_RANDOM_SEED_UID): nonvolatile random seed.Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
PSA_CRYPTO_ITS_RANDOM_SEED_UID): nonvolatile random seed.This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
The library integration and the PSA platform integration use different sets of file names. This is annoyingly non-uniform. For example, if we want to store non-key files, we have room in different ranges (0 through 0xffffffff on a PSA platform, 0xffff0000 through 0xffffffffffffffff in a library integration).
It would simplify things to always have a 32-bit owner, with a nonzero value, and thus reserve the range 0–0xffffffff for internal library use.
Tags: mbedcrypto-1.1.0
Released in early June 2019.
Integrated in Mbed OS 5.13.
Identical to 1.0.0 except for some changes in the key file format.
The key file format is identical to 1.0.0, except for the following changes:
A self-contained description of the file layout follows.
All integers are encoded in little-endian order in 8-bit bytes.
The layout of a key file is:
"PSA\0KEY\0"psa_key_type_t valuepsa_key_usage_t valuepsa_algorithm_t valuepsa_algorithm_t value [NEW:1.1.0]psa_export_keyTags: TBD
Released in TBD 2019.
Integrated in Mbed OS TBD.
Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
Assumption: the owner identifier is a nonzero value of type int32_t.
Assumption: ITS provides a 64-bit file identifier namespace. The entity using the crypto library can use arbitrary file identifiers and no other part of the system accesses the same file identifier namespace.
This is a library integration, so there is no owner. The key file identifier is identical to the key identifier.
File identifiers in the range 0xffff0000 through 0xffffffff are reserved for internal use in Mbed Crypto.
PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE + lifetime): secure element driver storage. The content of the file is the secure element driver's persistent data.PSA_CRYPTO_ITS_RANDOM_SEED_UID): nonvolatile random seed.PSA_CRYPTO_ITS_TRANSACTION_UID): transaction file.All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
The layout of a key file is:
"PSA\0KEY\0".psa_key_lifetime_t value.psa_key_type_t value.psa_key_usage_t value.psa_algorithm_t value.psa_algorithm_t value.psa_export_key.The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction.
All integers are encoded in platform endianness.
All currently existing transactions concern a key in a secure element.
The layout of a transaction file is:
psa_key_lifetime_t value that corresponds to a key in a secure element.psa_key_slot_number_t value. This is the unique designation of the key for the secure element driver.Tags: TBD
Released in TBD 2020.
Integrated in Mbed OS TBD.
All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated.
The layout of a key file is:
"PSA\0KEY\0".psa_key_lifetime_t value.psa_key_type_t value.psa_key_bits_t value.psa_key_usage_t value.psa_algorithm_t value.psa_algorithm_t value.psa_export_key.