Mbed OS Reference
Loading...
Searching...
No Matches
hkdf.h
Go to the documentation of this file.
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
12 *
13 * Licensed under the Apache License, Version 2.0 (the "License"); you may
14 * not use this file except in compliance with the License.
15 * You may obtain a copy of the License at
16 *
17 * http://www.apache.org/licenses/LICENSE-2.0
18 *
19 * Unless required by applicable law or agreed to in writing, software
20 * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
21 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
22 * See the License for the specific language governing permissions and
23 * limitations under the License.
24 */
25#ifndef MBEDTLS_HKDF_H
26#define MBEDTLS_HKDF_H
27
28#if !defined(MBEDTLS_CONFIG_FILE)
29#include "mbedtls/config.h"
30#else
31#include MBEDTLS_CONFIG_FILE
32#endif
33
34#include "mbedtls/md.h"
35
36/**
37 * \addtogroup mbedtls
38 * \{
39 * \defgroup mbedtls_hkdf_module HKDF
40 * \{
41 */
42
43/**
44 * \name HKDF Error codes
45 * \{
46 */
47#define MBEDTLS_ERR_HKDF_BAD_INPUT_DATA -0x5F80 /**< Bad input parameters to function. */
48/** \} name */
49
50#ifdef __cplusplus
51extern "C" {
52#endif
53
54/**
55 * \brief This is the HMAC-based Extract-and-Expand Key Derivation Function
56 * (HKDF).
57 *
58 * \param md A hash function; md.size denotes the length of the hash
59 * function output in bytes.
60 * \param salt An optional salt value (a non-secret random value);
61 * if the salt is not provided, a string of all zeros of
62 * md.size length is used as the salt.
63 * \param salt_len The length in bytes of the optional \p salt.
64 * \param ikm The input keying material.
65 * \param ikm_len The length in bytes of \p ikm.
66 * \param info An optional context and application specific information
67 * string. This can be a zero-length string.
68 * \param info_len The length of \p info in bytes.
69 * \param okm The output keying material of \p okm_len bytes.
70 * \param okm_len The length of the output keying material in bytes. This
71 * must be less than or equal to 255 * md.size bytes.
72 *
73 * \return 0 on success.
74 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
75 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
76 * MD layer.
77 */
78int mbedtls_hkdf( const mbedtls_md_info_t *md, const unsigned char *salt,
79 size_t salt_len, const unsigned char *ikm, size_t ikm_len,
80 const unsigned char *info, size_t info_len,
81 unsigned char *okm, size_t okm_len );
82
83/**
84 * \brief Take the input keying material \p ikm and extract from it a
85 * fixed-length pseudorandom key \p prk.
86 *
87 * \warning This function should only be used if the security of it has been
88 * studied and established in that particular context (eg. TLS 1.3
89 * key schedule). For standard HKDF security guarantees use
90 * \c mbedtls_hkdf instead.
91 *
92 * \param md A hash function; md.size denotes the length of the
93 * hash function output in bytes.
94 * \param salt An optional salt value (a non-secret random value);
95 * if the salt is not provided, a string of all zeros
96 * of md.size length is used as the salt.
97 * \param salt_len The length in bytes of the optional \p salt.
98 * \param ikm The input keying material.
99 * \param ikm_len The length in bytes of \p ikm.
100 * \param[out] prk A pseudorandom key of at least md.size bytes.
101 *
102 * \return 0 on success.
103 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
104 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
105 * MD layer.
106 */
107int mbedtls_hkdf_extract( const mbedtls_md_info_t *md,
108 const unsigned char *salt, size_t salt_len,
109 const unsigned char *ikm, size_t ikm_len,
110 unsigned char *prk );
111
112/**
113 * \brief Expand the supplied \p prk into several additional pseudorandom
114 * keys, which is the output of the HKDF.
115 *
116 * \warning This function should only be used if the security of it has been
117 * studied and established in that particular context (eg. TLS 1.3
118 * key schedule). For standard HKDF security guarantees use
119 * \c mbedtls_hkdf instead.
120 *
121 * \param md A hash function; md.size denotes the length of the hash
122 * function output in bytes.
123 * \param prk A pseudorandom key of at least md.size bytes. \p prk is
124 * usually the output from the HKDF extract step.
125 * \param prk_len The length in bytes of \p prk.
126 * \param info An optional context and application specific information
127 * string. This can be a zero-length string.
128 * \param info_len The length of \p info in bytes.
129 * \param okm The output keying material of \p okm_len bytes.
130 * \param okm_len The length of the output keying material in bytes. This
131 * must be less than or equal to 255 * md.size bytes.
132 *
133 * \return 0 on success.
134 * \return #MBEDTLS_ERR_HKDF_BAD_INPUT_DATA when the parameters are invalid.
135 * \return An MBEDTLS_ERR_MD_* error for errors returned from the underlying
136 * MD layer.
137 */
138int mbedtls_hkdf_expand( const mbedtls_md_info_t *md, const unsigned char *prk,
139 size_t prk_len, const unsigned char *info,
140 size_t info_len, unsigned char *okm, size_t okm_len );
141
142#ifdef __cplusplus
143}
144#endif
145
146/// \}
147/// \}
148
149#endif /* hkdf.h */
config.h
Configuration options (set of defines)
mbedtls_hkdf_expand
int mbedtls_hkdf_expand(const mbedtls_md_info_t *md, const unsigned char *prk, size_t prk_len, const unsigned char *info, size_t info_len, unsigned char *okm, size_t okm_len)
Expand the supplied prk into several additional pseudorandom keys, which is the output of the HKDF.
mbedtls_hkdf_extract
int mbedtls_hkdf_extract(const mbedtls_md_info_t *md, const unsigned char *salt, size_t salt_len, const unsigned char *ikm, size_t ikm_len, unsigned char *prk)
Take the input keying material ikm and extract from it a fixed-length pseudorandom key prk.
mbedtls_hkdf
int mbedtls_hkdf(const mbedtls_md_info_t *md, const unsigned char *salt, size_t salt_len, const unsigned char *ikm, size_t ikm_len, const unsigned char *info, size_t info_len, unsigned char *okm, size_t okm_len)
This is the HMAC-based Extract-and-Expand Key Derivation Function (HKDF).
md.h
This file contains the generic message-digest wrapper.
info
The key size.
Definition: kvstore_global_api.h:45
mbedtls_md_info_t
Message digest information.
Definition: md_internal.h:46