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
This commit is contained in:
Manuel Pégourié-Gonnard 2015-10-19 13:52:53 +02:00
parent b7da194939
commit 024b6df3b1
3 changed files with 18 additions and 21 deletions

View file

@ -1181,7 +1181,7 @@
/** /**
* \def MBEDTLS_SSL_EXPORT_KEYS * \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. * This is required for certain users of TLS, e.g. EAP-TLS.
* *
* Comment this macro to disable support for key export * Comment this macro to disable support for key export

View file

@ -545,7 +545,7 @@ struct mbedtls_ssl_config
#endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */ #endif /* MBEDTLS_SSL_SESSION_TICKETS && MBEDTLS_SSL_SRV_C */
#if defined(MBEDTLS_SSL_EXPORT_KEYS) #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 *, int (*f_export_keys)( void *, const unsigned char *,
const unsigned char *, size_t, size_t, size_t ); const unsigned char *, size_t, size_t, size_t );
void *p_export_keys; /*!< context for key export callback */ void *p_export_keys; /*!< context for key export callback */
@ -1080,17 +1080,18 @@ typedef int mbedtls_ssl_ticket_write_t( void *p_ticket,
#if defined(MBEDTLS_SSL_EXPORT_KEYS) #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 * \note This is required for certain uses of TLS, e.g. EAP-TLS
* (RFC 5216). The key pointers are ephemeral and therefore * (RFC 5216) and Thread. The key pointers are ephemeral and
* must not be stored. The keys should not be copied * therefore must not be stored. The master secret and keys
* verbatim and should be used specifically for key * should not be used directly except as an input to a key
* derivation purposes * derivation function.
* *
* \param p_expkey Context for the callback * \param p_expkey Context for the callback
* \param kb Pointer to key block * \param ms Pointer to master secret (fixed length: 48 bytes)
* \param mk Pointer to master key * \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 maclen MAC length
* \param keylen Key length * \param keylen Key length
* \param ivlen IV length * \param ivlen IV length
@ -1099,8 +1100,8 @@ typedef int mbedtls_ssl_ticket_write_t( void *p_ticket,
* a specific MBEDTLS_ERR_XXX code. * a specific MBEDTLS_ERR_XXX code.
*/ */
typedef int mbedtls_ssl_export_keys_t( void *p_expkey, typedef int mbedtls_ssl_export_keys_t( void *p_expkey,
const unsigned char *ms,
const unsigned char *kb, const unsigned char *kb,
const unsigned char *mk,
size_t maclen, size_t maclen,
size_t keylen, size_t keylen,
size_t ivlen ); size_t ivlen );
@ -1160,15 +1161,11 @@ void mbedtls_ssl_conf_session_tickets_cb( mbedtls_ssl_config *conf,
* \brief Configure key export callback. * \brief Configure key export callback.
* (Default: none.) * (Default: none.)
* *
* \note This is required for certain uses of TLS, e.g. EAP-TLS * \note See \c mbedtls_ssl_export_keys_t.
* (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
* *
* \param conf SSL configuration context * \param conf SSL configuration context
* \param f_export_keys Callback for exporting keys * \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, void mbedtls_ssl_conf_export_keys_cb( mbedtls_ssl_config *conf,
mbedtls_ssl_export_keys_t *f_export_keys, mbedtls_ssl_export_keys_t *f_export_keys,

View file

@ -863,10 +863,10 @@ int mbedtls_ssl_derive_keys( mbedtls_ssl_context *ssl )
#endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */ #endif /* MBEDTLS_SSL_HW_RECORD_ACCEL */
#if defined(MBEDTLS_SSL_EXPORT_KEYS) #if defined(MBEDTLS_SSL_EXPORT_KEYS)
if( ssl->conf->f_export_keys != NULL) if( ssl->conf->f_export_keys != NULL )
{ {
ssl->conf->f_export_keys( ssl->conf->p_export_keys, ssl->conf->f_export_keys( ssl->conf->p_export_keys,
keyblk, session->master, session->master, keyblk,
transform->maclen, transform->keylen, transform->maclen, transform->keylen,
iv_copy_len ); iv_copy_len );
} }