From 6d5f4946e6d13787bb2f99119c257c0dd63a1cc4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 7 Jul 2023 12:00:49 +0200 Subject: [PATCH 1/7] Add docs/driver-only-builds.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/driver-only-builds.md | 78 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 docs/driver-only-builds.md diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md new file mode 100644 index 000000000..42651d087 --- /dev/null +++ b/docs/driver-only-builds.md @@ -0,0 +1,78 @@ +This document explains how to create builds of Mbed TLS where some +cryptographic mechanisms are provided only by PSA drivers (that is, no +built-in implementation of those algorithms), from a user's perspective. + +This is useful to save code size for people who are using either a hardware +accelerator, or an alternative software implementation that's more +aggressively optimized for code size than the default one in Mbed TLS. + +General considerations +---------------------- + +This document assumes that you already have a working driver. +Otherwise, please see the [PSA driver example and +guide](psa-driver-example-and-guide.md) for information on writing a +driver. + +In order to have some mechanism provided only by a driver, you'll want +the following compile-time configuration options enabled: +- `MBEDTLS_PSA_CRYPTO_C` (enabled by default) - this enables PSA Crypto. +- `MBEDTLS_USE_PSA_CRYPTO` (disabled by default) - this makes PK, X.509 and + TLS use PSA Crypto. You need to enable this if you're using PK, X.509 or TLS +and want them to have access to the algorithms provided by your driver. (See +[the dedicated document](use-psa-crypto.md) for details.) +- `MBEDTLS_PSA_CRYPTO_CONFIG` (disabled by default) - this enables + configuration of cryptographic algorithms using `PSA_WANT` macros in +`include/psa/crypto_config.h`. See [Conditional inclusion of cryptographic +mechanism through the PSA API in Mbed +TLS](proposed/psa-conditional-inclusion-c.md) for details. + +In addition, for each mechanism you want provided only by your driver: +- Define the corresponding `PSA_WANT` macro in `psa/crypto_config.h` - this + means the algorithm will be available in the PSA Crypto API. +- Define the corresponding `MBEDTLS_PSA_ACCEL` in your build (could be in + `psa/crypto_config.h` or your compiler's command line). This informs the PSA +code that an accelerator is available for this. +- Undefine / comment out the corresponding `MBEDTLS_xxx_C` macro in + `mbedtls/mbedtls_config.h`. This ensures the built-in implementation is not +included in the build. + +For example, if you want SHA-256 to be provided only by a driver, you'll want +`PSA_WANT_ALG_SHA_256` and `MBEDTLS_PSA_ACCEL_SHA_256` defined, and +`MBEDTLS_SHA256_C` undefined. + +In addition to these compile-time considerations, at runtime you'll need to +make sure you call `psa_crypto_init()` before any function that uses the +mechanisms provided only by drivers. Note that this is already a requirement +for any use of the PSA Crypto API, as well as for use of the PK, X.509 and TLS +modules when `MBEDTLS_USE_PSA_CRYPTO` is enabled, so in most cases your +application will already be doing this. + +Mechanisms covered +------------------ + +For now, only two families are supported: +- hashes: SHA-3, SHA-2, SHA-1, MD5, etc. +- elliptic-curve cryptography (ECC): ECDH, ECDSA, EC J-PAKE, ECC key types. + +Supported means that when those are provided only by drivers, everything +(including PK, X.509 and TLS if `MBEDTLS_USE_PSA_CRYPTO` is enabled) should +work in the same way as if the mechanisms where built-in, except as documented +in the "Limitations" sub-sections of the sections dedicated to each family +below. + +In the near future (end of 2023), we are planning to also add support for +ciphers (AES) and AEADs (GCM, CCM, ChachaPoly). + +Currently (mid-2023) we don't have plans to extend this to RSA of FFDH. If +you're interested in driver-only support for those, please let us know. + +Hashes +------ + +TODO + +Elliptic-curve cryptography (ECC) +--------------------------------- + +TODO From 7a82e27a10c26c8916ca4bd80b65fc4714158c8b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 7 Jul 2023 16:43:56 +0200 Subject: [PATCH 2/7] Add documentation on driver-only ECC MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Just one part left for later. Signed-off-by: Manuel Pégourié-Gonnard --- docs/driver-only-builds.md | 70 +++++++++++++++++++++++++++++++++++++- 1 file changed, 69 insertions(+), 1 deletion(-) diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md index 42651d087..f50463cd0 100644 --- a/docs/driver-only-builds.md +++ b/docs/driver-only-builds.md @@ -75,4 +75,72 @@ TODO Elliptic-curve cryptography (ECC) --------------------------------- -TODO +Note: things are still evolving. This section describes the situation right +after #7452 has been merged. It will be updated again in #7757 when bignum is +done. + +It is possible to have most ECC operations provided only by a driver: +- the ECDH, ECDSA and EC J-PAKE algorithms; +- key import, export, and random generation. + +More precisely: +- you can enable `PSA_WANT_ALG_ECDH` without `MBEDTLS_ECDH_C` provided + `MBEDTLS_PSA_ACCEL_ALG_ECDH` is enabled; +- you can enable `PSA_WANT_ALG_ECDSA` without `MBEDTLS_ECDSA_C` provided + `MBEDTLS_PSA_ACCEL_ALG_ECDSA` is enabled; +- you can enable `PSA_WANT_ALG_JPAKE` without `MBEDTLS_ECJPAKE_C` provided + `MBEDTLS_PSA_ACCEL_ALG_JPAKE` is enabled. + +In addition, if none of `MBEDTLS_ECDH_C`, `MBEDTLS_ECDSA_C`, +`MBEDTLS_ECJPAKE_C` is enabled, you can enable: +- `PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY`; +- `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_BASIC`; +- `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT`; +- `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_EXPORT`; +- `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_GENERATE`; +without `MBEDTLS_ECP_C` provided the corresponding +`MBEDTLS_PSA_ACCEL_KEY_TYPE_xxx` are enabled. + +[Coming soon] If `MBEDTLS_ECP_C` is disabled and `ecp.c` is fully removed (see +"Limitations regarding fully removing `ecp.c`" below), and you're not using +RSA or FFDH, then you can also disable `MBEDTLS_BIGNUM_C` for further code +size saving. + +### Limitations regarding fully removing `ecp.c` + +A limited subset of `ecp.c` will still be automatically re-enabled if any of +the following is enabled: +- `MBEDTLS_PK_PARSE_EC_COMPRESSED` - support for parsing ECC keys where the + public part is in compressed format; +- `MBEDTLS_PK_PARSE_EC_EXTENDED` - support for parsing ECC keys where the + curve is identified not by name, but by explicit parameters; +- `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE` - support for deterministic + derivation of an ECC keypair with `psa_key_derivation_output_key()`. + +Note: when one of the above options is enabled, you can still `MBEDTLS_ECP_C` +in `mbedtls_config.h`, and it will still result in some code size savings, but +not as much as when none of these are enabled, as a subset of `ecp.c` will +still be included in the build in order to support these. + +We do have plans to support each of these with `ecp.c` fully removed in the +future, however no established timeline. If you're interested, please let us +know, so we can take it into consideration in our planning. + +### Limitations regarding restartable / interruptible ECC operations + +At the moment, the is not driver support for interruptible operations +(see `psa_sign_hash_start()` + `psa_sign_hash_complete()` etc.) so as a +consequence these are not supported in builds without `MBEDTLS_ECDSA_C`. + +Similarly, there is no PSA support for interruptible ECDH operations so these +are not supported without `ECDH_C`. See also limitations regarding +restartable operations with `MBEDTLS_USE_PSA_CRYPTO` in [its +documentation](use-psa-crypto.md). + +Again, we have plans to support this in the future but not established +timeline, please let us know if you're interested. + +### Limitations regarding the selection of curves + +TODO: apparently we don't really support having some curves built-in and +others driver-only... investigate and describe the situation. See also #7899. From d38ee855eb7f2e911a985f27119ea0f7bfd82721 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 7 Jul 2023 16:56:16 +0200 Subject: [PATCH 3/7] Add ChangeLog entry for PK_OPAQUE extensions MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- ChangeLog.d/extend-pk-opaque-ecc.txt | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 ChangeLog.d/extend-pk-opaque-ecc.txt diff --git a/ChangeLog.d/extend-pk-opaque-ecc.txt b/ChangeLog.d/extend-pk-opaque-ecc.txt new file mode 100644 index 000000000..ad5bdc096 --- /dev/null +++ b/ChangeLog.d/extend-pk-opaque-ecc.txt @@ -0,0 +1,6 @@ +Features + * Support for "opaque" (PSA-held) ECC keys in the PK module has been + extended: it is now possible to use mbedtls_pk_write_key_der(), + mbedtls_pk_write_key_pem(), mbedtls_pk_check_pair(), and + mbedtls_pk_verify() with opaque ECC keys (provided the PSA attributes + allow it). From a787c0f986bed745ebd544d220d3d094e03fa71c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 7 Jul 2023 17:01:22 +0200 Subject: [PATCH 4/7] Add Changelog for driver-only ECC so far MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- ChangeLog.d/{driver-only-ecdh.txt => driver-only-ecc.txt} | 3 +++ 1 file changed, 3 insertions(+) rename ChangeLog.d/{driver-only-ecdh.txt => driver-only-ecc.txt} (65%) diff --git a/ChangeLog.d/driver-only-ecdh.txt b/ChangeLog.d/driver-only-ecc.txt similarity index 65% rename from ChangeLog.d/driver-only-ecdh.txt rename to ChangeLog.d/driver-only-ecc.txt index 1aeed64fe..ca23db9ef 100644 --- a/ChangeLog.d/driver-only-ecdh.txt +++ b/ChangeLog.d/driver-only-ecc.txt @@ -5,3 +5,6 @@ Features MBEDTLS_USE_PSA_CRYPTO. Restartable/interruptible ECDHE operations in TLS 1.2 (ECDHE-ECDSA key exchange) are not supported in those builds yet, as PSA does not have an API for restartable ECDH yet. + * When all of ECDH, ECDSA and EC J-PAKE are either disabled or provided by + a driver, it is possible to disable MBEDTLS_ECP_C and still get support + for ECC keys and algorithms in PSA. See docs/driver-only-builds.txt. From c97775162ec82841e1884a787a29731cbeb22b24 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 11 Jul 2023 11:11:20 +0200 Subject: [PATCH 5/7] Fix inaccurate information about FFDH MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/driver-only-builds.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md index f50463cd0..1c4998240 100644 --- a/docs/driver-only-builds.md +++ b/docs/driver-only-builds.md @@ -51,9 +51,10 @@ application will already be doing this. Mechanisms covered ------------------ -For now, only two families are supported: +For now, only the following (families of) mechanisms are supported: - hashes: SHA-3, SHA-2, SHA-1, MD5, etc. - elliptic-curve cryptography (ECC): ECDH, ECDSA, EC J-PAKE, ECC key types. +- finite-field Diffie-Hellman: FFDH algorithm, DH key types. Supported means that when those are provided only by drivers, everything (including PK, X.509 and TLS if `MBEDTLS_USE_PSA_CRYPTO` is enabled) should @@ -64,8 +65,8 @@ below. In the near future (end of 2023), we are planning to also add support for ciphers (AES) and AEADs (GCM, CCM, ChachaPoly). -Currently (mid-2023) we don't have plans to extend this to RSA of FFDH. If -you're interested in driver-only support for those, please let us know. +Currently (mid-2023) we don't have plans to extend this to RSA. If +you're interested in driver-only support for RSA, please let us know. Hashes ------ @@ -144,3 +145,8 @@ timeline, please let us know if you're interested. TODO: apparently we don't really support having some curves built-in and others driver-only... investigate and describe the situation. See also #7899. + +Finite-field Diffie-Hellman +--------------------------- + +TODO From 1937cf8143bb9465b2d696aafbb93526d4f1e98c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 11 Jul 2023 11:14:15 +0200 Subject: [PATCH 6/7] Improve wording & fix a typo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/driver-only-builds.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md index 1c4998240..7263cfade 100644 --- a/docs/driver-only-builds.md +++ b/docs/driver-only-builds.md @@ -118,10 +118,11 @@ the following is enabled: - `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_DERIVE` - support for deterministic derivation of an ECC keypair with `psa_key_derivation_output_key()`. -Note: when one of the above options is enabled, you can still `MBEDTLS_ECP_C` -in `mbedtls_config.h`, and it will still result in some code size savings, but -not as much as when none of these are enabled, as a subset of `ecp.c` will -still be included in the build in order to support these. +Note: when any of the above options is enabled, a subset of `ecp.c` will +automatically be included in the build in order to support it. Therefore +you can still disable `MBEDTLS_ECP_C` in `mbedtls_config.h` and this will +result in some code size savings, but not as much as when none of the +above features are enabled. We do have plans to support each of these with `ecp.c` fully removed in the future, however no established timeline. If you're interested, please let us @@ -129,7 +130,7 @@ know, so we can take it into consideration in our planning. ### Limitations regarding restartable / interruptible ECC operations -At the moment, the is not driver support for interruptible operations +At the moment, there is not driver support for interruptible operations (see `psa_sign_hash_start()` + `psa_sign_hash_complete()` etc.) so as a consequence these are not supported in builds without `MBEDTLS_ECDSA_C`. From fb22c27f1dba59a56a1fa2f033f53fa1fad106bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 18 Jul 2023 10:40:56 +0200 Subject: [PATCH 7/7] Misc wording fixes and improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/driver-only-builds.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md index 7263cfade..a55bbc569 100644 --- a/docs/driver-only-builds.md +++ b/docs/driver-only-builds.md @@ -30,9 +30,9 @@ TLS](proposed/psa-conditional-inclusion-c.md) for details. In addition, for each mechanism you want provided only by your driver: - Define the corresponding `PSA_WANT` macro in `psa/crypto_config.h` - this means the algorithm will be available in the PSA Crypto API. -- Define the corresponding `MBEDTLS_PSA_ACCEL` in your build (could be in - `psa/crypto_config.h` or your compiler's command line). This informs the PSA -code that an accelerator is available for this. +- Define the corresponding `MBEDTLS_PSA_ACCEL` in your build. This could be + defined in `psa/crypto_config.h` or your compiler's command line. This +informs the PSA code that an accelerator is available for this mechanism. - Undefine / comment out the corresponding `MBEDTLS_xxx_C` macro in `mbedtls/mbedtls_config.h`. This ensures the built-in implementation is not included in the build. @@ -43,10 +43,10 @@ For example, if you want SHA-256 to be provided only by a driver, you'll want In addition to these compile-time considerations, at runtime you'll need to make sure you call `psa_crypto_init()` before any function that uses the -mechanisms provided only by drivers. Note that this is already a requirement -for any use of the PSA Crypto API, as well as for use of the PK, X.509 and TLS -modules when `MBEDTLS_USE_PSA_CRYPTO` is enabled, so in most cases your -application will already be doing this. +driver-only mechanisms. Note that this is already a requirement for any use of +the PSA Crypto API, as well as for use of the PK, X.509 and TLS modules when +`MBEDTLS_USE_PSA_CRYPTO` is enabled, so in most cases your application will +already be doing this. Mechanisms covered ------------------ @@ -93,7 +93,7 @@ More precisely: `MBEDTLS_PSA_ACCEL_ALG_JPAKE` is enabled. In addition, if none of `MBEDTLS_ECDH_C`, `MBEDTLS_ECDSA_C`, -`MBEDTLS_ECJPAKE_C` is enabled, you can enable: +`MBEDTLS_ECJPAKE_C` are enabled, you can enable: - `PSA_WANT_KEY_TYPE_ECC_PUBLIC_KEY`; - `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_BASIC`; - `PSA_WANT_KEY_TYPE_ECC_KEY_PAIR_IMPORT`; @@ -125,8 +125,8 @@ result in some code size savings, but not as much as when none of the above features are enabled. We do have plans to support each of these with `ecp.c` fully removed in the -future, however no established timeline. If you're interested, please let us -know, so we can take it into consideration in our planning. +future, however there is no established timeline. If you're interested, please +let us know, so we can take it into consideration in our planning. ### Limitations regarding restartable / interruptible ECC operations @@ -139,7 +139,7 @@ are not supported without `ECDH_C`. See also limitations regarding restartable operations with `MBEDTLS_USE_PSA_CRYPTO` in [its documentation](use-psa-crypto.md). -Again, we have plans to support this in the future but not established +Again, we have plans to support this in the future but not with an established timeline, please let us know if you're interested. ### Limitations regarding the selection of curves