1TLS 1.3 support 2=============== 3 4Overview 5-------- 6 7Mbed TLS provides an implementation of the TLS 1.3 protocol. The TLS 1.3 support 8may be enabled using the MBEDTLS_SSL_PROTO_TLS1_3 configuration option. 9 10Support description 11------------------- 12 13- Overview 14 15 - Mbed TLS implements both the client and the server side of the TLS 1.3 16 protocol. 17 18 - Mbed TLS supports ECDHE key establishment. 19 20 - Mbed TLS supports DHE key establishment. 21 22 - Mbed TLS supports pre-shared keys for key establishment, pre-shared keys 23 provisioned externally as well as provisioned via the ticket mechanism. 24 25 - Mbed TLS supports session resumption via the ticket mechanism. 26 27 - Mbed TLS supports sending and receiving early data (0-RTT data). 28 29- Supported cipher suites: depends on the library configuration. Potentially 30 all of them: 31 TLS_AES_128_GCM_SHA256, TLS_AES_256_GCM_SHA384, TLS_CHACHA20_POLY1305_SHA256, 32 TLS_AES_128_CCM_SHA256 and TLS_AES_128_CCM_8_SHA256. 33 34- Supported ClientHello extensions: 35 36 | Extension | Support | 37 | ---------------------------- | ------- | 38 | server_name | YES | 39 | max_fragment_length | no | 40 | status_request | no | 41 | supported_groups | YES | 42 | signature_algorithms | YES | 43 | use_srtp | no | 44 | heartbeat | no | 45 | alpn | YES | 46 | signed_certificate_timestamp | no | 47 | client_certificate_type | no | 48 | server_certificate_type | no | 49 | padding | no | 50 | key_share | YES | 51 | pre_shared_key | YES | 52 | psk_key_exchange_modes | YES | 53 | early_data | YES | 54 | cookie | no | 55 | supported_versions | YES | 56 | certificate_authorities | no | 57 | post_handshake_auth | no | 58 | signature_algorithms_cert | no | 59 60 61- Supported groups: depends on the library configuration. 62 Potentially all ECDHE groups: 63 secp256r1, x25519, secp384r1, x448 and secp521r1. 64 65 Potentially all DHE groups: 66 ffdhe2048, ffdhe3072, ffdhe4096, ffdhe6144 and ffdhe8192. 67 68- Supported signature algorithms (both for certificates and CertificateVerify): 69 depends on the library configuration. 70 Potentially: 71 ecdsa_secp256r1_sha256, ecdsa_secp384r1_sha384, ecdsa_secp521r1_sha512, 72 rsa_pkcs1_sha256, rsa_pkcs1_sha384, rsa_pkcs1_sha512, rsa_pss_rsae_sha256, 73 rsa_pss_rsae_sha384 and rsa_pss_rsae_sha512. 74 75 Note that in absence of an application profile standard specifying otherwise 76 rsa_pkcs1_sha256, rsa_pss_rsae_sha256 and ecdsa_secp256r1_sha256 are 77 mandatory (see section 9.1 of the specification). 78 79- Supported versions: 80 81 - TLS 1.2 and TLS 1.3 with version negotiation on client and server side. 82 83 - TLS 1.2 and TLS 1.3 can be enabled in the build independently of each 84 other. 85 86- Compatibility with existing SSL/TLS build options: 87 88 The TLS 1.3 implementation is compatible with nearly all TLS 1.2 89 configuration options in the sense that when enabling TLS 1.3 in the library 90 there is rarely any need to modify the configuration from that used for 91 TLS 1.2. There are two exceptions though: the TLS 1.3 implementation requires 92 MBEDTLS_PSA_CRYPTO_C and MBEDTLS_SSL_KEEP_PEER_CERTIFICATE, so these options 93 must be enabled. 94 95 Most of the Mbed TLS SSL/TLS related options are not supported or not 96 applicable to the TLS 1.3 implementation: 97 98 | Mbed TLS configuration option | Support | 99 | ---------------------------------------- | ------- | 100 | MBEDTLS_SSL_ALL_ALERT_MESSAGES | yes | 101 | MBEDTLS_SSL_ASYNC_PRIVATE | no | 102 | MBEDTLS_SSL_CONTEXT_SERIALIZATION | no | 103 | MBEDTLS_SSL_DEBUG_ALL | no | 104 | MBEDTLS_SSL_ENCRYPT_THEN_MAC | n/a | 105 | MBEDTLS_SSL_EXTENDED_MASTER_SECRET | n/a | 106 | MBEDTLS_SSL_KEEP_PEER_CERTIFICATE | no (1) | 107 | MBEDTLS_SSL_RENEGOTIATION | n/a | 108 | MBEDTLS_SSL_MAX_FRAGMENT_LENGTH | no | 109 | | | 110 | MBEDTLS_SSL_SESSION_TICKETS | yes | 111 | MBEDTLS_SSL_SERVER_NAME_INDICATION | yes | 112 | MBEDTLS_SSL_VARIABLE_BUFFER_LENGTH | no | 113 | | | 114 | MBEDTLS_ECP_RESTARTABLE | no | 115 | MBEDTLS_ECDH_VARIANT_EVEREST_ENABLED | no | 116 | | | 117 | MBEDTLS_KEY_EXCHANGE_PSK_ENABLED | n/a (2) | 118 | MBEDTLS_KEY_EXCHANGE_DHE_PSK_ENABLED | n/a | 119 | MBEDTLS_KEY_EXCHANGE_ECDHE_PSK_ENABLED | n/a | 120 | MBEDTLS_KEY_EXCHANGE_RSA_PSK_ENABLED | n/a | 121 | MBEDTLS_KEY_EXCHANGE_RSA_ENABLED | n/a | 122 | MBEDTLS_KEY_EXCHANGE_DHE_RSA_ENABLED | n/a | 123 | MBEDTLS_KEY_EXCHANGE_ECDHE_RSA_ENABLED | n/a | 124 | MBEDTLS_KEY_EXCHANGE_ECDHE_ECDSA_ENABLED | n/a | 125 | MBEDTLS_KEY_EXCHANGE_ECDH_ECDSA_ENABLED | n/a | 126 | MBEDTLS_KEY_EXCHANGE_ECDH_RSA_ENABLED | n/a | 127 | MBEDTLS_KEY_EXCHANGE_ECJPAKE_ENABLED | n/a | 128 | | | 129 | MBEDTLS_PSA_CRYPTO_C | no (1) | 130 | MBEDTLS_USE_PSA_CRYPTO | yes | 131 132 (1) These options must remain in their default state of enabled. 133 (2) See the TLS 1.3 specific build options section below. 134 135- TLS 1.3 specific build options: 136 137 - MBEDTLS_SSL_TLS1_3_COMPATIBILITY_MODE enables the support for middlebox 138 compatibility mode as defined in section D.4 of RFC 8446. 139 140 - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_ENABLED enables the support for 141 the PSK key exchange mode as defined by RFC 8446. If it is the only key 142 exchange mode enabled, the TLS 1.3 implementation does not contain any code 143 related to key exchange protocols, certificates and signatures. 144 145 - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_EPHEMERAL_ENABLED enables the 146 support for the ephemeral key exchange mode. If it is the only key exchange 147 mode enabled, the TLS 1.3 implementation does not contain any code related 148 to PSK based key exchange. The ephemeral key exchange mode requires at least 149 one of the key exchange protocol allowed by the TLS 1.3 specification, the 150 parsing and validation of x509 certificates and at least one signature 151 algorithm allowed by the TLS 1.3 specification for signature computing and 152 verification. 153 154 - MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_PSK_EPHEMERAL_ENABLED enables the 155 support for the PSK ephemeral key exchange mode. If it is the only key 156 exchange mode enabled, the TLS 1.3 implementation does not contain any code 157 related to certificates and signatures. The PSK ephemeral key exchange 158 mode requires at least one of the key exchange protocol allowed by the 159 TLS 1.3 specification. 160 161 162Coding rules checklist for TLS 1.3 163---------------------------------- 164 165The following coding rules are aimed to be a checklist for TLS 1.3 upstreaming 166work to reduce review rounds and the number of comments in each round. They 167come along (do NOT replace) the project coding rules 168(https://mbed-tls.readthedocs.io/en/latest/kb/development/mbedtls-coding-standards). They have been 169established and discussed following the review of #4882 that was the 170PR upstreaming the first part of TLS 1.3 ClientHello writing code. 171 172TLS 1.3 specific coding rules: 173 174 - TLS 1.3 specific C modules, headers, static functions names are prefixed 175 with `ssl_tls13_`. The same applies to structures and types that are 176 internal to C modules. 177 178 - TLS 1.3 specific exported functions, structures and types are 179 prefixed with `mbedtls_ssl_tls13_`. 180 181 - Use TLS1_3 in TLS 1.3 specific macros. 182 183 - The names of macros and variables related to a field or structure in the 184 TLS 1.3 specification should contain as far as possible the field name as 185 it is in the specification. If the field name is "too long" and we prefer 186 to introduce some kind of abbreviation of it, use the same abbreviation 187 everywhere in the code. 188 189 Example 1: #define CLIENT_HELLO_RANDOM_LEN 32, macro for the length of the 190 `random` field of the ClientHello message. 191 192 Example 2 (consistent abbreviation): `mbedtls_ssl_tls13_write_sig_alg_ext()` 193 and `MBEDTLS_TLS_EXT_SIG_ALG`, `sig_alg` standing for 194 `signature_algorithms`. 195 196 - Regarding vectors that are represented by a length followed by their value 197 in the data exchanged between servers and clients: 198 199 - Use `<vector name>_len` for the name of a variable used to compute the 200 length in bytes of the vector, where <vector name> is the name of the 201 vector as defined in the TLS 1.3 specification. 202 203 - Use `p_<vector_name>_len` for the name of a variable intended to hold 204 the address of the first byte of the vector length. 205 206 - Use `<vector_name>` for the name of a variable intended to hold the 207 address of the first byte of the vector value. 208 209 - Use `<vector_name>_end` for the name of a variable intended to hold 210 the address of the first byte past the vector value. 211 212 Those idioms should lower the risk of mis-using one of the address in place 213 of another one which could potentially lead to some nasty issues. 214 215 Example: `cipher_suites` vector of ClientHello in 216 `ssl_tls13_write_client_hello_cipher_suites()` 217 ``` 218 size_t cipher_suites_len; 219 unsigned char *p_cipher_suites_len; 220 unsigned char *cipher_suites; 221 ``` 222 223 - Where applicable, use: 224 - the macros to extract a byte from a multi-byte integer MBEDTLS_BYTE_{0-8}. 225 - the macros to write in memory in big-endian order a multi-byte integer 226 MBEDTLS_PUT_UINT{8|16|32|64}_BE. 227 - the macros to read from memory a multi-byte integer in big-endian order 228 MBEDTLS_GET_UINT{8|16|32|64}_BE. 229 - the macro to check for space when writing into an output buffer 230 `MBEDTLS_SSL_CHK_BUF_PTR`. 231 - the macro to check for data when reading from an input buffer 232 `MBEDTLS_SSL_CHK_BUF_READ_PTR`. 233 234 The three first types, MBEDTLS_BYTE_{0-8}, MBEDTLS_PUT_UINT{8|16|32|64}_BE 235 and MBEDTLS_GET_UINT{8|16|32|64}_BE improve the readability of the code and 236 reduce the risk of writing or reading bytes in the wrong order. 237 238 The two last types, `MBEDTLS_SSL_CHK_BUF_PTR` and 239 `MBEDTLS_SSL_CHK_BUF_READ_PTR`, improve the readability of the code and 240 reduce the risk of error in the non-completely-trivial arithmetic to 241 check that we do not write or read past the end of a data buffer. The 242 usage of those macros combined with the following rule mitigate the risk 243 to read/write past the end of a data buffer. 244 245 Examples: 246 ``` 247 hs_hdr[1] = MBEDTLS_BYTE_2( total_hs_len ); 248 MBEDTLS_PUT_UINT16_BE( MBEDTLS_TLS_EXT_SUPPORTED_VERSIONS, p, 0 ); 249 MBEDTLS_SSL_CHK_BUF_PTR( p, end, 7 ); 250 ``` 251 252 - To mitigate what happened here 253 (https://github.com/Mbed-TLS/mbedtls/pull/4882#discussion_r701704527) from 254 happening again, use always a local variable named `p` for the reading 255 pointer in functions parsing TLS 1.3 data, and for the writing pointer in 256 functions writing data into an output buffer and only that variable. The 257 name `p` has been chosen as it was already widely used in TLS code. 258 259 - When an TLS 1.3 structure is written or read by a function or as part of 260 a function, provide as documentation the definition of the structure as 261 it is in the TLS 1.3 specification. 262 263General coding rules: 264 265 - We prefer grouping "related statement lines" by not adding blank lines 266 between them. 267 268 Example 1: 269 ``` 270 ret = ssl_tls13_write_client_hello_cipher_suites( ssl, buf, end, &output_len ); 271 if( ret != 0 ) 272 return( ret ); 273 buf += output_len; 274 ``` 275 276 Example 2: 277 ``` 278 MBEDTLS_SSL_CHK_BUF_PTR( cipher_suites_iter, end, 2 ); 279 MBEDTLS_PUT_UINT16_BE( cipher_suite, cipher_suites_iter, 0 ); 280 cipher_suites_iter += 2; 281 ``` 282 283 - Use macros for constants that are used in different functions, different 284 places in the code. When a constant is used only locally in a function 285 (like the length in bytes of the vector lengths in functions reading and 286 writing TLS handshake message) there is no need to define a macro for it. 287 288 Example: `#define CLIENT_HELLO_RANDOM_LEN 32` 289 290 - When declaring a pointer the dereferencing operator should be prepended to 291 the pointer name not appended to the pointer type: 292 293 Example: `mbedtls_ssl_context *ssl;` 294 295 - Maximum line length is 80 characters. 296 297 Exceptions: 298 299 - string literals can extend beyond 80 characters as we do not want to 300 split them to ease their search in the code base. 301 302 - A line can be more than 80 characters by a few characters if just looking 303 at the 80 first characters is enough to fully understand the line. For 304 example it is generally fine if some closure characters like ";" or ")" 305 are beyond the 80 characters limit. 306 307 If a line becomes too long due to a refactoring (for example renaming a 308 function to a longer name, or indenting a block more), avoid rewrapping 309 lines in the same commit: it makes the review harder. Make one commit with 310 the longer lines and another commit with just the rewrapping. 311 312 - When in successive lines, functions and macros parameters should be aligned 313 vertically. 314 315 Example: 316 ``` 317 int mbedtls_ssl_start_handshake_msg( mbedtls_ssl_context *ssl, 318 unsigned hs_type, 319 unsigned char **buf, 320 size_t *buf_len ); 321 ``` 322 323 - When a function's parameters span several lines, group related parameters 324 together if possible. 325 326 For example, prefer: 327 328 ``` 329 mbedtls_ssl_start_handshake_msg( ssl, hs_type, 330 buf, buf_len ); 331 ``` 332 over 333 ``` 334 mbedtls_ssl_start_handshake_msg( ssl, hs_type, buf, 335 buf_len ); 336 ``` 337 even if it fits. 338 339 340Overview of handshake code organization 341--------------------------------------- 342 343The TLS 1.3 handshake protocol is implemented as a state machine. The 344functions `mbedtls_ssl_tls13_handshake_{client,server}_step` are the top level 345functions of that implementation. They are implemented as a switch over all the 346possible states of the state machine. 347 348Most of the states are either dedicated to the processing or writing of an 349handshake message. 350 351The implementation does not go systematically through all states as this would 352result in too many checks of whether something needs to be done or not in a 353given state to be duplicated across several state handlers. For example, on 354client side, the states related to certificate parsing and validation are 355bypassed if the handshake is based on a pre-shared key and thus does not 356involve certificates. 357 358On the contrary, the implementation goes systematically though some states 359even if they could be bypassed if it helps in minimizing when and where inbound 360and outbound keys are updated. The `MBEDTLS_SSL_CLIENT_CERTIFICATE` state on 361client side is a example of that. 362 363The names of the handlers processing/writing an handshake message are 364prefixed with `(mbedtls_)ssl_tls13_{process,write}`. To ease the maintenance and 365reduce the risk of bugs, the code of the message processing and writing 366handlers is split into a sequence of stages. 367 368The sending of data to the peer only occurs in `mbedtls_ssl_handshake_step` 369between the calls to the handlers and as a consequence handlers do not have to 370care about the MBEDTLS_ERR_SSL_WANT_WRITE error code. Furthermore, all pending 371data are flushed before to call the next handler. That way, handlers do not 372have to worry about pending data when changing outbound keys. 373 374### Message processing handlers 375For message processing handlers, the stages are: 376 377* coordination stage: check if the state should be bypassed. This stage is 378optional. The check is either purely based on the reading of the value of some 379fields of the SSL context or based on the reading of the type of the next 380message. The latter occurs when it is not known what the next handshake message 381will be, an example of that on client side being if we are going to receive a 382CertificateRequest message or not. The intent is, apart from the next record 383reading to not modify the SSL context as this stage may be repeated if the 384next handshake message has not been received yet. 385 386* fetching stage: at this stage we are sure of the type of the handshake 387message we must receive next and we try to fetch it. If we did not go through 388a coordination stage involving the next record type reading, the next 389handshake message may not have been received yet, the handler returns with 390`MBEDTLS_ERR_SSL_WANT_READ` without changing the current state and it will be 391called again later. 392 393* pre-processing stage: prepare the SSL context for the message parsing. This 394stage is optional. Any processing that must be done before the parsing of the 395message or that can be done to simplify the parsing code. Some simple and 396partial parsing of the handshake message may append at that stage like in the 397ServerHello message pre-processing. 398 399* parsing stage: parse the message and restrict as much as possible any 400update of the SSL context. The idea of the pre-processing/parsing/post-processing 401organization is to concentrate solely on the parsing in the parsing function to 402reduce the size of its code and to simplify it. 403 404* post-processing stage: following the parsing, further update of the SSL 405context to prepare for the next incoming and outgoing messages. This stage is 406optional. For example, secret and key computations occur at this stage, as well 407as handshake messages checksum update. 408 409* state change: the state change is done in the main state handler to ease the 410navigation of the state machine transitions. 411 412 413### Message writing handlers 414For message writing handlers, the stages are: 415 416* coordination stage: check if the state should be bypassed. This stage is 417optional. The check is based on the value of some fields of the SSL context. 418 419* preparation stage: prepare for the message writing. This stage is optional. 420Any processing that must be done before the writing of the message or that can 421be done to simplify the writing code. 422 423* writing stage: write the message and restrict as much as possible any update 424of the SSL context. The idea of the preparation/writing/finalization 425organization is to concentrate solely on the writing in the writing function to 426reduce the size of its code and simplify it. 427 428* finalization stage: following the writing, further update of the SSL 429context to prepare for the next incoming and outgoing messages. This stage is 430optional. For example, handshake secret and key computation occur at that 431stage (ServerHello writing finalization), switching to handshake keys for 432outbound message on server side as well. 433 434* state change: the state change is done in the main state handler to ease 435the navigation of the state machine transitions. 436
