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