d76a26e086
Keep applying the windows entropy patch (UWP support).
Remove no longer needed padlock patch.
Update thirdparty README to reflect changes, and new source inclusion
criteria.
(cherry picked from commit e375cbd094)
274 lines
12 KiB
C++
274 lines
12 KiB
C++
/*
|
|
* TLS 1.3 key schedule
|
|
*
|
|
* Copyright The Mbed TLS Contributors
|
|
* SPDX-License-Identifier: Apache-2.0
|
|
*
|
|
* Licensed under the Apache License, Version 2.0 ( the "License" ); you may
|
|
* not use this file except in compliance with the License.
|
|
* You may obtain a copy of the License at
|
|
*
|
|
* http://www.apache.org/licenses/LICENSE-2.0
|
|
*
|
|
* Unless required by applicable law or agreed to in writing, software
|
|
* distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
|
|
* WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
* See the License for the specific language governing permissions and
|
|
* limitations under the License.
|
|
*/
|
|
#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 */
|