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