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

@@ -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

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