/* * TLS 1.3 key schedule * * Copyright The Mbed TLS Contributors * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later */ #if !defined(MBEDTLS_SSL_TLS1_3_KEYS_H) #define MBEDTLS_SSL_TLS1_3_KEYS_H /* This requires MBEDTLS_SSL_TLS1_3_LABEL( idx, name, string ) to be defined at * the point of use. See e.g. the definition of mbedtls_ssl_tls13_labels_union * below. */ #define MBEDTLS_SSL_TLS1_3_LABEL_LIST … #define MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED … #define MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED … #define MBEDTLS_SSL_TLS1_3_PSK_EXTERNAL … #define MBEDTLS_SSL_TLS1_3_PSK_RESUMPTION … #if defined(MBEDTLS_SSL_PROTO_TLS1_3) #define MBEDTLS_SSL_TLS1_3_LABEL … mbedtls_ssl_tls13_labels_union; struct mbedtls_ssl_tls13_labels_struct { … }; #undef MBEDTLS_SSL_TLS1_3_LABEL extern const struct mbedtls_ssl_tls13_labels_struct mbedtls_ssl_tls13_labels; #define MBEDTLS_SSL_TLS1_3_LBL_LEN(LABEL) … #define MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(LABEL) … #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN … /* The maximum length of HKDF contexts used in the TLS 1.3 standard. * Since contexts are always hashes of message transcripts, this can * be approximated from above by the maximum hash size. */ #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_CONTEXT_LEN … /* Maximum desired length for expanded key material generated * by HKDF-Expand-Label. * * Warning: If this ever needs to be increased, the implementation * ssl_tls13_hkdf_encode_label() in ssl_tls13_keys.c needs to be * adjusted since it currently assumes that HKDF key expansion * is never used with more than 255 Bytes of output. */ #define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_EXPANSION_LEN … /** * \brief The \c HKDF-Expand-Label function from * the TLS 1.3 standard RFC 8446. * * <tt> * HKDF-Expand-Label( Secret, Label, Context, Length ) = * HKDF-Expand( Secret, HkdfLabel, Length ) * </tt> * * \param hash_alg The identifier for the hash algorithm to use. * \param secret The \c Secret argument to \c HKDF-Expand-Label. * This must be a readable buffer of length * \p secret_len Bytes. * \param secret_len The length of \p secret in Bytes. * \param label The \c Label argument to \c HKDF-Expand-Label. * This must be a readable buffer of length * \p label_len Bytes. * \param label_len The length of \p label in Bytes. * \param ctx The \c Context argument to \c HKDF-Expand-Label. * This must be a readable buffer of length \p ctx_len Bytes. * \param ctx_len The length of \p context in Bytes. * \param buf The destination buffer to hold the expanded secret. * This must be a writable buffer of length \p buf_len Bytes. * \param buf_len The desired size of the expanded secret in Bytes. * * \returns \c 0 on success. * \return A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /** * \brief This function is part of the TLS 1.3 key schedule. * It extracts key and IV for the actual client/server traffic * from the client/server traffic secrets. * * From RFC 8446: * * <tt> * [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) * [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)* * </tt> * * \param hash_alg The identifier for the hash algorithm to be used * for the HKDF-based expansion of the secret. * \param client_secret The client traffic secret. * This must be a readable buffer of size * \p secret_len Bytes * \param server_secret The server traffic secret. * This must be a readable buffer of size * \p secret_len Bytes * \param secret_len Length of the secrets \p client_secret and * \p server_secret in Bytes. * \param key_len The desired length of the key to be extracted in Bytes. * \param iv_len The desired length of the IV to be extracted in Bytes. * \param keys The address of the structure holding the generated * keys and IVs. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /** * \brief The \c Derive-Secret function from the TLS 1.3 standard RFC 8446. * * <tt> * Derive-Secret( Secret, Label, Messages ) = * HKDF-Expand-Label( Secret, Label, * Hash( Messages ), * Hash.Length ) ) * </tt> * * \param hash_alg The identifier for the hash function used for the * applications of HKDF. * \param secret The \c Secret argument to the \c Derive-Secret function. * This must be a readable buffer of length * \p secret_len Bytes. * \param secret_len The length of \p secret in Bytes. * \param label The \c Label argument to the \c Derive-Secret function. * This must be a readable buffer of length * \p label_len Bytes. * \param label_len The length of \p label in Bytes. * \param ctx The hash of the \c Messages argument to the * \c Derive-Secret function, or the \c Messages argument * itself, depending on \p ctx_hashed. * \param ctx_len The length of \p ctx in Bytes. * \param ctx_hashed This indicates whether the \p ctx contains the hash of * the \c Messages argument in the application of the * \c Derive-Secret function * (value MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED), or whether * it is the content of \c Messages itself, in which case * the function takes care of the hashing * (value MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED). * \param dstbuf The target buffer to write the output of * \c Derive-Secret to. This must be a writable buffer of * size \p dtsbuf_len Bytes. * \param dstbuf_len The length of \p dstbuf in Bytes. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /** * \brief Derive TLS 1.3 early data key material from early secret. * * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() * with the appropriate labels. * * <tt> * Early Secret * | * +-----> Derive-Secret(., "c e traffic", ClientHello) * | = client_early_traffic_secret * | * +-----> Derive-Secret(., "e exp master", ClientHello) * . = early_exporter_master_secret * . * . * </tt> * * \note To obtain the actual key and IV for the early data traffic, * the client secret derived by this function need to be * further processed by mbedtls_ssl_tls13_make_traffic_keys(). * * \note The binder key, which is also generated from the early secret, * is omitted here. Its calculation is part of the separate routine * mbedtls_ssl_tls13_create_psk_binder(). * * \param hash_alg The hash algorithm associated with the PSK for which * early data key material is being derived. * \param early_secret The early secret from which the early data key material * should be derived. This must be a readable buffer whose * length is the digest size of the hash algorithm * represented by \p md_size. * \param transcript The transcript of the handshake so far, calculated with * respect to \p hash_alg. This must be a readable buffer * whose length is the digest size of the hash algorithm * represented by \p md_size. * \param derived The address of the structure in which to store * the early data key material. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /** * \brief Derive TLS 1.3 handshake key material from the handshake secret. * * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() * with the appropriate labels from the standard. * * <tt> * Handshake Secret * | * +-----> Derive-Secret( ., "c hs traffic", * | ClientHello...ServerHello ) * | = client_handshake_traffic_secret * | * +-----> Derive-Secret( ., "s hs traffic", * . ClientHello...ServerHello ) * . = server_handshake_traffic_secret * . * </tt> * * \note To obtain the actual key and IV for the encrypted handshake traffic, * the client and server secret derived by this function need to be * further processed by mbedtls_ssl_tls13_make_traffic_keys(). * * \param hash_alg The hash algorithm associated with the ciphersuite * that's being used for the connection. * \param handshake_secret The handshake secret from which the handshake key * material should be derived. This must be a readable * buffer whose length is the digest size of the hash * algorithm represented by \p md_size. * \param transcript The transcript of the handshake so far, calculated * with respect to \p hash_alg. This must be a readable * buffer whose length is the digest size of the hash * algorithm represented by \p md_size. * \param derived The address of the structure in which to * store the handshake key material. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /** * \brief Derive TLS 1.3 application key material from the master secret. * * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() * with the appropriate labels from the standard. * * <tt> * Master Secret * | * +-----> Derive-Secret( ., "c ap traffic", * | ClientHello...server Finished ) * | = client_application_traffic_secret_0 * | * +-----> Derive-Secret( ., "s ap traffic", * | ClientHello...Server Finished ) * | = server_application_traffic_secret_0 * | * +-----> Derive-Secret( ., "exp master", * . ClientHello...server Finished) * . = exporter_master_secret * . * </tt> * * \note To obtain the actual key and IV for the (0-th) application traffic, * the client and server secret derived by this function need to be * further processed by mbedtls_ssl_tls13_make_traffic_keys(). * * \param hash_alg The hash algorithm associated with the ciphersuite * that's being used for the connection. * \param master_secret The master secret from which the application key * material should be derived. This must be a readable * buffer whose length is the digest size of the hash * algorithm represented by \p md_size. * \param transcript The transcript of the handshake up to and including * the ServerFinished message, calculated with respect * to \p hash_alg. This must be a readable buffer whose * length is the digest size of the hash algorithm * represented by \p hash_alg. * \param derived The address of the structure in which to * store the application key material. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_derive_application_secrets( psa_algorithm_t hash_alg, unsigned char const *master_secret, unsigned char const *transcript, size_t transcript_len, mbedtls_ssl_tls13_application_secrets *derived); /** * \brief Derive TLS 1.3 resumption master secret from the master secret. * * This is a small wrapper invoking mbedtls_ssl_tls13_derive_secret() * with the appropriate labels from the standard. * * \param hash_alg The hash algorithm used in the application for which * key material is being derived. * \param application_secret The application secret from which the resumption master * secret should be derived. This must be a readable * buffer whose length is the digest size of the hash * algorithm represented by \p md_size. * \param transcript The transcript of the handshake up to and including * the ClientFinished message, calculated with respect * to \p hash_alg. This must be a readable buffer whose * length is the digest size of the hash algorithm * represented by \p hash_alg. * \param transcript_len The length of \p transcript in Bytes. * \param derived The address of the structure in which to * store the resumption master secret. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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 Compute the next secret in the TLS 1.3 key schedule * * The TLS 1.3 key schedule proceeds as follows to compute * the three main secrets during the handshake: The early * secret for early data, the handshake secret for all * other encrypted handshake messages, and the master * secret for all application traffic. * * <tt> * 0 * | * v * PSK -> HKDF-Extract = Early Secret * | * v * Derive-Secret( ., "derived", "" ) * | * v * (EC)DHE -> HKDF-Extract = Handshake Secret * | * v * Derive-Secret( ., "derived", "" ) * | * v * 0 -> HKDF-Extract = Master Secret * </tt> * * Each of the three secrets in turn is the basis for further * key derivations, such as the derivation of traffic keys and IVs; * see e.g. mbedtls_ssl_tls13_make_traffic_keys(). * * This function implements one step in this evolution of secrets: * * <tt> * old_secret * | * v * Derive-Secret( ., "derived", "" ) * | * v * input -> HKDF-Extract = new_secret * </tt> * * \param hash_alg The identifier for the hash function used for the * applications of HKDF. * \param secret_old The address of the buffer holding the old secret * on function entry. If not \c NULL, this must be a * readable buffer whose size matches the output size * of the hash function represented by \p hash_alg. * If \c NULL, an all \c 0 array will be used instead. * \param input The address of the buffer holding the additional * input for the key derivation (e.g., the PSK or the * ephemeral (EC)DH secret). If not \c NULL, this must be * a readable buffer whose size \p input_len Bytes. * If \c NULL, an all \c 0 array will be used instead. * \param input_len The length of \p input in Bytes. * \param secret_new The address of the buffer holding the new secret * on function exit. This must be a writable buffer * whose size matches the output size of the hash * function represented by \p hash_alg. * This may be the same as \p secret_old. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /** * \brief Calculate a TLS 1.3 PSK binder. * * \param ssl The SSL context. This is used for debugging only and may * be \c NULL if MBEDTLS_DEBUG_C is disabled. * \param hash_alg The hash algorithm associated to the PSK \p psk. * \param psk The buffer holding the PSK for which to create a binder. * \param psk_len The size of \p psk in bytes. * \param psk_type This indicates whether the PSK \p psk is externally * provisioned (#MBEDTLS_SSL_TLS1_3_PSK_EXTERNAL) or a * resumption PSK (#MBEDTLS_SSL_TLS1_3_PSK_RESUMPTION). * \param transcript The handshake transcript up to the point where the * PSK binder calculation happens. This must be readable, * and its size must be equal to the digest size of * the hash algorithm represented by \p hash_alg. * \param result The address at which to store the PSK binder on success. * This must be writable, and its size must be equal to the * digest size of the hash algorithm represented by * \p hash_alg. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /** * \bref Setup an SSL transform structure representing the * record protection mechanism used by TLS 1.3 * * \param transform The SSL transform structure to be created. This must have * been initialized through mbedtls_ssl_transform_init() and * not used in any other way prior to calling this function. * In particular, this function does not clean up the * transform structure prior to installing the new keys. * \param endpoint Indicates whether the transform is for the client * (value #MBEDTLS_SSL_IS_CLIENT) or the server * (value #MBEDTLS_SSL_IS_SERVER). * \param ciphersuite The numerical identifier for the ciphersuite to use. * This must be one of the identifiers listed in * ssl_ciphersuites.h. * \param traffic_keys The key material to use. No reference is stored in * the SSL transform being generated, and the caller * should destroy the key material afterwards. * \param ssl (Debug-only) The SSL context to use for debug output * in case of failure. This parameter is only needed if * #MBEDTLS_DEBUG_C is set, and is ignored otherwise. * * \return \c 0 on success. In this case, \p transform is ready to * be used with mbedtls_ssl_transform_decrypt() and * mbedtls_ssl_transform_encrypt(). * \return A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL 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); /* * TLS 1.3 key schedule evolutions * * Early -> Handshake -> Application * * Small wrappers around mbedtls_ssl_tls13_evolve_secret(). */ /** * \brief Begin TLS 1.3 key schedule by calculating early secret. * * 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 Initial -> Early transition. * * \param ssl The SSL context to operate on. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_key_schedule_stage_early(mbedtls_ssl_context *ssl); /** * \brief Compute TLS 1.3 resumption master secret. * * \param ssl The SSL context to operate on. This must be in * key schedule stage \c Application, see * mbedtls_ssl_tls13_key_schedule_stage_application(). * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_compute_resumption_master_secret(mbedtls_ssl_context *ssl); /** * \brief Calculate the verify_data value for the client or server TLS 1.3 * Finished message. * * \param ssl The SSL context to operate on. This must be in * key schedule stage \c Handshake, see * mbedtls_ssl_tls13_key_schedule_stage_application(). * \param dst The address at which to write the verify_data value. * \param dst_len The size of \p dst in bytes. * \param actual_len The address at which to store the amount of data * actually written to \p dst upon success. * \param which The message to calculate the `verify_data` for: * - #MBEDTLS_SSL_IS_CLIENT for the Client's Finished message * - #MBEDTLS_SSL_IS_SERVER for the Server's Finished message * * \note Both client and server call this function twice, once to * generate their own Finished message, and once to verify the * peer's Finished message. * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_calculate_verify_data(mbedtls_ssl_context *ssl, unsigned char *dst, size_t dst_len, size_t *actual_len, int which); #if defined(MBEDTLS_SSL_EARLY_DATA) /** * \brief Compute TLS 1.3 early transform * * \param ssl The SSL context to operate on. * * \returns \c 0 on success. * \returns A negative error code on failure. * * \warning The function does not compute the early master secret. Call * mbedtls_ssl_tls13_key_schedule_stage_early() before to * call this function to generate the early master secret. * \note For a client/server endpoint, the function computes only the * encryption/decryption part of the transform as the decryption/ * encryption part is not defined by the specification (no early * traffic from the server to the client). */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_compute_early_transform(mbedtls_ssl_context *ssl); #endif /* MBEDTLS_SSL_EARLY_DATA */ /** * \brief Compute TLS 1.3 handshake transform * * \param ssl The SSL context to operate on. The early secret must have been * computed. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_compute_handshake_transform(mbedtls_ssl_context *ssl); /** * \brief Compute TLS 1.3 application transform * * \param ssl The SSL context to operate on. The early secret must have been * computed. * * \returns \c 0 on success. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_compute_application_transform(mbedtls_ssl_context *ssl); #if defined(MBEDTLS_SSL_TLS1_3_KEY_EXCHANGE_MODE_SOME_PSK_ENABLED) /** * \brief Export TLS 1.3 PSK from handshake context * * \param[in] ssl The SSL context to operate on. * \param[out] psk PSK output pointer. * \param[out] psk_len Length of PSK. * * \returns \c 0 if there is a configured PSK and it was exported * successfully. * \returns A negative error code on failure. */ MBEDTLS_CHECK_RETURN_CRITICAL int mbedtls_ssl_tls13_export_handshake_psk(mbedtls_ssl_context *ssl, unsigned char **psk, size_t *psk_len); #endif #endif /* MBEDTLS_SSL_PROTO_TLS1_3 */ #endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */
Codebase Browser
godot