BearSSL

bearssl_kdf.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2018 Thomas Pornin <pornin@bolet.org>
3 *
4 * Permission is hereby granted, free of charge, to any person obtaining
5 * a copy of this software and associated documentation files (the
6 * "Software"), to deal in the Software without restriction, including
7 * without limitation the rights to use, copy, modify, merge, publish,
8 * distribute, sublicense, and/or sell copies of the Software, and to
9 * permit persons to whom the Software is furnished to do so, subject to
10 * the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
16 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
17 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
18 * NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS
19 * BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN
20 * ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
21 * CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22 * SOFTWARE.
23 */
24
25#ifndef BR_BEARSSL_KDF_H__
26#define BR_BEARSSL_KDF_H__
27
28#include <stddef.h>
29#include <stdint.h>
30
31#include "bearssl_hash.h"
32#include "bearssl_hmac.h"
33
34#ifdef __cplusplus
35 extern "C" {
36#endif
37
38/** \file bearssl_kdf.h
39 *
40 * # Key Derivation Functions
41 *
42 * KDF are functions that takes a variable length input, and provide a
43 * variable length output, meant to be used to derive subkeys from a
44 * master key.
45 *
46 * ## HKDF
47 *
48 * HKDF is a KDF defined by [RFC 5869](https://tools.ietf.org/html/rfc5869).
49 * It is based on HMAC, itself using an underlying hash function. Any
50 * hash function can be used, as long as it is compatible with the rules
51 * for the HMAC implementation (i.e. output size is 64 bytes or less, hash
52 * internal state size is 64 bytes or less, and the internal block length is
53 * a power of 2 between 16 and 256 bytes). HKDF has two phases:
54 *
55 * - HKDF-Extract: the input data in ingested, along with a "salt" value.
56 *
57 * - HKDF-Expand: the output is produced, from the result of processing
58 * the input and salt, and using an extra non-secret parameter called
59 * "info".
60 *
61 * The "salt" and "info" strings are non-secret and can be empty. Their role
62 * is normally to bind the input and output, respectively, to conventional
63 * identifiers that qualifu them within the used protocol or application.
64 *
65 * The implementation defined in this file uses the following functions:
66 *
67 * - `br_hkdf_init()`: initialize an HKDF context, with a hash function,
68 * and the salt. This starts the HKDF-Extract process.
69 *
70 * - `br_hkdf_inject()`: inject more input bytes. This function may be
71 * called repeatedly if the input data is provided by chunks.
72 *
73 * - `br_hkdf_flip()`: end the HKDF-Extract process, and start the
74 * HKDF-Expand process.
75 *
76 * - `br_hkdf_produce()`: get the next bytes of output. This function
77 * may be called several times to obtain the full output by chunks.
78 * For correct HKDF processing, the same "info" string must be
79 * provided for each call.
80 *
81 * Note that the HKDF total output size (the number of bytes that
82 * HKDF-Expand is willing to produce) is limited: if the hash output size
83 * is _n_ bytes, then the maximum output size is _255*n_.
84 */
85
86/**
87 * \brief HKDF context.
88 *
89 * The HKDF context is initialized with a hash function implementation
90 * and a salt value. Contents are opaque (callers should not access them
91 * directly). The caller is responsible for allocating the context where
92 * appropriate. Context initialisation and usage incurs no dynamic
93 * allocation, so there is no release function.
94 */
95 typedef struct {
96#ifndef BR_DOXYGEN_IGNORE
97 union {
98 br_hmac_context hmac_ctx;
99 br_hmac_key_context prk_ctx;
100 } u;
101 unsigned char buf[64];
102 size_t ptr;
103 size_t dig_len;
104 unsigned chunk_num;
105#endif
106} br_hkdf_context;
107
108/**
109 * \brief HKDF context initialization.
110 *
111 * The underlying hash function and salt value are provided. Arbitrary
112 * salt lengths can be used.
113 *
114 * HKDF makes a difference between a salt of length zero, and an
115 * absent salt (the latter being equivalent to a salt consisting of
116 * bytes of value zero, of the same length as the hash function output).
117 * If `salt_len` is zero, then this function assumes that the salt is
118 * present but of length zero. To specify an _absent_ salt, use
119 * `BR_HKDF_NO_SALT` as `salt` parameter (`salt_len` is then ignored).
120 *
121 * \param hc HKDF context to initialise.
122 * \param digest_vtable pointer to the hash function implementation vtable.
123 * \param salt HKDF-Extract salt.
124 * \param salt_len HKDF-Extract salt length (in bytes).
125 */
126 void br_hkdf_init(br_hkdf_context *hc, const br_hash_class *digest_vtable,
127 const void *salt, size_t salt_len);
128
129/**
130 * \brief The special "absent salt" value for HKDF.
131 */
132#define BR_HKDF_NO_SALT (&br_hkdf_no_salt)
133
134#ifndef BR_DOXYGEN_IGNORE
135 extern const unsigned char br_hkdf_no_salt;
136#endif
137
138/**
139 * \brief HKDF input injection (HKDF-Extract).
140 *
141 * This function injects some more input bytes ("key material") into
142 * HKDF. This function may be called several times, after `br_hkdf_init()`
143 * but before `br_hkdf_flip()`.
144 *
145 * \param hc HKDF context.
146 * \param ikm extra input bytes.
147 * \param ikm_len number of extra input bytes.
148 */
149 void br_hkdf_inject(br_hkdf_context *hc, const void *ikm, size_t ikm_len);
150
151/**
152 * \brief HKDF switch to the HKDF-Expand phase.
153 *
154 * This call terminates the HKDF-Extract process (input injection), and
155 * starts the HKDF-Expand process (output production).
156 *
157 * \param hc HKDF context.
158 */
159 void br_hkdf_flip(br_hkdf_context *hc);
160
161/**
162 * \brief HKDF output production (HKDF-Expand).
163 *
164 * Produce more output bytes from the current state. This function may be
165 * called several times, but only after `br_hkdf_flip()`.
166 *
167 * Returned value is the number of actually produced bytes. The total
168 * output length is limited to 255 times the output length of the
169 * underlying hash function.
170 *
171 * \param hc HKDF context.
172 * \param info application specific information string.
173 * \param info_len application specific information string length (in bytes).
174 * \param out destination buffer for the HKDF output.
175 * \param out_len the length of the requested output (in bytes).
176 * \return the produced output length (in bytes).
177 */
178 size_t br_hkdf_produce(br_hkdf_context *hc,
179 const void *info, size_t info_len, void *out, size_t out_len);
180
181#ifdef __cplusplus
182}
183#endif
184
185#endif
bearssl_hash.h
bearssl_hmac.h
br_hkdf_inject
void br_hkdf_inject(br_hkdf_context *hc, const void *ikm, size_t ikm_len)
HKDF input injection (HKDF-Extract).
br_hkdf_flip
void br_hkdf_flip(br_hkdf_context *hc)
HKDF switch to the HKDF-Expand phase.
br_hkdf_produce
size_t br_hkdf_produce(br_hkdf_context *hc, const void *info, size_t info_len, void *out, size_t out_len)
HKDF output production (HKDF-Expand).
br_hkdf_init
void br_hkdf_init(br_hkdf_context *hc, const br_hash_class *digest_vtable, const void *salt, size_t salt_len)
HKDF context initialization.
br_hkdf_context
HKDF context.
Definition: bearssl_kdf.h:95
br_hmac_context
HMAC computation context.
Definition: bearssl_hmac.h:110
br_hmac_key_context
HMAC key context.
Definition: bearssl_hmac.h:66