mbed-crypto-storage-specification.md (26485B)
1 Mbed TLS storage specification 2 ================================= 3 4 This document specifies how Mbed TLS uses storage. 5 Key storage was originally introduced in a product called Mbed Crypto, which was re-distributed via Mbed TLS and has since been merged into Mbed TLS. 6 This document contains historical information both from before and after this merge. 7 8 Mbed Crypto may be upgraded on an existing device with the storage preserved. Therefore: 9 10 1. Any change may break existing installations and may require an upgrade path. 11 1. 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. 12 13 Mbed Crypto 0.1.0 14 ----------------- 15 16 Tags: mbedcrypto-0.1.0b, mbedcrypto-0.1.0b2 17 18 Released in November 2018. <br> 19 Integrated in Mbed OS 5.11. 20 21 Supported backends: 22 23 * [PSA ITS](#file-namespace-on-its-for-0.1.0) 24 * [C stdio](#file-namespace-on-stdio-for-0.1.0) 25 26 Supported features: 27 28 * [Persistent transparent keys](#key-file-format-for-0.1.0) designated by a [slot number](#key-names-for-0.1.0). 29 * [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0) on ITS only. 30 31 This is a beta release, and we do not promise backward compatibility, with one exception: 32 33 > 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. 34 35 We do not make any promises regarding key storage, or regarding the nonvolatile random seed file on other platforms. 36 37 ### Key names for 0.1.0 38 39 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](#key-file-format-for-0.1.0). 40 41 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. 42 43 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): 44 45 #define PSA_MAX_PERSISTENT_KEY_IDENTIFIER 0xffff0000 46 47 There is a shared namespace for all callers. 48 49 ### Key file format for 0.1.0 50 51 All integers are encoded in little-endian order in 8-bit bytes. 52 53 The layout of a key file is: 54 55 * magic (8 bytes): `"PSA\0KEY\0"` 56 * version (4 bytes): 0 57 * type (4 bytes): `psa_key_type_t` value 58 * policy usage flags (4 bytes): `psa_key_usage_t` value 59 * policy usage algorithm (4 bytes): `psa_algorithm_t` value 60 * key material length (4 bytes) 61 * key material: output of `psa_export_key` 62 * Any trailing data is rejected on load. 63 64 ### Nonvolatile random seed file format for 0.1.0 65 66 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. 67 68 The file format is just the seed as a byte string with no metadata or encoding of any kind. 69 70 ### File namespace on ITS for 0.1.0 71 72 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. 73 74 * File 0: unused. 75 * 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). 76 * File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0). 77 * Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff: unused. 78 79 ### File namespace on stdio for 0.1.0 80 81 Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23. 82 83 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). 84 85 * `CRYPTO_STORAGE_FILE_LOCATION "psa_key_slot_0"`: used as a temporary file. Must be writable. May be overwritten or deleted if present. 86 * `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`. 87 * Other files: unused. 88 89 Mbed Crypto 1.0.0 90 ----------------- 91 92 Tags: mbedcrypto-1.0.0d4, mbedcrypto-1.0.0 93 94 Released in February 2019. <br> 95 Integrated in Mbed OS 5.12. 96 97 Supported integrations: 98 99 * [PSA platform](#file-namespace-on-a-psa-platform-for-1.0.0) 100 * [library using PSA ITS](#file-namespace-on-its-as-a-library-for-1.0.0) 101 * [library using C stdio](#file-namespace-on-stdio-for-1.0.0) 102 103 Supported features: 104 105 * [Persistent transparent keys](#key-file-format-for-1.0.0) designated by a [key identifier and owner](#key-names-for-1.0.0). 106 * [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0) on ITS only. 107 108 Backward compatibility commitments: TBD 109 110 ### Key names for 1.0.0 111 112 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. 113 114 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](#key-file-format-for-1.0.0). 115 116 * Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value. 117 * PSA service integration: the key file name is `(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. 118 119 ### Key file format for 1.0.0 120 121 The 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). 122 123 ### Nonvolatile random seed file format for 1.0.0 124 125 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. 126 127 The file format is just the seed as a byte string with no metadata or encoding of any kind. 128 129 This is unchanged since [the feature was introduced in Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0). 130 131 ### File namespace on a PSA platform for 1.0.0 132 133 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. 134 135 Assumption: the owner identifier is a nonzero value of type `int32_t`. 136 137 * Files 0 through 0xffffff51, 0xffffff53 through 0xffffffff: unused, reserved for internal use of the crypto library or crypto service. 138 * File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0). 139 * 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. 140 141 ### File namespace on ITS as a library for 1.0.0 142 143 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. 144 145 This is a library integration, so there is no owner. The key file identifier is identical to the key identifier. 146 147 * File 0: unused. 148 * 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). 149 * File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0). 150 * Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff, 0x100000000 through 0xffffffffffffffff: unused. 151 152 ### File namespace on stdio for 1.0.0 153 154 This is a library integration, so there is no owner. The key file identifier is identical to the key identifier. 155 156 [Identical to 0.1.0](#file-namespace-on-stdio-for-0.1.0). 157 158 ### Upgrade from 0.1.0 to 1.0.0. 159 160 * Delete files 1 through 0xfffeffff, which contain keys in a format that is no longer supported. 161 162 ### Suggested changes to make before 1.0.0 163 164 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). 165 166 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. 167 168 Mbed Crypto 1.1.0 169 ----------------- 170 171 Tags: mbedcrypto-1.1.0 172 173 Released in early June 2019. <br> 174 Integrated in Mbed OS 5.13. 175 176 Changes since [1.0.0](#mbed-crypto-1.0.0): 177 178 * The stdio backend for storage has been replaced by an implementation of [PSA ITS over stdio](#file-namespace-on-stdio-for-1.1.0). 179 * [Some changes in the key file format](#key-file-format-for-1.1.0). 180 181 ### File namespace on stdio for 1.1.0 182 183 Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23. 184 185 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). 186 187 * `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present. 188 * `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](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a non-key file (currently: only the [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0)). The contents of the file are: 189 * Magic header (8 bytes): `"PSA\0ITS\0"` 190 * File contents. 191 192 ### Key file format for 1.1.0 193 194 The key file format is identical to [1.0.0](#key-file-format-for-1.0.0), except for the following changes: 195 196 * A new policy field, marked as [NEW:1.1.0] below. 197 * 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). 198 199 A self-contained description of the file layout follows. 200 201 All integers are encoded in little-endian order in 8-bit bytes. 202 203 The layout of a key file is: 204 205 * magic (8 bytes): `"PSA\0KEY\0"` 206 * version (4 bytes): 0 207 * type (4 bytes): `psa_key_type_t` value 208 * policy usage flags (4 bytes): `psa_key_usage_t` value 209 * policy usage algorithm (4 bytes): `psa_algorithm_t` value 210 * policy enrollment algorithm (4 bytes): `psa_algorithm_t` value [NEW:1.1.0] 211 * key material length (4 bytes) 212 * key material: output of `psa_export_key` 213 * Any trailing data is rejected on load. 214 215 Mbed Crypto TBD 216 --------------- 217 218 Tags: TBD 219 220 Released in TBD 2019. <br> 221 Integrated in Mbed OS TBD. 222 223 ### Changes introduced in TBD 224 225 * The layout of a key file now has a lifetime field before the type field. 226 * Key files can store references to keys in a secure element. In such key files, the key material contains the slot number. 227 228 ### File namespace on a PSA platform on TBD 229 230 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. 231 232 Assumption: the owner identifier is a nonzero value of type `int32_t`. 233 234 * Files 0 through 0xfffeffff: unused. 235 * Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd). 236 * 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. 237 238 ### File namespace on ITS as a library on TBD 239 240 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. 241 242 This is a library integration, so there is no owner. The key file identifier is identical to the key identifier. 243 244 * File 0: unused. 245 * 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). 246 * Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-tbd). 247 * Files 0x100000000 through 0xffffffffffffffff: unused. 248 249 ### Non-key files on TBD 250 251 File identifiers in the range 0xffff0000 through 0xffffffff are reserved for internal use in Mbed Crypto. 252 253 * 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. 254 * File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-1.0.0). 255 * File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-tbd). 256 * Other files are unused and reserved for future use. 257 258 ### Key file format for TBD 259 260 All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated. 261 262 The layout of a key file is: 263 264 * magic (8 bytes): `"PSA\0KEY\0"`. 265 * version (4 bytes): 0. 266 * lifetime (4 bytes): `psa_key_lifetime_t` value. 267 * type (4 bytes): `psa_key_type_t` value. 268 * policy usage flags (4 bytes): `psa_key_usage_t` value. 269 * policy usage algorithm (4 bytes): `psa_algorithm_t` value. 270 * policy enrollment algorithm (4 bytes): `psa_algorithm_t` value. 271 * key material length (4 bytes). 272 * key material: 273 * For a transparent key: output of `psa_export_key`. 274 * For an opaque key (unified driver interface): driver-specific opaque key blob. 275 * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness. 276 * Any trailing data is rejected on load. 277 278 ### Transaction file format for TBD 279 280 The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction. 281 282 All integers are encoded in platform endianness. 283 284 All currently existing transactions concern a key in a secure element. 285 286 The layout of a transaction file is: 287 288 * type (2 bytes): the [transaction type](#transaction-types-on-tbd). 289 * unused (2 bytes) 290 * lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element. 291 * slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver. 292 * 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)). 293 294 #### Transaction types on TBD 295 296 * 0x0001: key creation. The following locations may or may not contain data about the key that is being created: 297 * The slot in the secure element designated by the slot number. 298 * The file containing the key metadata designated by the key identifier. 299 * The driver persistent data. 300 * 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed: 301 * The slot in the secure element designated by the slot number. 302 * The file containing the key metadata designated by the key identifier. 303 * The driver persistent data. 304 305 Mbed Crypto TBD 306 --------------- 307 308 Tags: TBD 309 310 Released in TBD 2020. <br> 311 Integrated in Mbed OS TBD. 312 313 ### Changes introduced in TBD 314 315 * The type field has been split into a type and a bits field of 2 bytes each. 316 317 ### Key file format for TBD 318 319 All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated. 320 321 The layout of a key file is: 322 323 * magic (8 bytes): `"PSA\0KEY\0"`. 324 * version (4 bytes): 0. 325 * lifetime (4 bytes): `psa_key_lifetime_t` value. 326 * type (2 bytes): `psa_key_type_t` value. 327 * bits (2 bytes): `psa_key_bits_t` value. 328 * policy usage flags (4 bytes): `psa_key_usage_t` value. 329 * policy usage algorithm (4 bytes): `psa_algorithm_t` value. 330 * policy enrollment algorithm (4 bytes): `psa_algorithm_t` value. 331 * key material length (4 bytes). 332 * key material: 333 * For a transparent key: output of `psa_export_key`. 334 * For an opaque key (unified driver interface): driver-specific opaque key blob. 335 * For an opaque key (key in a secure element): slot number (8 bytes), in platform endianness. 336 * Any trailing data is rejected on load. 337 338 Mbed TLS 2.25.0 339 --------------- 340 341 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` 342 343 First released in December 2020. 344 345 Note: this is the first version that is officially supported. The version number is still 0. 346 347 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`](../../BRANCHES.md) for more details. 348 349 Supported integrations: 350 351 * [PSA platform](#file-namespace-on-a-psa-platform-on-mbed-tls-2.25.0) 352 * [library using PSA ITS](#file-namespace-on-its-as-a-library-on-mbed-tls-2.25.0) 353 * [library using C stdio](#file-namespace-on-stdio-for-mbed-tls-2.25.0) 354 355 Supported features: 356 357 * [Persistent keys](#key-file-format-for-mbed-tls-2.25.0) designated by a [key identifier and owner](#key-names-for-mbed-tls-2.25.0). Keys can be: 358 * Transparent, stored in the export format. 359 * Opaque, using the PSA driver interface with statically registered drivers. The driver determines the content of the opaque key blob. 360 * Opaque, using the deprecated secure element interface with dynamically registered drivers (`MBEDTLS_PSA_CRYPTO_SE_C`). The driver picks a slot number which is stored in the place of the key material. 361 * [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0) on ITS only. 362 363 ### Changes introduced in Mbed TLS 2.25.0 364 365 * The numerical encodings of `psa_key_type_t`, `psa_key_usage_t` and `psa_algorithm_t` have changed. 366 367 ### File namespace on a PSA platform on Mbed TLS 2.25.0 368 369 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. 370 371 Assumption: the owner identifier is a nonzero value of type `int32_t`. 372 373 * Files 0 through 0xfffeffff: unused. 374 * Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0). 375 * Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0). The upper 32 bits determine the owner. 376 377 ### File namespace on ITS as a library on Mbed TLS 2.25.0 378 379 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. 380 381 This is a library integration, so there is no owner. The key file identifier is identical to the key identifier. 382 383 * File 0: unused. 384 * Files 1 through 0xfffeffff: [content](#key-file-format-for-mbed-tls-2.25.0) of the [key whose identifier is the file identifier](#key-names-for-mbed-tls-2.25.0). 385 * Files 0xffff0000 through 0xffffffff: reserved for internal use of the crypto library or crypto service. See [non-key files](#non-key-files-on-mbed-tls-2.25.0). 386 * Files 0x100000000 through 0xffffffffffffffff: unused. 387 388 ### File namespace on stdio for Mbed TLS 2.25.0 389 390 Assumption: C stdio, allowing names containing lowercase letters, digits and underscores, of length up to 23. 391 392 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). 393 394 * `PSA_ITS_STORAGE_PREFIX "tempfile.psa_its"`: used as a temporary file. Must be writable. May be overwritten or deleted if present. 395 * `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](#key-names-for-mbed-tls-2.25.0) for a key file or some reserved identifier for a [non-key file](#non-key-files-on-mbed-tls-2.25.0). The contents of the file are: 396 * Magic header (8 bytes): `"PSA\0ITS\0"` 397 * File contents. 398 399 ### Key names for Mbed TLS 2.25.0 400 401 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. 402 403 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](#key-file-format-for-mbed-tls-2.25.0). 404 405 * Library integration: the key file name is just the key identifier as defined in the PSA crypto specification. This is a 32-bit value which must be in the range 0x00000001..0x3fffffff (`PSA_KEY_ID_USER_MIN`..`PSA_KEY_ID_USER_MAX`). 406 * PSA service integration: the key file name is `(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. 407 408 ### Key file format for Mbed TLS 2.25.0 409 410 All integers are encoded in little-endian order in 8-bit bytes except where otherwise indicated. 411 412 The layout of a key file is: 413 414 * magic (8 bytes): `"PSA\0KEY\0"`. 415 * version (4 bytes): 0. 416 * lifetime (4 bytes): `psa_key_lifetime_t` value. 417 * type (2 bytes): `psa_key_type_t` value. 418 * bits (2 bytes): `psa_key_bits_t` value. 419 * policy usage flags (4 bytes): `psa_key_usage_t` value. 420 * policy usage algorithm (4 bytes): `psa_algorithm_t` value. 421 * policy enrollment algorithm (4 bytes): `psa_algorithm_t` value. 422 * key material length (4 bytes). 423 * key material: 424 * For a transparent key: output of `psa_export_key`. 425 * For an opaque key (unified driver interface): driver-specific opaque key blob. 426 * For an opaque key (key in a dynamic secure element): slot number (8 bytes), in platform endianness. 427 * Any trailing data is rejected on load. 428 429 ### Non-key files on Mbed TLS 2.25.0 430 431 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. 432 433 * Files 0xfffffe02 through 0xfffffeff (`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. 434 * File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-mbed-tls-2.25.0). 435 * File 0xffffff54 (`PSA_CRYPTO_ITS_TRANSACTION_UID`): [transaction file](#transaction-file-format-for-mbed-tls-2.25.0). 436 * Other files are unused and reserved for future use. 437 438 ### Nonvolatile random seed file format for Mbed TLS 2.25.0 439 440 [Identical to Mbed Crypto 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0). 441 442 ### Transaction file format for Mbed TLS 2.25.0 443 444 The transaction file contains data about an ongoing action that cannot be completed atomically. It exists only if there is an ongoing transaction. 445 446 All integers are encoded in platform endianness. 447 448 All currently existing transactions concern a key in a dynamic secure element. 449 450 The layout of a transaction file is: 451 452 * type (2 bytes): the [transaction type](#transaction-types-on-mbed-tls-2.25.0). 453 * unused (2 bytes) 454 * lifetime (4 bytes): `psa_key_lifetime_t` value that corresponds to a key in a secure element. 455 * slot number (8 bytes): `psa_key_slot_number_t` value. This is the unique designation of the key for the secure element driver. 456 * 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-mbed-tls-2.25.0)). 457 458 #### Transaction types on Mbed TLS 2.25.0 459 460 * 0x0001: key creation. The following locations may or may not contain data about the key that is being created: 461 * The slot in the secure element designated by the slot number. 462 * The file containing the key metadata designated by the key identifier. 463 * The driver persistent data. 464 * 0x0002: key destruction. The following locations may or may not still contain data about the key that is being destroyed: 465 * The slot in the secure element designated by the slot number. 466 * The file containing the key metadata designated by the key identifier. 467 * The driver persistent data.