1 /** 2 * \file hkdf.h 3 * 4 * \brief This file contains the HKDF interface. 5 * 6 * The HMAC-based Extract-and-Expand Key Derivation Function (HKDF) is 7 * specified by RFC 5869. 8 */ 9 /* 10 * Copyright The Mbed TLS Contributors 11 * SPDX-License-Identifier: Apache-2.0 OR GPL-2.0-or-later 12 */ 13 #ifndef MBEDTLS_HKDF_H 14 #define MBEDTLS_HKDF_H 15 16 #include "mbedtls/build_info.h" 17 18 #include "mbedtls/md.h" 19 20 /** 21 * \name HKDF Error codes 22 * \{ 23 */ 24 /** Bad input parameters to function. */ 25 #define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA -0x5F80 26 /** \} name */ 27 28 #ifdef __cplusplus 29 extern "C" { 30 #endif 31 32 /** 33 * \brief This is the HMAC-based Extract-and-Expand Key Derivation Function 34 * (HKDF). 35 * 36 * \param md A hash function; md.size denotes the length of the hash 37 * function output in bytes. 38 * \param salt An optional salt value (a non-secret random value); 39 * if the salt is not provided, a string of all zeros of 40 * md.size length is used as the salt. 41 * \param salt_len The length in bytes of the optional \p salt. 42 * \param ikm The input keying material. 43 * \param ikm_len The length in bytes of \p ikm. 44 * \param info An optional context and application specific information 45 * string. This can be a zero-length string. 46 * \param info_len The length of \p info in bytes. 47 * \param okm The output keying material of \p okm_len bytes. 48 * \param okm_len The length of the output keying material in bytes. This 49 * must be less than or equal to 255 * md.size bytes. 50 * 51 * \return 0 on success. 52 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid. 53 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying 54 * MD layer. 55 */ 56 int mbedtls_hkdf(const mbedtls_md_info_t *md, const unsigned char *salt, 57 size_t salt_len, const unsigned char *ikm, size_t ikm_len, 58 const unsigned char *info, size_t info_len, 59 unsigned char *okm, size_t okm_len); 60 61 /** 62 * \brief Take the input keying material \p ikm and extract from it a 63 * fixed-length pseudorandom key \p prk. 64 * 65 * \warning This function should only be used if the security of it has been 66 * studied and established in that particular context (eg. TLS 1.3 67 * key schedule). For standard HKDF security guarantees use 68 * \c mbedtls_hkdf instead. 69 * 70 * \param md A hash function; md.size denotes the length of the 71 * hash function output in bytes. 72 * \param salt An optional salt value (a non-secret random value); 73 * if the salt is not provided, a string of all zeros 74 * of md.size length is used as the salt. 75 * \param salt_len The length in bytes of the optional \p salt. 76 * \param ikm The input keying material. 77 * \param ikm_len The length in bytes of \p ikm. 78 * \param[out] prk A pseudorandom key of at least md.size bytes. 79 * 80 * \return 0 on success. 81 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid. 82 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying 83 * MD layer. 84 */ 85 int mbedtls_hkdf_extract(const mbedtls_md_info_t *md, 86 const unsigned char *salt, size_t salt_len, 87 const unsigned char *ikm, size_t ikm_len, 88 unsigned char *prk); 89 90 /** 91 * \brief Expand the supplied \p prk into several additional pseudorandom 92 * keys, which is the output of the HKDF. 93 * 94 * \warning This function should only be used if the security of it has been 95 * studied and established in that particular context (eg. TLS 1.3 96 * key schedule). For standard HKDF security guarantees use 97 * \c mbedtls_hkdf instead. 98 * 99 * \param md A hash function; md.size denotes the length of the hash 100 * function output in bytes. 101 * \param prk A pseudorandom key of at least md.size bytes. \p prk is 102 * usually the output from the HKDF extract step. 103 * \param prk_len The length in bytes of \p prk. 104 * \param info An optional context and application specific information 105 * string. This can be a zero-length string. 106 * \param info_len The length of \p info in bytes. 107 * \param okm The output keying material of \p okm_len bytes. 108 * \param okm_len The length of the output keying material in bytes. This 109 * must be less than or equal to 255 * md.size bytes. 110 * 111 * \return 0 on success. 112 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid. 113 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying 114 * MD layer. 115 */ 116 int mbedtls_hkdf_expand(const mbedtls_md_info_t *md, const unsigned char *prk, 117 size_t prk_len, const unsigned char *info, 118 size_t info_len, unsigned char *okm, size_t okm_len); 119 120 #ifdef __cplusplus 121 } 122 #endif 123 124 #endif /* hkdf.h */ 125
