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