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 * This file is provided under the Apache License 2.0, or the 14 * GNU General Public License v2.0 or later. 15 * 16 * ********** 17 * Apache License 2.0: 18 * 19 * Licensed under the Apache License, Version 2.0 (the "License"); you may 20 * not use this file except in compliance with the License. 21 * You may obtain a copy of the License at 22 * 23 * http://www.apache.org/licenses/LICENSE-2.0 24 * 25 * Unless required by applicable law or agreed to in writing, software 26 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT 27 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 28 * See the License for the specific language governing permissions and 29 * limitations under the License. 30 * 31 * ********** 32 * 33 * ********** 34 * GNU General Public License v2.0 or later: 35 * 36 * This program is free software; you can redistribute it and/or modify 37 * it under the terms of the GNU General Public License as published by 38 * the Free Software Foundation; either version 2 of the License, or 39 * (at your option) any later version. 40 * 41 * This program is distributed in the hope that it will be useful, 42 * but WITHOUT ANY WARRANTY; without even the implied warranty of 43 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 44 * GNU General Public License for more details. 45 * 46 * You should have received a copy of the GNU General Public License along 47 * with this program; if not, write to the Free Software Foundation, Inc., 48 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. 49 * 50 * ********** 51 */ 52 #ifndef MBEDTLS_HKDF_H 53 #define MBEDTLS_HKDF_H 54 55 #if !defined(MBEDTLS_CONFIG_FILE) 56 #include "config.h" 57 #else 58 #include MBEDTLS_CONFIG_FILE 59 #endif 60 61 #include "md.h" 62 63 /** 64 * \name HKDF Error codes 65 * \{ 66 */ 67 #define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA -0x5F80 /**< Bad input parameters to function. */ 68 /* \} name */ 69 70 #ifdef __cplusplus 71 extern "C" { 72 #endif 73 74 /** 75 * \brief This is the HMAC-based Extract-and-Expand Key Derivation Function 76 * (HKDF). 77 * 78 * \param md A hash function; md.size denotes the length of the hash 79 * function output in bytes. 80 * \param salt An optional salt value (a non-secret random value); 81 * if the salt is not provided, a string of all zeros of 82 * md.size length is used as the salt. 83 * \param salt_len The length in bytes of the optional \p salt. 84 * \param ikm The input keying material. 85 * \param ikm_len The length in bytes of \p ikm. 86 * \param info An optional context and application specific information 87 * string. This can be a zero-length string. 88 * \param info_len The length of \p info in bytes. 89 * \param okm The output keying material of \p okm_len bytes. 90 * \param okm_len The length of the output keying material in bytes. This 91 * must be less than or equal to 255 * md.size bytes. 92 * 93 * \return 0 on success. 94 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid. 95 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying 96 * MD layer. 97 */ 98 int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt, 99 size_t salt_len, const unsigned char *ikm, size_t ikm_len, 100 const unsigned char *info, size_t info_len, 101 unsigned char *okm, size_t okm_len ); 102 103 /** 104 * \brief Take the input keying material \p ikm and extract from it a 105 * fixed-length pseudorandom key \p prk. 106 * 107 * \warning This function should only be used if the security of it has been 108 * studied and established in that particular context (eg. TLS 1.3 109 * key schedule). For standard HKDF security guarantees use 110 * \c mbedtls_hkdf instead. 111 * 112 * \param md A hash function; md.size denotes the length of the 113 * hash function output in bytes. 114 * \param salt An optional salt value (a non-secret random value); 115 * if the salt is not provided, a string of all zeros 116 * of md.size length is used as the salt. 117 * \param salt_len The length in bytes of the optional \p salt. 118 * \param ikm The input keying material. 119 * \param ikm_len The length in bytes of \p ikm. 120 * \param[out] prk A pseudorandom key of at least md.size bytes. 121 * 122 * \return 0 on success. 123 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid. 124 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying 125 * MD layer. 126 */ 127 int mbedtls_hkdf_extract( const mbedtls_md_info_t *md, 128 const unsigned char *salt, size_t salt_len, 129 const unsigned char *ikm, size_t ikm_len, 130 unsigned char *prk ); 131 132 /** 133 * \brief Expand the supplied \p prk into several additional pseudorandom 134 * keys, which is the output of the HKDF. 135 * 136 * \warning This function should only be used if the security of it has been 137 * studied and established in that particular context (eg. TLS 1.3 138 * key schedule). For standard HKDF security guarantees use 139 * \c mbedtls_hkdf instead. 140 * 141 * \param md A hash function; md.size denotes the length of the hash 142 * function output in bytes. 143 * \param prk A pseudorandom key of at least md.size bytes. \p prk is 144 * usually the output from the HKDF extract step. 145 * \param prk_len The length in bytes of \p prk. 146 * \param info An optional context and application specific information 147 * string. This can be a zero-length string. 148 * \param info_len The length of \p info in bytes. 149 * \param okm The output keying material of \p okm_len bytes. 150 * \param okm_len The length of the output keying material in bytes. This 151 * must be less than or equal to 255 * md.size bytes. 152 * 153 * \return 0 on success. 154 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid. 155 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying 156 * MD layer. 157 */ 158 int mbedtls_hkdf_expand( const mbedtls_md_info_t *md, const unsigned char *prk, 159 size_t prk_len, const unsigned char *info, 160 size_t info_len, unsigned char *okm, size_t okm_len ); 161 162 #ifdef __cplusplus 163 } 164 #endif 165 166 #endif /* hkdf.h */ 167