From 2ba0d23c65db88058d74c39c18959b4e2700fae0 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Fri, 1 Jul 2022 11:25:49 +0200 Subject: [PATCH 1/3] Update TLS 1.3 support documentation Signed-off-by: Ronald Cron --- docs/architecture/tls13-support.md | 172 ++++++++++------------------- 1 file changed, 57 insertions(+), 115 deletions(-) diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md index 85219c307..de92690d7 100644 --- a/docs/architecture/tls13-support.md +++ b/docs/architecture/tls13-support.md @@ -4,8 +4,8 @@ TLS 1.3 support Overview -------- -Mbed TLS provides a minimum viable implementation of the TLS 1.3 protocol -defined in the "MVP definition" section below. The TLS 1.3 support enablement +Mbed TLS provides a partial implementation of the TLS 1.3 protocol defined in +the "Support description" section below. The TLS 1.3 support enablement is controlled by the MBEDTLS_SSL_PROTO_TLS1_3 configuration option. The development of the TLS 1.3 protocol is based on the TLS 1.3 prototype @@ -16,38 +16,22 @@ development branch into the prototype. The section "Prototype upstreaming status" below describes what remains to be upstreamed. -MVP definition --------------- +Support description +------------------- - Overview - - The TLS 1.3 MVP implements only the client side of the protocol. + - Mbed TLS implements both the client and the server side of the TLS 1.3 + protocol. - - The TLS 1.3 MVP supports ECDHE key establishment. + - Mbed TLS supports ECDHE key establishment. - - The TLS 1.3 MVP does not support DHE key establishment. + - Mbed TLS does not support DHE key establishment. - - The TLS 1.3 MVP does not support pre-shared keys, including any form of + - Mbed TLS does not support pre-shared keys, including any form of session resumption. This implies that it does not support sending early data (0-RTT data). - - The TLS 1.3 MVP supports the authentication of the server by the client - but does not support authentication of the client by the server. In terms - of TLS 1.3 authentication messages, this means that the TLS 1.3 MVP - supports the processing of the Certificate and CertificateVerify messages - but not of the CertificateRequest message. - - - The TLS 1.3 MVP does not support the handling of server HelloRetryRequest - message. In practice, this means that the handshake will fail if the MVP - does not provide in its ClientHello the shared secret associated to the - group selected by the server for key establishement. For more information, - see the comment associated to the `key_share` extension below. - - - If the TLS 1.3 MVP receives a HelloRetryRequest or a CertificateRequest - message, it aborts the handshake with an handshake_failure closure alert - and the `mbedtls_ssl_handshake()` returns in error with the - `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` error code. - - Supported cipher suites: depends on the library configuration. Potentially all of them: TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, @@ -55,100 +39,73 @@ MVP definition - Supported ClientHello extensions: - | Extension | MVP | Prototype (1) | - | ---------------------------- | ------- | ------------- | - | server_name | YES | YES | - | max_fragment_length | no | YES | - | status_request | no | no | - | supported_groups | YES | YES | - | signature_algorithms | YES | YES | - | use_srtp | no | no | - | heartbeat | no | no | - | apln | no | YES | - | signed_certificate_timestamp | no | no | - | client_certificate_type | no | no | - | server_certificate_type | no | no | - | padding | no | no | - | key_share | YES (2) | YES | - | pre_shared_key | no | YES | - | psk_key_exchange_modes | no | YES | - | early_data | no | YES | - | cookie | no | YES | - | supported_versions | YES (3) | YES | - | certificate_authorities | no | no | - | post_handshake_auth | no | no | - | signature_algorithms_cert | no | no | + | Extension | Mbed TLS | Prototype (1) | + | ---------------------------- | -------- | ------------- | + | server_name | YES | YES | + | max_fragment_length | no | YES | + | status_request | no | no | + | supported_groups | YES | YES | + | signature_algorithms | YES | YES | + | use_srtp | no | no | + | heartbeat | no | no | + | apln | YES | YES | + | signed_certificate_timestamp | no | no | + | client_certificate_type | no | no | + | server_certificate_type | no | no | + | padding | no | no | + | key_share | YES | YES | + | pre_shared_key | no | YES | + | psk_key_exchange_modes | no | YES | + | early_data | no | YES | + | cookie | no | YES | + | supported_versions | YES | YES | + | certificate_authorities | no | no | + | post_handshake_auth | no | no | + | signature_algorithms_cert | no | no | (1) This is just for comparison. - (2) The MVP sends only one shared secret corresponding to the configured - preferred group. This could end up with connection failure if the - server does not support our preferred curve, as the MVP does not implement - HelloRetryRequest. The preferred group is the group of the first curve in - the list of allowed curves as defined by the configuration. The allowed - curves are by default ordered as follows: `x25519`, `secp256r1`, - `secp384r1` and finally `secp521r1`. Note that, in the absence of an - application profile standard specifying otherwise, section 9.1 of the - specification rather promotes curve `secp256r1` to be supported over - curve `x25519`. The MVP would, however, rather keep the preference order - currently promoted by Mbed TLS as this applies to TLS 1.2 as well, and - changing the order only for TLS1.3 would be potentially difficult. - In the unlikely event a server does not support curve `x25519` but does - support curve `secp256r1`, curve `secp256r1` can be set as the preferred - curve through the `mbedtls_ssl_conf_curves()` API. - - (3) The MVP proposes only TLS 1.3 and does not support version negotiation. - Out-of-protocol fallback is supported though if the Mbed TLS library - has been built to support both TLS 1.3 and TLS 1.2: just set the - maximum of the minor version of the SSL configuration to - MBEDTLS_SSL_MINOR_VERSION_3 (`mbedtls_ssl_conf_min_version()` API) and - re-initiate a server handshake. - - Supported groups: depends on the library configuration. - Potentially all ECDHE groups but x448: - secp256r1, x25519, secp384r1 and secp521r1. + Potentially all ECDHE groups: + secp256r1, x25519, secp384r1, x448 and secp521r1. Finite field groups (DHE) are not supported. - Supported signature algorithms (both for certificates and CertificateVerify): depends on the library configuration. Potentially: - rsa_pkcs1_sha256, rsa_pss_rsae_sha256, ecdsa_secp256r1_sha256, - ecdsa_secp384r1_sha384 and ecdsa_secp521r1_sha512. + ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp521r1_sha512, + rsa_pkcs1_sha256, rsa_pkcs1_sha384, rsa_pkcs1_sha512, rsa_pss_rsae_sha256, + rsa_pss_rsae_sha384 and rsa_pss_rsae_sha512. Note that in absence of an application profile standard specifying otherwise - the three first ones in the list above are mandatory (see section 9.1 of the - specification). + rsa_pkcs1_sha256, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256 are + mandatory (see section 9.1 of the specification). - Supported versions: - - TLS 1.2 and TLS 1.3 but version negotiation is not supported. + - TLS 1.2 and TLS 1.3 with version negotiation on the client side, not server + side. - - TLS 1.3 cannot be enabled in the build (MBEDTLS_SSL_PROTO_TLS1_3 - configuration option) without TLS 1.2 (MBEDTLS_SSL_PROTO_TLS1_2 configuration - option). - - - TLS 1.2 can be enabled in the build independently of TLS 1.3. + - TLS 1.2 and TLS 1.3 can be enabled in the build independently of each + other. - If both TLS 1.3 and TLS 1.2 are enabled at build time, only one of them can - be configured at runtime via `mbedtls_ssl_conf_{min,max}_version`. Otherwise, - `mbedtls_ssl_setup` will raise `MBEDTLS_ERR_SSL_BAD_CONFIG` error. + be configured at runtime via `mbedtls_ssl_conf_{min,max}_tls_version` for a + server endpoint. Otherwise, `mbedtls_ssl_setup` will raise + `MBEDTLS_ERR_SSL_BAD_CONFIG` error. - Compatibility with existing SSL/TLS build options: - The TLS 1.3 MVP is compatible with nearly all TLS 1.2 configuration options - in the sense that when enabling the TLS 1.3 MVP in the library there is rarely - any need to modify the configuration from that used for TLS 1.2. + The TLS 1.3 implementation is compatible with nearly all TLS 1.2 + configuration options in the sense that when enabling TLS 1.3 in the library + there is rarely any need to modify the configuration from that used for + TLS 1.2. There are two exceptions though: the TLS 1.3 implementation requires + MBEDTLS_PSA_CRYPTO_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE, so these options + must be enabled. - The exceptions to this are: - - - The TLS 1.3 MVP is not compatible with MBEDTLS_USE_PSA_CRYPTO, so this option - must be disabled. - - The TLS 1.3 MVP requires MBEDTLS_PSA_CRYPTO_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE, - so these options must be enabled. - - Mbed TLS SSL/TLS related features are not supported or not applicable to the - TLS 1.3 MVP: + Most of Mbed TLS SSL/TLS related features are not supported or not applicable + to the TLS 1.3 implementation: | Mbed TLS configuration option | Support | | ---------------------------------------- | ------- | @@ -163,13 +120,13 @@ MVP definition | MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no | | | | | MBEDTLS_SSL_SESSION_TICKETS | no | - | MBEDTLS_SSL_SERVER_NAME_INDICATION | no | + | MBEDTLS_SSL_SERVER_NAME_INDICATION | yes | | MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH | no | | | | | MBEDTLS_ECP_RESTARTABLE | no | | MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED | no | | | | - | MBEDTLS_KEY_EXCHANGE_PSK_ENABLED | n/a (2) | + | MBEDTLS_KEY_EXCHANGE_PSK_ENABLED | n/a (1) | | MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED | n/a | | MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a | | MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED | n/a | @@ -182,7 +139,7 @@ MVP definition | MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a | | | | | MBEDTLS_PSA_CRYPTO_C | no (1) | - | MBEDTLS_USE_PSA_CRYPTO | no | + | MBEDTLS_USE_PSA_CRYPTO | yes | (1) These options must remain in their default state of enabled. (2) Key exchange configuration options for TLS 1.3 will likely to be @@ -190,16 +147,6 @@ MVP definition of the MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE/PSK/PSK_EPHEMERAL/EPHEMERAL runtime configuration macros. -- Quality considerations - - Standard Mbed TLS review bar - - Interoperability testing with OpenSSL and GnuTLS. Test with all the - cipher suites and signature algorithms supported by OpenSSL/GnuTLS server. - - Negative testing against OpenSSL/GnuTLS servers with which the - handshake fails due to incompatibility with the capabilities of the - MVP: TLS 1.2 or 1.1 server, server sending an HelloRetryRequest message in - response to the MVP ClientHello, server sending a CertificateRequest - message ... - Prototype upstreaming status ---------------------------- @@ -207,11 +154,6 @@ Prototype upstreaming status The following summarizes which parts of the TLS 1.3 prototype remain to be upstreamed: -- Ephemeral only handshake on client side: client authentication, - HelloRetryRequest support, version negotiation. - -- Ephemeral only handshake server side. - - Pre-shared keys, session resumption and 0-RTT data (both client and server side). From 08346434d21fd6d69a9b5e6fa5ae1404e23b4596 Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Fri, 1 Jul 2022 11:27:19 +0200 Subject: [PATCH 2/3] Add TLS 1.3 change logs Signed-off-by: Ronald Cron --- ChangeLog.d/tls13-misc-changelogs.txt | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 ChangeLog.d/tls13-misc-changelogs.txt diff --git a/ChangeLog.d/tls13-misc-changelogs.txt b/ChangeLog.d/tls13-misc-changelogs.txt new file mode 100644 index 000000000..f097d6cca --- /dev/null +++ b/ChangeLog.d/tls13-misc-changelogs.txt @@ -0,0 +1,19 @@ +Bugfix + * Fix a TLS 1.3 handshake failure when the first attempt to send the client + Finished message on the network cannot be satisfied. + +Features + * Add support for authentication of TLS 1.3 clients by TLS 1.3 servers. + * Add support for server HelloRetryRequest message. The TLS 1.3 client is + now capable of negotiating another shared secret if the one sent in its + first ClientHello was not suitable to the server. + * Add support for TLS version negotiation. If both TLS 1.2 and TLS 1.3 + protocols are enabled in the build of Mbed TLS, the TLS client now + negotiates TLS 1.3 or TLS 1.2 with TLS servers. + * Enable building of Mbed TLS with TLS 1.3 protocol support but without TLS + 1.2 protocol support. + * Mbed TLS provides an implementation of a TLS 1.3 server (ephemeral key + establishment only). See docs/architecture/tls13-support.md for a + description of the support. The MBEDTLS_SSL_PROTO_TLS1_3 and + MBEDTLS_SSL_SRV_C configuration options control the enablement of the + support. From 3cb707dc6d7ace9d874b3a1aa206f8ec7fdb406e Mon Sep 17 00:00:00 2001 From: Ronald Cron Date: Fri, 1 Jul 2022 14:36:52 +0200 Subject: [PATCH 3/3] Fix and improve logs and documentation Signed-off-by: Ronald Cron --- ChangeLog.d/tls13-misc-changelogs.txt | 9 ++--- docs/architecture/tls13-support.md | 56 +++++++++++++-------------- 2 files changed, 31 insertions(+), 34 deletions(-) diff --git a/ChangeLog.d/tls13-misc-changelogs.txt b/ChangeLog.d/tls13-misc-changelogs.txt index f097d6cca..a575b3345 100644 --- a/ChangeLog.d/tls13-misc-changelogs.txt +++ b/ChangeLog.d/tls13-misc-changelogs.txt @@ -1,19 +1,18 @@ Bugfix * Fix a TLS 1.3 handshake failure when the first attempt to send the client - Finished message on the network cannot be satisfied. + Finished message on the network cannot be satisfied. Fixes #5499. Features * Add support for authentication of TLS 1.3 clients by TLS 1.3 servers. * Add support for server HelloRetryRequest message. The TLS 1.3 client is now capable of negotiating another shared secret if the one sent in its first ClientHello was not suitable to the server. - * Add support for TLS version negotiation. If both TLS 1.2 and TLS 1.3 - protocols are enabled in the build of Mbed TLS, the TLS client now + * Add support for client-side TLS version negotiation. If both TLS 1.2 and + TLS 1.3 protocols are enabled in the build of Mbed TLS, the TLS client now negotiates TLS 1.3 or TLS 1.2 with TLS servers. * Enable building of Mbed TLS with TLS 1.3 protocol support but without TLS 1.2 protocol support. * Mbed TLS provides an implementation of a TLS 1.3 server (ephemeral key establishment only). See docs/architecture/tls13-support.md for a description of the support. The MBEDTLS_SSL_PROTO_TLS1_3 and - MBEDTLS_SSL_SRV_C configuration options control the enablement of the - support. + MBEDTLS_SSL_SRV_C configuration options control this. diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md index de92690d7..10da3c5ab 100644 --- a/docs/architecture/tls13-support.md +++ b/docs/architecture/tls13-support.md @@ -39,31 +39,30 @@ Support description - Supported ClientHello extensions: - | Extension | Mbed TLS | Prototype (1) | - | ---------------------------- | -------- | ------------- | - | server_name | YES | YES | - | max_fragment_length | no | YES | - | status_request | no | no | - | supported_groups | YES | YES | - | signature_algorithms | YES | YES | - | use_srtp | no | no | - | heartbeat | no | no | - | apln | YES | YES | - | signed_certificate_timestamp | no | no | - | client_certificate_type | no | no | - | server_certificate_type | no | no | - | padding | no | no | - | key_share | YES | YES | - | pre_shared_key | no | YES | - | psk_key_exchange_modes | no | YES | - | early_data | no | YES | - | cookie | no | YES | - | supported_versions | YES | YES | - | certificate_authorities | no | no | - | post_handshake_auth | no | no | - | signature_algorithms_cert | no | no | + | Extension | Support | + | ---------------------------- | ------- | + | server_name | YES | + | max_fragment_length | no | + | status_request | no | + | supported_groups | YES | + | signature_algorithms | YES | + | use_srtp | no | + | heartbeat | no | + | apln | YES | + | signed_certificate_timestamp | no | + | client_certificate_type | no | + | server_certificate_type | no | + | padding | no | + | key_share | YES | + | pre_shared_key | no | + | psk_key_exchange_modes | no | + | early_data | no | + | cookie | no | + | supported_versions | YES | + | certificate_authorities | no | + | post_handshake_auth | no | + | signature_algorithms_cert | no | - (1) This is just for comparison. - Supported groups: depends on the library configuration. Potentially all ECDHE groups: @@ -104,8 +103,8 @@ Support description MBEDTLS_PSA_CRYPTO_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE, so these options must be enabled. - Most of Mbed TLS SSL/TLS related features are not supported or not applicable - to the TLS 1.3 implementation: + Most of the Mbed TLS SSL/TLS related options are not supported or not + applicable to the TLS 1.3 implementation: | Mbed TLS configuration option | Support | | ---------------------------------------- | ------- | @@ -126,7 +125,7 @@ Support description | MBEDTLS_ECP_RESTARTABLE | no | | MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED | no | | | | - | MBEDTLS_KEY_EXCHANGE_PSK_ENABLED | n/a (1) | + | MBEDTLS_KEY_EXCHANGE_PSK_ENABLED | n/a (2) | | MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED | n/a | | MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a | | MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED | n/a | @@ -151,8 +150,7 @@ Support description Prototype upstreaming status ---------------------------- -The following summarizes which parts of the TLS 1.3 prototype remain to be -upstreamed: +The following parts of the TLS 1.3 prototype remain to be upstreamed: - Pre-shared keys, session resumption and 0-RTT data (both client and server side).