From 263b6925a26e8b011a5cff0c94d36047d8f3fcf9 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Sep 2023 13:14:43 +0200 Subject: [PATCH 1/2] The PSA implementation is production-quality This has been the case for a while, but we forgot to update the readme. Don't prominently label it a "reference" implementation. That implies that it's a complete implementation, but it isn't: we do not intend to implement every mechanism that the PSA specification has an encoding for. That also tends to imply that it's for demonstration purposes and not ready for production, but Mbed TLS is intended to be used in production. Signed-off-by: Gilles Peskine --- README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index d731d4ba02..d1cf0c2e2e 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,7 @@ README for Mbed TLS =================== -Mbed TLS is a C library that implements cryptographic primitives, X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems. - -Mbed TLS includes a reference implementation of the [PSA Cryptography API](#psa-cryptography-api). This is currently a preview for evaluation purposes only. +Mbed TLS is a C library that implements cryptographic primitives (including the [PSA Cryptography API](#psa-cryptography-api)), X.509 certificate manipulation and the SSL/TLS and DTLS protocols. Its small code footprint makes it suitable for embedded systems. Configuration ------------- @@ -298,8 +296,7 @@ Arm welcomes feedback on the design of the API. If you think something could be ### PSA implementation in Mbed TLS -Mbed TLS includes a reference implementation of the PSA Cryptography API. -However, it does not aim to implement the whole specification; in particular it does not implement all the algorithms. +Mbed TLS includes an implementation of the PSA Cryptography API. It covers most, but not all algorithms. 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. From b6bf893c70713d2892e4e914a87f772268421071 Mon Sep 17 00:00:00 2001 From: Gilles Peskine Date: Wed, 13 Sep 2023 13:19:41 +0200 Subject: [PATCH 2/2] Qualify "reference implementation" wording Signed-off-by: Gilles Peskine --- docs/architecture/psa-crypto-implementation-structure.md | 2 +- docs/proposed/psa-driver-interface.md | 2 +- library/psa_crypto.c | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/architecture/psa-crypto-implementation-structure.md b/docs/architecture/psa-crypto-implementation-structure.md index 3421354843..c5337ffa71 100644 --- a/docs/architecture/psa-crypto-implementation-structure.md +++ b/docs/architecture/psa-crypto-implementation-structure.md @@ -3,7 +3,7 @@ PSA Cryptography API implementation and PSA driver interface ## Introduction -The [PSA Cryptography API specification](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) defines an interface to cryptographic operations for which the Mbed TLS library provides a reference implementation. The PSA Cryptography API specification is complemented by the PSA driver interface specification which defines an interface for cryptoprocessor drivers. +The [PSA Cryptography API specification](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface) defines an interface to cryptographic operations for which the Mbed TLS library provides a reference implementation (in the sense that it implements most features, and it is where new features are usually tried out). The PSA Cryptography API specification is complemented by the PSA driver interface specification which defines an interface for cryptoprocessor drivers. This document describes the high level organization of the Mbed TLS PSA Cryptography API implementation which is tightly related to the PSA driver interface. diff --git a/docs/proposed/psa-driver-interface.md b/docs/proposed/psa-driver-interface.md index 1aa55b3cc3..f90ed5dd78 100644 --- a/docs/proposed/psa-driver-interface.md +++ b/docs/proposed/psa-driver-interface.md @@ -3,7 +3,7 @@ PSA Cryptoprocessor Driver Interface This document describes an interface for cryptoprocessor drivers in the PSA cryptography API. This interface complements the [PSA Cryptography API specification](https://armmbed.github.io/mbed-crypto/psa/#application-programming-interface), which describes the interface between a PSA Cryptography implementation and an application. -This specification is work in progress and should be considered to be in a beta stage. There is ongoing work to implement this interface in Mbed TLS, which is the reference implementation of the PSA Cryptography API. At this stage, Arm does not expect major changes, but minor changes are expected based on experience from the first implementation and on external feedback. +This specification is work in progress and should be considered to be in a beta stage. There is ongoing work to implement this interface in Mbed TLS, which is the reference implementation of the PSA Cryptography API (although it omits a few functions and mechanisms). At this stage, Arm does not expect major changes, but minor changes are expected based on experience from the first implementation and on external feedback. For a practical guide, with a description of the current state of drivers Mbed TLS, see our [PSA Cryptoprocessor driver development examples](../psa-driver-example-and-guide.html). diff --git a/library/psa_crypto.c b/library/psa_crypto.c index 9c28609d7e..357986ebf3 100644 --- a/library/psa_crypto.c +++ b/library/psa_crypto.c @@ -1494,8 +1494,8 @@ psa_status_t psa_export_key_internal( key_buffer, key_buffer_size, data, data_size, data_length); } else { - /* This shouldn't happen in the reference implementation, but - it is valid for a special-purpose implementation to omit + /* This shouldn't happen in the built-in implementation, but + it is valid for a special-purpose drivers to omit support for exporting certain key types. */ return PSA_ERROR_NOT_SUPPORTED; }