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