Update TLS 1.3 support documentation
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
diff --git a/docs/architecture/tls13-support.md b/docs/architecture/tls13-support.md
index 85219c3..de92690 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,73 @@
- 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 @@
| 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 @@
| 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 @@
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 @@
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).
