Improve key export API and documentation
- "master secret" is the usual name
- move key block arg closer to the related lengths
- document lengths
Also fix some trailing whitespace while at it
diff --git a/include/mbedtls/config.h b/include/mbedtls/config.h
index 5834279..9c96a05 100644
--- a/include/mbedtls/config.h
+++ b/include/mbedtls/config.h
@@ -1181,7 +1181,7 @@
/**
* \def MBEDTLS_SSL_EXPORT_KEYS
*
- * Enable support for exporting key block and master key.
+ * Enable support for exporting key block and master secret.
* This is required for certain users of TLS, e.g. EAP-TLS.
*
* Comment this macro to disable support for key export
diff --git a/include/mbedtls/ssl.h b/include/mbedtls/ssl.h
index c3cd006..e6b73d0 100644
--- a/include/mbedtls/ssl.h
+++ b/include/mbedtls/ssl.h
@@ -545,7 +545,7 @@
#endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
#if defined(MBEDTLS_SSL_EXPORT_KEYS)
- /** Callback to export key block and master key */
+ /** Callback to export key block and master secret */
int (*f_export_keys)( void *, const unsigned char *,
const unsigned char *, size_t, size_t, size_t );
void *p_export_keys; /*!< context for key export callback */
@@ -1080,17 +1080,18 @@
#if defined(MBEDTLS_SSL_EXPORT_KEYS)
/**
- * \brief Callback type: Export key block and master key
+ * \brief Callback type: Export key block and master secret
*
* \note This is required for certain uses of TLS, e.g. EAP-TLS
- * (RFC 5216). The key pointers are ephemeral and therefore
- * must not be stored. The keys should not be copied
- * verbatim and should be used specifically for key
- * derivation purposes
+ * (RFC 5216) and Thread. The key pointers are ephemeral and
+ * therefore must not be stored. The master secret and keys
+ * should not be used directly except as an input to a key
+ * derivation function.
*
* \param p_expkey Context for the callback
- * \param kb Pointer to key block
- * \param mk Pointer to master key
+ * \param ms Pointer to master secret (fixed length: 48 bytes)
+ * \param kb Pointer to key block, see RFC 5246 section 6.3
+ * (variable length: 2 * maclen + 2 * keylen + 2 * ivlen).
* \param maclen MAC length
* \param keylen Key length
* \param ivlen IV length
@@ -1099,13 +1100,13 @@
* a specific MBEDTLS_ERR_XXX code.
*/
typedef int mbedtls_ssl_export_keys_t( void *p_expkey,
+ const unsigned char *ms,
const unsigned char *kb,
- const unsigned char *mk,
size_t maclen,
size_t keylen,
size_t ivlen );
#endif /* MBEDTLS_SSL_EXPORT_KEYS */
-
+
/**
* \brief Callback type: parse and load session ticket
*
@@ -1160,15 +1161,11 @@
* \brief Configure key export callback.
* (Default: none.)
*
- * \note This is required for certain uses of TLS, e.g. EAP-TLS
- * (RFC 5216). The key pointers are ephemeral and therefore
- * must not be stored. The keys should not be copied
- * verbatim and should be used specifically for key
- * derivation purposes
+ * \note See \c mbedtls_ssl_export_keys_t.
*
* \param conf SSL configuration context
* \param f_export_keys Callback for exporting keys
- * \param p_export_keys Context shared by the callback
+ * \param p_export_keys Context for the callback
*/
void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf,
mbedtls_ssl_export_keys_t *f_export_keys,
diff --git a/library/ssl_tls.c b/library/ssl_tls.c
index a42fcc5..bc82158 100644
--- a/library/ssl_tls.c
+++ b/library/ssl_tls.c
@@ -862,11 +862,11 @@
}
#endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */
-#if defined(MBEDTLS_SSL_EXPORT_KEYS)
- if( ssl->conf->f_export_keys != NULL)
+#if defined(MBEDTLS_SSL_EXPORT_KEYS)
+ if( ssl->conf->f_export_keys != NULL )
{
- ssl->conf->f_export_keys( ssl->conf->p_export_keys,
- keyblk, session->master,
+ ssl->conf->f_export_keys( ssl->conf->p_export_keys,
+ session->master, keyblk,
transform->maclen, transform->keylen,
iv_copy_len );
}
