blob: 07ffe83b23d61ee95c4efd69623c039bfe0f0405 [file] [log] [blame]
Thomas Fossati656864b2016-07-17 08:51:22 +01001/**
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/*
Bence Szépkútia2947ac2020-08-19 16:37:36 +020010 * Copyright The Mbed TLS Contributors
Bence Szépkútif744bd72020-06-05 13:02:18 +020011 * 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:
Thomas Fossati656864b2016-07-17 08:51:22 +010018 *
Ron Eldor420f3582019-07-31 13:58:29 +030019 * 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
Thomas Fossati656864b2016-07-17 08:51:22 +010022 *
Ron Eldor420f3582019-07-31 13:58:29 +030023 * http://www.apache.org/licenses/LICENSE-2.0
Thomas Fossati656864b2016-07-17 08:51:22 +010024 *
Ron Eldor420f3582019-07-31 13:58:29 +030025 * 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.
Thomas Fossati656864b2016-07-17 08:51:22 +010030 *
Bence Szépkútif744bd72020-06-05 13:02:18 +020031 * **********
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 * **********
Thomas Fossati656864b2016-07-17 08:51:22 +010051 */
52#ifndef MBEDTLS_HKDF_H
53#define MBEDTLS_HKDF_H
54
Ron Eldor9cbd1b22018-12-16 12:14:37 +020055#if !defined(MBEDTLS_CONFIG_FILE)
56#include "config.h"
57#else
58#include MBEDTLS_CONFIG_FILE
59#endif
60
Thomas Fossati656864b2016-07-17 08:51:22 +010061#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
71extern "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 */
98int 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 *
Janos Follath08a4aeb2018-08-06 14:20:15 +0100107 * \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 *
Thomas Fossati656864b2016-07-17 08:51:22 +0100112 * \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 */
127int 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 *
Janos Follath08a4aeb2018-08-06 14:20:15 +0100136 * \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 *
Thomas Fossati656864b2016-07-17 08:51:22 +0100141 * \param md A hash function; md.size denotes the length of the hash
142 * function output in bytes.
Janos Follathd0a78e92018-08-06 13:55:46 +0100143 * \param prk A pseudorandom key of at least md.size bytes. \p prk is
144 * usually the output from the HKDF extract step.
Thomas Fossati656864b2016-07-17 08:51:22 +0100145 * \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 */
158int 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 */