260 lines
11 KiB
C++
260 lines
11 KiB
C++
/*
|
|
* 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_tls1_3_labels_union
|
|
* below. */
|
|
#define MBEDTLS_SSL_TLS1_3_LABEL_LIST \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(finished, "finished") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(resumption, "resumption") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(traffic_upd, "traffic upd") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(exporter, "exporter") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(key, "key") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(iv, "iv") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(c_hs_traffic, "c hs traffic") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(c_ap_traffic, "c ap traffic") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(c_e_traffic, "c e traffic") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(s_hs_traffic, "s hs traffic") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(s_ap_traffic, "s ap traffic") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(s_e_traffic, "s e traffic") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(e_exp_master, "e exp master") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(res_master, "res master") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(exp_master, "exp master") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(ext_binder, "ext binder") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(res_binder, "res binder") \
|
|
MBEDTLS_SSL_TLS1_3_LABEL(derived, "derived")
|
|
|
|
#define MBEDTLS_SSL_TLS1_3_LABEL(name, string) \
|
|
const unsigned char name [sizeof(string) - 1];
|
|
|
|
union mbedtls_ssl_tls1_3_labels_union {
|
|
MBEDTLS_SSL_TLS1_3_LABEL_LIST
|
|
};
|
|
struct mbedtls_ssl_tls1_3_labels_struct {
|
|
MBEDTLS_SSL_TLS1_3_LABEL_LIST
|
|
};
|
|
#undef MBEDTLS_SSL_TLS1_3_LABEL
|
|
|
|
extern const struct mbedtls_ssl_tls1_3_labels_struct mbedtls_ssl_tls1_3_labels;
|
|
|
|
#define MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN(LABEL) \
|
|
mbedtls_ssl_tls1_3_labels.LABEL, \
|
|
sizeof(mbedtls_ssl_tls1_3_labels.LABEL)
|
|
|
|
#define MBEDTLS_SSL_TLS1_3_KEY_SCHEDULE_MAX_LABEL_LEN \
|
|
sizeof(union mbedtls_ssl_tls1_3_labels_union)
|
|
|
|
/* 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 \
|
|
MBEDTLS_MD_MAX_SIZE
|
|
|
|
/* Maximum desired length for expanded key material generated
|
|
* by HKDF-Expand-Label.
|
|
*
|
|
* Warning: If this ever needs to be increased, the implementation
|
|
* ssl_tls1_3_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 255
|
|
|
|
/**
|
|
* \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 slen Bytes.
|
|
* \param slen 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 llen Bytes.
|
|
* \param llen 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 clen Bytes.
|
|
* \param clen 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 blen Bytes.
|
|
* \param blen The desired size of the expanded secret in Bytes.
|
|
*
|
|
* \returns \c 0 on success.
|
|
* \return A negative error code on failure.
|
|
*/
|
|
|
|
int mbedtls_ssl_tls1_3_hkdf_expand_label(
|
|
mbedtls_md_type_t hash_alg,
|
|
const unsigned char *secret, size_t slen,
|
|
const unsigned char *label, size_t llen,
|
|
const unsigned char *ctx, size_t clen,
|
|
unsigned char *buf, size_t blen);
|
|
|
|
/**
|
|
* \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 slen Bytes
|
|
* \param server_secret The server traffic secret.
|
|
* This must be a readable buffer of size \p slen Bytes
|
|
* \param slen 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.
|
|
*/
|
|
|
|
int mbedtls_ssl_tls1_3_make_traffic_keys(
|
|
mbedtls_md_type_t hash_alg,
|
|
const unsigned char *client_secret,
|
|
const unsigned char *server_secret,
|
|
size_t slen, size_t key_len, size_t iv_len,
|
|
mbedtls_ssl_key_set *keys);
|
|
|
|
|
|
#define MBEDTLS_SSL_TLS1_3_CONTEXT_UNHASHED 0
|
|
#define MBEDTLS_SSL_TLS1_3_CONTEXT_HASHED 1
|
|
|
|
/**
|
|
* \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 slen Bytes.
|
|
* \param slen 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 llen Bytes.
|
|
* \param llen 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 context_already_hashed.
|
|
* \param clen The length of \p hash.
|
|
* \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 buflen Bytes.
|
|
* \param buflen The length of \p dstbuf in Bytes.
|
|
*
|
|
* \returns \c 0 on success.
|
|
* \returns A negative error code on failure.
|
|
*/
|
|
int mbedtls_ssl_tls1_3_derive_secret(
|
|
mbedtls_md_type_t hash_alg,
|
|
const unsigned char *secret, size_t slen,
|
|
const unsigned char *label, size_t llen,
|
|
const unsigned char *ctx, size_t clen,
|
|
int ctx_hashed,
|
|
unsigned char *dstbuf, size_t buflen);
|
|
|
|
/**
|
|
* \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_tls1_3_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.
|
|
*/
|
|
|
|
int mbedtls_ssl_tls1_3_evolve_secret(
|
|
mbedtls_md_type_t hash_alg,
|
|
const unsigned char *secret_old,
|
|
const unsigned char *input, size_t input_len,
|
|
unsigned char *secret_new);
|
|
|
|
#endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */
|