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 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 located at https://github.com/hannestschofenig/mbedtls. The prototype is itself based on a version of the development branch that we aim to keep as recent as possible (ideally the head) by merging regularly commits of the development branch into the prototype. The section “Prototype upstreaming status” below describes what remains to be upstreamed.
Overview
The TLS 1.3 MVP implements only the client side of the protocol.
The TLS 1.3 MVP supports ECDHE key establishment.
The TLS 1.3 MVP does not support DHE key establishment.
The TLS 1.3 MVP 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, TLS_AES_128_CCM_SHA256 and TLS_AES_128_CCM_8_SHA256.
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 |
(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.
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.
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).
Supported versions:
TLS 1.2 and TLS 1.3 but version negotiation is not supported.
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.
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.
Compatibility with existing SSL/TLS build options:
The TLS 1.3 MVP is compatible with all TLS 1.2 configuration options in the sense that when enabling the TLS 1.3 MVP in the library there is no need to modify the configuration for TLS 1.2. The MBEDTLS_USE_PSA_CRYPTO configuration option is an exception though, the TLS 1.3 MVP is not compatible with it.
Mbed TLS SSL/TLS related features are not supported or not applicable to the TLS 1.3 MVP:
| Mbed TLS configuration option | Support |
|---|---|
| MBEDTLS_SSL_ALL_ALERT_MESSAGES | no |
| MBEDTLS_SSL_ASYNC_PRIVATE | no |
| MBEDTLS_SSL_CONTEXT_SERIALIZATION | no |
| MBEDTLS_SSL_DEBUG_ALL | no |
| MBEDTLS_SSL_ENCRYPT_THEN_MAC | n/a |
| MBEDTLS_SSL_EXTENDED_MASTER_SECRET | n/a |
| MBEDTLS_SSL_KEEP_PEER_CERTIFICATE | no |
| MBEDTLS_SSL_RENEGOTIATION | n/a |
| MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no |
| MBEDTLS_SSL_SESSION_TICKETS | no |
| MBEDTLS_SSL_EXPORT_KEYS | no (1) |
| MBEDTLS_SSL_SERVER_NAME_INDICATION | no |
| 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_DHE_PSK_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_RSA_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED | n/a |
| MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a |
| MBEDTLS_USE_PSA_CRYPTO | no |
(1) Some support has already been upstreamed but it is incomplete. (2) Key exchange configuration options for TLS 1.3 will likely to be organized around the notion of key exchange mode along the line of the MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE/PSK/PSK_EPHEMERAL/EPHEMERAL runtime configuration macros.
Quality considerations
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).
New TLS Message Processing Stack (MPS)
The TLS 1.3 prototype is developed alongside a rewrite of the TLS messaging layer, encompassing low-level details such as record parsing, handshake reassembly, and DTLS retransmission state machine.
MPS has the following components:
Of those components, the following have been upstreamed as part of MBEDTLS_SSL_PROTO_TLS1_3:
library/mps_reader.h)The following coding rules are aimed to be a checklist for TLS 1.3 upstreaming work to reduce review rounds and the number of comments in each round. They come along (do NOT replace) the project coding rules (https://tls.mbed.org/kb/development/mbedtls-coding-standards). They have been established and discussed following the review of #4882 that was the PR upstreaming the first part of TLS 1.3 ClientHello writing code.
TLS 1.3 specific coding rules:
TLS 1.3 specific C modules, headers, static functions names are prefixed with ssl_tls13_. The same applies to structures and types that are internal to C modules.
TLS 1.3 specific exported functions, structures and types are prefixed with mbedtls_ssl_tls13_.
Use TLS1_3 in TLS 1.3 specific macros.
The names of macros and variables related to a field or structure in the TLS 1.3 specification should contain as far as possible the field name as it is in the specification. If the field name is “too long” and we prefer to introduce some kind of abbreviation of it, use the same abbreviation everywhere in the code.
Example 1: #define CLIENT_HELLO_RANDOM_LEN 32, macro for the length of the random field of the ClientHello message.
Example 2 (consistent abbreviation): mbedtls_ssl_tls13_write_sig_alg_ext() and MBEDTLS_TLS_EXT_SIG_ALG, sig_alg standing for signature_algorithms.
Regarding vectors that are represented by a length followed by their value in the data exchanged between servers and clients:
Use <vector name>_len for the name of a variable used to compute the length in bytes of the vector, where is the name of the vector as defined in the TLS 1.3 specification.
Use p_<vector_name>_len for the name of a variable intended to hold the address of the first byte of the vector length.
Use <vector_name> for the name of a variable intended to hold the address of the first byte of the vector value.
Use <vector_name>_end for the name of a variable intended to hold the address of the first byte past the vector value.
Those idioms should lower the risk of mis-using one of the address in place of another one which could potentially lead to some nasty issues.
Example: cipher_suites vector of ClientHello in ssl_tls13_write_client_hello_cipher_suites()
size_t cipher_suites_len; unsigned char *p_cipher_suites_len; unsigned char *cipher_suites;
Where applicable, use:
MBEDTLS_SSL_CHK_BUF_PTR.MBEDTLS_SSL_CHK_BUF_READ_PTR.These macros were introduced after the prototype was written thus are likely not to be used in prototype where we now would use them in development.
The three first types, MBEDTLS_BYTE_{0-8}, MBEDTLS_PUT_UINT{8|16|32|64}_BE and MBEDTLS_GET_UINT{8|16|32|64}_BE improve the readability of the code and reduce the risk of writing or reading bytes in the wrong order.
The two last types, MBEDTLS_SSL_CHK_BUF_PTR and MBEDTLS_SSL_CHK_BUF_READ_PTR, improve the readability of the code and reduce the risk of error in the non-completely-trivial arithmetic to check that we do not write or read past the end of a data buffer. The usage of those macros combined with the following rule mitigate the risk to read/write past the end of a data buffer.
Examples:
hs_hdr[1] = MBEDTLS_BYTE_2( total_hs_len ); MBEDTLS_PUT_UINT16_BE( MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS, p, 0 ); MBEDTLS_SSL_CHK_BUF_PTR( p, end, 7 );
To mitigate what happened here (https://github.com/Mbed-TLS/mbedtls/pull/4882#discussion_r701704527) from happening again, use always a local variable named p for the reading pointer in functions parsing TLS 1.3 data, and for the writing pointer in functions writing data into an output buffer and only that variable. The name p has been chosen as it was already widely used in TLS code.
When an TLS 1.3 structure is written or read by a function or as part of a function, provide as documentation the definition of the structure as it is in the TLS 1.3 specification.
General coding rules:
We prefer grouping “related statement lines” by not adding blank lines between them.
Example 1:
ret = ssl_tls13_write_client_hello_cipher_suites( ssl, buf, end, &output_len );
if( ret != 0 )
return( ret );
buf += output_len;
Example 2:
MBEDTLS_SSL_CHK_BUF_PTR( cipher_suites_iter, end, 2 ); MBEDTLS_PUT_UINT16_BE( cipher_suite, cipher_suites_iter, 0 ); cipher_suites_iter += 2;
Use macros for constants that are used in different functions, different places in the code. When a constant is used only locally in a function (like the length in bytes of the vector lengths in functions reading and writing TLS handshake message) there is no need to define a macro for it.
Example: #define CLIENT_HELLO_RANDOM_LEN 32
When declaring a pointer the dereferencing operator should be prepended to the pointer name not appended to the pointer type:
Example: mbedtls_ssl_context *ssl;
Maximum line length is 80 characters.
Exceptions:
string literals can extend beyond 80 characters as we do not want to split them to ease their search in the code base.
A line can be more than 80 characters by a few characters if just looking at the 80 first characters is enough to fully understand the line. For example it is generally fine if some closure characters like “;” or “)” are beyond the 80 characters limit.
If a line becomes too long due to a refactoring (for example renaming a function to a longer name, or indenting a block more), avoid rewrapping lines in the same commit: it makes the review harder. Make one commit with the longer lines and another commit with just the rewrapping.
When in successive lines, functions and macros parameters should be aligned vertically.
Example:
int mbedtls_ssl_start_handshake_msg( mbedtls_ssl_context *ssl,
unsigned hs_type,
unsigned char **buf,
size_t *buf_len );
When a function's parameters span several lines, group related parameters together if possible.
For example, prefer:
mbedtls_ssl_start_handshake_msg( ssl, hs_type,
buf, buf_len );
over
mbedtls_ssl_start_handshake_msg( ssl, hs_type, buf,
buf_len );
even if it fits.
The TLS 1.3 handshake protocol is implemented as a state machine. The functions mbedtls_ssl_tls13_handshake_{client,server}_step are the top level functions of that implementation. They are implemented as a switch over all the possible states of the state machine.
Most of the states are either dedicated to the processing or writing of an handshake message.
The implementation does not go systematically through all states as this would result in too many checks of whether something needs to be done or not in a given state to be duplicated across several state handlers. For example, on client side, the states related to certificate parsing and validation are bypassed if the handshake is based on a pre-shared key and thus does not involve certificates.
On the contrary, the implementation goes systematically though some states even if they could be bypassed if it helps in minimizing when and where inbound and outbound keys are updated. The MBEDTLS_SSL_CLIENT_CERTIFICATE state on client side is a example of that.
The names of the handlers processing/writing an handshake message are prefixed with (mbedtls_)ssl_tls13_{process,write}. To ease the maintenance and reduce the risk of bugs, the code of the message processing and writing handlers is split into a sequence of stages.
The sending of data to the peer only occurs in mbedtls_ssl_handshake_step between the calls to the handlers and as a consequence handlers do not have to care about the MBEDTLS_ERR_SSL_WANT_WRITE error code. Furthermore, all pending data are flushed before to call the next handler. That way, handlers do not have to worry about pending data when changing outbound keys.
For message processing handlers, the stages are:
coordination stage: check if the state should be bypassed. This stage is optional. The check is either purely based on the reading of the value of some fields of the SSL context or based on the reading of the type of the next message. The latter occurs when it is not known what the next handshake message will be, an example of that on client side being if we are going to receive a CertificateRequest message or not. The intent is, apart from the next record reading to not modify the SSL context as this stage may be repeated if the next handshake message has not been received yet.
fetching stage: at this stage we are sure of the type of the handshake message we must receive next and we try to fetch it. If we did not go through a coordination stage involving the next record type reading, the next handshake message may not have been received yet, the handler returns with MBEDTLS_ERR_SSL_WANT_READ without changing the current state and it will be called again later.
pre-processing stage: prepare the SSL context for the message parsing. This stage is optional. Any processing that must be done before the parsing of the message or that can be done to simplify the parsing code. Some simple and partial parsing of the handshake message may append at that stage like in the ServerHello message pre-processing.
parsing stage: parse the message and restrict as much as possible any update of the SSL context. The idea of the pre-processing/parsing/post-processing organization is to concentrate solely on the parsing in the parsing function to reduce the size of its code and to simplify it.
post-processing stage: following the parsing, further update of the SSL context to prepare for the next incoming and outgoing messages. This stage is optional. For example, secret and key computations occur at this stage, as well as handshake messages checksum update.
state change: the state change is done in the main state handler to ease the navigation of the state machine transitions.
For message writing handlers, the stages are:
coordination stage: check if the state should be bypassed. This stage is optional. The check is based on the value of some fields of the SSL context.
preparation stage: prepare for the message writing. This stage is optional. Any processing that must be done before the writing of the message or that can be done to simplify the writing code.
writing stage: write the message and restrict as much as possible any update of the SSL context. The idea of the preparation/writing/finalization organization is to concentrate solely on the writing in the writing function to reduce the size of its code and simplify it.
finalization stage: following the writing, further update of the SSL context to prepare for the next incoming and outgoing messages. This stage is optional. For example, handshake secret and key computation occur at that stage (ServerHello writing finalization), switching to handshake keys for outbound message on server side as well.
state change: the state change is done in the main state handler to ease the navigation of the state machine transitions.