From d0a78e91b39e3851b69550d214872a812d1130ac Mon Sep 17 00:00:00 2001 From: Janos Follath Date: Mon, 6 Aug 2018 13:55:46 +0100 Subject: [PATCH 1/2] HKDF: Fix style issue --- include/mbedtls/hkdf.h | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/include/mbedtls/hkdf.h b/include/mbedtls/hkdf.h index 6833e7272e..235c5ad5e3 100644 --- a/include/mbedtls/hkdf.h +++ b/include/mbedtls/hkdf.h @@ -99,8 +99,8 @@ int mbedtls_hkdf_extract( const mbedtls_md_info_t *md, * * \param md A hash function; md.size denotes the length of the hash * function output in bytes. - * \param prk A pseudorandom key of at least md.size bytes. \p prk is usually, - * the output from the HKDF extract step. + * \param prk A pseudorandom key of at least md.size bytes. \p prk is + * usually the output from the HKDF extract step. * \param prk_len The length in bytes of \p prk. * \param info An optional context and application specific information * string. This can be a zero-length string. From 08a4aebc4694640f555b775f3bc4ad0a6a74170e Mon Sep 17 00:00:00 2001 From: Janos Follath Date: Mon, 6 Aug 2018 14:20:15 +0100 Subject: [PATCH 2/2] HKDF: Add warning to partial functions The standard HKDF security guarantees only hold if `mbedtls_hkdf()` is used or if `mbedtls_hkdf_extract()` and `mbedtls_hkdf_expand()` are called in succession carefully and an equivalent way. Making `mbedtls_hkdf_extract()` and `mbedtls_hkdf_expand()` static would prevent any misuse, but doing so would require the TLS 1.3 stack to break abstraction and bypass the module API. To reduce the risk of misuse we add warnings to the function descriptions. --- ChangeLog | 5 +++++ include/mbedtls/hkdf.h | 10 ++++++++++ 2 files changed, 15 insertions(+) diff --git a/ChangeLog b/ChangeLog index bda3de8f5c..5575678830 100644 --- a/ChangeLog +++ b/ChangeLog @@ -6,6 +6,11 @@ Bugfix * Fixes an issue with MBEDTLS_CHACHAPOLY_C which would not compile if MBEDTLS_ARC4_C and MBEDTLS_CIPHER_NULL_CIPHER weren't also defined. #1890 +Changes + * Add warnings to the documentation of the HKDF module to reduce the risk + of misusing the mbedtls_hkdf_extract() and mbedtls_hkdf_expand() + functions. Fixes #1775. Reported by Brian J. Murray. + = mbed TLS 2.12.0 branch released 2018-07-25 Security diff --git a/include/mbedtls/hkdf.h b/include/mbedtls/hkdf.h index 235c5ad5e3..e6ed7cde97 100644 --- a/include/mbedtls/hkdf.h +++ b/include/mbedtls/hkdf.h @@ -73,6 +73,11 @@ int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt, * \brief Take the input keying material \p ikm and extract from it a * fixed-length pseudorandom key \p prk. * + * \warning This function should only be used if the security of it has been + * studied and established in that particular context (eg. TLS 1.3 + * key schedule). For standard HKDF security guarantees use + * \c mbedtls_hkdf instead. + * * \param md A hash function; md.size denotes the length of the * hash function output in bytes. * \param salt An optional salt value (a non-secret random value); @@ -97,6 +102,11 @@ int mbedtls_hkdf_extract( const mbedtls_md_info_t *md, * \brief Expand the supplied \p prk into several additional pseudorandom * keys, which is the output of the HKDF. * + * \warning This function should only be used if the security of it has been + * studied and established in that particular context (eg. TLS 1.3 + * key schedule). For standard HKDF security guarantees use + * \c mbedtls_hkdf instead. + * * \param md A hash function; md.size denotes the length of the hash * function output in bytes. * \param prk A pseudorandom key of at least md.size bytes. \p prk is