From 13b0bebf7dc3689ef1c210ecf3b770213c444cc5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Mon, 20 Sep 2021 13:21:25 +0200 Subject: [PATCH 1/9] Add docs/use-psa-crypto.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 19 +++++++++++++++++++ include/mbedtls/mbedtls_config.h | 3 +++ 2 files changed, 22 insertions(+) create mode 100644 docs/use-psa-crypto.md diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md new file mode 100644 index 0000000000..a4f43b7832 --- /dev/null +++ b/docs/use-psa-crypto.md @@ -0,0 +1,19 @@ +This document describes the compile-time configutation option +`MBEDTLS_USE_PSA_CRYPTO`: its current effects as well as some design +considerations and plans for the future. + +Current effects +=============== + +(To be written.) + +Parts that are not affected yet +=============================== + +(To be written.) + +Design considerations +===================== + +(To be written.) + diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index d470c0054b..0680dd98f8 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1718,6 +1718,9 @@ * will still continue to work as usual, so enabling this option should not * break backwards compatibility. * + * \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 The PSA Crypto API is in beta stage. While you're welcome to * experiment using it, incompatible API changes are still possible, and some * parts may not have reached the same quality as the rest of Mbed TLS yet. From 1b08c5f042263b2919431eaa80797476a4876523 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 21 Sep 2021 11:21:23 +0200 Subject: [PATCH 2/9] Document current effects of USE_PSA_CRYPTO MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 144 ++++++++++++++++++++++++++++++++++++++++- 1 file changed, 141 insertions(+), 3 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index a4f43b7832..d1298af2b3 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -5,10 +5,148 @@ considerations and plans for the future. Current effects =============== -(To be written.) +General limitations +------------------- -Parts that are not affected yet -=============================== +Compile-time: enabling `MBEDTLS_USE_PSA_CRYPTO` requires +`MBEDTLS_ECP_RESTARTABLE` and +`MBEDTLS_PSA_CRYPTO_KEY_ID_ENCODES_OWNER` to be disabled. + +Effect: `MBEDTLS_USE_PSA_CRYPTO` currently has no effect on TLS 1.3 (which is +itself experimental and only partially supported so far): TLS 1.3 always uses +the legacy APIs even when this option is set. + +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 +------------------------- + +Some of these APIs are meant for the application to use in place of +pre-existing APIs, in order to get access to the benefits; in the sub-sections +below these are indicated by "Use in (X.509 and) TLS: opt-in", meaning that +this requires changes to the application code for the (X.509 and) TLS layers +to pick up the improvements. + +Some of these APIs are mostly meant for internal use by the TLS (and X.509) +layers; they are indicated below by "Use in (X.509 and) TLS: automatic", +meaning that no changes to the application code are required for the TLS (and +X.509) layers to pick up the improvements. + +### PSA-held (opaque) keys in the PK layer + +Add `mbedtls_pk_setup_opaque()` to wrap a PSA keypair into a PK context. The key +can be used for private-key operations and its public part can be written out. + +Benefits: isolation of long-term secrets, use of PSA Crypto drivers. + +Limitations: only for private keys, only ECC. (That is, only ECDSA signature +generation.) The following operations are not supported with a context set +this way, while they would be available with a normal `ECKEY` context: +`mbedtls_pk_verify()`, `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`. + +Use in X.509 and TLS: opt-in. The application needs to construct the PK context +using the new API in order to get the benefits; it can then pass the +resulting context to the following existing APIs: + +- `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the + key together with a certificate for ECDSA-based key exchanges; +- `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature + request). + +In the TLS and X.509 API, there's two other function which accept a key or +keypair as a PK context: `mbedtls_x509write_crt_set_subject_key()` and +`mbedtls_x509write_crt_set_issuer_key()`. Use of opaque contexts here probably +works but is so far untested. + +### PSA-held (opaque) keys for TLS 1.2 pre-shared keys (PSK) + +Add `mbedtls_ssl_conf_psk_opaque()` and `mbedtls_ssl_set_hs_psk_opaque()` to +register a PSA key for use with a PSK key exchange. + +Benefits: isolation of long-term secrets. + +Limitations: the key can only be used with with TLS 1.2, and only with "pure" +PSK key exchanges (ciphersuites starting with `TLS_PSK_WITH_`), to the +exclusion of RSA-PSK, DHE-PSK and ECDHE-PSK key exchanges. It is the responsibility of +the user to make sure that when provisioning an opaque pre-shared key, the +only PSK ciphersuites that can be negotiated are "pure" PSK; other XXX-PSK key +exchanges will result in a handshake failure with the handshake function +returning `MBEDTLS_ERR_SSL_FEATURE_UNAVAILABLE`. + +Use in TLS: opt-in. The application needs to register the key using the new +APIs to get the benefits. + +### PSA-based operations in the Cipher layer + +Add `mbedtls_cipher_setup_psa()` to set up a context that will call PSA to +store the key and perform the operations. + +Benefits: use of PSA Crypto drivers; partial isolation of short-term secrets +(still generated outside of PSA, but then held by PSA). + +Limitations: the key is still passed in the clear by the application. The +multi-part APIs are not supported, only the one-shot APIs. The only modes +supported are ECB, CBC without padding, GCM and CCM (this excludes stream +ciphers and ChachaPoly); the only cipher supported is AES (this excludes Aria, +Camellia, and ChachaPoly). + +Use in TLS: automatic. Used when the cipher and mode is supported (with +gracious fallback to the legacy API otherwise) in all places where a cipher is +used. There are two such places: in `ssl_tls.c` for record protection, and in +`ssl_ticket.c` for protecting tickets we issue. + +Internal changes +---------------- + +All of these internal changes are active as soon as `MBEDTLS_USE_PSA_CRYPTO` +is enabled, no change required on the application side. + +### TLS: cipher operations based on PSA + +See "PSA-based operations in the Cipher layer" above. + +### PK layer: ECDSA verification based on PSA + +Scope: `mbedtls_pk_verify()` will call to PSA for ECDSA signature +verification. + +Benefits: use of PSA Crypto drivers. + +Use in TLS and X.509: in all places where an ECDSA signature is verified. + +### TLS: ECDHE computation based on PSA + +Scope: Client-side, for ECDHE-RSA and ECDHE-ECDSA key exchanges, the +computation of the ECDHE key exchange is done by PSA. + +Limitations: client-side only, ECDHE-PSK not covered + +Benefits: use of PSA Crypto drivers. + +### TLS: handshake hashes and PRF computed with PSA + +Scope: with TLS 1.2, the following are computed with PSA: +- the running handshake hashes; +- the hash of the ServerKeyExchange part that is signed; +- the `verify_data` part of the Finished message; +- the TLS PRF. + +Benefits: use of PSA Crypto drivers. + +### X.509: some hashes computed with PSA + +Scope: the following hashes are computed with PSA: +- when verifying a certificate chain, hash of the child for verifying the + parent's signature; +- when writing a CSR, hash of the request for self-signing the request. + +Benefits: use of PSA Crypto drivers. + +Parts that are not covered yet +============================== (To be written.) From 200bcf77f820b45ebfffa4f193116792aecadb76 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 21 Sep 2021 11:30:52 +0200 Subject: [PATCH 3/9] Remove warning about PSA Crypto being beta MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The API reached 1.0.0 some time ago, and we've caught up with the incompatible changes already. Signed-off-by: Manuel Pégourié-Gonnard --- include/mbedtls/mbedtls_config.h | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/include/mbedtls/mbedtls_config.h b/include/mbedtls/mbedtls_config.h index 0680dd98f8..683c9131c6 100644 --- a/include/mbedtls/mbedtls_config.h +++ b/include/mbedtls/mbedtls_config.h @@ -1721,15 +1721,10 @@ * \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 The PSA Crypto API is in beta stage. While you're welcome to - * experiment using it, incompatible API changes are still possible, and some - * parts may not have reached the same quality as the rest of Mbed TLS yet. - * - * \warning This option enables new Mbed TLS APIs that are dependent on the - * PSA Crypto API, so can't come with the same stability guarantees as the - * rest of the Mbed TLS APIs. You're welcome to experiment with them, but for - * now, access to these APIs is opt-in (via enabling the present option), in - * order to clearly differentiate them from the stable Mbed TLS APIs. + * \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. * * Requires: MBEDTLS_PSA_CRYPTO_C. * @@ -2595,10 +2590,6 @@ * * Enable the Platform Security Architecture cryptography API. * - * \warning The PSA Crypto API is still beta status. While you're welcome to - * experiment using it, incompatible API changes are still possible, and some - * parts may not have reached the same quality as the rest of Mbed TLS yet. - * * Module: library/psa_crypto.c * * Requires: either MBEDTLS_CTR_DRBG_C and MBEDTLS_ENTROPY_C, From 73a0e1da0d1acec38a54e0b3d84358dea0bfce09 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Tue, 21 Sep 2021 13:55:00 +0200 Subject: [PATCH 4/9] Document parts not covered by USE_PSA_CRYPTO MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Also, remove the section about design considerations for now. It's probably more suitable for a developer-oriented document that would also include considerations about possible paths for the future, which would better be separated from user documentation (separating the certain that is now, from the uncertain that might or might not be later). Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 43 +++++++++++++++++++++++++++++++++++------- 1 file changed, 36 insertions(+), 7 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index d1298af2b3..c8f89d0c24 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -1,6 +1,6 @@ -This document describes the compile-time configutation option -`MBEDTLS_USE_PSA_CRYPTO`: its current effects as well as some design -considerations and plans for the future. +This document describes the compile-time configuration option +`MBEDTLS_USE_PSA_CRYPTO` from a user's perspective, more specifically its +current effects as well as the parts that aren't covered yet. Current effects =============== @@ -148,10 +148,39 @@ Benefits: use of PSA Crypto drivers. Parts that are not covered yet ============================== -(To be written.) +This is only a high-level overview, grouped by theme -Design considerations -===================== +TLS: key exchanges / asymmetric crypto +-------------------------------------- -(To be written.) +- RSA: not covered +- DHE-RSA: not covered +- ECDHE-RSA: ECDHE computation client-side only +- ECDHE-ECDSA: + - ECDHE computation client-side + - ECDSA verification both sides + - ECDSA signature (if using `mbedtls_pk_setup_opaque()`) +- PSK: client-side PSA-held using `mbedtls_ssl_conf_psk_opaque()` +- DHE-PSK: not covered +- RSA-PSK: not covered +- ECDHE-PSK: not covered +- ECDH-RSA: not covered +- ECDH-ECDSA: not covered +- ECJPAKE: not covered +TLS: symmetric crypto +--------------------- + +- some ciphers not supported via PSA yet: ARIA, Camellia, ChachaPoly (silent + fallback to the legacy APIs) +- the HMAC part of the CBC and NULL ciphersuites is not covered +- the HMAC computation in `ssl_cookie.c` + +X.509 +----- + +- most hash operations are still done via the legacy API, except the few that + are documented above as using PSA +- RSA PKCS#1 v1.5 signature generation (from PSA-held keys): not covered +- RSA PKCS#1 v1.5 signature verification: not covered +- RSA-PSS signature verification: not covered From 1e07869381a0a66d08094919090f6f5dbcf4ecfb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Wed, 22 Sep 2021 10:11:53 +0200 Subject: [PATCH 5/9] Fix inaccuracy in key exchange summary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index c8f89d0c24..6300bf02e2 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -160,7 +160,7 @@ TLS: key exchanges / asymmetric crypto - ECDHE computation client-side - ECDSA verification both sides - ECDSA signature (if using `mbedtls_pk_setup_opaque()`) -- PSK: client-side PSA-held using `mbedtls_ssl_conf_psk_opaque()` +- PSK: PSA-held keys using `mbedtls_ssl_conf_psk_opaque()` - DHE-PSK: not covered - RSA-PSK: not covered - ECDHE-PSK: not covered From d3ac4a9a8abeba0232c43a7cf38b2905c0fe5862 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 24 Sep 2021 10:06:04 +0200 Subject: [PATCH 6/9] Clarify wording of "not covered" section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The section is about things that are not covered, but some lists are about things that are covered, which was very confusing. Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 42 ++++++++++++++++++++++++------------------ 1 file changed, 24 insertions(+), 18 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index 6300bf02e2..4292aa6b94 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -153,27 +153,33 @@ This is only a high-level overview, grouped by theme TLS: key exchanges / asymmetric crypto -------------------------------------- -- RSA: not covered -- DHE-RSA: not covered -- ECDHE-RSA: ECDHE computation client-side only -- ECDHE-ECDSA: - - ECDHE computation client-side - - ECDSA verification both sides - - ECDSA signature (if using `mbedtls_pk_setup_opaque()`) -- PSK: PSA-held keys using `mbedtls_ssl_conf_psk_opaque()` -- DHE-PSK: not covered -- RSA-PSK: not covered -- ECDHE-PSK: not covered -- ECDH-RSA: not covered -- ECDH-ECDSA: not covered -- ECJPAKE: not covered +The following key exchanges are not covered at all: + +- RSA +- DHE-RSA +- DHE-PSK +- RSA-PSK +- ECDHE-PSK +- ECDH-RSA +- ECDH-ECDSA +- ECJPAKE + +The following key exchanges are only partially covered: + +- ECDHE-RSA: RSA operations are not covered and, server-side, the ECDHE + operation isn't either +- ECDHE-ECDSA: server-side, the ECDHE operation isn't covered. (ECDSA + signature generation is only covered if using `mbedtls_pk_setup_opaque()`.) + +PSK if covered when the application uses `mbedtls_ssl_conf_psk_opaque()` or +`mbedtls_ssl_set_hs_psk_opaque()`. TLS: symmetric crypto --------------------- - some ciphers not supported via PSA yet: ARIA, Camellia, ChachaPoly (silent fallback to the legacy APIs) -- the HMAC part of the CBC and NULL ciphersuites is not covered +- the HMAC part of the CBC and NULL ciphersuites - the HMAC computation in `ssl_cookie.c` X.509 @@ -181,6 +187,6 @@ X.509 - most hash operations are still done via the legacy API, except the few that are documented above as using PSA -- RSA PKCS#1 v1.5 signature generation (from PSA-held keys): not covered -- RSA PKCS#1 v1.5 signature verification: not covered -- RSA-PSS signature verification: not covered +- RSA PKCS#1 v1.5 signature generation (from PSA-held keys) +- RSA PKCS#1 v1.5 signature verification +- RSA-PSS signature verification From ca9101739aca97117d1889489515c2262f8846bb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 24 Sep 2021 10:14:32 +0200 Subject: [PATCH 7/9] Improve wording and fix some typos. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 22 +++++++++++++--------- 1 file changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index 4292aa6b94..cdae3a8273 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -37,15 +37,18 @@ X.509) layers to pick up the improvements. ### PSA-held (opaque) keys in the PK layer -Add `mbedtls_pk_setup_opaque()` to wrap a PSA keypair into a PK context. The key -can be used for private-key operations and its public part can be written out. +There is a new API function `mbedtls_pk_setup_opaque()` that can be used to +wrap a PSA keypair into a PK context. The key can be used for private-key +operations and its public part can be exported. Benefits: isolation of long-term secrets, use of PSA Crypto drivers. Limitations: only for private keys, only ECC. (That is, only ECDSA signature -generation.) The following operations are not supported with a context set -this way, while they would be available with a normal `ECKEY` context: -`mbedtls_pk_verify()`, `mbedtls_pk_check_pair()`, `mbedtls_pk_debug()`. +generation. Note: currently this will use randomized ECDSA while Mbed TLS uses +deterministic ECDSA by default.) The following operations are not supported +with a context set this way, while they would be available with a normal +`ECKEY` context: `mbedtls_pk_verify()`, `mbedtls_pk_check_pair()`, +`mbedtls_pk_debug()`. Use in X.509 and TLS: opt-in. The application needs to construct the PK context using the new API in order to get the benefits; it can then pass the @@ -56,14 +59,15 @@ resulting context to the following existing APIs: - `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature request). -In the TLS and X.509 API, there's two other function which accept a key or +In the TLS and X.509 API, there are two other functions which accept a key or keypair as a PK context: `mbedtls_x509write_crt_set_subject_key()` and `mbedtls_x509write_crt_set_issuer_key()`. Use of opaque contexts here probably works but is so far untested. ### PSA-held (opaque) keys for TLS 1.2 pre-shared keys (PSK) -Add `mbedtls_ssl_conf_psk_opaque()` and `mbedtls_ssl_set_hs_psk_opaque()` to +There are two new API functions `mbedtls_ssl_conf_psk_opaque()` and +`mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to register a PSA key for use with a PSK key exchange. Benefits: isolation of long-term secrets. @@ -81,8 +85,8 @@ APIs to get the benefits. ### PSA-based operations in the Cipher layer -Add `mbedtls_cipher_setup_psa()` to set up a context that will call PSA to -store the key and perform the operations. +There is a new API function `mbedtls_cipher_setup_psa()` to set up a context +that will call PSA to store the key and perform the operations. Benefits: use of PSA Crypto drivers; partial isolation of short-term secrets (still generated outside of PSA, but then held by PSA). From 9155b0e396b0cc90642d452916b4a4264025d42c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 24 Sep 2021 10:17:07 +0200 Subject: [PATCH 8/9] Clarify that 1.3 is excluded MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Don't mention "TLS 1.2 only" for PSK, as that could give the impression that the other things about TLS are supported beyond 1.2, which isn't the case currently. Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index cdae3a8273..af485ce8e7 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -64,7 +64,7 @@ keypair as a PK context: `mbedtls_x509write_crt_set_subject_key()` and `mbedtls_x509write_crt_set_issuer_key()`. Use of opaque contexts here probably works but is so far untested. -### PSA-held (opaque) keys for TLS 1.2 pre-shared keys (PSK) +### PSA-held (opaque) keys for TLS pre-shared keys (PSK) There are two new API functions `mbedtls_ssl_conf_psk_opaque()` and `mbedtls_ssl_set_hs_psk_opaque()`. Call one of these from an application to @@ -72,7 +72,7 @@ register a PSA key for use with a PSK key exchange. Benefits: isolation of long-term secrets. -Limitations: the key can only be used with with TLS 1.2, and only with "pure" +Limitations: the key can only be used with "pure" PSK key exchanges (ciphersuites starting with `TLS_PSK_WITH_`), to the exclusion of RSA-PSK, DHE-PSK and ECDHE-PSK key exchanges. It is the responsibility of the user to make sure that when provisioning an opaque pre-shared key, the @@ -154,6 +154,11 @@ Parts that are not covered yet This is only a high-level overview, grouped by theme +TLS: 1.3 experimental support +----------------------------- + +No part of the experimental support for TLS 1.3 is covered at the moment. + TLS: key exchanges / asymmetric crypto -------------------------------------- From 13841cb719d4d2af13de8c5ac0fbd4e4afd79664 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Manuel=20P=C3=A9gouri=C3=A9-Gonnard?= Date: Fri, 24 Sep 2021 11:43:14 +0200 Subject: [PATCH 9/9] Mention areas that are not (well) tested. MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Manuel Pégourié-Gonnard --- docs/use-psa-crypto.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/use-psa-crypto.md b/docs/use-psa-crypto.md index af485ce8e7..6ec2dcaa1b 100644 --- a/docs/use-psa-crypto.md +++ b/docs/use-psa-crypto.md @@ -55,7 +55,8 @@ using the new API in order to get the benefits; it can then pass the resulting context to the following existing APIs: - `mbedtls_ssl_conf_own_cert()` or `mbedtls_ssl_set_hs_own_cert()` to use the - key together with a certificate for ECDSA-based key exchanges; + key together with a certificate for ECDSA-based key exchanges (note: while +this is supported on both sides, it's currently only tested client-side); - `mbedtls_x509write_csr_set_key()` to generate a CSR (certificate signature request). @@ -95,7 +96,9 @@ Limitations: the key is still passed in the clear by the application. The multi-part APIs are not supported, only the one-shot APIs. The only modes supported are ECB, CBC without padding, GCM and CCM (this excludes stream ciphers and ChachaPoly); the only cipher supported is AES (this excludes Aria, -Camellia, and ChachaPoly). +Camellia, and ChachaPoly). (Note: ECB is currently not tested.) (Note: it is +possible to perform multiple one-shot operations with the same context; +however this is not unit-tested, only tested via usage in TLS.) Use in TLS: automatic. Used when the cipher and mode is supported (with gracious fallback to the legacy API otherwise) in all places where a cipher is