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_HASH_H__
26 #define BR_BEARSSL_HASH_H__
36 * For hash function 'xxx', the following elements are defined:
39 * An externally defined instance of br_hash_class.
42 * A macro that evaluates to the output size (in bytes) of the
46 * A macro that evaluates to a symbolic identifier for the hash
47 * function. Such identifiers are used with HMAC and signature
48 * algorithm implementations.
49 * NOTE: the numerical value of these identifiers MUST match the
50 * constants for hash function identification in TLS 1.2 (see RFC
51 * 5246, section 7.4.1.4.1). These are values 1 to 6, for MD5,
52 * SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512, respectively.
55 * Context for an ongoing computation. It is allocated by the
56 * caller, and a pointer to it is passed to all functions. A
57 * context contains no interior pointer, so it can be moved around
58 * and cloned (with a simple memcpy() or equivalent) in order to
59 * capture the function state at some point. Computations that use
60 * distinct context structures are independent of each other. The
61 * first field of br_xxx_context is always a pointer to the
62 * br_xxx_vtable structure; br_xxx_init() sets that pointer.
64 * br_xxx_init(br_xxx_context *ctx)
65 * Initialize the provided context. Previous contents of the structure
66 * are ignored. This calls resets the context to the start of a new
69 * br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)
70 * Add some more bytes to the hash computation represented by the
73 * br_xxx_out(const br_xxx_context *ctx, void *out)
74 * Complete the hash computation and write the result in the provided
75 * buffer. The output buffer MUST be large enough to accomodate the
76 * result. The context is NOT modified by this operation, so this
77 * function can be used to get a "partial hash" while still keeping
78 * the possibility of adding more bytes to the input.
80 * br_xxx_state(const br_xxx_context *ctx, void *out)
81 * Get a copy of the "current state" for the computation so far. For
82 * MD functions (MD5, SHA-1, SHA-2 family), this is the running state
83 * resulting from the processing of the last complete input block.
84 * Returned value is the current input length (in bytes).
86 * br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)
87 * Set the internal state to the provided values. The 'stb' and 'count'
88 * values shall match that which was obtained from br_xxx_state(). This
89 * restores the hash state only if the state values were at an
90 * appropriate block boundary. This does NOT set the 'vtable' pointer
93 * Context structures can be discarded without any explicit deallocation.
94 * Hash function implementations are purely software and don't reserve
95 * any resources outside of the context structure itself.
97 * Implemented hash functions are:
99 * Function Name Output length State length
103 * SHA-224 sha224 28 32
104 * SHA-256 sha256 32 32
105 * SHA-384 sha384 48 64
106 * SHA-512 sha512 64 64
107 * MD5+SHA-1 md5sha1 36 36
109 * (MD5+SHA-1 is the concatenation of MD5 and SHA-1 computed over the
110 * same input; in the implementation, the internal data buffer is
111 * shared, thus making it more memory-efficient than separate MD5 and
112 * SHA-1. It can be useful in implementing SSL 3.0, TLS 1.0 and TLS
116 * An object-oriented API is also available: the first field of the
117 * context is a pointer to a br_hash_class structure, that has the
118 * following contents:
120 * context_size total size of the required context structure
121 * desc descriptor (see below)
122 * init context initialization or reset (function pointer)
123 * update process some more bytes (function pointer)
124 * out get hash output so far (function pointer)
125 * state get copy of internal state (function pointer)
126 * set_state reset the internal state (function pointer)
128 * The descriptor is a combination of the following elements:
129 * bits 0 to 7 hash algorithm identifier
130 * bits 8 to 14 hash output size (in bytes)
131 * bits 15 to 22 hash internal state size (in bytes)
132 * bits 23 to 26 log (base 2) of hash internal block size (in bytes)
133 * bit 28 1 if using MD padding, 0 otherwise
134 * bit 29 1 if MD padding uses a 128-bit bit length, 0 otherwise
135 * bit 30 1 if MD padding is big-endian, 0 otherwise
137 * For function 'xxx', the br_xxx_init() function sets the first field
138 * to a pointer to the relevant br_hash_class instance (i.e.
141 * Users of this object-oriented API may make the following assumptions:
142 * Hash output size is no more than 64 bytes.
143 * Hash internal state size is no more than 64 bytes.
144 * Internal block size is a power of two, no less than 2^4 and no more
146 * For functions that do not have an internal block size that is a
147 * power of 2, the relevant element is 0.
150 typedef struct br_hash_class_ br_hash_class
;
151 struct br_hash_class_
{
154 void (*init
)(const br_hash_class
**ctx
);
155 void (*update
)(const br_hash_class
**ctx
, const void *data
, size_t len
);
156 void (*out
)(const br_hash_class
*const *ctx
, void *dst
);
157 uint64_t (*state
)(const br_hash_class
*const *ctx
, void *dst
);
158 void (*set_state
)(const br_hash_class
**ctx
,
159 const void *stb
, uint64_t count
);
162 #define BR_HASHDESC_ID(id) ((uint32_t)(id) << BR_HASHDESC_ID_OFF)
163 #define BR_HASHDESC_ID_OFF 0
164 #define BR_HASHDESC_ID_MASK 0xFF
166 #define BR_HASHDESC_OUT(size) ((uint32_t)(size) << BR_HASHDESC_OUT_OFF)
167 #define BR_HASHDESC_OUT_OFF 8
168 #define BR_HASHDESC_OUT_MASK 0x7F
170 #define BR_HASHDESC_STATE(size) ((uint32_t)(size) << BR_HASHDESC_STATE_OFF)
171 #define BR_HASHDESC_STATE_OFF 15
172 #define BR_HASHDESC_STATE_MASK 0xFF
174 #define BR_HASHDESC_LBLEN(ls) ((uint32_t)(ls) << BR_HASHDESC_LBLEN_OFF)
175 #define BR_HASHDESC_LBLEN_OFF 23
176 #define BR_HASHDESC_LBLEN_MASK 0x0F
178 #define BR_HASHDESC_MD_PADDING ((uint32_t)1 << 28)
179 #define BR_HASHDESC_MD_PADDING_128 ((uint32_t)1 << 29)
180 #define BR_HASHDESC_MD_PADDING_BE ((uint32_t)1 << 30)
183 * Specific hash functions.
185 * Rules for contexts:
186 * -- No interior pointer.
187 * -- No pointer to external dynamically allocated resources.
188 * -- First field is called 'vtable' and is a pointer to a
189 * const-qualified br_hash_class instance (pointer is set by init()).
190 * -- SHA-224 and SHA-256 contexts are identical.
191 * -- SHA-384 and SHA-512 contexts are identical.
193 * Thus, contexts can be moved and cloned to capture the hash function
194 * current state; and there is no need for any explicit "release" function.
198 #define br_md5_SIZE 16
199 extern const br_hash_class br_md5_vtable
;
201 const br_hash_class
*vtable
;
202 unsigned char buf
[64];
206 void br_md5_init(br_md5_context
*ctx
);
207 void br_md5_update(br_md5_context
*ctx
, const void *data
, size_t len
);
208 void br_md5_out(const br_md5_context
*ctx
, void *out
);
209 uint64_t br_md5_state(const br_md5_context
*ctx
, void *out
);
210 void br_md5_set_state(br_md5_context
*ctx
, const void *stb
, uint64_t count
);
213 #define br_sha1_SIZE 20
214 extern const br_hash_class br_sha1_vtable
;
216 const br_hash_class
*vtable
;
217 unsigned char buf
[64];
221 void br_sha1_init(br_sha1_context
*ctx
);
222 void br_sha1_update(br_sha1_context
*ctx
, const void *data
, size_t len
);
223 void br_sha1_out(const br_sha1_context
*ctx
, void *out
);
224 uint64_t br_sha1_state(const br_sha1_context
*ctx
, void *out
);
225 void br_sha1_set_state(br_sha1_context
*ctx
, const void *stb
, uint64_t count
);
227 #define br_sha224_ID 3
228 #define br_sha224_SIZE 28
229 extern const br_hash_class br_sha224_vtable
;
231 const br_hash_class
*vtable
;
232 unsigned char buf
[64];
236 void br_sha224_init(br_sha224_context
*ctx
);
237 void br_sha224_update(br_sha224_context
*ctx
, const void *data
, size_t len
);
238 void br_sha224_out(const br_sha224_context
*ctx
, void *out
);
239 uint64_t br_sha224_state(const br_sha224_context
*ctx
, void *out
);
240 void br_sha224_set_state(br_sha224_context
*ctx
,
241 const void *stb
, uint64_t count
);
243 #define br_sha256_ID 4
244 #define br_sha256_SIZE 32
245 extern const br_hash_class br_sha256_vtable
;
246 typedef br_sha224_context br_sha256_context
;
247 void br_sha256_init(br_sha256_context
*ctx
);
248 #define br_sha256_update br_sha224_update
249 void br_sha256_out(const br_sha256_context
*ctx
, void *out
);
250 #define br_sha256_state br_sha224_state
251 #define br_sha256_set_state br_sha224_set_state
253 #define br_sha384_ID 5
254 #define br_sha384_SIZE 48
255 extern const br_hash_class br_sha384_vtable
;
257 const br_hash_class
*vtable
;
258 unsigned char buf
[128];
262 void br_sha384_init(br_sha384_context
*ctx
);
263 void br_sha384_update(br_sha384_context
*ctx
, const void *data
, size_t len
);
264 void br_sha384_out(const br_sha384_context
*ctx
, void *out
);
265 uint64_t br_sha384_state(const br_sha384_context
*ctx
, void *out
);
266 void br_sha384_set_state(br_sha384_context
*ctx
,
267 const void *stb
, uint64_t count
);
269 #define br_sha512_ID 6
270 #define br_sha512_SIZE 64
271 extern const br_hash_class br_sha512_vtable
;
272 typedef br_sha384_context br_sha512_context
;
273 void br_sha512_init(br_sha512_context
*ctx
);
274 #define br_sha512_update br_sha384_update
275 void br_sha512_out(const br_sha512_context
*ctx
, void *out
);
276 #define br_sha512_state br_sha384_state
277 #define br_sha512_set_state br_sha384_set_state
280 * "md5sha1" is a special hash function that computes both MD5 and SHA-1
281 * on the same input, and produces a 36-byte output (MD5 and SHA-1
282 * concatenation, in that order). State size is also 36 bytes.
284 #define br_md5sha1_ID 0
285 #define br_md5sha1_SIZE 36
286 extern const br_hash_class br_md5sha1_vtable
;
288 const br_hash_class
*vtable
;
289 unsigned char buf
[64];
292 uint32_t val_sha1
[5];
293 } br_md5sha1_context
;
294 void br_md5sha1_init(br_md5sha1_context
*ctx
);
295 void br_md5sha1_update(br_md5sha1_context
*ctx
, const void *data
, size_t len
);
296 void br_md5sha1_out(const br_md5sha1_context
*ctx
, void *out
);
297 uint64_t br_md5sha1_state(const br_md5sha1_context
*ctx
, void *out
);
298 void br_md5sha1_set_state(br_md5sha1_context
*ctx
,
299 const void *stb
, uint64_t count
);
302 * The br_hash_compat_context type is a type which is large enough to
303 * serve as context for all standard hash functions defined above.
306 const br_hash_class
*vtable
;
308 br_sha1_context sha1
;
309 br_sha224_context sha224
;
310 br_sha256_context sha256
;
311 br_sha384_context sha384
;
312 br_sha512_context sha512
;
313 } br_hash_compat_context
;
316 * The multi-hasher is a construct that handles hashing of the same input
317 * data with several hash functions, with a single shared input buffer.
318 * It can handle MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512
319 * simultaneously, though which functions are activated depends on
320 * the set implementation pointers.
324 unsigned char buf
[128];
328 const br_hash_class
*impl
[6];
329 } br_multihash_context
;
332 * Clear a complete multihash context. This should always be called once
333 * on a given context, before setting implementation pointers.
335 void br_multihash_zero(br_multihash_context
*ctx
);
338 * Set a hash function implementation, identified by ID.
341 br_multihash_setimpl(br_multihash_context
*ctx
,
342 int id
, const br_hash_class
*impl
)
345 * This code relies on hash functions ID being values 1 to 6,
346 * in the MD5 to SHA-512 order.
348 ctx
->impl
[id
- 1] = impl
;
352 * Get the configured hash implementation, identified by ID. This returns
353 * NULL for unsupported hash implementations. The hash identifier MUST
354 * be a valid one (from br_md5_ID to br_sha512_ID, inclusive).
356 static inline const br_hash_class
*
357 br_multihash_getimpl(const br_multihash_context
*ctx
, int id
)
359 return ctx
->impl
[id
- 1];
363 * Reset a multihash context. The hash functions for which implementation
364 * pointers have been set are reset and initialized.
366 void br_multihash_init(br_multihash_context
*ctx
);
369 * Input some bytes into the context.
371 void br_multihash_update(br_multihash_context
*ctx
,
372 const void *data
, size_t len
);
375 * Get the hash of the bytes injected so far, with the specified hash
376 * function. The hash function is given by ID (e.g. br_md5_ID for MD5).
377 * The hash output is written on 'dst'. The hash length is returned (in
378 * bytes); if the specified hash function is not implemented by this
379 * context, then this function returns 0.
381 * Obtaining the hash output does not invalidate the current hashing
382 * operation, thus "partial hashes" can be obtained.
384 size_t br_multihash_out(const br_multihash_context
*ctx
, int id
, void *dst
);
387 * Type for a GHASH implementation. GHASH is a sort of keyed hash meant
388 * to be used to implement GCM in combination with a block cipher (with
391 * The y[] array has length 16 bytes and is used for input and output; in
392 * a complete GHASH run, it starts with an all-zero value. h[] is a 16-byte
393 * value that serves as key (it is derived from the encryption key in GCM,
394 * using the block cipher). The data length (len) is expressed in bytes.
396 * If the data length is not a multiple of 16, then the data is implicitly
397 * padded with zeros up to the next multiple of 16. Thus, when using GHASH
398 * in GCM, this method may be called twice, for the associated data and
399 * for the ciphertext, respectively; the zero-padding implements exactly
402 typedef void (*br_ghash
)(void *y
, const void *h
, const void *data
, size_t len
);
405 * Implementation of GHASH using normal 32x32->64 multiplications. It is
406 * constant-time (if multiplications are constant-time).
408 void br_ghash_ctmul(void *y
, const void *h
, const void *data
, size_t len
);
411 * Implementation of GHASH using normal 32x32->32 multiplications; this
412 * may be faster than br_ghash_ctmul() on platforms for which the inner
413 * multiplication opcode does not yield the upper 32 bits of the product.
414 * It is constant-time (if multiplications are constant-time).
416 void br_ghash_ctmul32(void *y
, const void *h
, const void *data
, size_t len
);
419 * Implementation of GHASH using 64x64->64 multiplications. It is
420 * constant-time (if multiplications are constant-time).
422 void br_ghash_ctmul64(void *y
, const void *h
, const void *data
, size_t len
);