Merge remote-tracking branch 'public/pr/1920' into development
diff --git a/ChangeLog b/ChangeLog
index 5d72364..68427ca 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -61,6 +61,11 @@
INTERNAL NOTE: need to bump soversion of libmbedtls:
- added new member 'mtu' to public 'mbedtls_ssl_conf' structure
+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 6833e72..e6ed7cd 100644
--- a/include/mbedtls/hkdf.h
+++ b/include/mbedtls/hkdf.h
@@ -73,6 +73,11 @@
* \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,10 +102,15 @@
* \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 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.