1Mbed Crypto storage specification 2================================= 3 4This document specifies how Mbed Crypto uses storage. 5 6Mbed Crypto may be upgraded on an existing device with the storage preserved. Therefore: 7 81. Any change may break existing installations and may require an upgrade path. 91. This document retains historical information about all past released versions. Do not remove information from this document unless it has always been incorrect or it is about a version that you are sure was never released. 10 11Mbed Crypto 0.1.0 12----------------- 13 14Tags: mbedcrypto-0.1.0b, mbedcrypto-0.1.0b2 15 16Released in November 2018. <br> 17Integrated in Mbed OS 5.11. 18 19Supported backends: 20 21* [PSA ITS](#file-namespace-on-its-for-0.1.0) 22* [C stdio](#file-namespace-on-stdio-for-0.1.0) 23 24Supported features: 25 26* [Persistent transparent keys](#key-file-format-for-0.1.0) designated by a [slot number](#key-names-for-0.1.0). 27* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0) on ITS only. 28 29This is a beta release, and we do not promise backward compatibility, with one exception: 30 31> 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. 32 33We do not make any promises regarding key storage, or regarding the nonvolatile random seed file on other platforms. 34 35### Key names for 0.1.0 36 37Information 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](#key-file-format-for-0.1.0). 38 39The 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. 40 41The code uses the following constant in an internal header (note that despite the name, this value is actually one plus the maximum permitted value): 42 43 #define PSA_MAX_PERSISTENT_KEY_IDENTIFIER 0xffff0000 44 45There is a shared namespace for all callers. 46 47### Key file format for 0.1.0 48 49All integers are encoded in little-endian order in 8-bit bytes. 50 51The layout of a key file is: 52 53* magic (8 bytes): `"PSA\0KEY\0"` 54* version (4 bytes): 0 55* type (4 bytes): `psa_key_type_t` value 56* policy usage flags (4 bytes): `psa_key_usage_t` value 57* policy usage algorithm (4 bytes): `psa_algorithm_t` value 58* key material length (4 bytes) 59* key material: output of `psa_export_key` 60* Any trailing data is rejected on load. 61 62### Nonvolatile random seed file format for 0.1.0 63 64The 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. 65 66The file format is just the seed as a byte string with no metadata or encoding of any kind. 67 68### File namespace on ITS for 0.1.0 69 70Assumption: 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. 71 72* File 0: unused. 73* Files 1 through 0xfffeffff: [content](#key-file-format-for-0.1.0) of the [key whose identifier is the file identifier](#key-names-for-0.1.0). 74* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0). 75* Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff: unused. 76 77### File namespace on stdio for 0.1.0 78 79Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23. 80 81An 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). 82 83* `CRYPTO_STORAGE_FILE_LOCATION "psa_key_slot_0"`: used as a temporary file. Must be writable. May be overwritten or deleted if present. 84* `sprintf(CRYPTO_STORAGE_FILE_LOCATION "psa_key_slot_%lu", key_id)` [content](#key-file-format-for-0.1.0) of the [key whose identifier](#key-names-for-0.1.0) is `key_id`. 85* Other files: unused. 86 87Mbed Crypto 1.0.0 88----------------- 89 90Tags: mbedcrypto-1.0.0d4, mbedcrypto-1.0.0 91 92Released in February 2019. <br> 93Integrated in Mbed OS 5.12. 94 95Supported integrations: 96 97* [PSA platform](#file-namespace-on-a-psa-platform-for-1.0.0) 98* [library using PSA ITS](#file-namespace-on-its-as-a-library-for-1.0.0) 99* [library using C stdio](#file-namespace-on-stdio-for-1.0.0) 100 101Supported features: 102 103* [Persistent transparent keys](#key-file-format-for-1.0.0) designated by a [key identifier and owner](#key-names-for-1.0.0). 104* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0) on ITS only. 105 106Backward compatibility commitments: TBD 107 108### Key names for 1.0.0 109 110Information 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. 111 112The 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](#key-file-format-for-1.0.0). 113 114* Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value. 115* PSA service integration: the key file name is `(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. 116 117### Key file format for 1.0.0 118 119The layout is identical to [0.1.0](#key-file-format-for-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). 120 121### Nonvolatile random seed file format for 1.0.0 122 123[Identical to 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0). 124 125### File namespace on a PSA platform for 1.0.0 126 127Assumption: 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. 128 129Assumption: the owner identifier is a nonzero value of type `int32_t`. 130 131* Files 0 through 0xffffff51, 0xffffff53 through 0xffffffff: unused, reserved for internal use of the crypto library or crypto service. 132* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0). 133* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0). The upper 32 bits determine the owner. 134 135### File namespace on ITS as a library for 1.0.0 136 137Assumption: 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. 138 139This is a library integration, so there is no owner. The key file identifier is identical to the key identifier. 140 141* File 0: unused. 142* Files 1 through 0xfffeffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0). 143* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0). 144* Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff, 0x100000000 through 0xffffffffffffffff: unused. 145 146### File namespace on stdio for 1.0.0 147 148This is a library integration, so there is no owner. The key file identifier is identical to the key identifier. 149 150[Identical to 0.1.0](#file-namespace-on-stdio-for-0.1.0). 151 152### Upgrade from 0.1.0 to 1.0.0. 153 154* Delete files 1 through 0xfffeffff, which contain keys in a format that is no longer supported. 155 156### Suggested changes to make before 1.0.0 157 158The 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). 159 160It 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. 161 162Mbed Crypto 1.1.0 163----------------- 164 165Tags: mbedcrypto-1.1.0 166 167Released in early June 2019. <br> 168Integrated in Mbed OS 5.13. 169 170Identical to [1.0.0](#mbed-crypto-1.0.0) except for some changes in the key file format. 171 172### Key file format for 1.1.0 173 174The key file format is identical to [1.0.0](#key-file-format-for-1.0.0), except for the following changes: 175 176* A new policy field, marked as [NEW:1.1.0] below. 177* 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). 178 179A self-contained description of the file layout follows. 180 181All integers are encoded in little-endian order in 8-bit bytes. 182 183The layout of a key file is: 184 185* magic (8 bytes): `"PSA\0KEY\0"` 186* version (4 bytes): 0 187* type (4 bytes): `psa_key_type_t` value 188* policy usage flags (4 bytes): `psa_key_usage_t` value 189* policy usage algorithm (4 bytes): `psa_algorithm_t` value 190* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value [NEW:1.1.0] 191* key material length (4 bytes) 192* key material: output of `psa_export_key` 193* Any trailing data is rejected on load. 194 195Mbed Crypto TBD 196--------------- 197 198Tags: TBD 199 200Released in TBD 2019. <br> 201Integrated in Mbed OS TBD. 202 203### Changes introduced in TBD 204 205* The layout of a key file now has a lifetime field before the type field. 206* Key files can store references to keys in a secure element. In such key files, the key material contains the slot number. 207 208### File namespace on a PSA platform on TBD 209 210Assumption: 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. 211 212Assumption: the owner identifier is a nonzero value of type `int32_t`. 213 214* Files 0 through 0xfffeffff: unused. 215* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd). 216* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0). The upper 32 bits determine the owner. 217 218### File namespace on ITS as a library on TBD 219 220Assumption: 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. 221 222This is a library integration, so there is no owner. The key file identifier is identical to the key identifier. 223 224* File 0: unused. 225* Files 1 through 0xfffeffff: [content](#key-file-format-for-1.0.0) of the [key whose identifier is the file identifier](#key-names-for-1.0.0). 226* Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd). 227* Files 0x100000000 through 0xffffffffffffffff: unused. 228 229### Non-key files on TBD 230 231File identifiers in the range 0xffff0000 through 0xffffffff are reserved for internal use in Mbed Crypto. 232 233* Files 0xfffffe02 through 0xfffffeff (`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. 234* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0). 235* File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-tbd). 236* Other files are unused and reserved for future use. 237 238### Key file format for TBD 239 240All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated. 241 242The layout of a key file is: 243 244* magic (8 bytes): `"PSA\0KEY\0"`. 245* version (4 bytes): 0. 246* lifetime (4 bytes): `psa_key_lifetime_t` value. 247* type (4 bytes): `psa_key_type_t` value. 248* policy usage flags (4 bytes): `psa_key_usage_t` value. 249* policy usage algorithm (4 bytes): `psa_algorithm_t` value. 250* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value. 251* key material length (4 bytes). 252* key material: 253 * For a transparent key: output of `psa_export_key`. 254 * For an opaque key (unified driver interface): driver-specific opaque key blob. 255 * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness. 256* Any trailing data is rejected on load. 257 258### Transaction file format for TBD 259 260The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction. 261 262All integers are encoded in platform endianness. 263 264All currently existing transactions concern a key in a secure element. 265 266The layout of a transaction file is: 267 268* type (2 bytes): the [transaction type](#transaction-types-on-tbd). 269* unused (2 bytes) 270* lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element. 271* slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver. 272* key identifier (4 bytes in a library integration, 8 bytes on a PSA platform): the internal representation of the key identifier. On a PSA platform, this encodes the key owner in the same way as [in file identifiers for key files](#file-namespace-on-a-psa-platform-on-tbd)). 273 274#### Transaction types on TBD 275 276* 0x0001: key creation. The following locations may or may not contain data about the key that is being created: 277 * The slot in the secure element designated by the slot number. 278 * The file containing the key metadata designated by the key identifier. 279 * The driver persistent data. 280* 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed: 281 * The slot in the secure element designated by the slot number. 282 * The file containing the key metadata designated by the key identifier. 283 * The driver persistent data. 284 285Mbed Crypto TBD 286--------------- 287 288Tags: TBD 289 290Released in TBD 2020. <br> 291Integrated in Mbed OS TBD. 292 293### Changes introduced in TBD 294 295* The type field has been split into a type and a bits field of 2 bytes each. 296 297### Key file format for TBD 298 299All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated. 300 301The layout of a key file is: 302 303* magic (8 bytes): `"PSA\0KEY\0"`. 304* version (4 bytes): 0. 305* lifetime (4 bytes): `psa_key_lifetime_t` value. 306* type (2 bytes): `psa_key_type_t` value. 307* bits (2 bytes): `psa_key_bits_t` value. 308* policy usage flags (4 bytes): `psa_key_usage_t` value. 309* policy usage algorithm (4 bytes): `psa_algorithm_t` value. 310* policy enrollment algorithm (4 bytes): `psa_algorithm_t` value. 311* key material length (4 bytes). 312* key material: 313 * For a transparent key: output of `psa_export_key`. 314 * For an opaque key (unified driver interface): driver-specific opaque key blob. 315 * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness. 316* Any trailing data is rejected on load. 317