Merge pull request #6005 from ronald-cron-arm/tls13-changelogs-doc-update
TLS 1.3: Add missing change logs and update doc for 3.2 release
Validated by the internal CI, ready to be merged.
diff --git a/ChangeLog.d/tls13-misc-changelogs.txt b/ChangeLog.d/tls13-misc-changelogs.txt
new file mode 100644
index 0000000..a575b33
--- /dev/null
+++ b/ChangeLog.d/tls13-misc-changelogs.txt
@@ -0,0 +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. 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 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 this.
diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md
index 85219c3..10da3c5 100644
--- a/docs/architecture/tls13-support.md
+++ b/docs/architecture/tls13-support.md
@@ -4,8 +4,8 @@
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 @@
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,72 @@
- 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 | 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.
-
- (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 the Mbed TLS SSL/TLS related options are not supported or not
+ applicable to the TLS 1.3 implementation:
| Mbed TLS configuration option | Support |
| ---------------------------------------- | ------- |
@@ -163,7 +119,7 @@
| 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 |
@@ -182,7 +138,7 @@
| 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,27 +146,11 @@
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
----------------------------
-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.
+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).