1TLS 1.3 support 2=============== 3 4Overview 5-------- 6 7Mbed TLS provides a minimum viable implementation of the TLS 1.3 protocol 8defined in the "MVP definition" section below. The TLS 1.3 support enablement 9is controlled by the MBEDTLS_SSL_PROTO_TLS1_3 configuration option. 10 11The development of the TLS 1.3 protocol is based on the TLS 1.3 prototype 12located at https://github.com/hannestschofenig/mbedtls. The prototype is 13itself based on a version of the development branch that we aim to keep as 14recent as possible (ideally the head) by merging regularly commits of the 15development branch into the prototype. The section "Prototype upstreaming 16status" below describes what remains to be upstreamed. 17 18 19MVP definition 20-------------- 21 22- Overview 23 24 - The TLS 1.3 MVP implements only the client side of the protocol. 25 26 - The TLS 1.3 MVP supports ECDHE key establishment. 27 28 - The TLS 1.3 MVP does not support DHE key establishment. 29 30 - The TLS 1.3 MVP does not support pre-shared keys, including any form of 31 session resumption. This implies that it does not support sending early 32 data (0-RTT data). 33 34 - The TLS 1.3 MVP supports the authentication of the server by the client 35 but does not support authentication of the client by the server. In terms 36 of TLS 1.3 authentication messages, this means that the TLS 1.3 MVP 37 supports the processing of the Certificate and CertificateVerify messages 38 but not of the CertificateRequest message. 39 40 - The TLS 1.3 MVP does not support the handling of server HelloRetryRequest 41 message. In practice, this means that the handshake will fail if the MVP 42 does not provide in its ClientHello the shared secret associated to the 43 group selected by the server for key establishement. For more information, 44 see the comment associated to the `key_share` extension below. 45 46 - If the TLS 1.3 MVP receives a HelloRetryRequest or a CertificateRequest 47 message, it aborts the handshake with an handshake_failure closure alert 48 and the `mbedtls_ssl_handshake()` returns in error with the 49 `MBEDTLS_ERR_SSL_HANDSHAKE_FAILURE` error code. 50 51- Supported cipher suites: depends on the library configuration. Potentially 52 all of them: 53 TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, 54 TLS_AES_128_CCM_SHA256 and TLS_AES_128_CCM_8_SHA256. 55 56- Supported ClientHello extensions: 57 58 | Extension | MVP | Prototype (1) | 59 | ---------------------------- | ------- | ------------- | 60 | server_name | YES | YES | 61 | max_fragment_length | no | YES | 62 | status_request | no | no | 63 | supported_groups | YES | YES | 64 | signature_algorithms | YES | YES | 65 | use_srtp | no | no | 66 | heartbeat | no | no | 67 | apln | no | YES | 68 | signed_certificate_timestamp | no | no | 69 | client_certificate_type | no | no | 70 | server_certificate_type | no | no | 71 | padding | no | no | 72 | key_share | YES (2) | YES | 73 | pre_shared_key | no | YES | 74 | psk_key_exchange_modes | no | YES | 75 | early_data | no | YES | 76 | cookie | no | YES | 77 | supported_versions | YES (3) | YES | 78 | certificate_authorities | no | no | 79 | post_handshake_auth | no | no | 80 | signature_algorithms_cert | no | no | 81 82 (1) This is just for comparison. 83 84 (2) The MVP sends only one shared secret corresponding to the configured 85 preferred group. This could end up with connection failure if the 86 server does not support our preferred curve, as the MVP does not implement 87 HelloRetryRequest. The preferred group is the group of the first curve in 88 the list of allowed curves as defined by the configuration. The allowed 89 curves are by default ordered as follows: `x25519`, `secp256r1`, 90 `secp384r1` and finally `secp521r1`. Note that, in the absence of an 91 application profile standard specifying otherwise, section 9.1 of the 92 specification rather promotes curve `secp256r1` to be supported over 93 curve `x25519`. The MVP would, however, rather keep the preference order 94 currently promoted by Mbed TLS as this applies to TLS 1.2 as well, and 95 changing the order only for TLS1.3 would be potentially difficult. 96 In the unlikely event a server does not support curve `x25519` but does 97 support curve `secp256r1`, curve `secp256r1` can be set as the preferred 98 curve through the `mbedtls_ssl_conf_curves()` API. 99 100 (3) The MVP proposes only TLS 1.3 and does not support version negotiation. 101 Out-of-protocol fallback is supported though if the Mbed TLS library 102 has been built to support both TLS 1.3 and TLS 1.2: just set the 103 maximum of the minor version of the SSL configuration to 104 MBEDTLS_SSL_MINOR_VERSION_3 (`mbedtls_ssl_conf_min_version()` API) and 105 re-initiate a server handshake. 106 107- Supported groups: depends on the library configuration. 108 Potentially all ECDHE groups but x448: 109 secp256r1, x25519, secp384r1 and secp521r1. 110 111 Finite field groups (DHE) are not supported. 112 113- Supported signature algorithms (both for certificates and CertificateVerify): 114 depends on the library configuration. 115 Potentially: 116 rsa_pkcs1_sha256, rsa_pss_rsae_sha256, ecdsa_secp256r1_sha256, 117 ecdsa_secp384r1_sha384 and ecdsa_secp521r1_sha512. 118 119 Note that in absence of an application profile standard specifying otherwise 120 the three first ones in the list above are mandatory (see section 9.1 of the 121 specification). 122 123- Supported versions: only TLS 1.3, version negotiation is not supported. 124 125- Compatibility with existing SSL/TLS build options: 126 127 The TLS 1.3 MVP is compatible with all TLS 1.2 configuration options in the 128 sense that when enabling the TLS 1.3 MVP in the library there is no need to 129 modify the configuration for TLS 1.2. Mbed TLS SSL/TLS related features are 130 not supported or not applicable to the TLS 1.3 MVP: 131 132 | Mbed TLS configuration option | Support | 133 | ---------------------------------------- | ------- | 134 | MBEDTLS_SSL_ALL_ALERT_MESSAGES | no | 135 | MBEDTLS_SSL_ASYNC_PRIVATE | no | 136 | MBEDTLS_SSL_CONTEXT_SERIALIZATION | no | 137 | MBEDTLS_SSL_DEBUG_ALL | no | 138 | MBEDTLS_SSL_ENCRYPT_THEN_MAC | n/a | 139 | MBEDTLS_SSL_EXTENDED_MASTER_SECRET | n/a | 140 | MBEDTLS_SSL_KEEP_PEER_CERTIFICATE | no | 141 | MBEDTLS_SSL_RENEGOTIATION | n/a | 142 | MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no | 143 | | | 144 | MBEDTLS_SSL_SESSION_TICKETS | no | 145 | MBEDTLS_SSL_EXPORT_KEYS | no (1) | 146 | MBEDTLS_SSL_SERVER_NAME_INDICATION | no | 147 | MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH | no | 148 | | | 149 | MBEDTLS_ECP_RESTARTABLE | no | 150 | MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED | no | 151 | | | 152 | MBEDTLS_KEY_EXCHANGE_PSK_ENABLED | n/a (2) | 153 | MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED | n/a | 154 | MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a | 155 | MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED | n/a | 156 | MBEDTLS_KEY_EXCHANGE_RSA_ENABLED | n/a | 157 | MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED | n/a | 158 | MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED | n/a | 159 | MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED | n/a | 160 | MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED | n/a | 161 | MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED | n/a | 162 | MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a | 163 | | | 164 | MBEDTLS_USE_PSA_CRYPTO | no | 165 166 (1) Some support has already been upstreamed but it is incomplete. 167 (2) Key exchange configuration options for TLS 1.3 will likely to be 168 organized around the notion of key exchange mode along the line 169 of the MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_NONE/PSK/PSK_EPHEMERAL/EPHEMERAL 170 runtime configuration macros. 171 172- Quality considerations 173 - Standard Mbed TLS review bar 174 - Interoperability testing with OpenSSL and GnuTLS. Test with all the 175 cipher suites and signature algorithms supported by OpenSSL/GnuTLS server. 176 - Negative testing against OpenSSL/GnuTLS servers with which the 177 handshake fails due to incompatibility with the capabilities of the 178 MVP: TLS 1.2 or 1.1 server, server sending an HelloRetryRequest message in 179 response to the MVP ClientHello, server sending a CertificateRequest 180 message ... 181 182 183Prototype upstreaming status 184---------------------------- 185 186The following summarizes which parts of the TLS 1.3 prototype remain to be 187upstreamed: 188 189- Ephemeral only handshake on client side: client authentication, 190 HelloRetryRequest support, version negotiation. 191 192- Ephemeral only handshake server side. 193 194- Pre-shared keys, session resumption and 0-RTT data (both client and server 195 side). 196 197- New TLS Message Processing Stack (MPS) 198 199 The TLS 1.3 prototype is developed alongside a rewrite of the TLS messaging layer, 200 encompassing low-level details such as record parsing, handshake reassembly, and 201 DTLS retransmission state machine. 202 203 MPS has the following components: 204 - Layer 1 (Datagram handling) 205 - Layer 2 (Record handling) 206 - Layer 3 (Message handling) 207 - Layer 4 (Retransmission State Machine) 208 - Reader (Abstracted pointer arithmetic and reassembly logic for incoming data) 209 - Writer (Abstracted pointer arithmetic and fragmentation logic for outgoing data) 210 211 Of those components, the following have been upstreamed 212 as part of `MBEDTLS_SSL_PROTO_TLS1_3`: 213 214 - Reader ([`library/mps_reader.h`](../../library/mps_reader.h)) 215 216 217Coding rules checklist for TLS 1.3 218---------------------------------- 219 220The following coding rules are aimed to be a checklist for TLS 1.3 upstreaming 221work to reduce review rounds and the number of comments in each round. They 222come along (do NOT replace) the project coding rules 223(https://tls.mbed.org/kb/development/mbedtls-coding-standards). They have been 224established and discussed following the review of #4882 that was the 225PR upstreaming the first part of TLS 1.3 ClientHello writing code. 226 227TLS 1.3 specific coding rules: 228 229 - TLS 1.3 specific C modules, headers, static functions names are prefixed 230 with `ssl_tls13_`. The same applies to structures and types that are 231 internal to C modules. 232 233 - TLS 1.3 specific exported functions, structures and types are 234 prefixed with `mbedtls_ssl_tls13_`. 235 236 - Use TLS1_3 in TLS 1.3 specific macros. 237 238 - The names of macros and variables related to a field or structure in the 239 TLS 1.3 specification should contain as far as possible the field name as 240 it is in the specification. If the field name is "too long" and we prefer 241 to introduce some kind of abbreviation of it, use the same abbreviation 242 everywhere in the code. 243 244 Example 1: #define CLIENT_HELLO_RANDOM_LEN 32, macro for the length of the 245 `random` field of the ClientHello message. 246 247 Example 2 (consistent abbreviation): `mbedtls_ssl_tls13_write_sig_alg_ext()` 248 and `MBEDTLS_TLS_EXT_SIG_ALG`, `sig_alg` standing for 249 `signature_algorithms`. 250 251 - Regarding vectors that are represented by a length followed by their value 252 in the data exchanged between servers and clients: 253 254 - Use `<vector name>_len` for the name of a variable used to compute the 255 length in bytes of the vector, where <vector name> is the name of the 256 vector as defined in the TLS 1.3 specification. 257 258 - Use `p_<vector_name>_len` for the name of a variable intended to hold 259 the address of the first byte of the vector length. 260 261 - Use `<vector_name>` for the name of a variable intended to hold the 262 address of the first byte of the vector value. 263 264 - Use `<vector_name>_end` for the name of a variable intended to hold 265 the address of the first byte past the vector value. 266 267 Those idioms should lower the risk of mis-using one of the address in place 268 of another one which could potentially lead to some nasty issues. 269 270 Example: `cipher_suites` vector of ClientHello in 271 `ssl_tls13_write_client_hello_cipher_suites()` 272 ``` 273 size_t cipher_suites_len; 274 unsigned char *p_cipher_suites_len; 275 unsigned char *cipher_suites; 276 ``` 277 278 - Where applicable, use: 279 - the macros to extract a byte from a multi-byte integer MBEDTLS_BYTE_{0-8}. 280 - the macros to write in memory in big-endian order a multi-byte integer 281 MBEDTLS_PUT_UINT{8|16|32|64}_BE. 282 - the macros to read from memory a multi-byte integer in big-endian order 283 MBEDTLS_GET_UINT{8|16|32|64}_BE. 284 - the macro to check for space when writing into an output buffer 285 `MBEDTLS_SSL_CHK_BUF_PTR`. 286 - the macro to check for data when reading from an input buffer 287 `MBEDTLS_SSL_CHK_BUF_READ_PTR`. 288 289 These macros were introduced after the prototype was written thus are 290 likely not to be used in prototype where we now would use them in 291 development. 292 293 The three first types, MBEDTLS_BYTE_{0-8}, MBEDTLS_PUT_UINT{8|16|32|64}_BE 294 and MBEDTLS_GET_UINT{8|16|32|64}_BE improve the readability of the code and 295 reduce the risk of writing or reading bytes in the wrong order. 296 297 The two last types, `MBEDTLS_SSL_CHK_BUF_PTR` and 298 `MBEDTLS_SSL_CHK_BUF_READ_PTR`, improve the readability of the code and 299 reduce the risk of error in the non-completely-trivial arithmetic to 300 check that we do not write or read past the end of a data buffer. The 301 usage of those macros combined with the following rule mitigate the risk 302 to read/write past the end of a data buffer. 303 304 Examples: 305 ``` 306 hs_hdr[1] = MBEDTLS_BYTE_2( total_hs_len ); 307 MBEDTLS_PUT_UINT16_BE( MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS, p, 0 ); 308 MBEDTLS_SSL_CHK_BUF_PTR( p, end, 7 ); 309 ``` 310 311 - To mitigate what happened here 312 (https://github.com/ARMmbed/mbedtls/pull/4882#discussion_r701704527) from 313 happening again, use always a local variable named `p` for the reading 314 pointer in functions parsing TLS 1.3 data, and for the writing pointer in 315 functions writing data into an output buffer and only that variable. The 316 name `p` has been chosen as it was already widely used in TLS code. 317 318 - When an TLS 1.3 structure is written or read by a function or as part of 319 a function, provide as documentation the definition of the structure as 320 it is in the TLS 1.3 specification. 321 322General coding rules: 323 324 - We prefer grouping "related statement lines" by not adding blank lines 325 between them. 326 327 Example 1: 328 ``` 329 ret = ssl_tls13_write_client_hello_cipher_suites( ssl, buf, end, &output_len ); 330 if( ret != 0 ) 331 return( ret ); 332 buf += output_len; 333 ``` 334 335 Example 2: 336 ``` 337 MBEDTLS_SSL_CHK_BUF_PTR( cipher_suites_iter, end, 2 ); 338 MBEDTLS_PUT_UINT16_BE( cipher_suite, cipher_suites_iter, 0 ); 339 cipher_suites_iter += 2; 340 ``` 341 342 - Use macros for constants that are used in different functions, different 343 places in the code. When a constant is used only locally in a function 344 (like the length in bytes of the vector lengths in functions reading and 345 writing TLS handshake message) there is no need to define a macro for it. 346 347 Example: `#define CLIENT_HELLO_RANDOM_LEN 32` 348 349 - When declaring a pointer the dereferencing operator should be prepended to 350 the pointer name not appended to the pointer type: 351 352 Example: `mbedtls_ssl_context *ssl;` 353 354 - Maximum line length is 80 characters. 355 356 Exceptions: 357 358 - string literals can extend beyond 80 characters as we do not want to 359 split them to ease their search in the code base. 360 361 - A line can be more than 80 characters by a few characters if just looking 362 at the 80 first characters is enough to fully understand the line. For 363 example it is generally fine if some closure characters like ";" or ")" 364 are beyond the 80 characters limit. 365 366 If a line becomes too long due to a refactoring (for example renaming a 367 function to a longer name, or indenting a block more), avoid rewrapping 368 lines in the same commit: it makes the review harder. Make one commit with 369 the longer lines and another commit with just the rewrapping. 370 371 - When in successive lines, functions and macros parameters should be aligned 372 vertically. 373 374 Example: 375 ``` 376 int mbedtls_ssl_tls13_start_handshake_msg( mbedtls_ssl_context *ssl, 377 unsigned hs_type, 378 unsigned char **buf, 379 size_t *buf_len ); 380 ``` 381 382 - When a function's parameters span several lines, group related parameters 383 together if possible. 384 385 For example, prefer: 386 387 ``` 388 mbedtls_ssl_tls13_start_handshake_msg( ssl, hs_type, 389 buf, buf_len ); 390 ``` 391 over 392 ``` 393 mbedtls_ssl_tls13_start_handshake_msg( ssl, hs_type, buf, 394 buf_len ); 395 ``` 396 even if it fits. 397