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. The range is not documented.
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
.Warning: the information in this section is provisional and may change before Mbed Crypto is released for Mbed OS 5.12. At the time of writing, we don't even know whether this version will be called 0.2.0.
To be released for Mbed OS 5.12.
Supported backends:
Supported features:
Backward compatibility commitments: TBD
Information about each key is stored in a dedicated file whose name is constructed from the 32-bit key identifier (psa_key_id_t
) and, if applicable, the owner 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. The range is not documented.
key_id << 32 | owner_uid
where key_id
is the key identifier specified by the application and owner_uid
is the calling partition identifier provided to the serve 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 version 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.
PSA_CRYPTO_ITS_RANDOM_SEED_UID
): nonvolatile random seed.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.
PSA_CRYPTO_ITS_RANDOM_SEED_UID
): nonvolatile random seed.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.