Merge pull request #7900 from mpg/doc-driver-only
ECPf wrap-up
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 1aeed64..ca23db9 100644
--- a/ChangeLog.d/driver-only-ecdh.txt
+++ b/ChangeLog.d/driver-only-ecc.txt
@@ -5,3 +5,6 @@
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 0000000..ad5bdc0
--- /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 0000000..a55bbc5
--- /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