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 242