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 1aeed64fe0..ca23db9ef7 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. diff --git a/ChangeLog.d/extend-pk-opaque-ecc.txt b/ChangeLog.d/extend-pk-opaque-ecc.txt new file mode 100644 index 0000000000..ad5bdc0964 --- /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). diff --git a/docs/driver-only-builds.md b/docs/driver-only-builds.md new file mode 100644 index 0000000000..a55bbc5697 --- /dev/null +++ b/docs/driver-only-builds.md @@ -0,0 +1,153 @@ +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. 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. + +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 +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 +------------------ + +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 +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. If +you're interested in driver-only support for RSA, please let us know. + +Hashes +------ + +TODO + +Elliptic-curve cryptography (ECC) +--------------------------------- + +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` 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`; +- `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 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 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 + +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`. + +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 with an 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. + +Finite-field Diffie-Hellman +--------------------------- + +TODO