From 17467c59b2e1b9a4d7e27703a320ceb2fdb40c31 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Tue, 25 Apr 2023 21:14:31 +0200 Subject: [PATCH] README: add section about drivers Everything discussed in "Upcoming features" section is now available as a usable, but incomplete feature (except "wider set of cryptographic algorithms", but that doesn't need to be said). So replace it by a section that briefly presents these features: drivers, and MBEDTLS_PSA_CRYPTO_CONFIG which is primarily useful with drivers and thus doesn't get its own section. Include an explicit note that the driver interface can still change. At this time, it's the only place where we say that the driver interface is not covered by the (application) interface stability promise. Signed-off-by: Gilles Peskine --- README.md | 18 ++++++++++++------ 1 file changed, 12 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 288e692baf..fe49659cbe 100644 --- a/README.md +++ b/README.md @@ -293,14 +293,20 @@ However, it does not aim to implement the whole specification; in particular it The X.509 and TLS code can use PSA cryptography for most operations. To enable this support, activate the compilation option `MBEDTLS_USE_PSA_CRYPTO` in `mbedtls_config.h`. Note that TLS 1.3 uses PSA cryptography for most operations regardless of this option. See `docs/use-psa-crypto.md` for details. -### Upcoming features +### PSA drivers -Future releases of this library will include: +Mbed TLS supports drivers for cryptographic accelerators, secure elements and random generators. This is work in progress. Please note that the driver interfaces are not fully stable yet and may change without notice. We intend to preserve backward compatibility for application code (using the PSA Crypto API), but the code of the drivers may have to change in future minor releases of Mbed TLS. -* A driver programming interface, which makes it possible to use hardware accelerators instead of the default software implementation for chosen algorithms. -* Support for external keys to be stored and manipulated exclusively in a separate cryptoprocessor. -* A configuration mechanism to compile only the algorithms you need for your application. -* A wider set of cryptographic algorithms. +Driver-related documentation is a work in progress. The following documents describe the end goal; note that the current implementation may not be up-to-date. + +* [Driver interface specification](docs/proposed/psa-driver-interface.md) +* [Driver developer's guide](docs/proposed/psa-driver-developer-guide.md) +* [Driver integration guide](docs/proposed/psa-driver-integration-guide.md) + +When using drivers, you will generally want to enable two compilation options (see the reference manual for more information): + +* `MBEDTLS_USE_PSA_CRYPTO` is necessary so that the X.509 and TLS code calls the PSA drivers rather than the built-in software implementation. +* `MBEDTLS_PSA_CRYPTO_CONFIG` allows you to enable PSA cryptographic mechanisms without including the code of the corresponding software implementation. This is not yet supported for all mechanisms. License -------