mirror of
https://github.com/Mbed-TLS/mbedtls.git
synced 2025-03-28 19:21:08 +00:00
Update TLS 1.3 support documentation
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
This commit is contained in:
Ronald Cron
parent
11ccb35987
commit
2ba0d23c65
@ -4,8 +4,8 @@ TLS 1.3 support
|
|||||||
Overview
|
Overview
|
||||||
--------
|
--------
|
||||||
|
|
||||||
Mbed TLS provides a minimum viable implementation of the TLS 1.3 protocol
|
Mbed TLS provides a partial implementation of the TLS 1.3 protocol defined in
|
||||||
defined in the "MVP definition" section below. The TLS 1.3 support enablement
|
the "Support description" section below. The TLS 1.3 support enablement
|
||||||
is controlled by the MBEDTLS_SSL_PROTO_TLS1_3 configuration option.
|
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
|
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.
|
status" below describes what remains to be upstreamed.
|
||||||
|
|
||||||
|
|
||||||
MVP definition
|
Support description
|
||||||
--------------
|
-------------------
|
||||||
|
|
||||||
- Overview
|
- 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
|
session resumption. This implies that it does not support sending early
|
||||||
data (0-RTT data).
|
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
|
- Supported cipher suites: depends on the library configuration. Potentially
|
||||||
all of them:
|
all of them:
|
||||||
TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256,
|
TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256,
|
||||||
@ -55,100 +39,73 @@ MVP definition
|
|||||||
|
|
||||||
- Supported ClientHello extensions:
|
- Supported ClientHello extensions:
|
||||||
|
|
||||||
| Extension | MVP | Prototype (1) |
|
| Extension | Mbed TLS | Prototype (1) |
|
||||||
| ---------------------------- | ------- | ------------- |
|
| ---------------------------- | -------- | ------------- |
|
||||||
| server_name | YES | YES |
|
| server_name | YES | YES |
|
||||||
| max_fragment_length | no | YES |
|
| max_fragment_length | no | YES |
|
||||||
| status_request | no | no |
|
| status_request | no | no |
|
||||||
| supported_groups | YES | YES |
|
| supported_groups | YES | YES |
|
||||||
| signature_algorithms | YES | YES |
|
| signature_algorithms | YES | YES |
|
||||||
| use_srtp | no | no |
|
| use_srtp | no | no |
|
||||||
| heartbeat | no | no |
|
| heartbeat | no | no |
|
||||||
| apln | no | YES |
|
| apln | YES | YES |
|
||||||
| signed_certificate_timestamp | no | no |
|
| signed_certificate_timestamp | no | no |
|
||||||
| client_certificate_type | no | no |
|
| client_certificate_type | no | no |
|
||||||
| server_certificate_type | no | no |
|
| server_certificate_type | no | no |
|
||||||
| padding | no | no |
|
| padding | no | no |
|
||||||
| key_share | YES (2) | YES |
|
| key_share | YES | YES |
|
||||||
| pre_shared_key | no | YES |
|
| pre_shared_key | no | YES |
|
||||||
| psk_key_exchange_modes | no | YES |
|
| psk_key_exchange_modes | no | YES |
|
||||||
| early_data | no | YES |
|
| early_data | no | YES |
|
||||||
| cookie | no | YES |
|
| cookie | no | YES |
|
||||||
| supported_versions | YES (3) | YES |
|
| supported_versions | YES | YES |
|
||||||
| certificate_authorities | no | no |
|
| certificate_authorities | no | no |
|
||||||
| post_handshake_auth | no | no |
|
| post_handshake_auth | no | no |
|
||||||
| signature_algorithms_cert | no | no |
|
| signature_algorithms_cert | no | no |
|
||||||
|
|
||||||
(1) This is just for comparison.
|
(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.
|
- Supported groups: depends on the library configuration.
|
||||||
Potentially all ECDHE groups but x448:
|
Potentially all ECDHE groups:
|
||||||
secp256r1, x25519, secp384r1 and secp521r1.
|
secp256r1, x25519, secp384r1, x448 and secp521r1.
|
||||||
|
|
||||||
Finite field groups (DHE) are not supported.
|
Finite field groups (DHE) are not supported.
|
||||||
|
|
||||||
- Supported signature algorithms (both for certificates and CertificateVerify):
|
- Supported signature algorithms (both for certificates and CertificateVerify):
|
||||||
depends on the library configuration.
|
depends on the library configuration.
|
||||||
Potentially:
|
Potentially:
|
||||||
rsa_pkcs1_sha256, rsa_pss_rsae_sha256, ecdsa_secp256r1_sha256,
|
ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp521r1_sha512,
|
||||||
ecdsa_secp384r1_sha384 and 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
|
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
|
rsa_pkcs1_sha256, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256 are
|
||||||
specification).
|
mandatory (see section 9.1 of the specification).
|
||||||
|
|
||||||
- Supported versions:
|
- 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
|
- TLS 1.2 and TLS 1.3 can be enabled in the build independently of each
|
||||||
configuration option) without TLS 1.2 (MBEDTLS_SSL_PROTO_TLS1_2 configuration
|
other.
|
||||||
option).
|
|
||||||
|
|
||||||
- TLS 1.2 can be enabled in the build independently of TLS 1.3.
|
|
||||||
|
|
||||||
- If both TLS 1.3 and TLS 1.2 are enabled at build time, only one of them can
|
- 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,
|
be configured at runtime via `mbedtls_ssl_conf_{min,max}_tls_version` for a
|
||||||
`mbedtls_ssl_setup` will raise `MBEDTLS_ERR_SSL_BAD_CONFIG` error.
|
server endpoint. Otherwise, `mbedtls_ssl_setup` will raise
|
||||||
|
`MBEDTLS_ERR_SSL_BAD_CONFIG` error.
|
||||||
|
|
||||||
- Compatibility with existing SSL/TLS build options:
|
- Compatibility with existing SSL/TLS build options:
|
||||||
|
|
||||||
The TLS 1.3 MVP is compatible with nearly all TLS 1.2 configuration options
|
The TLS 1.3 implementation is compatible with nearly all TLS 1.2
|
||||||
in the sense that when enabling the TLS 1.3 MVP in the library there is rarely
|
configuration options in the sense that when enabling TLS 1.3 in the library
|
||||||
any need to modify the configuration from that used for TLS 1.2.
|
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:
|
Most of Mbed TLS SSL/TLS related features are not supported or not applicable
|
||||||
|
to the TLS 1.3 implementation:
|
||||||
- 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:
|
|
||||||
|
|
||||||
| Mbed TLS configuration option | Support |
|
| Mbed TLS configuration option | Support |
|
||||||
| ---------------------------------------- | ------- |
|
| ---------------------------------------- | ------- |
|
||||||
@ -163,13 +120,13 @@ MVP definition
|
|||||||
| MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no |
|
| MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no |
|
||||||
| | |
|
| | |
|
||||||
| MBEDTLS_SSL_SESSION_TICKETS | 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_SSL_VARIABLE_BUFFER_LENGTH | no |
|
||||||
| | |
|
| | |
|
||||||
| MBEDTLS_ECP_RESTARTABLE | no |
|
| MBEDTLS_ECP_RESTARTABLE | no |
|
||||||
| MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED | 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_DHE_PSK_ENABLED | n/a |
|
||||||
| MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a |
|
| MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a |
|
||||||
| MBEDTLS_KEY_EXCHANGE_RSA_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_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a |
|
||||||
| | |
|
| | |
|
||||||
| MBEDTLS_PSA_CRYPTO_C | no (1) |
|
| 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.
|
(1) These options must remain in their default state of enabled.
|
||||||
(2) Key exchange configuration options for TLS 1.3 will likely to be
|
(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
|
of the MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE/PSK/PSK_EPHEMERAL/EPHEMERAL
|
||||||
runtime configuration macros.
|
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
|
Prototype upstreaming status
|
||||||
----------------------------
|
----------------------------
|
||||||
@ -207,11 +154,6 @@ Prototype upstreaming status
|
|||||||
The following summarizes which parts of the TLS 1.3 prototype remain to be
|
The following summarizes which parts of the TLS 1.3 prototype remain to be
|
||||||
upstreamed:
|
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
|
- Pre-shared keys, session resumption and 0-RTT data (both client and server
|
||||||
side).
|
side).
|
||||||
|
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user