/* * TLS 1.3 key schedule * * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later */ #include "common.h" #if defined(MBEDTLS_SSL_PROTO_TLS1_3) #include <stdint.h> #include <string.h> #include "mbedtls/hkdf.h" #include "debug_internal.h" #include "mbedtls/error.h" #include "mbedtls/platform.h" #include "ssl_misc.h" #include "ssl_tls13_keys.h" #include "ssl_tls13_invasive.h" #include "psa/crypto.h" #include "mbedtls/psa_util.h" /* Define a local translating function to save code size by not using too many * arguments in each translating place. */ static int local_err_translation(psa_status_t status) { … } #define PSA_TO_MBEDTLS_ERR(status) … #define MBEDTLS_SSL_TLS1_3_LABEL … struct mbedtls_ssl_tls13_labels_struct const mbedtls_ssl_tls13_labels = …; #undef MBEDTLS_SSL_TLS1_3_LABEL /* * This function creates a HkdfLabel structure used in the TLS 1.3 key schedule. * * The HkdfLabel is specified in RFC 8446 as follows: * * struct HkdfLabel { * uint16 length; // Length of expanded key material * opaque label<7..255>; // Always prefixed by "tls13 " * opaque context<0..255>; // Usually a communication transcript hash * }; * * Parameters: * - desired_length: Length of expanded key material * Even though the standard allows expansion to up to * 2**16 Bytes, TLS 1.3 never uses expansion to more than * 255 Bytes, so we require `desired_length` to be at most * 255. This allows us to save a few Bytes of code by * hardcoding the writing of the high bytes. * - (label, label_len): label + label length, without "tls13 " prefix * The label length MUST be less than or equal to * MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN * It is the caller's responsibility to ensure this. * All (label, label length) pairs used in TLS 1.3 * can be obtained via MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(). * - (ctx, ctx_len): context + context length * The context length MUST be less than or equal to * MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN * It is the caller's responsibility to ensure this. * - dst: Target buffer for HkdfLabel structure, * This MUST be a writable buffer of size * at least SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN Bytes. * - dst_len: Pointer at which to store the actual length of * the HkdfLabel structure on success. */ static const char tls13_label_prefix[6] = …; #define SSL_TLS1_3_KEY_SCHEDULE_HKDF_LABEL_LEN(label_len, context_len) … #define SSL_TLS1_3_KEY_SCHEDULE_MAX_HKDF_LABEL_LEN … static void ssl_tls13_hkdf_encode_label( size_t desired_length, const unsigned char *label, size_t label_len, const unsigned char *ctx, size_t ctx_len, unsigned char *dst, size_t *dst_len) { … } int mbedtls_ssl_tls13_hkdf_expand_label( psa_algorithm_t hash_alg, const unsigned char *secret, size_t secret_len, const unsigned char *label, size_t label_len, const unsigned char *ctx, size_t ctx_len, unsigned char *buf, size_t buf_len) { … } MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_make_traffic_key( psa_algorithm_t hash_alg, const unsigned char *secret, size_t secret_len, unsigned char *key, size_t key_len, unsigned char *iv, size_t iv_len) { … } /* * The traffic keying material is generated from the following inputs: * * - One secret value per sender. * - A purpose value indicating the specific value being generated * - The desired lengths of key and IV. * * The expansion itself is based on HKDF: * * [sender]_write_key = HKDF-Expand-Label( Secret, "key", "", key_length ) * [sender]_write_iv = HKDF-Expand-Label( Secret, "iv" , "", iv_length ) * * [sender] denotes the sending side and the Secret value is provided * by the function caller. Note that we generate server and client side * keys in a single function call. */ int mbedtls_ssl_tls13_make_traffic_keys( psa_algorithm_t hash_alg, const unsigned char *client_secret, const unsigned char *server_secret, size_t secret_len, size_t key_len, size_t iv_len, mbedtls_ssl_key_set *keys) { … } int mbedtls_ssl_tls13_derive_secret( psa_algorithm_t hash_alg, const unsigned char *secret, size_t secret_len, const unsigned char *label, size_t label_len, const unsigned char *ctx, size_t ctx_len, int ctx_hashed, unsigned char *dstbuf, size_t dstbuf_len) { … } int mbedtls_ssl_tls13_evolve_secret( psa_algorithm_t hash_alg, const unsigned char *secret_old, const unsigned char *input, size_t input_len, unsigned char *secret_new) { … } int mbedtls_ssl_tls13_derive_early_secrets( psa_algorithm_t hash_alg, unsigned char const *early_secret, unsigned char const *transcript, size_t transcript_len, mbedtls_ssl_tls13_early_secrets *derived) { … } int mbedtls_ssl_tls13_derive_handshake_secrets( psa_algorithm_t hash_alg, unsigned char const *handshake_secret, unsigned char const *transcript, size_t transcript_len, mbedtls_ssl_tls13_handshake_secrets *derived) { … } int mbedtls_ssl_tls13_derive_application_secrets( psa_algorithm_t hash_alg, unsigned char const *application_secret, unsigned char const *transcript, size_t transcript_len, mbedtls_ssl_tls13_application_secrets *derived) { … } /* Generate resumption_master_secret for use with the ticket exchange. * * This is not integrated with mbedtls_ssl_tls13_derive_application_secrets() * because it uses the transcript hash up to and including ClientFinished. */ int mbedtls_ssl_tls13_derive_resumption_master_secret( psa_algorithm_t hash_alg, unsigned char const *application_secret, unsigned char const *transcript, size_t transcript_len, mbedtls_ssl_tls13_application_secrets *derived) { … } /** * \brief Transition into application stage of TLS 1.3 key schedule. * * The TLS 1.3 key schedule can be viewed as a simple state machine * with states Initial -> Early -> Handshake -> Application, and * this function represents the Handshake -> Application transition. * * In the handshake stage, ssl_tls13_generate_application_keys() * can be used to derive the handshake traffic keys. * * \param ssl The SSL context to operate on. This must be in key schedule * stage \c Handshake. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_key_schedule_stage_application(mbedtls_ssl_context *ssl) { … } MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_calc_finished_core(psa_algorithm_t hash_alg, unsigned char const *base_key, unsigned char const *transcript, unsigned char *dst, size_t *dst_len) { … } int mbedtls_ssl_tls13_calculate_verify_data(mbedtls_ssl_context *ssl, unsigned char *dst, size_t dst_len, size_t *actual_len, int from) { … } int mbedtls_ssl_tls13_create_psk_binder(mbedtls_ssl_context *ssl, const psa_algorithm_t hash_alg, unsigned char const *psk, size_t psk_len, int psk_type, unsigned char const *transcript, unsigned char *result) { … } int mbedtls_ssl_tls13_populate_transform( mbedtls_ssl_transform *transform, int endpoint, int ciphersuite, mbedtls_ssl_key_set const *traffic_keys, mbedtls_ssl_context *ssl /* DEBUG ONLY */) { … } MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_get_cipher_key_info( const mbedtls_ssl_ciphersuite_t *ciphersuite_info, size_t *key_len, size_t *iv_len) { … } #if defined(MBEDTLS_SSL_EARLY_DATA) /* * ssl_tls13_generate_early_key() generates the key necessary for protecting * the early application data and handshake messages as described in section 7 * of RFC 8446. * * NOTE: Only one key is generated, the key for the traffic from the client to * the server. The TLS 1.3 specification does not define a secret and thus * a key for server early traffic. */ MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_generate_early_key(mbedtls_ssl_context *ssl, mbedtls_ssl_key_set *traffic_keys) { int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED; mbedtls_md_type_t md_type; psa_algorithm_t hash_alg; size_t hash_len; unsigned char transcript[MBEDTLS_TLS1_3_MD_MAX_SIZE]; size_t transcript_len; size_t key_len = 0; size_t iv_len = 0; mbedtls_ssl_tls13_early_secrets tls13_early_secrets; mbedtls_ssl_handshake_params *handshake = ssl->handshake; const mbedtls_ssl_ciphersuite_t *ciphersuite_info = handshake->ciphersuite_info; MBEDTLS_SSL_DEBUG_MSG(2, ("=> ssl_tls13_generate_early_key")); ret = ssl_tls13_get_cipher_key_info(ciphersuite_info, &key_len, &iv_len); if (ret != 0) { MBEDTLS_SSL_DEBUG_RET(1, "ssl_tls13_get_cipher_key_info", ret); goto cleanup; } md_type = (mbedtls_md_type_t) ciphersuite_info->mac; hash_alg = mbedtls_md_psa_alg_from_type((mbedtls_md_type_t) ciphersuite_info->mac); hash_len = PSA_HASH_LENGTH(hash_alg); ret = mbedtls_ssl_get_handshake_transcript(ssl, md_type, transcript, sizeof(transcript), &transcript_len); if (ret != 0) { MBEDTLS_SSL_DEBUG_RET(1, "mbedtls_ssl_get_handshake_transcript", ret); goto cleanup; } ret = mbedtls_ssl_tls13_derive_early_secrets( hash_alg, handshake->tls13_master_secrets.early, transcript, transcript_len, &tls13_early_secrets); if (ret != 0) { MBEDTLS_SSL_DEBUG_RET( 1, "mbedtls_ssl_tls13_derive_early_secrets", ret); goto cleanup; } MBEDTLS_SSL_DEBUG_BUF( 4, "Client early traffic secret", tls13_early_secrets.client_early_traffic_secret, hash_len); /* * Export client handshake traffic secret */ if (ssl->f_export_keys != NULL) { ssl->f_export_keys( ssl->p_export_keys, MBEDTLS_SSL_KEY_EXPORT_TLS1_3_CLIENT_EARLY_SECRET, tls13_early_secrets.client_early_traffic_secret, hash_len, handshake->randbytes, handshake->randbytes + MBEDTLS_CLIENT_HELLO_RANDOM_LEN, MBEDTLS_SSL_TLS_PRF_NONE /* TODO: FIX! */); } ret = ssl_tls13_make_traffic_key( hash_alg, tls13_early_secrets.client_early_traffic_secret, hash_len, traffic_keys->client_write_key, key_len, traffic_keys->client_write_iv, iv_len); if (ret != 0) { MBEDTLS_SSL_DEBUG_RET(1, "ssl_tls13_make_traffic_key", ret); goto cleanup; } traffic_keys->key_len = key_len; traffic_keys->iv_len = iv_len; MBEDTLS_SSL_DEBUG_BUF(4, "client early write_key", traffic_keys->client_write_key, traffic_keys->key_len); MBEDTLS_SSL_DEBUG_BUF(4, "client early write_iv", traffic_keys->client_write_iv, traffic_keys->iv_len); MBEDTLS_SSL_DEBUG_MSG(2, ("<= ssl_tls13_generate_early_key")); cleanup: /* Erase early secrets and transcript */ mbedtls_platform_zeroize( &tls13_early_secrets, sizeof(mbedtls_ssl_tls13_early_secrets)); mbedtls_platform_zeroize(transcript, sizeof(transcript)); return ret; } int mbedtls_ssl_tls13_compute_early_transform(mbedtls_ssl_context *ssl) { int ret = MBEDTLS_ERR_ERROR_CORRUPTION_DETECTED; mbedtls_ssl_key_set traffic_keys; mbedtls_ssl_transform *transform_earlydata = NULL; mbedtls_ssl_handshake_params *handshake = ssl->handshake; /* Next evolution in key schedule: Establish early_data secret and * key material. */ ret = ssl_tls13_generate_early_key(ssl, &traffic_keys); if (ret != 0) { MBEDTLS_SSL_DEBUG_RET(1, "ssl_tls13_generate_early_key", ret); goto cleanup; } transform_earlydata = mbedtls_calloc(1, sizeof(mbedtls_ssl_transform)); if (transform_earlydata == NULL) { ret = MBEDTLS_ERR_SSL_ALLOC_FAILED; goto cleanup; } ret = mbedtls_ssl_tls13_populate_transform( transform_earlydata, ssl->conf->endpoint, handshake->ciphersuite_info->id, &traffic_keys, ssl); if (ret != 0) { MBEDTLS_SSL_DEBUG_RET(1, "mbedtls_ssl_tls13_populate_transform", ret); goto cleanup; } handshake->transform_earlydata = transform_earlydata; cleanup: mbedtls_platform_zeroize(&traffic_keys, sizeof(traffic_keys)); if (ret != 0) { mbedtls_free(transform_earlydata); } return ret; } #endif /* MBEDTLS_SSL_EARLY_DATA */ int mbedtls_ssl_tls13_key_schedule_stage_early(mbedtls_ssl_context *ssl) { … } /** * \brief Compute TLS 1.3 handshake traffic keys. * * ssl_tls13_generate_handshake_keys() generates keys necessary for * protecting the handshake messages, as described in Section 7 of * RFC 8446. * * \param ssl The SSL context to operate on. This must be in * key schedule stage \c Handshake, see * ssl_tls13_key_schedule_stage_handshake(). * \param traffic_keys The address at which to store the handshake traffic * keys. This must be writable but may be uninitialized. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_generate_handshake_keys(mbedtls_ssl_context *ssl, mbedtls_ssl_key_set *traffic_keys) { … } /** * \brief Transition into handshake stage of TLS 1.3 key schedule. * * The TLS 1.3 key schedule can be viewed as a simple state machine * with states Initial -> Early -> Handshake -> Application, and * this function represents the Early -> Handshake transition. * * In the handshake stage, ssl_tls13_generate_handshake_keys() * can be used to derive the handshake traffic keys. * * \param ssl The SSL context to operate on. This must be in key schedule * stage \c Early. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_key_schedule_stage_handshake(mbedtls_ssl_context *ssl) { … } /** * \brief Compute TLS 1.3 application traffic keys. * * ssl_tls13_generate_application_keys() generates application traffic * keys, since any record following a 1-RTT Finished message MUST be * encrypted under the application traffic key. * * \param ssl The SSL context to operate on. This must be in * key schedule stage \c Application, see * ssl_tls13_key_schedule_stage_application(). * \param traffic_keys The address at which to store the application traffic * keys. This must be writable but may be uninitialized. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL static int ssl_tls13_generate_application_keys( mbedtls_ssl_context *ssl, mbedtls_ssl_key_set *traffic_keys) { … } int mbedtls_ssl_tls13_compute_handshake_transform(mbedtls_ssl_context *ssl) { … } int mbedtls_ssl_tls13_compute_resumption_master_secret(mbedtls_ssl_context *ssl) { … } int mbedtls_ssl_tls13_compute_application_transform(mbedtls_ssl_context *ssl) { … } #if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED) int mbedtls_ssl_tls13_export_handshake_psk(mbedtls_ssl_context *ssl, unsigned char **psk, size_t *psk_len) { … } #endif /* MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED */ #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */
Codebase Browser
godot