From 00b72fc35fd84f3d622cee8323121c02be6acf08 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/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 000000000..a4f43b783 --- /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/config.h b/include/mbedtls/config.h index 2c7bed206..cc804718b 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2119,6 +2119,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 04bc6875a00a15e3c118d0d5b5e7ba97bf958203 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 a4f43b783..d1298af2b 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 b52b91d9493890594e229bfb1a2a27f8a620ab6b 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/config.h | 17 ++++------------- 1 file changed, 4 insertions(+), 13 deletions(-) diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h index cc804718b..3c9967ec4 100644 --- a/include/mbedtls/config.h +++ b/include/mbedtls/config.h @@ -2122,15 +2122,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. * @@ -3202,10 +3197,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 6cf7d94ab43307f5a30f16719a41438814c968b8 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 d1298af2b..c8f89d0c2 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 1fa923a5bc93171f8cd0541b43230fa9e66c8836 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 c8f89d0c2..6300bf02e 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 b4113bac9ab95d5466c5d8ebfbcca659efd0425e 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 6300bf02e..4292aa6b9 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 12ab49aaf7300c8ecb60bbf395f754b492cbae08 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 4292aa6b9..cdae3a827 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 ee20baf6e114ca144ab4daa541cfc7c55d77fbab 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 cdae3a827..af485ce8e 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 fec7ef8270c13b4cac5580733ac2424d54e751a8 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 af485ce8e..6ec2dcaa1 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