yuzu-emu/mbedtls
2
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Update TLS 1.3 support documentation

Browse source 
Signed-off-by: Ronald Cron <ronald.cron@arm.com>
This commit is contained in:
Ronald Cron 2022-07-01 11:25:49 +02:00
parent 11ccb35987
commit 2ba0d23c65
1 changed files with 57 additions and 115 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

172
docs/architecture/tls13-support.md
View file

@ -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).