2 * Copyright (c) 2016 Thomas Pornin <pornin@bolet.org>
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:
12 * The above copyright notice and this permission notice shall be
13 * included in all copies or substantial portions of the Software.
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
25 #ifndef BR_BEARSSL_HMAC_H__
26 #define BR_BEARSSL_HMAC_H__
31 #include "bearssl_hash.h"
37 * HMAC is initialized with a key and an underlying hash function; it
38 * then fills a "key context". That context contains the processed
41 * With the key context, a HMAC context can be initialized to process
42 * the input bytes and obtain the MAC output. The key context is not
43 * modified during that process, and can be reused.
45 * IMPORTANT: HMAC shall be used only with functions that have the
46 * following properties:
47 * hash output size does not exceed 64 bytes
48 * hash internal state size does not exceed 64 bytes
49 * internal block length is a power of 2 between 16 and 256 bytes
56 const br_hash_class
*dig_vtable
;
57 unsigned char ksi
[64], kso
[64];
58 } br_hmac_key_context
;
61 * Initialize the key context with the provided key, using the hash function
62 * identified by digest_class.
64 void br_hmac_key_init(br_hmac_key_context
*kc
,
65 const br_hash_class
*digest_class
, const void *key
, size_t key_len
);
68 * A helper structure that is big enough to accommodate all context
69 * structures for all hash functions for which HMAC is supported.
72 const br_hash_class
*vtable
;
75 br_sha224_context sha224
;
76 br_sha256_context sha256
;
77 br_sha384_context sha384
;
78 br_sha512_context sha512
;
79 } br_hmac_allhash_context
;
82 * Context for an HMAC computation.
85 br_hmac_allhash_context dig
;
86 unsigned char kso
[64];
91 * Initialize a HMAC context with a key context. The key context is
92 * unmodified. Relevant data from the key context is immediately copied;
93 * the key context can thus be independently reused, modified or released
94 * without impacting this HMAC computation.
96 * An explicit output length can be specified; the actual output length
97 * will be the minimum of that value and the natural HMAC output length.
98 * If out_len is 0, then the natural HMAC output length is selected.
100 void br_hmac_init(br_hmac_context
*ctx
,
101 const br_hmac_key_context
*kc
, size_t out_len
);
104 * Get the MAC output size. The context must have been initialized.
106 #define br_hmac_size(ctx) ((ctx)->out_len)
109 * Process some more bytes.
111 void br_hmac_update(br_hmac_context
*ctx
, const void *data
, size_t len
);
114 * Compute the HMAC output. The destination buffer MUST be large enough
115 * to accomodate the result. The context is NOT modified; further bytes
116 * may be processed. Thus, "partial HMAC" values can be efficiently
119 * Returned value is the output length (in bytes).
121 size_t br_hmac_out(const br_hmac_context
*ctx
, void *out
);
124 * Compute the HMAC output in constant time. Some extra input bytes are
125 * processed, then the output is computed. The extra input consists in
126 * the 'len' bytes pointed to by 'data'. The 'len' parameter must lie
127 * between 'min_len' and 'max_len' (inclusive); max_len bytes are
128 * actually read from 'data'. Computing time (and memory access pattern)
129 * will not depend upon the data bytes or the value of 'len'.
131 * The output is written in the 'out' buffer, that MUST be large enough
134 * The difference max_len-min_len MUST be less than 2^30.
136 * This function computes the output properly only if the underlying
137 * hash function uses MD padding (i.e. MD5, SHA-1, SHA-224, SHA-256,
138 * SHA-384 or SHA-512).
140 * The provided context is NOT modified.
142 * Returned value is the MAC length (in bytes).
144 size_t br_hmac_outCT(const br_hmac_context
*ctx
,
145 const void *data
, size_t len
, size_t min_len
, size_t max_len
,