BearSSL

bearssl_hmac.h
Go to the documentation of this file.
1/*
2 * Copyright (c) 2016 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_HMAC_H__
26#define BR_BEARSSL_HMAC_H__
27
28#include <stddef.h>
29#include <stdint.h>
30
31#include "bearssl_hash.h"
32
33#ifdef __cplusplus
34 extern "C" {
35#endif
36
37/** \file bearssl_hmac.h
38 *
39 * # HMAC
40 *
41 * HMAC is initialized with a key and an underlying hash function; it
42 * then fills a "key context". That context contains the processed
43 * key.
44 *
45 * With the key context, a HMAC context can be initialized to process
46 * the input bytes and obtain the MAC output. The key context is not
47 * modified during that process, and can be reused.
48 *
49 * IMPORTANT: HMAC shall be used only with functions that have the
50 * following properties:
51 *
52 * - hash output size does not exceed 64 bytes;
53 * - hash internal state size does not exceed 64 bytes;
54 * - internal block length is a power of 2 between 16 and 256 bytes.
55 */
56
57/**
58 * \brief HMAC key context.
59 *
60 * The HMAC key context is initialised with a hash function implementation
61 * and a secret key. Contents are opaque (callers should not access them
62 * directly). The caller is responsible for allocating the context where
63 * appropriate. Context initialisation and usage incurs no dynamic
64 * allocation, so there is no release function.
65 */
66 typedef struct {
67#ifndef BR_DOXYGEN_IGNORE
68 const br_hash_class *dig_vtable;
69 unsigned char ksi[64], kso[64];
70#endif
71} br_hmac_key_context;
72
73/**
74 * \brief HMAC key context initialisation.
75 *
76 * Initialise the key context with the provided key, using the hash function
77 * identified by `digest_vtable`. This supports arbitrary key lengths.
78 *
79 * \param kc HMAC key context to initialise.
80 * \param digest_vtable pointer to the hash function implementation vtable.
81 * \param key pointer to the HMAC secret key.
82 * \param key_len HMAC secret key length (in bytes).
83 */
84 void br_hmac_key_init(br_hmac_key_context *kc,
85 const br_hash_class *digest_vtable, const void *key, size_t key_len);
86
87/*
88 * \brief Get the underlying hash function.
89 *
90 * This function returns a pointer to the implementation vtable of the
91 * hash function used for this HMAC key context.
92 *
93 * \param kc HMAC key context.
94 * \return the hash function implementation.
95 */
96 static inline const br_hash_class *br_hmac_key_get_digest(
97 const br_hmac_key_context *kc)
98{
99 return kc->dig_vtable;
100}
101
102/**
103 * \brief HMAC computation context.
104 *
105 * The HMAC computation context maintains the state for a single HMAC
106 * computation. It is modified as input bytes are injected. The context
107 * is caller-allocated and has no release function since it does not
108 * dynamically allocate external resources. Its contents are opaque.
109 */
110 typedef struct {
111#ifndef BR_DOXYGEN_IGNORE
112 br_hash_compat_context dig;
113 unsigned char kso[64];
114 size_t out_len;
115#endif
116} br_hmac_context;
117
118/**
119 * \brief HMAC computation initialisation.
120 *
121 * Initialise a HMAC context with a key context. The key context is
122 * unmodified. Relevant data from the key context is immediately copied;
123 * the key context can thus be independently reused, modified or released
124 * without impacting this HMAC computation.
125 *
126 * An explicit output length can be specified; the actual output length
127 * will be the minimum of that value and the natural HMAC output length.
128 * If `out_len` is 0, then the natural HMAC output length is selected. The
129 * "natural output length" is the output length of the underlying hash
130 * function.
131 *
132 * \param ctx HMAC context to initialise.
133 * \param kc HMAC key context (already initialised with the key).
134 * \param out_len HMAC output length (0 to select "natural length").
135 */
136 void br_hmac_init(br_hmac_context *ctx,
137 const br_hmac_key_context *kc, size_t out_len);
138
139/**
140 * \brief Get the HMAC output size.
141 *
142 * The HMAC output size is the number of bytes that will actually be
143 * produced with `br_hmac_out()` with the provided context. This function
144 * MUST NOT be called on a non-initialised HMAC computation context.
145 * The returned value is the minimum of the HMAC natural length (output
146 * size of the underlying hash function) and the `out_len` parameter which
147 * was used with the last `br_hmac_init()` call on that context (if the
148 * initialisation `out_len` parameter was 0, then this function will
149 * return the HMAC natural length).
150 *
151 * \param ctx the (already initialised) HMAC computation context.
152 * \return the HMAC actual output size.
153 */
154 static inline size_t
155 br_hmac_size(br_hmac_context *ctx)
156{
157 return ctx->out_len;
158}
159
160/*
161 * \brief Get the underlying hash function.
162 *
163 * This function returns a pointer to the implementation vtable of the
164 * hash function used for this HMAC context.
165 *
166 * \param hc HMAC context.
167 * \return the hash function implementation.
168 */
169 static inline const br_hash_class *br_hmac_get_digest(
170 const br_hmac_context *hc)
171{
172 return hc->dig.vtable;
173}
174
175/**
176 * \brief Inject some bytes in HMAC.
177 *
178 * The provided `len` bytes are injected as extra input in the HMAC
179 * computation incarnated by the `ctx` HMAC context. It is acceptable
180 * that `len` is zero, in which case `data` is ignored (and may be
181 * `NULL`) and this function does nothing.
182 */
183 void br_hmac_update(br_hmac_context *ctx, const void *data, size_t len);
184
185/**
186 * \brief Compute the HMAC output.
187 *
188 * The destination buffer MUST be large enough to accommodate the result;
189 * its length is at most the "natural length" of HMAC (i.e. the output
190 * length of the underlying hash function). The context is NOT modified;
191 * further bytes may be processed. Thus, "partial HMAC" values can be
192 * efficiently obtained.
193 *
194 * Returned value is the output length (in bytes).
195 *
196 * \param ctx HMAC computation context.
197 * \param out destination buffer for the HMAC output.
198 * \return the produced value length (in bytes).
199 */
200 size_t br_hmac_out(const br_hmac_context *ctx, void *out);
201
202/**
203 * \brief Constant-time HMAC computation.
204 *
205 * This function compute the HMAC output in constant time. Some extra
206 * input bytes are processed, then the output is computed. The extra
207 * input consists in the `len` bytes pointed to by `data`. The `len`
208 * parameter must lie between `min_len` and `max_len` (inclusive);
209 * `max_len` bytes are actually read from `data`. Computing time (and
210 * memory access pattern) will not depend upon the data byte contents or
211 * the value of `len`.
212 *
213 * The output is written in the `out` buffer, that MUST be large enough
214 * to receive it.
215 *
216 * The difference `max_len - min_len` MUST be less than 2<sup>30</sup>
217 * (i.e. about one gigabyte).
218 *
219 * This function computes the output properly only if the underlying
220 * hash function uses MD padding (i.e. MD5, SHA-1, SHA-224, SHA-256,
221 * SHA-384 or SHA-512).
222 *
223 * The provided context is NOT modified.
224 *
225 * \param ctx the (already initialised) HMAC computation context.
226 * \param data the extra input bytes.
227 * \param len the extra input length (in bytes).
228 * \param min_len minimum extra input length (in bytes).
229 * \param max_len maximum extra input length (in bytes).
230 * \param out destination buffer for the HMAC output.
231 * \return the produced value length (in bytes).
232 */
233 size_t br_hmac_outCT(const br_hmac_context *ctx,
234 const void *data, size_t len, size_t min_len, size_t max_len,
235 void *out);
236
237#ifdef __cplusplus
238}
239#endif
240
241#endif
bearssl_hash.h
br_hmac_get_digest
static const br_hash_class * br_hmac_get_digest(const br_hmac_context *hc)
Definition: bearssl_hmac.h:169
br_hmac_update
void br_hmac_update(br_hmac_context *ctx, const void *data, size_t len)
Inject some bytes in HMAC.
br_hmac_out
size_t br_hmac_out(const br_hmac_context *ctx, void *out)
Compute the HMAC output.
br_hmac_key_get_digest
static const br_hash_class * br_hmac_key_get_digest(const br_hmac_key_context *kc)
Definition: bearssl_hmac.h:96
br_hmac_key_init
void br_hmac_key_init(br_hmac_key_context *kc, const br_hash_class *digest_vtable, const void *key, size_t key_len)
HMAC key context initialisation.
br_hmac_init
void br_hmac_init(br_hmac_context *ctx, const br_hmac_key_context *kc, size_t out_len)
HMAC computation initialisation.
br_hmac_outCT
size_t br_hmac_outCT(const br_hmac_context *ctx, const void *data, size_t len, size_t min_len, size_t max_len, void *out)
Constant-time HMAC computation.
br_hmac_size
static size_t br_hmac_size(br_hmac_context *ctx)
Get the HMAC output size.
Definition: bearssl_hmac.h:155
br_hmac_context
HMAC computation context.
Definition: bearssl_hmac.h:110
br_hmac_key_context
HMAC key context.
Definition: bearssl_hmac.h:66
br_hash_compat_context
Aggregate context for configurable hash function support.
Definition: bearssl_hash.h:1077