From 95434380e14be572e374e415122a91ff56efa5c0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 21 Sep 2020 20:08:51 +0200 Subject: [PATCH 01/12] Detailed architecture of symbol definitions and header inclusion Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 27 ++++++++++++++++++-- 1 file changed, 25 insertions(+), 2 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 08306d283..753aaf7b7 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/09/07 08:27:32 GMT" +Time-stamp: "2020/09/21 18:07:09 GMT" ## Introduction @@ -109,7 +109,30 @@ These symbols are not part of the public interface of Mbed TLS towards applicati #### Definition of internal inclusion symbols -The header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. +When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. + +When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` is only needed to build the PSA parts of the library, including `psa/crypto_struct.h`. Therefore, * `psa/crypto_struct.h` needs to include `mbedtls/config_psa.h`. + +`mbedtls/config_psa.h` includes two header files: + +* `psa/crypto_config.h` is the user-editable file that defines application requirements. It is only included when `MBEDTLS_PSA_CRYPTO_CONFIG` is set. +* `mbedtls/crypto_drivers.h` is a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback. + +The following table summarized where symbols are defined depending on the configuration mode. + +* (U) indicates a symbol that is defined by the user (application). +* (D) indicates a symbol that is deduced from other symbols by code that ships with Mbed TLS. +* (G) indicates a symbol that is generated from driver descriptions. + +------------------------------------------------------------------------------------------------ +Symbols With `MBEDTLS_PSA_CRYPTO_CONFIG` Without `MBEDTLS_PSA_CRYPTO_CONFIG` +------------------------- -------------------------------- ----------------------------------- +`MBEDTLS_xxx_C` `mbedtls/config.h` (U) or `mbedtls/config.h` (U) + `mbedtls/config_psa.h` (D) +`PSA_WANT_xxx` `psa/crypto_config.h` (U) N/A +`MBEDTLS_PSA_BUILTIN_xxx` `mbedtls/config_psa.h` (D) `mbedtls/config_psa.h` (D) +`MBEDTLS_PSA_ACCEL_xxx` `mbedtls/crypto_drivers` (G) N/A +------------------------------------------------------------------------------------------------ #### Visibility of internal symbols From 55687646c84239efc5ce58873b71bdbc2ef4a53f Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 12 Oct 2020 23:23:52 +0200 Subject: [PATCH 02/12] PSA_WANT_xxx needs to be defined in the old-style config mechanism Without MBEDTLS_PSA_CRYPTO_CONFIG, PSA_WANT_xxx needs to be defined, for the sake of code that calls the PSA API (TLS code, tests, sample apps). Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 753aaf7b7..5212c59a3 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/09/21 18:07:09 GMT" +Time-stamp: "2020/10/12 21:23:39 GMT" ## Introduction @@ -129,7 +129,7 @@ Symbols With `MBEDTLS_PSA_CRYPTO_CONFIG` Without `MBEDTLS_PS ------------------------- -------------------------------- ----------------------------------- `MBEDTLS_xxx_C` `mbedtls/config.h` (U) or `mbedtls/config.h` (U) `mbedtls/config_psa.h` (D) -`PSA_WANT_xxx` `psa/crypto_config.h` (U) N/A +`PSA_WANT_xxx` `psa/crypto_config.h` (U) `mbedtls/config_psa.h (D) `MBEDTLS_PSA_BUILTIN_xxx` `mbedtls/config_psa.h` (D) `mbedtls/config_psa.h` (D) `MBEDTLS_PSA_ACCEL_xxx` `mbedtls/crypto_drivers` (G) N/A ------------------------------------------------------------------------------------------------ From 48584b589f5a7171c6f124af1fde4ea185403e46 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 13 Oct 2020 19:07:02 +0200 Subject: [PATCH 03/12] Editorial fixes Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 5212c59a3..6267f103c 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/10/12 21:23:39 GMT" +Time-stamp: "2020/10/13 17:05:02 GMT" ## Introduction @@ -51,9 +51,9 @@ The current model is difficult to adapt to the PSA interface for several reasons ### PSA Crypto configuration file -The PSA crypto configuration file `psa/crypto_config.h` defines a series of symbols of the form `PSA_WANT_xxx` where `xxx` . The symbols are documented in the section [“PSA Crypto configuration symbols”](#psa-crypto-configuration-symbols) below. +The PSA crypto configuration file `psa/crypto_config.h` defines a series of symbols of the form `PSA_WANT_xxx` where `xxx` describes the feature that the symbol enables. The symbols are documented in the section [“PSA Crypto configuration symbols”](#psa-crypto-configuration-symbols) below. -The symbol `MBEDTLS_PSA_CRYPTO_CONFIG` in `mbedtls/config.h` determines whether `psa/crypto_config.h`. is used. +The symbol `MBEDTLS_PSA_CRYPTO_CONFIG` in `mbedtls/config.h` determines whether `psa/crypto_config.h` is used. * If `MBEDTLS_PSA_CRYPTO_CONFIG` is unset, which is the default at least in Mbed TLS 2.x versions, things are as they are today: the PSA subsystem includes generic code unconditionally, and includes support for specific mechanisms conditionally based on the existing `MBEDTLS_xxx_` symbols. * If `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the necessary software implementations of cryptographic algorithms are included based on both the content of the PSA crypto configuration file and the Mbed TLS configuration file. For example, the code in `aes.c` is enabled if either `mbedtls/config.h` contains `MBEDTLS_AES_C` or `psa/crypto_config.h` contains `PSA_WANT_KEY_TYPE_AES`. From 7b5e6b9dcc1f5ca9d560e10445331a7883da24da Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 4 Nov 2020 18:30:01 +0100 Subject: [PATCH 04/12] Typos and clarifications Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 6267f103c..bf969f5e6 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -111,7 +111,7 @@ These symbols are not part of the public interface of Mbed TLS towards applicati When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. -When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` is only needed to build the PSA parts of the library, including `psa/crypto_struct.h`. Therefore, * `psa/crypto_struct.h` needs to include `mbedtls/config_psa.h`. +When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` is only needed to build the PSA parts of the library, including `psa/crypto_struct.h` (where the layout of some structures depends on the configuration). Therefore, `psa/crypto_struct.h` (or a header that is included before it) needs to include `mbedtls/config_psa.h`. `mbedtls/config_psa.h` includes two header files: @@ -131,7 +131,7 @@ Symbols With `MBEDTLS_PSA_CRYPTO_CONFIG` Without `MBEDTLS_PS `mbedtls/config_psa.h` (D) `PSA_WANT_xxx` `psa/crypto_config.h` (U) `mbedtls/config_psa.h (D) `MBEDTLS_PSA_BUILTIN_xxx` `mbedtls/config_psa.h` (D) `mbedtls/config_psa.h` (D) -`MBEDTLS_PSA_ACCEL_xxx` `mbedtls/crypto_drivers` (G) N/A +`MBEDTLS_PSA_ACCEL_xxx` `mbedtls/crypto_drivers.h` (G) N/A ------------------------------------------------------------------------------------------------ #### Visibility of internal symbols From b2679984d973c43f02cdf2d288aacb2236613409 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 5 Nov 2020 10:50:35 +0100 Subject: [PATCH 05/12] Note that crypto_sizes.h needs config_psa.h as well Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index bf969f5e6..1f4fef3e9 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/10/13 17:05:02 GMT" +Time-stamp: "2020/11/05 09:50:28 GMT" ## Introduction @@ -111,7 +111,7 @@ These symbols are not part of the public interface of Mbed TLS towards applicati When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. -When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` is only needed to build the PSA parts of the library, including `psa/crypto_struct.h` (where the layout of some structures depends on the configuration). Therefore, `psa/crypto_struct.h` (or a header that is included before it) needs to include `mbedtls/config_psa.h`. +When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` is only needed to build the PSA parts of the library and code that uses these parts. Note that `psa/crypto_struct.h` and `psa/crypto_sizes.h` include definitions that depend on the configuration, so `mbedtls/config_psa.h` needs to be included in or before these headers (it isn't enough to include it only from files in `library`). `mbedtls/config_psa.h` includes two header files: From 993c2492426ab49a0644afa2e38cfe52dab6a504 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Fri, 13 Nov 2020 22:45:13 +0100 Subject: [PATCH 06/12] Add a section explaining the uses of PSA_WANT_xxx PSA_WANT_xxx is useful regardless of how the symbols are defined: explicitly (with MBEDTLS_PSA_CRYPTO_CONFIG) or implicitly (without MBEDTLS_PSA_CRYPTO_CONFIG). Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 1f4fef3e9..383bf5f00 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/05 09:50:28 GMT" +Time-stamp: "2020/11/13 21:45:08 GMT" ## Introduction @@ -68,6 +68,14 @@ A PSA crypto configuration symbol is a C preprocessor symbol whose name starts w * If the symbol is defined to a preprocessor expression with the value `1`, the corresponding feature is included. * If the symbol is defined with a different value, the behavior is currently undefined and reserved for future use. +#### Configuration symbol usage + +The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptogrraphic mechanism, including: + +* In Mbed TLS test code. +* In Mbed TLS library code using `MBEDTLS_USE_PSA_CRYPTO`, for example in TLS to determine which cipher suites to enable. +* In application code that provides additional features based on crypto capabilities, for example additional key parsing and formatting functions, or cipher suite availability for network protocols. + #### Configuration symbol semantics If a feature is not requested for inclusion in the PSA crypto configuration file, it may still be included in the build, either because the feature has been requested in some other way, or because the library does not support the exclusion of this feature. Mbed TLS should make a best effort to support the exclusion of all features, but in some cases this may be judged too much effort for too little benefit. From 9e069070de459a39f48f68ae59741284b61695d4 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 16 Nov 2020 10:26:01 +0100 Subject: [PATCH 07/12] Fix typos Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 383bf5f00..238688bcc 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/13 21:45:08 GMT" +Time-stamp: "2020/11/16 09:25:51 GMT" ## Introduction @@ -51,18 +51,18 @@ The current model is difficult to adapt to the PSA interface for several reasons ### PSA Crypto configuration file -The PSA crypto configuration file `psa/crypto_config.h` defines a series of symbols of the form `PSA_WANT_xxx` where `xxx` describes the feature that the symbol enables. The symbols are documented in the section [“PSA Crypto configuration symbols”](#psa-crypto-configuration-symbols) below. +The PSA Crypto configuration file `psa/crypto_config.h` defines a series of symbols of the form `PSA_WANT_xxx` where `xxx` describes the feature that the symbol enables. The symbols are documented in the section [“PSA Crypto configuration symbols”](#psa-crypto-configuration-symbols) below. The symbol `MBEDTLS_PSA_CRYPTO_CONFIG` in `mbedtls/config.h` determines whether `psa/crypto_config.h` is used. * If `MBEDTLS_PSA_CRYPTO_CONFIG` is unset, which is the default at least in Mbed TLS 2.x versions, things are as they are today: the PSA subsystem includes generic code unconditionally, and includes support for specific mechanisms conditionally based on the existing `MBEDTLS_xxx_` symbols. -* If `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the necessary software implementations of cryptographic algorithms are included based on both the content of the PSA crypto configuration file and the Mbed TLS configuration file. For example, the code in `aes.c` is enabled if either `mbedtls/config.h` contains `MBEDTLS_AES_C` or `psa/crypto_config.h` contains `PSA_WANT_KEY_TYPE_AES`. +* If `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the necessary software implementations of cryptographic algorithms are included based on both the content of the PSA Crypto configuration file and the Mbed TLS configuration file. For example, the code in `aes.c` is enabled if either `mbedtls/config.h` contains `MBEDTLS_AES_C` or `psa/crypto_config.h` contains `PSA_WANT_KEY_TYPE_AES`. ### PSA Crypto configuration symbols #### Configuration symbol syntax -A PSA crypto configuration symbol is a C preprocessor symbol whose name starts with `PSA_WANT_`. +A PSA Crypto configuration symbol is a C preprocessor symbol whose name starts with `PSA_WANT_`. * If the symbol is not defined, the corresponding feature is not included. * If the symbol is defined to a preprocessor expression with the value `1`, the corresponding feature is included. @@ -70,7 +70,7 @@ A PSA crypto configuration symbol is a C preprocessor symbol whose name starts w #### Configuration symbol usage -The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptogrraphic mechanism, including: +The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptographic mechanism, including: * In Mbed TLS test code. * In Mbed TLS library code using `MBEDTLS_USE_PSA_CRYPTO`, for example in TLS to determine which cipher suites to enable. @@ -78,7 +78,7 @@ The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines #### Configuration symbol semantics -If a feature is not requested for inclusion in the PSA crypto configuration file, it may still be included in the build, either because the feature has been requested in some other way, or because the library does not support the exclusion of this feature. Mbed TLS should make a best effort to support the exclusion of all features, but in some cases this may be judged too much effort for too little benefit. +If a feature is not requested for inclusion in the PSA Crypto configuration file, it may still be included in the build, either because the feature has been requested in some other way, or because the library does not support the exclusion of this feature. Mbed TLS should make a best effort to support the exclusion of all features, but in some cases this may be judged too much effort for too little benefit. #### Configuration symbols for key types @@ -117,7 +117,7 @@ These symbols are not part of the public interface of Mbed TLS towards applicati #### Definition of internal inclusion symbols -When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. +When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` is only needed to build the PSA parts of the library and code that uses these parts. Note that `psa/crypto_struct.h` and `psa/crypto_sizes.h` include definitions that depend on the configuration, so `mbedtls/config_psa.h` needs to be included in or before these headers (it isn't enough to include it only from files in `library`). @@ -158,7 +158,7 @@ Since configuration symbols must be undefined or 1, any other value should trigg A lot of the preprocessor symbol manipulation is systematic calculations that analyze the configuration. `mbedtls/config_psa.h` and `library/psa_check_config.h` should be generated automatically, in the same manner as `version_features.c`. -### Structure of PSA crypto library code +### Structure of PSA Crypto library code #### Conditional inclusion of library entry points From 1b1f3fb96d4b8e4a1fbbe64fcc4e08b253d2d3ea Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 16 Nov 2020 12:02:01 +0100 Subject: [PATCH 08/12] Minor clarifications Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 238688bcc..2107b395b 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/16 09:25:51 GMT" +Time-stamp: "2020/11/16 11:00:23 GMT" ## Introduction @@ -70,11 +70,11 @@ A PSA Crypto configuration symbol is a C preprocessor symbol whose name starts w #### Configuration symbol usage -The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptographic mechanism, including: +The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available through the PSA API. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptographic mechanism, including: * In Mbed TLS test code. * In Mbed TLS library code using `MBEDTLS_USE_PSA_CRYPTO`, for example in TLS to determine which cipher suites to enable. -* In application code that provides additional features based on crypto capabilities, for example additional key parsing and formatting functions, or cipher suite availability for network protocols. +* In application code that provides additional features based on cryptographic capabilities, for example additional key parsing and formatting functions, or cipher suite availability for network protocols. #### Configuration symbol semantics @@ -119,7 +119,7 @@ These symbols are not part of the public interface of Mbed TLS towards applicati When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. -When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` is only needed to build the PSA parts of the library and code that uses these parts. Note that `psa/crypto_struct.h` and `psa/crypto_sizes.h` include definitions that depend on the configuration, so `mbedtls/config_psa.h` needs to be included in or before these headers (it isn't enough to include it only from files in `library`). +When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). The definitions in `mbedtls/config_psa.h` are only needed to build the PSA parts of the library and code that uses these parts. Note that `psa/crypto_struct.h` and `psa/crypto_sizes.h` include definitions that depend on the configuration, so `mbedtls/config_psa.h` needs to be included in or before these headers (it isn't enough to include it only from files in `library`). `mbedtls/config_psa.h` includes two header files: From 198024cd020f2251d7f6320a17c5bec825df9c39 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 16 Nov 2020 12:04:40 +0100 Subject: [PATCH 09/12] Note that application code needs PSA_WANT_xxx too Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 2107b395b..feface74d 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/16 11:00:23 GMT" +Time-stamp: "2020/11/16 11:04:35 GMT" ## Introduction @@ -119,7 +119,7 @@ These symbols are not part of the public interface of Mbed TLS towards applicati When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. -When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). The definitions in `mbedtls/config_psa.h` are only needed to build the PSA parts of the library and code that uses these parts. Note that `psa/crypto_struct.h` and `psa/crypto_sizes.h` include definitions that depend on the configuration, so `mbedtls/config_psa.h` needs to be included in or before these headers (it isn't enough to include it only from files in `library`). +When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that contains code that's specific to a given cryptographic mechanism (which is reflected in Mbed TLS in code under `MBEDTLS_USE_PSA_CRYPTO` and in conditional compilation guards in tests and sample programs). `mbedtls/config_psa.h` includes two header files: From bb483f6af8ee9452a8aec23455f122b6d369ec77 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 16 Nov 2020 14:35:12 +0100 Subject: [PATCH 10/12] Improve explanations around config_psa.h Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 21 +++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index feface74d..3327acee9 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/16 11:04:35 GMT" +Time-stamp: "2020/11/16 13:35:03 GMT" ## Introduction @@ -115,18 +115,25 @@ These symbols are not part of the public interface of Mbed TLS towards applicati ### Architecture of symbol definitions -#### Definition of internal inclusion symbols +#### New-style definition of configuration symbols When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` needs to define all the `MBEDTLS_xxx_C` configuration symbols, including the ones deduced from the PSA Crypto configuration. It does this by including the new header file **`mbedtls/config_psa.h`**, which defines the `MBEDTLS_PSA_BUILTIN_xxx` symbols and deduces the corresponding `MBEDTLS_xxx_C` (and other) symbols. -When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. In this case, `mbedtls/config_psa.h` deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that contains code that's specific to a given cryptographic mechanism (which is reflected in Mbed TLS in code under `MBEDTLS_USE_PSA_CRYPTO` and in conditional compilation guards in tests and sample programs). +`mbedtls/config_psa.h` includes `psa/crypto_config.h`, the user-editable file that defines application requirements. -`mbedtls/config_psa.h` includes two header files: +#### New-style definition of configuration symbols -* `psa/crypto_config.h` is the user-editable file that defines application requirements. It is only included when `MBEDTLS_PSA_CRYPTO_CONFIG` is set. -* `mbedtls/crypto_drivers.h` is a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback. +When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. Furthermore, a new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). -The following table summarized where symbols are defined depending on the configuration mode. +The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that's specific to a given cryptographic mechanism. In Mbed TLS itself, code under `MBEDTLS_USE_PSA_CRYPTO` and conditional compilation guards in tests and sample programs need `PSA_WANT_xxx`. + +Since some existing applications use a handwritten `mbedtls/config.h` or an edited copy of `mbedtls/config.h` from an earlier version of Mbed TLS, `mbedtls/config_psa.h` must be included via an already existing header that is not `mbedtls/config.h`, so it is included via `psa/crypto.h` (for example from `psa/crypto_platform.h`). + +#### Summary of definitions of configuration symbols + +Both with and without `MBEDTLS_PSA_CRYPTO_CONFIG`, `mbedtls/config_psa.h` includes `mbedtls/crypto_drivers.h`, a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback. + +The following table summarizes where symbols are defined depending on the configuration mode. * (U) indicates a symbol that is defined by the user (application). * (D) indicates a symbol that is deduced from other symbols by code that ships with Mbed TLS. From d8c27ccab009c66da57b582bce96c02081d8f0f0 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Mon, 16 Nov 2020 21:44:23 +0100 Subject: [PATCH 11/12] Fix copypasta; minor wording improvements Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 3327acee9..39ae0f9d4 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/16 13:35:03 GMT" +Time-stamp: "2020/11/16 20:44:13 GMT" ## Introduction @@ -70,7 +70,7 @@ A PSA Crypto configuration symbol is a C preprocessor symbol whose name starts w #### Configuration symbol usage -The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available through the PSA API. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptographic mechanism, including: +The presence of a symbol `PSA_WANT_xxx` in the Mbed TLS configuration determines whether a feature is available through the PSA API. These symbols should be used in any place that requires conditional compilation based on the availability of a cryptographic mechanism through the PSA API, including: * In Mbed TLS test code. * In Mbed TLS library code using `MBEDTLS_USE_PSA_CRYPTO`, for example in TLS to determine which cipher suites to enable. @@ -121,7 +121,7 @@ When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` need `mbedtls/config_psa.h` includes `psa/crypto_config.h`, the user-editable file that defines application requirements. -#### New-style definition of configuration symbols +#### Old-style definition of configuration symbols When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. Furthermore, a new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). @@ -131,7 +131,7 @@ Since some existing applications use a handwritten `mbedtls/config.h` or an edit #### Summary of definitions of configuration symbols -Both with and without `MBEDTLS_PSA_CRYPTO_CONFIG`, `mbedtls/config_psa.h` includes `mbedtls/crypto_drivers.h`, a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback. +Whether `MBEDTLS_PSA_CRYPTO_CONFIG` is set or not, `mbedtls/config_psa.h` includes `mbedtls/crypto_drivers.h`, a header file generated by the transpilation of the driver descriptions. It defines `MBEDTLS_PSA_ACCEL_xxx` symbols according to the availability of transparent drivers without fallback. The following table summarizes where symbols are defined depending on the configuration mode. From 43818f861401b1118a65e5150ee57c40ee5e06ff Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Thu, 19 Nov 2020 11:24:11 +0100 Subject: [PATCH 12/12] Copyediting Signed-off-by: Gilles Peskine --- docs/proposed/psa-conditional-inclusion-c.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/proposed/psa-conditional-inclusion-c.md b/docs/proposed/psa-conditional-inclusion-c.md index 39ae0f9d4..83fd88df2 100644 --- a/docs/proposed/psa-conditional-inclusion-c.md +++ b/docs/proposed/psa-conditional-inclusion-c.md @@ -5,7 +5,7 @@ This document is a proposed interface for deciding at build time which cryptogra This is currently a proposal for Mbed TLS. It is not currently on track for standardization in PSA. -Time-stamp: "2020/11/16 20:44:13 GMT" +Time-stamp: "2020/11/19 10:24:03 GMT" ## Introduction @@ -123,7 +123,7 @@ When `MBEDTLS_PSA_CRYPTO_CONFIG` is set, the header file `mbedtls/config.h` need #### Old-style definition of configuration symbols -When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. Furthermore, a new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). +When `MBEDTLS_PSA_CRYPTO_CONFIG` is not set, the configuration of Mbed TLS works as before, and the inclusion of non-PSA code only depends on `MBEDTLS_xxx` symbols defined (or not) in `mbedtls/config.h`. Furthermore, the new header file **`mbedtls/config_psa.h`** deduces PSA configuration symbols (`PSA_WANT_xxx`, `MBEDTLS_PSA_BUILTIN_xxx`) from classic configuration symbols (`MBEDTLS_xxx`). The `PSA_WANT_xxx` definitions in `mbedtls/config_psa.h` are needed not only to build the PSA parts of the library, but also to build code that uses these parts. This includes structure definitions in `psa/crypto_struct.h`, size calculations in `psa/crypto_sizes.h`, and application code that's specific to a given cryptographic mechanism. In Mbed TLS itself, code under `MBEDTLS_USE_PSA_CRYPTO` and conditional compilation guards in tests and sample programs need `PSA_WANT_xxx`.