Implement TLS 1.3 traffic key generation
See the documentation in library/ssl_tls13_keys.h.
Signed-off-by: Hanno Becker <hanno.becker@arm.com>
diff --git a/include/mbedtls/ssl_internal.h b/include/mbedtls/ssl_internal.h
index b3d53d3..6167f56 100644
--- a/include/mbedtls/ssl_internal.h
+++ b/include/mbedtls/ssl_internal.h
@@ -378,6 +378,31 @@
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 448d03a..4b07aa7 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 <stdint.h>
@@ -179,4 +180,67 @@
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 49f4121..996a1c7 100644
--- a/library/ssl_tls13_keys.h
+++ b/library/ssl_tls13_keys.h
@@ -101,6 +101,42 @@
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 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 */
