From 4945176ebe196321051884455e5267070300bd24 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 12 Feb 2019 14:25:40 +0100 Subject: [PATCH 1/4] Add framework for architecture documents in Markdown --- docs/architecture/.gitignore | 2 ++ docs/architecture/Makefile | 18 ++++++++++++++++++ 2 files changed, 20 insertions(+) create mode 100644 docs/architecture/.gitignore create mode 100644 docs/architecture/Makefile diff --git a/docs/architecture/.gitignore b/docs/architecture/.gitignore new file mode 100644 index 000000000..23f832b73 --- /dev/null +++ b/docs/architecture/.gitignore @@ -0,0 +1,2 @@ +*.html +*.pdf diff --git a/docs/architecture/Makefile b/docs/architecture/Makefile new file mode 100644 index 000000000..4873daeb8 --- /dev/null +++ b/docs/architecture/Makefile @@ -0,0 +1,18 @@ +PANDOC = pandoc + +default: all + +all_markdown = \ + # This line is intentionally left blank + +html: $(all_markdown:.md=.html) +pdf: $(all_markdown:.md=.pdf) +all: html pdf + +.SUFFIXES: +.SUFFIXES: .md .html .pdf + +.md.html: + $(PANDOC) -o $@ $< +.md.pdf: + $(PANDOC) -o $@ $< From 0b02002fec185d5c1e2f96e9b570709335417aeb Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 12 Feb 2019 14:25:57 +0100 Subject: [PATCH 2/4] Specification of how Mbed Crypto uses storage Describe the storage format for keys and random seed in Mbed Crypto 0.1.0 released with Mbed OS 5.11, over C stdio and over ITS with 32-bit file identifiers. Describe the proposed storage format for keys and random seed in the future release of Mbed Crypto for Mbed OS 5.12, over C stdio and over ITS with 64-bit file identifiers. --- docs/architecture/Makefile | 1 + .../mbed-crypto-storage-specification.md | 153 ++++++++++++++++++ 2 files changed, 154 insertions(+) create mode 100644 docs/architecture/mbed-crypto-storage-specification.md diff --git a/docs/architecture/Makefile b/docs/architecture/Makefile index 4873daeb8..f763c9c54 100644 --- a/docs/architecture/Makefile +++ b/docs/architecture/Makefile @@ -3,6 +3,7 @@ PANDOC = pandoc default: all all_markdown = \ + mbed-crypto-storage-specification.md \ # This line is intentionally left blank html: $(all_markdown:.md=.html) diff --git a/docs/architecture/mbed-crypto-storage-specification.md b/docs/architecture/mbed-crypto-storage-specification.md new file mode 100644 index 000000000..fc95b3644 --- /dev/null +++ b/docs/architecture/mbed-crypto-storage-specification.md @@ -0,0 +1,153 @@ +Mbed Crypto storage specification +================================= + +This document specifies how Mbed Crypto uses storage. + +Mbed Crypto may be upgraded on an existing device with the storage preserved. Therefore: + +1. Any change may break existing installations and may require an upgrade path. +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. + +Mbed Crypto 0.1.0 +----------------- + +Tags: mbedcrypto-0.1.0b, mbedcrypto-0.1.0b2 + +Released in November 2018.
+Integrated in Mbed OS 5.11. + +Supported backends: + +* [PSA ITS](#file-namespace-on-its-for-0.1.0) +* [C stdio](#file-namespace-on-stdio-for-0.1.0) + +Supported features: + +* [Persistent transparent keys](#key-file-format-for-0.1.0) designated by a [slot number](#key-names-for-0.1.0). +* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0) on ITS only. + +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. + +### Key names for 0.1.0 + +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). + +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. + +### Key file format for 0.1.0 + +All integers are encoded in little-endian order in 8-bit bytes. + +The layout of a key file is: + +* magic (8 bytes): `"PSA\0KEY\0"` +* version (4 bytes): 0 +* type (4 bytes): `psa_key_type_t` value +* policy usage flags (4 bytes): `psa_key_usage_t` value +* policy usage algorithm (4 bytes): `psa_algorithm_t` value +* key material length (4 bytes) +* key material: output of `psa_export_key` +* Any trailing data is rejected on load. + +### Nonvolatile random seed file format for 0.1.0 + +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. + +### File namespace on ITS for 0.1.0 + +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. + +* File 0: unused. +* 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). +* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0). +* Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff: unused. + +### File namespace on stdio for 0.1.0 + +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](#key-file-format-for-0.1.0) of the [key whose identifier](#key-names-for-0.1.0) is `key_id`. +* Other files: unused. + +Mbed Crypto 0.2.0 +----------------- + +**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: + +* [PSA platform](#file-namespace-on-a-psa-platform-for-0.2.0) +* [library using PSA ITS](#file-namespace-on-its-as-a-library-for-0.2.0) +* [library using C stdio](#file-namespace-on-stdio-for-0.2.0) + +Supported features: + +* [Persistent transparent keys](#key-file-format-for-0.2.0) designated by a [key identifier and owner](#key-names-for-0.2.0). +* [Nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.2.0) on ITS only. + +Backward compatibility commitments: TBD + +### Key names for 0.2.0 + +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](#key-file-format-for-0.2.0). + +The valid values for a key identifier are the range from 1 to 0xfffeffff. The range is not documented. + +* Library integration: the key file name is just the key identifer. This is a 32-bit value. +* PSA service integration: the key file name is `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. + +### Key file format for 0.2.0 + +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 version so far). + +### Nonvolatile random seed file format for 0.2.0 + +[Identical to 0.1.0](#nonvolatile-random-seed-file-format-for-0.1.0). + +### File namespace on a PSA platform for 0.2.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. + +* Files 0 through 0xffffff51, 0xffffff53 through 0xffffffff: unused. +* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.1.0). +* Files 0x100000000 through 0xffffffffffff: [content](#key-file-format-for-0.2.0) of the [key whose identifier is the file identifier](#key-names-for-0.2.0). + +### File namespace on ITS as a library for 0.2.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. + +* File 0: unused. +* Files 1 through 0xfffeffff: [content](#key-file-format-for-0.2.0) of the [key whose identifier is the file identifier](#key-names-for-0.2.0). +* File 0xffffff52 (`PSA_CRYPTO_ITS_RANDOM_SEED_UID`): [nonvolatile random seed](#nonvolatile-random-seed-file-format-for-0.2.0). +* Files 0xffff0000 through 0xffffff51, 0xffffff53 through 0xffffffff, 0x100000000 through 0xffffffffffffffff: unused. + +### File namespace on stdio for 0.2.0 + +[Identical to 0.1.0](#file-namespace-on-stdio-for-0.1.0). + +### Upgrade from 0.1.0 to 0.2.0. + +* Delete files 1 through 0xfffeffff, which contain keys in a format that is no longer supported. + +### Suggested changes to make before 0.2.0 + +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. From b5a132f26c21bdf530affaa5db18fbc7fcf8c670 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 12 Feb 2019 16:47:20 +0100 Subject: [PATCH 3/4] Minor clarifications --- docs/architecture/mbed-crypto-storage-specification.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/architecture/mbed-crypto-storage-specification.md b/docs/architecture/mbed-crypto-storage-specification.md index fc95b3644..1557a4f90 100644 --- a/docs/architecture/mbed-crypto-storage-specification.md +++ b/docs/architecture/mbed-crypto-storage-specification.md @@ -36,7 +36,7 @@ We do not make any promises regarding key storage, or regarding the nonvolatile 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). -The valid values for a key identifier are the range from 1 to 0xfffeffff. The range is not documented. +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): @@ -108,14 +108,14 @@ 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](#key-file-format-for-0.2.0). -The valid values for a key identifier are the range from 1 to 0xfffeffff. The range is not documented. +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. * Library integration: the key file name is just the key identifer. This is a 32-bit value. * PSA service integration: the key file name is `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. ### Key file format for 0.2.0 -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 version so far). +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). ### Nonvolatile random seed file format for 0.2.0 From f02fbf4bbe216b37723bbbfc65d359b941391880 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Feb 2019 15:43:35 +0100 Subject: [PATCH 4/4] Don't mention "crypto service" when discussing a library integration --- docs/architecture/mbed-crypto-storage-specification.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/architecture/mbed-crypto-storage-specification.md b/docs/architecture/mbed-crypto-storage-specification.md index 1557a4f90..d56d3331c 100644 --- a/docs/architecture/mbed-crypto-storage-specification.md +++ b/docs/architecture/mbed-crypto-storage-specification.md @@ -111,7 +111,7 @@ Information about each key is stored in a dedicated file whose name is construct 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. * Library integration: the key file name is just the key identifer. This is a 32-bit value. -* PSA service integration: the key file name is `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. +* PSA service integration: the key file name is `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 server by the partition manager. This is a 64-bit value. ### Key file format for 0.2.0 @@ -131,7 +131,7 @@ Assumption: ITS provides a 64-bit file identifier namespace. The Crypto service ### File namespace on ITS as a library for 0.2.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: 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. * File 0: unused. * Files 1 through 0xfffeffff: [content](#key-file-format-for-0.2.0) of the [key whose identifier is the file identifier](#key-names-for-0.2.0).