docs/driver-only-builds.md - mirror/mbed-tls.git - TrustedFirmware Git Browser

 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
	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