From ff43ff6e7835b0673d81acddf15002b5e6de253e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 20 Apr 2022 15:32:01 +0200 Subject: [PATCH] Remove stability waiver from USE_PSA MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit It was initially motivated by the fact that the PSA Crypto APIs themselves were not stable. In the meantime, PSA Crypto has reached 1.0.0 so this no longer applies. If we want user to be able to fully benefit from PSA in order to isolate long-term secrets, they need to be able to use the new APIs with confidence. There is no reason to think those APIs are any more likely to change than any of our other APIs, and if they do, we'll follow the normal process (deprecated in favour of a new variant). For reference, the APIs in question are: mbedtls_pk_setup_opaque() // to use PSA-held ECDSA/RSA keys in TLS mbedtls_ssl_conf_psk_opaque() // for PSA-held PSKs in TLS mbedtls_ssl_set_hs_psk_opaque() // for PSA-held PSKs in TLS mbedtls_cipher_setup_psa() (deprecated in 3.2) mbedtls_pk_wrap_as_opaque() (documented internal, to be removed in 3.2) Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 5 ----- include/mbedtls/mbedtls_config.h | 7 +++---- 2 files changed, 3 insertions(+), 9 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index a3eebc59b..4058cb65f 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -17,11 +17,6 @@ are specific to TLS 1.3; those parts always use PSA Crypto. The parts of the TLS 1.3 code that are common with TLS 1.2, however, follow this option (this is currently just the record protection code). -Stability: any API that's only available when `MBEDTLS_USE_PSA_CRYPTO` is -defined is considered experimental and may change in incompatible ways at any -time. Said otherwise, these APIs are explicitly excluded from the usual API -stability promises. - New APIs / API extensions ------------------------- diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 37200e7d5..e24366021 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1763,12 +1763,11 @@ * \note See docs/use-psa-crypto.md for a complete description of what this * option currently does, and of parts that are not affected by it so far. * - * \warning This option enables new Mbed TLS APIs which are currently - * considered experimental and may change in incompatible ways at any time. - * That is, the APIs enabled by this option are not covered by the usual - * promises of API stability. + * \warning If you enable this option, you need to call `psa_crypto_init()` + * before calling any function from the SSL/TLS, X.509 or PK modules. * * Requires: MBEDTLS_PSA_CRYPTO_C. + * Conflicts with: MBEDTLS_ECP_RESTARTABLE * * Uncomment this to enable internal use of PSA Crypto and new associated APIs. */