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>

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.
  */

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 @@ 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 */

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:
+ *
+ * <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 */