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.
diff --git a/include/mbedtls/hkdf.h b/include/mbedtls/hkdf.h
index 235c5ad..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,6 +102,11 @@
* \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