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_key
The 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.
(uint64_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).
The 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.
This is unchanged since the feature was introduced in Mbed Crypto 0.1.0.
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.
Changes since 1.0.0:
Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
An undocumented build-time configuration value PSA_ITS_STORAGE_PREFIX
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).
PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"
: used as a temporary file. Must be writable. May be overwritten or deleted if present.sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)
: a key or non-key file. The key_id
in the name is the 64-bit file identifier, which is the key identifier for a key file or some reserved identifier for a non-key file (currently: only the nonvolatile random seed). The contents of the file are:"PSA\0ITS\0"
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_key
Tags: 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
.Tags: mbedtls-2.25.0
, mbedtls-2.26.0
, mbedtls-2.27.0
, mbedtls-2.28.0
, mbedtls-3.0.0
, mbedtls-3.1.0
First released in December 2020.
Note: this is the first version that is officially supported. The version number is still 0.
Backward compatibility commitments: we promise backward compatibility for stored keys when Mbed TLS is upgraded from x to y if x >= 2.25 and y < 4. See BRANCHES.md
for more details.
Supported integrations:
Supported features:
MBEDTLS_PSA_CRYPTO_DRIVERS
). The driver determines the content of the opaque key blob.MBEDTLS_PSA_CRYPTO_SE_C
). The driver picks a slot number which is stored in the place of the key material.psa_key_type_t
, psa_key_usage_t
and psa_algorithm_t
have changed.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.
Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23.
An undocumented build-time configuration value PSA_ITS_STORAGE_PREFIX
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).
PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"
: used as a temporary file. Must be writable. May be overwritten or deleted if present.sprintf(PSA_ITS_STORAGE_PREFIX "%016llx.psa_its", key_id)
: a key or non-key file. The key_id
in the name is the 64-bit file identifier, which is the key identifier for a key file or some reserved identifier for a non-key file. The contents of the file are:"PSA\0ITS\0"
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.
PSA_KEY_ID_USER_MIN
..PSA_KEY_ID_USER_MAX
).(uint64_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.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
.File identifiers that are outside the range of persistent key identifiers are reserved for internal use by the library. The only identifiers currently in use have the owner id (top 32 bits) set to 0.
PSA_CRYPTO_SE_DRIVER_ITS_UID_BASE + lifetime
): dynamic 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.Identical to Mbed Crypto 0.1.0.
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 dynamic 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.