1 /* 2 * TLS 1.3 key schedule 3 * 4 * Copyright The Mbed TLS Contributors 5 * SPDX-License-Identifier: Apache-2.0 6 * 7 * Licensed under the Apache License, Version 2.0 ( the "License" ); you may 8 * not use this file except in compliance with the License. 9 * You may obtain a copy of the License at 10 * 11 * http://www.apache.org/licenses/LICENSE-2.0 12 * 13 * Unless required by applicable law or agreed to in writing, software 14 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 15 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 16 * See the License for the specific language governing permissions and 17 * limitations under the License. 18 */ 19 #if !defined(MBEDTLS_SSL_TLS1_3_KEYS_H) 20 #define MBEDTLS_SSL_TLS1_3_KEYS_H 21 22 /* This requires MBEDTLS_SSL_TLS1_3_LABEL( idx, name, string ) to be defined at 23 * the point of use. See e.g. the definition of mbedtls_ssl_tls13_labels_union 24 * below. */ 25 #define MBEDTLS_SSL_TLS1_3_LABEL_LIST \ 26 MBEDTLS_SSL_TLS1_3_LABEL( finished , "finished" ) \ 27 MBEDTLS_SSL_TLS1_3_LABEL( resumption , "resumption" ) \ 28 MBEDTLS_SSL_TLS1_3_LABEL( traffic_upd , "traffic upd" ) \ 29 MBEDTLS_SSL_TLS1_3_LABEL( exporter , "exporter" ) \ 30 MBEDTLS_SSL_TLS1_3_LABEL( key , "key" ) \ 31 MBEDTLS_SSL_TLS1_3_LABEL( iv , "iv" ) \ 32 MBEDTLS_SSL_TLS1_3_LABEL( c_hs_traffic, "c hs traffic" ) \ 33 MBEDTLS_SSL_TLS1_3_LABEL( c_ap_traffic, "c ap traffic" ) \ 34 MBEDTLS_SSL_TLS1_3_LABEL( c_e_traffic , "c e traffic" ) \ 35 MBEDTLS_SSL_TLS1_3_LABEL( s_hs_traffic, "s hs traffic" ) \ 36 MBEDTLS_SSL_TLS1_3_LABEL( s_ap_traffic, "s ap traffic" ) \ 37 MBEDTLS_SSL_TLS1_3_LABEL( s_e_traffic , "s e traffic" ) \ 38 MBEDTLS_SSL_TLS1_3_LABEL( e_exp_master, "e exp master" ) \ 39 MBEDTLS_SSL_TLS1_3_LABEL( res_master , "res master" ) \ 40 MBEDTLS_SSL_TLS1_3_LABEL( exp_master , "exp master" ) \ 41 MBEDTLS_SSL_TLS1_3_LABEL( ext_binder , "ext binder" ) \ 42 MBEDTLS_SSL_TLS1_3_LABEL( res_binder , "res binder" ) \ 43 MBEDTLS_SSL_TLS1_3_LABEL( derived , "derived" ) \ 44 MBEDTLS_SSL_TLS1_3_LABEL( client_cv , "TLS 1.3, client CertificateVerify" ) \ 45 MBEDTLS_SSL_TLS1_3_LABEL( server_cv , "TLS 1.3, server CertificateVerify" ) 46 47 #define MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED 0 48 #define MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED 1 49 50 #define MBEDTLS_SSL_TLS1_3_PSK_EXTERNAL 0 51 #define MBEDTLS_SSL_TLS1_3_PSK_RESUMPTION 1 52 53 #if defined(MBEDTLS_SSL_PROTO_TLS1_3) 54 55 #define MBEDTLS_SSL_TLS1_3_LABEL( name, string ) \ 56 const unsigned char name [ sizeof(string) - 1 ]; 57 58 union mbedtls_ssl_tls13_labels_union 59 { 60 MBEDTLS_SSL_TLS1_3_LABEL_LIST 61 }; 62 struct mbedtls_ssl_tls13_labels_struct 63 { 64 MBEDTLS_SSL_TLS1_3_LABEL_LIST 65 }; 66 #undef MBEDTLS_SSL_TLS1_3_LABEL 67 68 extern const struct mbedtls_ssl_tls13_labels_struct mbedtls_ssl_tls13_labels; 69 70 #define MBEDTLS_SSL_TLS1_3_LBL_LEN( LABEL ) \ 71 sizeof(mbedtls_ssl_tls13_labels.LABEL) 72 73 #define MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( LABEL ) \ 74 mbedtls_ssl_tls13_labels.LABEL, \ 75 MBEDTLS_SSL_TLS1_3_LBL_LEN( LABEL ) 76 77 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN \ 78 sizeof( union mbedtls_ssl_tls13_labels_union ) 79 80 /* The maximum length of HKDF contexts used in the TLS 1.3 standard. 81 * Since contexts are always hashes of message transcripts, this can 82 * be approximated from above by the maximum hash size. */ 83 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN \ 84 PSA_HASH_MAX_SIZE 85 86 /* Maximum desired length for expanded key material generated 87 * by HKDF-Expand-Label. 88 * 89 * Warning: If this ever needs to be increased, the implementation 90 * ssl_tls13_hkdf_encode_label() in ssl_tls13_keys.c needs to be 91 * adjusted since it currently assumes that HKDF key expansion 92 * is never used with more than 255 Bytes of output. */ 93 #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN 255 94 95 /** 96 * \brief The \c HKDF-Expand-Label function from 97 * the TLS 1.3 standard RFC 8446. 98 * 99 * <tt> 100 * HKDF-Expand-Label( Secret, Label, Context, Length ) = 101 * HKDF-Expand( Secret, HkdfLabel, Length ) 102 * </tt> 103 * 104 * \param hash_alg The identifier for the hash algorithm to use. 105 * \param secret The \c Secret argument to \c HKDF-Expand-Label. 106 * This must be a readable buffer of length 107 * \p secret_len Bytes. 108 * \param secret_len The length of \p secret in Bytes. 109 * \param label The \c Label argument to \c HKDF-Expand-Label. 110 * This must be a readable buffer of length 111 * \p label_len Bytes. 112 * \param label_len The length of \p label in Bytes. 113 * \param ctx The \c Context argument to \c HKDF-Expand-Label. 114 * This must be a readable buffer of length \p ctx_len Bytes. 115 * \param ctx_len The length of \p context in Bytes. 116 * \param buf The destination buffer to hold the expanded secret. 117 * This must be a writable buffer of length \p buf_len Bytes. 118 * \param buf_len The desired size of the expanded secret in Bytes. 119 * 120 * \returns \c 0 on success. 121 * \return A negative error code on failure. 122 */ 123 124 MBEDTLS_CHECK_RETURN_CRITICAL 125 int mbedtls_ssl_tls13_hkdf_expand_label( 126 psa_algorithm_t hash_alg, 127 const unsigned char *secret, size_t secret_len, 128 const unsigned char *label, size_t label_len, 129 const unsigned char *ctx, size_t ctx_len, 130 unsigned char *buf, size_t buf_len ); 131 132 /** 133 * \brief This function is part of the TLS 1.3 key schedule. 134 * It extracts key and IV for the actual client/server traffic 135 * from the client/server traffic secrets. 136 * 137 * From RFC 8446: 138 * 139 * <tt> 140 * [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) 141 * [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)* 142 * </tt> 143 * 144 * \param hash_alg The identifier for the hash algorithm to be used 145 * for the HKDF-based expansion of the secret. 146 * \param client_secret The client traffic secret. 147 * This must be a readable buffer of size 148 * \p secret_len Bytes 149 * \param server_secret The server traffic secret. 150 * This must be a readable buffer of size 151 * \p secret_len Bytes 152 * \param secret_len Length of the secrets \p client_secret and 153 * \p server_secret in Bytes. 154 * \param key_len The desired length of the key to be extracted in Bytes. 155 * \param iv_len The desired length of the IV to be extracted in Bytes. 156 * \param keys The address of the structure holding the generated 157 * keys and IVs. 158 * 159 * \returns \c 0 on success. 160 * \returns A negative error code on failure. 161 */ 162 163 MBEDTLS_CHECK_RETURN_CRITICAL 164 int mbedtls_ssl_tls13_make_traffic_keys( 165 psa_algorithm_t hash_alg, 166 const unsigned char *client_secret, 167 const unsigned char *server_secret, size_t secret_len, 168 size_t key_len, size_t iv_len, 169 mbedtls_ssl_key_set *keys ); 170 171 /** 172 * \brief The \c Derive-Secret function from the TLS 1.3 standard RFC 8446. 173 * 174 * <tt> 175 * Derive-Secret( Secret, Label, Messages ) = 176 * HKDF-Expand-Label( Secret, Label, 177 * Hash( Messages ), 178 * Hash.Length ) ) 179 * </tt> 180 * 181 * \param hash_alg The identifier for the hash function used for the 182 * applications of HKDF. 183 * \param secret The \c Secret argument to the \c Derive-Secret function. 184 * This must be a readable buffer of length 185 * \p secret_len Bytes. 186 * \param secret_len The length of \p secret in Bytes. 187 * \param label The \c Label argument to the \c Derive-Secret function. 188 * This must be a readable buffer of length 189 * \p label_len Bytes. 190 * \param label_len The length of \p label in Bytes. 191 * \param ctx The hash of the \c Messages argument to the 192 * \c Derive-Secret function, or the \c Messages argument 193 * itself, depending on \p ctx_hashed. 194 * \param ctx_len The length of \p ctx in Bytes. 195 * \param ctx_hashed This indicates whether the \p ctx contains the hash of 196 * the \c Messages argument in the application of the 197 * \c Derive-Secret function 198 * (value MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED), or whether 199 * it is the content of \c Messages itself, in which case 200 * the function takes care of the hashing 201 * (value MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED). 202 * \param dstbuf The target buffer to write the output of 203 * \c Derive-Secret to. This must be a writable buffer of 204 * size \p dtsbuf_len Bytes. 205 * \param dstbuf_len The length of \p dstbuf in Bytes. 206 * 207 * \returns \c 0 on success. 208 * \returns A negative error code on failure. 209 */ 210 MBEDTLS_CHECK_RETURN_CRITICAL 211 int mbedtls_ssl_tls13_derive_secret( 212 psa_algorithm_t hash_alg, 213 const unsigned char *secret, size_t secret_len, 214 const unsigned char *label, size_t label_len, 215 const unsigned char *ctx, size_t ctx_len, 216 int ctx_hashed, 217 unsigned char *dstbuf, size_t dstbuf_len ); 218 219 /** 220 * \brief Derive TLS 1.3 early data key material from early secret. 221 * 222 * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() 223 * with the appropriate labels. 224 * 225 * <tt> 226 * Early Secret 227 * | 228 * +-----> Derive-Secret(., "c e traffic", ClientHello) 229 * | = client_early_traffic_secret 230 * | 231 * +-----> Derive-Secret(., "e exp master", ClientHello) 232 * . = early_exporter_master_secret 233 * . 234 * . 235 * </tt> 236 * 237 * \note To obtain the actual key and IV for the early data traffic, 238 * the client secret derived by this function need to be 239 * further processed by mbedtls_ssl_tls13_make_traffic_keys(). 240 * 241 * \note The binder key, which is also generated from the early secret, 242 * is omitted here. Its calculation is part of the separate routine 243 * mbedtls_ssl_tls13_create_psk_binder(). 244 * 245 * \param hash_alg The hash algorithm associated with the PSK for which 246 * early data key material is being derived. 247 * \param early_secret The early secret from which the early data key material 248 * should be derived. This must be a readable buffer whose 249 * length is the digest size of the hash algorithm 250 * represented by \p md_size. 251 * \param transcript The transcript of the handshake so far, calculated with 252 * respect to \p hash_alg. This must be a readable buffer 253 * whose length is the digest size of the hash algorithm 254 * represented by \p md_size. 255 * \param derived The address of the structure in which to store 256 * the early data key material. 257 * 258 * \returns \c 0 on success. 259 * \returns A negative error code on failure. 260 */ 261 MBEDTLS_CHECK_RETURN_CRITICAL 262 int mbedtls_ssl_tls13_derive_early_secrets( 263 psa_algorithm_t hash_alg, 264 unsigned char const *early_secret, 265 unsigned char const *transcript, size_t transcript_len, 266 mbedtls_ssl_tls13_early_secrets *derived ); 267 268 /** 269 * \brief Derive TLS 1.3 handshake key material from the handshake secret. 270 * 271 * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() 272 * with the appropriate labels from the standard. 273 * 274 * <tt> 275 * Handshake Secret 276 * | 277 * +-----> Derive-Secret( ., "c hs traffic", 278 * | ClientHello...ServerHello ) 279 * | = client_handshake_traffic_secret 280 * | 281 * +-----> Derive-Secret( ., "s hs traffic", 282 * . ClientHello...ServerHello ) 283 * . = server_handshake_traffic_secret 284 * . 285 * </tt> 286 * 287 * \note To obtain the actual key and IV for the encrypted handshake traffic, 288 * the client and server secret derived by this function need to be 289 * further processed by mbedtls_ssl_tls13_make_traffic_keys(). 290 * 291 * \param hash_alg The hash algorithm associated with the ciphersuite 292 * that's being used for the connection. 293 * \param handshake_secret The handshake secret from which the handshake key 294 * material should be derived. This must be a readable 295 * buffer whose length is the digest size of the hash 296 * algorithm represented by \p md_size. 297 * \param transcript The transcript of the handshake so far, calculated 298 * with respect to \p hash_alg. This must be a readable 299 * buffer whose length is the digest size of the hash 300 * algorithm represented by \p md_size. 301 * \param derived The address of the structure in which to 302 * store the handshake key material. 303 * 304 * \returns \c 0 on success. 305 * \returns A negative error code on failure. 306 */ 307 MBEDTLS_CHECK_RETURN_CRITICAL 308 int mbedtls_ssl_tls13_derive_handshake_secrets( 309 psa_algorithm_t hash_alg, 310 unsigned char const *handshake_secret, 311 unsigned char const *transcript, size_t transcript_len, 312 mbedtls_ssl_tls13_handshake_secrets *derived ); 313 314 /** 315 * \brief Derive TLS 1.3 application key material from the master secret. 316 * 317 * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() 318 * with the appropriate labels from the standard. 319 * 320 * <tt> 321 * Master Secret 322 * | 323 * +-----> Derive-Secret( ., "c ap traffic", 324 * | ClientHello...server Finished ) 325 * | = client_application_traffic_secret_0 326 * | 327 * +-----> Derive-Secret( ., "s ap traffic", 328 * | ClientHello...Server Finished ) 329 * | = server_application_traffic_secret_0 330 * | 331 * +-----> Derive-Secret( ., "exp master", 332 * . ClientHello...server Finished) 333 * . = exporter_master_secret 334 * . 335 * </tt> 336 * 337 * \note To obtain the actual key and IV for the (0-th) application traffic, 338 * the client and server secret derived by this function need to be 339 * further processed by mbedtls_ssl_tls13_make_traffic_keys(). 340 * 341 * \param hash_alg The hash algorithm associated with the ciphersuite 342 * that's being used for the connection. 343 * \param master_secret The master secret from which the application key 344 * material should be derived. This must be a readable 345 * buffer whose length is the digest size of the hash 346 * algorithm represented by \p md_size. 347 * \param transcript The transcript of the handshake up to and including 348 * the ServerFinished message, calculated with respect 349 * to \p hash_alg. This must be a readable buffer whose 350 * length is the digest size of the hash algorithm 351 * represented by \p hash_alg. 352 * \param derived The address of the structure in which to 353 * store the application key material. 354 * 355 * \returns \c 0 on success. 356 * \returns A negative error code on failure. 357 */ 358 MBEDTLS_CHECK_RETURN_CRITICAL 359 int mbedtls_ssl_tls13_derive_application_secrets( 360 psa_algorithm_t hash_alg, 361 unsigned char const *master_secret, 362 unsigned char const *transcript, size_t transcript_len, 363 mbedtls_ssl_tls13_application_secrets *derived ); 364 365 /** 366 * \brief Derive TLS 1.3 resumption master secret from the master secret. 367 * 368 * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() 369 * with the appropriate labels from the standard. 370 * 371 * \param hash_alg The hash algorithm used in the application for which 372 * key material is being derived. 373 * \param application_secret The application secret from which the resumption master 374 * secret should be derived. This must be a readable 375 * buffer whose length is the digest size of the hash 376 * algorithm represented by \p md_size. 377 * \param transcript The transcript of the handshake up to and including 378 * the ClientFinished message, calculated with respect 379 * to \p hash_alg. This must be a readable buffer whose 380 * length is the digest size of the hash algorithm 381 * represented by \p hash_alg. 382 * \param transcript_len The length of \p transcript in Bytes. 383 * \param derived The address of the structure in which to 384 * store the resumption master secret. 385 * 386 * \returns \c 0 on success. 387 * \returns A negative error code on failure. 388 */ 389 MBEDTLS_CHECK_RETURN_CRITICAL 390 int mbedtls_ssl_tls13_derive_resumption_master_secret( 391 psa_algorithm_t hash_alg, 392 unsigned char const *application_secret, 393 unsigned char const *transcript, size_t transcript_len, 394 mbedtls_ssl_tls13_application_secrets *derived ); 395 396 /** 397 * \brief Compute the next secret in the TLS 1.3 key schedule 398 * 399 * The TLS 1.3 key schedule proceeds as follows to compute 400 * the three main secrets during the handshake: The early 401 * secret for early data, the handshake secret for all 402 * other encrypted handshake messages, and the master 403 * secret for all application traffic. 404 * 405 * <tt> 406 * 0 407 * | 408 * v 409 * PSK -> HKDF-Extract = Early Secret 410 * | 411 * v 412 * Derive-Secret( ., "derived", "" ) 413 * | 414 * v 415 * (EC)DHE -> HKDF-Extract = Handshake Secret 416 * | 417 * v 418 * Derive-Secret( ., "derived", "" ) 419 * | 420 * v 421 * 0 -> HKDF-Extract = Master Secret 422 * </tt> 423 * 424 * Each of the three secrets in turn is the basis for further 425 * key derivations, such as the derivation of traffic keys and IVs; 426 * see e.g. mbedtls_ssl_tls13_make_traffic_keys(). 427 * 428 * This function implements one step in this evolution of secrets: 429 * 430 * <tt> 431 * old_secret 432 * | 433 * v 434 * Derive-Secret( ., "derived", "" ) 435 * | 436 * v 437 * input -> HKDF-Extract = new_secret 438 * </tt> 439 * 440 * \param hash_alg The identifier for the hash function used for the 441 * applications of HKDF. 442 * \param secret_old The address of the buffer holding the old secret 443 * on function entry. If not \c NULL, this must be a 444 * readable buffer whose size matches the output size 445 * of the hash function represented by \p hash_alg. 446 * If \c NULL, an all \c 0 array will be used instead. 447 * \param input The address of the buffer holding the additional 448 * input for the key derivation (e.g., the PSK or the 449 * ephemeral (EC)DH secret). If not \c NULL, this must be 450 * a readable buffer whose size \p input_len Bytes. 451 * If \c NULL, an all \c 0 array will be used instead. 452 * \param input_len The length of \p input in Bytes. 453 * \param secret_new The address of the buffer holding the new secret 454 * on function exit. This must be a writable buffer 455 * whose size matches the output size of the hash 456 * function represented by \p hash_alg. 457 * This may be the same as \p secret_old. 458 * 459 * \returns \c 0 on success. 460 * \returns A negative error code on failure. 461 */ 462 463 MBEDTLS_CHECK_RETURN_CRITICAL 464 int mbedtls_ssl_tls13_evolve_secret( 465 psa_algorithm_t hash_alg, 466 const unsigned char *secret_old, 467 const unsigned char *input, size_t input_len, 468 unsigned char *secret_new ); 469 470 /** 471 * \brief Calculate a TLS 1.3 PSK binder. 472 * 473 * \param ssl The SSL context. This is used for debugging only and may 474 * be \c NULL if MBEDTLS_DEBUG_C is disabled. 475 * \param hash_alg The hash algorithm associated to the PSK \p psk. 476 * \param psk The buffer holding the PSK for which to create a binder. 477 * \param psk_len The size of \p psk in bytes. 478 * \param psk_type This indicates whether the PSK \p psk is externally 479 * provisioned (#MBEDTLS_SSL_TLS1_3_PSK_EXTERNAL) or a 480 * resumption PSK (#MBEDTLS_SSL_TLS1_3_PSK_RESUMPTION). 481 * \param transcript The handshake transcript up to the point where the 482 * PSK binder calculation happens. This must be readable, 483 * and its size must be equal to the digest size of 484 * the hash algorithm represented by \p hash_alg. 485 * \param result The address at which to store the PSK binder on success. 486 * This must be writable, and its size must be equal to the 487 * digest size of the hash algorithm represented by 488 * \p hash_alg. 489 * 490 * \returns \c 0 on success. 491 * \returns A negative error code on failure. 492 */ 493 MBEDTLS_CHECK_RETURN_CRITICAL 494 int mbedtls_ssl_tls13_create_psk_binder( mbedtls_ssl_context *ssl, 495 const psa_algorithm_t hash_alg, 496 unsigned char const *psk, size_t psk_len, 497 int psk_type, 498 unsigned char const *transcript, 499 unsigned char *result ); 500 501 /** 502 * \bref Setup an SSL transform structure representing the 503 * record protection mechanism used by TLS 1.3 504 * 505 * \param transform The SSL transform structure to be created. This must have 506 * been initialized through mbedtls_ssl_transform_init() and 507 * not used in any other way prior to calling this function. 508 * In particular, this function does not clean up the 509 * transform structure prior to installing the new keys. 510 * \param endpoint Indicates whether the transform is for the client 511 * (value #MBEDTLS_SSL_IS_CLIENT) or the server 512 * (value #MBEDTLS_SSL_IS_SERVER). 513 * \param ciphersuite The numerical identifier for the ciphersuite to use. 514 * This must be one of the identifiers listed in 515 * ssl_ciphersuites.h. 516 * \param traffic_keys The key material to use. No reference is stored in 517 * the SSL transform being generated, and the caller 518 * should destroy the key material afterwards. 519 * \param ssl (Debug-only) The SSL context to use for debug output 520 * in case of failure. This parameter is only needed if 521 * #MBEDTLS_DEBUG_C is set, and is ignored otherwise. 522 * 523 * \return \c 0 on success. In this case, \p transform is ready to 524 * be used with mbedtls_ssl_transform_decrypt() and 525 * mbedtls_ssl_transform_encrypt(). 526 * \return A negative error code on failure. 527 */ 528 MBEDTLS_CHECK_RETURN_CRITICAL 529 int mbedtls_ssl_tls13_populate_transform( mbedtls_ssl_transform *transform, 530 int endpoint, 531 int ciphersuite, 532 mbedtls_ssl_key_set const *traffic_keys, 533 mbedtls_ssl_context *ssl ); 534 535 /* 536 * TLS 1.3 key schedule evolutions 537 * 538 * Early -> Handshake -> Application 539 * 540 * Small wrappers around mbedtls_ssl_tls13_evolve_secret(). 541 */ 542 543 /** 544 * \brief Begin TLS 1.3 key schedule by calculating early secret. 545 * 546 * The TLS 1.3 key schedule can be viewed as a simple state machine 547 * with states Initial -> Early -> Handshake -> Application, and 548 * this function represents the Initial -> Early transition. 549 * 550 * \param ssl The SSL context to operate on. 551 * 552 * \returns \c 0 on success. 553 * \returns A negative error code on failure. 554 */ 555 MBEDTLS_CHECK_RETURN_CRITICAL 556 int mbedtls_ssl_tls13_key_schedule_stage_early( mbedtls_ssl_context *ssl ); 557 558 /** 559 * \brief Transition into handshake stage of TLS 1.3 key schedule. 560 * 561 * The TLS 1.3 key schedule can be viewed as a simple state machine 562 * with states Initial -> Early -> Handshake -> Application, and 563 * this function represents the Early -> Handshake transition. 564 * 565 * In the handshake stage, mbedtls_ssl_tls13_generate_handshake_keys() 566 * can be used to derive the handshake traffic keys. 567 * 568 * \param ssl The SSL context to operate on. This must be in key schedule 569 * stage \c Early. 570 * 571 * \returns \c 0 on success. 572 * \returns A negative error code on failure. 573 */ 574 MBEDTLS_CHECK_RETURN_CRITICAL 575 int mbedtls_ssl_tls13_key_schedule_stage_handshake( mbedtls_ssl_context *ssl ); 576 577 /** 578 * \brief Compute TLS 1.3 handshake traffic keys. 579 * 580 * \param ssl The SSL context to operate on. This must be in 581 * key schedule stage \c Handshake, see 582 * mbedtls_ssl_tls13_key_schedule_stage_handshake(). 583 * \param traffic_keys The address at which to store the handshake traffic key 584 * keys. This must be writable but may be uninitialized. 585 * 586 * \returns \c 0 on success. 587 * \returns A negative error code on failure. 588 */ 589 MBEDTLS_CHECK_RETURN_CRITICAL 590 int mbedtls_ssl_tls13_generate_handshake_keys( mbedtls_ssl_context *ssl, 591 mbedtls_ssl_key_set *traffic_keys ); 592 593 /** 594 * \brief Transition into application stage of TLS 1.3 key schedule. 595 * 596 * The TLS 1.3 key schedule can be viewed as a simple state machine 597 * with states Initial -> Early -> Handshake -> Application, and 598 * this function represents the Handshake -> Application transition. 599 * 600 * In the handshake stage, mbedtls_ssl_tls13_generate_application_keys() 601 * can be used to derive the handshake traffic keys. 602 * 603 * \param ssl The SSL context to operate on. This must be in key schedule 604 * stage \c Handshake. 605 * 606 * \returns \c 0 on success. 607 * \returns A negative error code on failure. 608 */ 609 MBEDTLS_CHECK_RETURN_CRITICAL 610 int mbedtls_ssl_tls13_key_schedule_stage_application( mbedtls_ssl_context *ssl ); 611 612 /** 613 * \brief Compute TLS 1.3 application traffic keys. 614 * 615 * \param ssl The SSL context to operate on. This must be in 616 * key schedule stage \c Application, see 617 * mbedtls_ssl_tls13_key_schedule_stage_application(). 618 * \param traffic_keys The address at which to store the application traffic key 619 * keys. This must be writable but may be uninitialized. 620 * 621 * \returns \c 0 on success. 622 * \returns A negative error code on failure. 623 */ 624 MBEDTLS_CHECK_RETURN_CRITICAL 625 int mbedtls_ssl_tls13_generate_application_keys( 626 mbedtls_ssl_context* ssl, mbedtls_ssl_key_set *traffic_keys ); 627 628 /** 629 * \brief Compute TLS 1.3 resumption master secret. 630 * 631 * \param ssl The SSL context to operate on. This must be in 632 * key schedule stage \c Application, see 633 * mbedtls_ssl_tls13_key_schedule_stage_application(). 634 * 635 * \returns \c 0 on success. 636 * \returns A negative error code on failure. 637 */ 638 MBEDTLS_CHECK_RETURN_CRITICAL 639 int mbedtls_ssl_tls13_compute_resumption_master_secret( mbedtls_ssl_context *ssl ); 640 641 /** 642 * \brief Calculate the verify_data value for the client or server TLS 1.3 643 * Finished message. 644 * 645 * \param ssl The SSL context to operate on. This must be in 646 * key schedule stage \c Handshake, see 647 * mbedtls_ssl_tls13_key_schedule_stage_application(). 648 * \param dst The address at which to write the verify_data value. 649 * \param dst_len The size of \p dst in bytes. 650 * \param actual_len The address at which to store the amount of data 651 * actually written to \p dst upon success. 652 * \param which The message to calculate the `verify_data` for: 653 * - #MBEDTLS_SSL_IS_CLIENT for the Client's Finished message 654 * - #MBEDTLS_SSL_IS_SERVER for the Server's Finished message 655 * 656 * \note Both client and server call this function twice, once to 657 * generate their own Finished message, and once to verify the 658 * peer's Finished message. 659 660 * \returns \c 0 on success. 661 * \returns A negative error code on failure. 662 */ 663 MBEDTLS_CHECK_RETURN_CRITICAL 664 int mbedtls_ssl_tls13_calculate_verify_data( mbedtls_ssl_context *ssl, 665 unsigned char *dst, 666 size_t dst_len, 667 size_t *actual_len, 668 int which ); 669 670 #if defined(MBEDTLS_SSL_EARLY_DATA) 671 /** 672 * \brief Compute TLS 1.3 early transform 673 * 674 * \param ssl The SSL context to operate on. 675 * 676 * \returns \c 0 on success. 677 * \returns A negative error code on failure. 678 * 679 * \warning The function does not compute the early master secret. Call 680 * mbedtls_ssl_tls13_key_schedule_stage_early() before to 681 * call this function to generate the early master secret. 682 * \note For a client/server endpoint, the function computes only the 683 * encryption/decryption part of the transform as the decryption/ 684 * encryption part is not defined by the specification (no early 685 * traffic from the server to the client). 686 */ 687 MBEDTLS_CHECK_RETURN_CRITICAL 688 int mbedtls_ssl_tls13_compute_early_transform( mbedtls_ssl_context *ssl ); 689 #endif /* MBEDTLS_SSL_EARLY_DATA */ 690 691 /** 692 * \brief Compute TLS 1.3 handshake transform 693 * 694 * \param ssl The SSL context to operate on. The early secret must have been 695 * computed. 696 * 697 * \returns \c 0 on success. 698 * \returns A negative error code on failure. 699 */ 700 MBEDTLS_CHECK_RETURN_CRITICAL 701 int mbedtls_ssl_tls13_compute_handshake_transform( mbedtls_ssl_context *ssl ); 702 703 /** 704 * \brief Compute TLS 1.3 application transform 705 * 706 * \param ssl The SSL context to operate on. The early secret must have been 707 * computed. 708 * 709 * \returns \c 0 on success. 710 * \returns A negative error code on failure. 711 */ 712 MBEDTLS_CHECK_RETURN_CRITICAL 713 int mbedtls_ssl_tls13_compute_application_transform( mbedtls_ssl_context *ssl ); 714 715 #if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED) 716 /** 717 * \brief Export TLS 1.3 PSK from handshake context 718 * 719 * \param[in] ssl The SSL context to operate on. 720 * \param[out] psk PSK output pointer. 721 * \param[out] psk_len Length of PSK. 722 * 723 * \returns \c 0 if there is a configured PSK and it was exported 724 * successfully. 725 * \returns A negative error code on failure. 726 */ 727 MBEDTLS_CHECK_RETURN_CRITICAL 728 int mbedtls_ssl_tls13_export_handshake_psk( mbedtls_ssl_context *ssl, 729 unsigned char **psk, 730 size_t *psk_len ); 731 #endif 732 733 #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ 734 735 #endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */ 736
