From 3385a4d5cf6a19adc89d31eee85805874267917b Mon Sep 17 00:00:00 2001 From: Hanno Becker Date: Fri, 21 Aug 2020 13:03:34 +0100 Subject: [PATCH] Implement TLS 1.3 traffic key generation See the documentation in library/ssl_tls13_keys.h. Signed-off-by: Hanno Becker --- include/mbedtls/ssl_internal.h | 25 +++++++++++++ library/ssl_tls13_keys.c | 64 ++++++++++++++++++++++++++++++++++ library/ssl_tls13_keys.h | 36 +++++++++++++++++++ 3 files changed, 125 insertions(+) diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h index b3d53d34ae..6167f567c1 100644 --- a/include/mbedtls/ssl_internal.h +++ b/include/mbedtls/ssl_internal.h @@ -378,6 +378,31 @@ typedef int mbedtls_ssl_tls_prf_cb( const unsigned char *secret, size_t slen, const char *label, const unsigned char *random, size_t rlen, unsigned char *dstbuf, size_t dlen ); + +#if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) +/** + * \brief The data structure holding the cryptographic material (key and IV) + * used for record protection in TLS 1.3. + */ +struct mbedtls_ssl_key_set +{ + /*! The key for client->server records. */ + unsigned char client_write_key[ MBEDTLS_MAX_KEY_LENGTH ]; + /*! The key for server->client records. */ + unsigned char server_write_key[ MBEDTLS_MAX_KEY_LENGTH ]; + /*! The IV for client->server records. */ + unsigned char client_write_iv[ MBEDTLS_MAX_IV_LENGTH ]; + /*! The IV for server->client records. */ + unsigned char server_write_iv[ MBEDTLS_MAX_IV_LENGTH ]; + + size_t keyLen; /*!< The length of client_write_key and + * server_write_key, in Bytes. */ + size_t ivLen; /*!< The length of client_write_iv and + * server_write_iv, in Bytes. */ +}; +typedef struct mbedtls_ssl_key_set mbedtls_ssl_key_set; +#endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ + /* * This structure contains the parameters only needed during handshake. */ diff --git a/library/ssl_tls13_keys.c b/library/ssl_tls13_keys.c index 448d03a61a..4b07aa7f47 100644 --- a/library/ssl_tls13_keys.c +++ b/library/ssl_tls13_keys.c @@ -26,6 +26,7 @@ #if defined(MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL) #include "mbedtls/hkdf.h" +#include "mbedtls/ssl_internal.h" #include "ssl_tls13_keys.h" #include @@ -179,4 +180,67 @@ int mbedtls_ssl_tls1_3_hkdf_expand_label( buf, blen ) ); } +/* + * 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_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 keyLen, size_t ivLen, + mbedtls_ssl_key_set *keys ) +{ + int ret = 0; + + ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, + client_secret, slen, + MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( key ), + NULL, 0, + keys->client_write_key, keyLen ); + if( ret != 0 ) + return( ret ); + + ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, + server_secret, slen, + MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( key ), + NULL, 0, + keys->server_write_key, keyLen ); + if( ret != 0 ) + return( ret ); + + ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, + client_secret, slen, + MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( iv ), + NULL, 0, + keys->client_write_iv, ivLen ); + if( ret != 0 ) + return( ret ); + + ret = mbedtls_ssl_tls1_3_hkdf_expand_label( hash_alg, + server_secret, slen, + MBEDTLS_SSL_TLS1_3_LBL_WITH_LEN( iv ), + NULL, 0, + keys->server_write_iv, ivLen ); + if( ret != 0 ) + return( ret ); + + keys->keyLen = keyLen; + keys->ivLen = ivLen; + + return( 0 ); +} + #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ diff --git a/library/ssl_tls13_keys.h b/library/ssl_tls13_keys.h index 49f4121137..996a1c79f0 100644 --- a/library/ssl_tls13_keys.h +++ b/library/ssl_tls13_keys.h @@ -101,6 +101,42 @@ int mbedtls_ssl_tls1_3_hkdf_expand_label( 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: + * + * + * [sender]_write_key = HKDF-Expand-Label(Secret, "key", "", key_length) + * [sender]_write_iv = HKDF-Expand-Label(Secret, "iv", "", iv_length)* + * + * + * \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 keyLen The desired length of the key to be extracted in Bytes. + * \param ivLen 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 keyLen, size_t ivLen, + mbedtls_ssl_key_set *keys ); + #endif /* MBEDTLS_SSL_PROTO_TLS1_3_EXPERIMENTAL */ #endif /* MBEDTLS_SSL_TLS1_3_KEYS_H */