Fixed a spurious warning on some compilers.
[BearSSL] / inc / bearssl_hash.h
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_HASH_H__
26 #define BR_BEARSSL_HASH_H__
27
28 #include <stddef.h>
29 #include <stdint.h>
30 #include <string.h>
31
32 #ifdef __cplusplus
33 extern "C" {
34 #endif
35
36 /** \file bearssl_hash.h
37 *
38 * # Hash Functions
39 *
40 * This file documents the API for hash functions.
41 *
42 *
43 * ## Procedural API
44 *
45 * For each implemented hash function, of name "`xxx`", the following
46 * elements are defined:
47 *
48 * - `br_xxx_vtable`
49 *
50 * An externally defined instance of `br_hash_class`.
51 *
52 * - `br_xxx_SIZE`
53 *
54 * A macro that evaluates to the output size (in bytes) of the
55 * hash function.
56 *
57 * - `br_xxx_ID`
58 *
59 * A macro that evaluates to a symbolic identifier for the hash
60 * function. Such identifiers are used with HMAC and signature
61 * algorithm implementations.
62 *
63 * NOTE: for the "standard" hash functions defined in [the TLS
64 * standard](https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1),
65 * the symbolic identifiers match the constants used in TLS, i.e.
66 * 1 to 6 for MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512,
67 * respectively.
68 *
69 * - `br_xxx_context`
70 *
71 * Context for an ongoing computation. It is allocated by the
72 * caller, and a pointer to it is passed to all functions. A
73 * context contains no interior pointer, so it can be moved around
74 * and cloned (with a simple `memcpy()` or equivalent) in order to
75 * capture the function state at some point. Computations that use
76 * distinct context structures are independent of each other. The
77 * first field of `br_xxx_context` is always a pointer to the
78 * `br_xxx_vtable` structure; `br_xxx_init()` sets that pointer.
79 *
80 * - `br_xxx_init(br_xxx_context *ctx)`
81 *
82 * Initialise the provided context. Previous contents of the structure
83 * are ignored. This calls resets the context to the start of a new
84 * hash computation; it also sets the first field of the context
85 * structure (called `vtable`) to a pointer to the statically
86 * allocated constant `br_xxx_vtable` structure.
87 *
88 * - `br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)`
89 *
90 * Add some more bytes to the hash computation represented by the
91 * provided context.
92 *
93 * - `br_xxx_out(const br_xxx_context *ctx, void *out)`
94 *
95 * Complete the hash computation and write the result in the provided
96 * buffer. The output buffer MUST be large enough to accommodate the
97 * result. The context is NOT modified by this operation, so this
98 * function can be used to get a "partial hash" while still keeping
99 * the possibility of adding more bytes to the input.
100 *
101 * - `br_xxx_state(const br_xxx_context *ctx, void *out)`
102 *
103 * Get a copy of the "current state" for the computation so far. For
104 * MD functions (MD5, SHA-1, SHA-2 family), this is the running state
105 * resulting from the processing of the last complete input block.
106 * Returned value is the current input length (in bytes).
107 *
108 * - `br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)`
109 *
110 * Set the internal state to the provided values. The 'stb' and
111 * 'count' values shall match that which was obtained from
112 * `br_xxx_state()`. This restores the hash state only if the state
113 * values were at an appropriate block boundary. This does NOT set
114 * the `vtable` pointer in the context.
115 *
116 * Context structures can be discarded without any explicit deallocation.
117 * Hash function implementations are purely software and don't reserve
118 * any resources outside of the context structure itself.
119 *
120 *
121 * ## Object-Oriented API
122 *
123 * For each hash function that follows the procedural API described
124 * above, an object-oriented API is also provided. In that API, function
125 * pointers from the vtable (`br_xxx_vtable`) are used. The vtable
126 * incarnates object-oriented programming. An introduction on the OOP
127 * concept used here can be read on the BearSSL Web site:<br />
128 * &nbsp;&nbsp;&nbsp;[https://www.bearssl.org/oop.html](https://www.bearssl.org/oop.html)
129 *
130 * The vtable offers functions called `init()`, `update()`, `out()`,
131 * `set()` and `set_state()`, which are in fact the functions from
132 * the procedural API. That vtable also contains two informative fields:
133 *
134 * - `context_size`
135 *
136 * The size of the context structure (`br_xxx_context`), in bytes.
137 * This can be used by generic implementations to perform dynamic
138 * context allocation.
139 *
140 * - `desc`
141 *
142 * A "descriptor" field that encodes some information on the hash
143 * function: symbolic identifier, output size, state size,
144 * internal block size, details on the padding.
145 *
146 * Users of this object-oriented API (in particular generic HMAC
147 * implementations) may make the following assumptions:
148 *
149 * - Hash output size is no more than 64 bytes.
150 * - Hash internal state size is no more than 64 bytes.
151 * - Internal block size is a power of two, no less than 16 and no more
152 * than 256.
153 *
154 *
155 * ## Implemented Hash Functions
156 *
157 * Implemented hash functions are:
158 *
159 * | Function | Name | Output length | State length |
160 * | :-------- | :------ | :-----------: | :----------: |
161 * | MD5 | md5 | 16 | 16 |
162 * | SHA-1 | sha1 | 20 | 20 |
163 * | SHA-224 | sha224 | 28 | 32 |
164 * | SHA-256 | sha256 | 32 | 32 |
165 * | SHA-384 | sha384 | 48 | 64 |
166 * | SHA-512 | sha512 | 64 | 64 |
167 * | MD5+SHA-1 | md5sha1 | 36 | 36 |
168 *
169 * (MD5+SHA-1 is the concatenation of MD5 and SHA-1 computed over the
170 * same input; in the implementation, the internal data buffer is
171 * shared, thus making it more memory-efficient than separate MD5 and
172 * SHA-1. It can be useful in implementing SSL 3.0, TLS 1.0 and TLS
173 * 1.1.)
174 *
175 *
176 * ## Multi-Hasher
177 *
178 * An aggregate hasher is provided, that can compute several standard
179 * hash functions in parallel. It uses `br_multihash_context` and a
180 * procedural API. It is configured with the implementations (the vtables)
181 * that it should use; it will then compute all these hash functions in
182 * parallel, on the same input. It is meant to be used in cases when the
183 * hash of an object will be used, but the exact hash function is not
184 * known yet (typically, streamed processing on X.509 certificates).
185 *
186 * Only the standard hash functions (MD5, SHA-1, SHA-224, SHA-256, SHA-384
187 * and SHA-512) are supported by the multi-hasher.
188 *
189 *
190 * ## GHASH
191 *
192 * GHASH is not a generic hash function; it is a _universal_ hash function,
193 * which, as the name does not say, means that it CANNOT be used in most
194 * places where a hash function is needed. GHASH is used within the GCM
195 * encryption mode, to provide the checked integrity functionality.
196 *
197 * A GHASH implementation is basically a function that uses the type defined
198 * in this file under the name `br_ghash`:
199 *
200 * typedef void (*br_ghash)(void *y, const void *h, const void *data, size_t len);
201 *
202 * The `y` pointer refers to a 16-byte value which is used as input, and
203 * receives the output of the GHASH invocation. `h` is a 16-byte secret
204 * value (that serves as key). `data` and `len` define the input data.
205 *
206 * Three GHASH implementations are provided, all constant-time, based on
207 * the use of integer multiplications with appropriate masking to cancel
208 * carry propagation.
209 */
210
211 /**
212 * \brief Class type for hash function implementations.
213 *
214 * A `br_hash_class` instance references the methods implementing a hash
215 * function. Constant instances of this structure are defined for each
216 * implemented hash function. Such instances are also called "vtables".
217 *
218 * Vtables are used to support object-oriented programming, as
219 * described on [the BearSSL Web site](https://www.bearssl.org/oop.html).
220 */
221 typedef struct br_hash_class_ br_hash_class;
222 struct br_hash_class_ {
223 /**
224 * \brief Size (in bytes) of the context structure appropriate for
225 * computing this hash function.
226 */
227 size_t context_size;
228
229 /**
230 * \brief Descriptor word that contains information about the hash
231 * function.
232 *
233 * For each word `xxx` described below, use `BR_HASHDESC_xxx_OFF`
234 * and `BR_HASHDESC_xxx_MASK` to access the specific value, as
235 * follows:
236 *
237 * (hf->desc >> BR_HASHDESC_xxx_OFF) & BR_HASHDESC_xxx_MASK
238 *
239 * The defined elements are:
240 *
241 * - `ID`: the symbolic identifier for the function, as defined
242 * in [TLS](https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1)
243 * (MD5 = 1, SHA-1 = 2,...).
244 *
245 * - `OUT`: hash output size, in bytes.
246 *
247 * - `STATE`: internal running state size, in bytes.
248 *
249 * - `LBLEN`: base-2 logarithm for the internal block size, as
250 * defined for HMAC processing (this is 6 for MD5, SHA-1, SHA-224
251 * and SHA-256, since these functions use 64-byte blocks; for
252 * SHA-384 and SHA-512, this is 7, corresponding to their
253 * 128-byte blocks).
254 *
255 * The descriptor may contain a few other flags.
256 */
257 uint32_t desc;
258
259 /**
260 * \brief Initialisation method.
261 *
262 * This method takes as parameter a pointer to a context area,
263 * that it initialises. The first field of the context is set
264 * to this vtable; other elements are initialised for a new hash
265 * computation.
266 *
267 * \param ctx pointer to (the first field of) the context.
268 */
269 void (*init)(const br_hash_class **ctx);
270
271 /**
272 * \brief Data injection method.
273 *
274 * The `len` bytes starting at address `data` are injected into
275 * the running hash computation incarnated by the specified
276 * context. The context is updated accordingly. It is allowed
277 * to have `len == 0`, in which case `data` is ignored (and could
278 * be `NULL`), and nothing happens.
279 * on the input data.
280 *
281 * \param ctx pointer to (the first field of) the context.
282 * \param data pointer to the first data byte to inject.
283 * \param len number of bytes to inject.
284 */
285 void (*update)(const br_hash_class **ctx, const void *data, size_t len);
286
287 /**
288 * \brief Produce hash output.
289 *
290 * The hash output corresponding to all data bytes injected in the
291 * context since the last `init()` call is computed, and written
292 * in the buffer pointed to by `dst`. The hash output size depends
293 * on the implemented hash function (e.g. 16 bytes for MD5).
294 * The context is _not_ modified by this call, so further bytes
295 * may be afterwards injected to continue the current computation.
296 *
297 * \param ctx pointer to (the first field of) the context.
298 * \param dst destination buffer for the hash output.
299 */
300 void (*out)(const br_hash_class *const *ctx, void *dst);
301
302 /**
303 * \brief Get running state.
304 *
305 * This method saves the current running state into the `dst`
306 * buffer. What constitutes the "running state" depends on the
307 * hash function; for Merkle-Damgård hash functions (like
308 * MD5 or SHA-1), this is the output obtained after processing
309 * each block. The number of bytes injected so far is returned.
310 * The context is not modified by this call.
311 *
312 * \param ctx pointer to (the first field of) the context.
313 * \param dst destination buffer for the state.
314 * \return the injected total byte length.
315 */
316 uint64_t (*state)(const br_hash_class *const *ctx, void *dst);
317
318 /**
319 * \brief Set running state.
320 *
321 * This methods replaces the running state for the function.
322 *
323 * \param ctx pointer to (the first field of) the context.
324 * \param stb source buffer for the state.
325 * \param count injected total byte length.
326 */
327 void (*set_state)(const br_hash_class **ctx,
328 const void *stb, uint64_t count);
329 };
330
331 #ifndef BR_DOXYGEN_IGNORE
332 #define BR_HASHDESC_ID(id) ((uint32_t)(id) << BR_HASHDESC_ID_OFF)
333 #define BR_HASHDESC_ID_OFF 0
334 #define BR_HASHDESC_ID_MASK 0xFF
335
336 #define BR_HASHDESC_OUT(size) ((uint32_t)(size) << BR_HASHDESC_OUT_OFF)
337 #define BR_HASHDESC_OUT_OFF 8
338 #define BR_HASHDESC_OUT_MASK 0x7F
339
340 #define BR_HASHDESC_STATE(size) ((uint32_t)(size) << BR_HASHDESC_STATE_OFF)
341 #define BR_HASHDESC_STATE_OFF 15
342 #define BR_HASHDESC_STATE_MASK 0xFF
343
344 #define BR_HASHDESC_LBLEN(ls) ((uint32_t)(ls) << BR_HASHDESC_LBLEN_OFF)
345 #define BR_HASHDESC_LBLEN_OFF 23
346 #define BR_HASHDESC_LBLEN_MASK 0x0F
347
348 #define BR_HASHDESC_MD_PADDING ((uint32_t)1 << 28)
349 #define BR_HASHDESC_MD_PADDING_128 ((uint32_t)1 << 29)
350 #define BR_HASHDESC_MD_PADDING_BE ((uint32_t)1 << 30)
351 #endif
352
353 /*
354 * Specific hash functions.
355 *
356 * Rules for contexts:
357 * -- No interior pointer.
358 * -- No pointer to external dynamically allocated resources.
359 * -- First field is called 'vtable' and is a pointer to a
360 * const-qualified br_hash_class instance (pointer is set by init()).
361 * -- SHA-224 and SHA-256 contexts are identical.
362 * -- SHA-384 and SHA-512 contexts are identical.
363 *
364 * Thus, contexts can be moved and cloned to capture the hash function
365 * current state; and there is no need for any explicit "release" function.
366 */
367
368 /**
369 * \brief Symbolic identifier for MD5.
370 */
371 #define br_md5_ID 1
372
373 /**
374 * \brief MD5 output size (in bytes).
375 */
376 #define br_md5_SIZE 16
377
378 /**
379 * \brief Constant vtable for MD5.
380 */
381 extern const br_hash_class br_md5_vtable;
382
383 /**
384 * \brief MD5 context.
385 *
386 * First field is a pointer to the vtable; it is set by the initialisation
387 * function. Other fields are not supposed to be accessed by user code.
388 */
389 typedef struct {
390 /**
391 * \brief Pointer to vtable for this context.
392 */
393 const br_hash_class *vtable;
394 #ifndef BR_DOXYGEN_IGNORE
395 unsigned char buf[64];
396 uint64_t count;
397 uint32_t val[4];
398 #endif
399 } br_md5_context;
400
401 /**
402 * \brief MD5 context initialisation.
403 *
404 * This function initialises or resets a context for a new MD5
405 * computation. It also sets the vtable pointer.
406 *
407 * \param ctx pointer to the context structure.
408 */
409 void br_md5_init(br_md5_context *ctx);
410
411 /**
412 * \brief Inject some data bytes in a running MD5 computation.
413 *
414 * The provided context is updated with some data bytes. If the number
415 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
416 * and may be `NULL`, and this function does nothing.
417 *
418 * \param ctx pointer to the context structure.
419 * \param data pointer to the injected data.
420 * \param len injected data length (in bytes).
421 */
422 void br_md5_update(br_md5_context *ctx, const void *data, size_t len);
423
424 /**
425 * \brief Compute MD5 output.
426 *
427 * The MD5 output for the concatenation of all bytes injected in the
428 * provided context since the last initialisation or reset call, is
429 * computed and written in the buffer pointed to by `out`. The context
430 * itself is not modified, so extra bytes may be injected afterwards
431 * to continue that computation.
432 *
433 * \param ctx pointer to the context structure.
434 * \param out destination buffer for the hash output.
435 */
436 void br_md5_out(const br_md5_context *ctx, void *out);
437
438 /**
439 * \brief Save MD5 running state.
440 *
441 * The running state for MD5 (output of the last internal block
442 * processing) is written in the buffer pointed to by `out`. The
443 * number of bytes injected since the last initialisation or reset
444 * call is returned. The context is not modified.
445 *
446 * \param ctx pointer to the context structure.
447 * \param out destination buffer for the running state.
448 * \return the injected total byte length.
449 */
450 uint64_t br_md5_state(const br_md5_context *ctx, void *out);
451
452 /**
453 * \brief Restore MD5 running state.
454 *
455 * The running state for MD5 is set to the provided values.
456 *
457 * \param ctx pointer to the context structure.
458 * \param stb source buffer for the running state.
459 * \param count the injected total byte length.
460 */
461 void br_md5_set_state(br_md5_context *ctx, const void *stb, uint64_t count);
462
463 /**
464 * \brief Symbolic identifier for SHA-1.
465 */
466 #define br_sha1_ID 2
467
468 /**
469 * \brief SHA-1 output size (in bytes).
470 */
471 #define br_sha1_SIZE 20
472
473 /**
474 * \brief Constant vtable for SHA-1.
475 */
476 extern const br_hash_class br_sha1_vtable;
477
478 /**
479 * \brief SHA-1 context.
480 *
481 * First field is a pointer to the vtable; it is set by the initialisation
482 * function. Other fields are not supposed to be accessed by user code.
483 */
484 typedef struct {
485 /**
486 * \brief Pointer to vtable for this context.
487 */
488 const br_hash_class *vtable;
489 #ifndef BR_DOXYGEN_IGNORE
490 unsigned char buf[64];
491 uint64_t count;
492 uint32_t val[5];
493 #endif
494 } br_sha1_context;
495
496 /**
497 * \brief SHA-1 context initialisation.
498 *
499 * This function initialises or resets a context for a new SHA-1
500 * computation. It also sets the vtable pointer.
501 *
502 * \param ctx pointer to the context structure.
503 */
504 void br_sha1_init(br_sha1_context *ctx);
505
506 /**
507 * \brief Inject some data bytes in a running SHA-1 computation.
508 *
509 * The provided context is updated with some data bytes. If the number
510 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
511 * and may be `NULL`, and this function does nothing.
512 *
513 * \param ctx pointer to the context structure.
514 * \param data pointer to the injected data.
515 * \param len injected data length (in bytes).
516 */
517 void br_sha1_update(br_sha1_context *ctx, const void *data, size_t len);
518
519 /**
520 * \brief Compute SHA-1 output.
521 *
522 * The SHA-1 output for the concatenation of all bytes injected in the
523 * provided context since the last initialisation or reset call, is
524 * computed and written in the buffer pointed to by `out`. The context
525 * itself is not modified, so extra bytes may be injected afterwards
526 * to continue that computation.
527 *
528 * \param ctx pointer to the context structure.
529 * \param out destination buffer for the hash output.
530 */
531 void br_sha1_out(const br_sha1_context *ctx, void *out);
532
533 /**
534 * \brief Save SHA-1 running state.
535 *
536 * The running state for SHA-1 (output of the last internal block
537 * processing) is written in the buffer pointed to by `out`. The
538 * number of bytes injected since the last initialisation or reset
539 * call is returned. The context is not modified.
540 *
541 * \param ctx pointer to the context structure.
542 * \param out destination buffer for the running state.
543 * \return the injected total byte length.
544 */
545 uint64_t br_sha1_state(const br_sha1_context *ctx, void *out);
546
547 /**
548 * \brief Restore SHA-1 running state.
549 *
550 * The running state for SHA-1 is set to the provided values.
551 *
552 * \param ctx pointer to the context structure.
553 * \param stb source buffer for the running state.
554 * \param count the injected total byte length.
555 */
556 void br_sha1_set_state(br_sha1_context *ctx, const void *stb, uint64_t count);
557
558 /**
559 * \brief Symbolic identifier for SHA-224.
560 */
561 #define br_sha224_ID 3
562
563 /**
564 * \brief SHA-224 output size (in bytes).
565 */
566 #define br_sha224_SIZE 28
567
568 /**
569 * \brief Constant vtable for SHA-224.
570 */
571 extern const br_hash_class br_sha224_vtable;
572
573 /**
574 * \brief SHA-224 context.
575 *
576 * First field is a pointer to the vtable; it is set by the initialisation
577 * function. Other fields are not supposed to be accessed by user code.
578 */
579 typedef struct {
580 /**
581 * \brief Pointer to vtable for this context.
582 */
583 const br_hash_class *vtable;
584 #ifndef BR_DOXYGEN_IGNORE
585 unsigned char buf[64];
586 uint64_t count;
587 uint32_t val[8];
588 #endif
589 } br_sha224_context;
590
591 /**
592 * \brief SHA-224 context initialisation.
593 *
594 * This function initialises or resets a context for a new SHA-224
595 * computation. It also sets the vtable pointer.
596 *
597 * \param ctx pointer to the context structure.
598 */
599 void br_sha224_init(br_sha224_context *ctx);
600
601 /**
602 * \brief Inject some data bytes in a running SHA-224 computation.
603 *
604 * The provided context is updated with some data bytes. If the number
605 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
606 * and may be `NULL`, and this function does nothing.
607 *
608 * \param ctx pointer to the context structure.
609 * \param data pointer to the injected data.
610 * \param len injected data length (in bytes).
611 */
612 void br_sha224_update(br_sha224_context *ctx, const void *data, size_t len);
613
614 /**
615 * \brief Compute SHA-224 output.
616 *
617 * The SHA-224 output for the concatenation of all bytes injected in the
618 * provided context since the last initialisation or reset call, is
619 * computed and written in the buffer pointed to by `out`. The context
620 * itself is not modified, so extra bytes may be injected afterwards
621 * to continue that computation.
622 *
623 * \param ctx pointer to the context structure.
624 * \param out destination buffer for the hash output.
625 */
626 void br_sha224_out(const br_sha224_context *ctx, void *out);
627
628 /**
629 * \brief Save SHA-224 running state.
630 *
631 * The running state for SHA-224 (output of the last internal block
632 * processing) is written in the buffer pointed to by `out`. The
633 * number of bytes injected since the last initialisation or reset
634 * call is returned. The context is not modified.
635 *
636 * \param ctx pointer to the context structure.
637 * \param out destination buffer for the running state.
638 * \return the injected total byte length.
639 */
640 uint64_t br_sha224_state(const br_sha224_context *ctx, void *out);
641
642 /**
643 * \brief Restore SHA-224 running state.
644 *
645 * The running state for SHA-224 is set to the provided values.
646 *
647 * \param ctx pointer to the context structure.
648 * \param stb source buffer for the running state.
649 * \param count the injected total byte length.
650 */
651 void br_sha224_set_state(br_sha224_context *ctx,
652 const void *stb, uint64_t count);
653
654 /**
655 * \brief Symbolic identifier for SHA-256.
656 */
657 #define br_sha256_ID 4
658
659 /**
660 * \brief SHA-256 output size (in bytes).
661 */
662 #define br_sha256_SIZE 32
663
664 /**
665 * \brief Constant vtable for SHA-256.
666 */
667 extern const br_hash_class br_sha256_vtable;
668
669 #ifdef BR_DOXYGEN_IGNORE
670 /**
671 * \brief SHA-256 context.
672 *
673 * First field is a pointer to the vtable; it is set by the initialisation
674 * function. Other fields are not supposed to be accessed by user code.
675 */
676 typedef struct {
677 /**
678 * \brief Pointer to vtable for this context.
679 */
680 const br_hash_class *vtable;
681 } br_sha256_context;
682 #else
683 typedef br_sha224_context br_sha256_context;
684 #endif
685
686 /**
687 * \brief SHA-256 context initialisation.
688 *
689 * This function initialises or resets a context for a new SHA-256
690 * computation. It also sets the vtable pointer.
691 *
692 * \param ctx pointer to the context structure.
693 */
694 void br_sha256_init(br_sha256_context *ctx);
695
696 #ifdef BR_DOXYGEN_IGNORE
697 /**
698 * \brief Inject some data bytes in a running SHA-256 computation.
699 *
700 * The provided context is updated with some data bytes. If the number
701 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
702 * and may be `NULL`, and this function does nothing.
703 *
704 * \param ctx pointer to the context structure.
705 * \param data pointer to the injected data.
706 * \param len injected data length (in bytes).
707 */
708 void br_sha256_update(br_sha256_context *ctx, const void *data, size_t len);
709 #else
710 #define br_sha256_update br_sha224_update
711 #endif
712
713 /**
714 * \brief Compute SHA-256 output.
715 *
716 * The SHA-256 output for the concatenation of all bytes injected in the
717 * provided context since the last initialisation or reset call, is
718 * computed and written in the buffer pointed to by `out`. The context
719 * itself is not modified, so extra bytes may be injected afterwards
720 * to continue that computation.
721 *
722 * \param ctx pointer to the context structure.
723 * \param out destination buffer for the hash output.
724 */
725 void br_sha256_out(const br_sha256_context *ctx, void *out);
726
727 #ifdef BR_DOXYGEN_IGNORE
728 /**
729 * \brief Save SHA-256 running state.
730 *
731 * The running state for SHA-256 (output of the last internal block
732 * processing) is written in the buffer pointed to by `out`. The
733 * number of bytes injected since the last initialisation or reset
734 * call is returned. The context is not modified.
735 *
736 * \param ctx pointer to the context structure.
737 * \param out destination buffer for the running state.
738 * \return the injected total byte length.
739 */
740 uint64_t br_sha256_state(const br_sha256_context *ctx, void *out);
741 #else
742 #define br_sha256_state br_sha224_state
743 #endif
744
745 #ifdef BR_DOXYGEN_IGNORE
746 /**
747 * \brief Restore SHA-256 running state.
748 *
749 * The running state for SHA-256 is set to the provided values.
750 *
751 * \param ctx pointer to the context structure.
752 * \param stb source buffer for the running state.
753 * \param count the injected total byte length.
754 */
755 void br_sha256_set_state(br_sha256_context *ctx,
756 const void *stb, uint64_t count);
757 #else
758 #define br_sha256_set_state br_sha224_set_state
759 #endif
760
761 /**
762 * \brief Symbolic identifier for SHA-384.
763 */
764 #define br_sha384_ID 5
765
766 /**
767 * \brief SHA-384 output size (in bytes).
768 */
769 #define br_sha384_SIZE 48
770
771 /**
772 * \brief Constant vtable for SHA-384.
773 */
774 extern const br_hash_class br_sha384_vtable;
775
776 /**
777 * \brief SHA-384 context.
778 *
779 * First field is a pointer to the vtable; it is set by the initialisation
780 * function. Other fields are not supposed to be accessed by user code.
781 */
782 typedef struct {
783 /**
784 * \brief Pointer to vtable for this context.
785 */
786 const br_hash_class *vtable;
787 #ifndef BR_DOXYGEN_IGNORE
788 unsigned char buf[128];
789 uint64_t count;
790 uint64_t val[8];
791 #endif
792 } br_sha384_context;
793
794 /**
795 * \brief SHA-384 context initialisation.
796 *
797 * This function initialises or resets a context for a new SHA-384
798 * computation. It also sets the vtable pointer.
799 *
800 * \param ctx pointer to the context structure.
801 */
802 void br_sha384_init(br_sha384_context *ctx);
803
804 /**
805 * \brief Inject some data bytes in a running SHA-384 computation.
806 *
807 * The provided context is updated with some data bytes. If the number
808 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
809 * and may be `NULL`, and this function does nothing.
810 *
811 * \param ctx pointer to the context structure.
812 * \param data pointer to the injected data.
813 * \param len injected data length (in bytes).
814 */
815 void br_sha384_update(br_sha384_context *ctx, const void *data, size_t len);
816
817 /**
818 * \brief Compute SHA-384 output.
819 *
820 * The SHA-384 output for the concatenation of all bytes injected in the
821 * provided context since the last initialisation or reset call, is
822 * computed and written in the buffer pointed to by `out`. The context
823 * itself is not modified, so extra bytes may be injected afterwards
824 * to continue that computation.
825 *
826 * \param ctx pointer to the context structure.
827 * \param out destination buffer for the hash output.
828 */
829 void br_sha384_out(const br_sha384_context *ctx, void *out);
830
831 /**
832 * \brief Save SHA-384 running state.
833 *
834 * The running state for SHA-384 (output of the last internal block
835 * processing) is written in the buffer pointed to by `out`. The
836 * number of bytes injected since the last initialisation or reset
837 * call is returned. The context is not modified.
838 *
839 * \param ctx pointer to the context structure.
840 * \param out destination buffer for the running state.
841 * \return the injected total byte length.
842 */
843 uint64_t br_sha384_state(const br_sha384_context *ctx, void *out);
844
845 /**
846 * \brief Restore SHA-384 running state.
847 *
848 * The running state for SHA-384 is set to the provided values.
849 *
850 * \param ctx pointer to the context structure.
851 * \param stb source buffer for the running state.
852 * \param count the injected total byte length.
853 */
854 void br_sha384_set_state(br_sha384_context *ctx,
855 const void *stb, uint64_t count);
856
857 /**
858 * \brief Symbolic identifier for SHA-512.
859 */
860 #define br_sha512_ID 6
861
862 /**
863 * \brief SHA-512 output size (in bytes).
864 */
865 #define br_sha512_SIZE 64
866
867 /**
868 * \brief Constant vtable for SHA-512.
869 */
870 extern const br_hash_class br_sha512_vtable;
871
872 #ifdef BR_DOXYGEN_IGNORE
873 /**
874 * \brief SHA-512 context.
875 *
876 * First field is a pointer to the vtable; it is set by the initialisation
877 * function. Other fields are not supposed to be accessed by user code.
878 */
879 typedef struct {
880 /**
881 * \brief Pointer to vtable for this context.
882 */
883 const br_hash_class *vtable;
884 } br_sha512_context;
885 #else
886 typedef br_sha384_context br_sha512_context;
887 #endif
888
889 /**
890 * \brief SHA-512 context initialisation.
891 *
892 * This function initialises or resets a context for a new SHA-512
893 * computation. It also sets the vtable pointer.
894 *
895 * \param ctx pointer to the context structure.
896 */
897 void br_sha512_init(br_sha512_context *ctx);
898
899 #ifdef BR_DOXYGEN_IGNORE
900 /**
901 * \brief Inject some data bytes in a running SHA-512 computation.
902 *
903 * The provided context is updated with some data bytes. If the number
904 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
905 * and may be `NULL`, and this function does nothing.
906 *
907 * \param ctx pointer to the context structure.
908 * \param data pointer to the injected data.
909 * \param len injected data length (in bytes).
910 */
911 void br_sha512_update(br_sha512_context *ctx, const void *data, size_t len);
912 #else
913 #define br_sha512_update br_sha384_update
914 #endif
915
916 /**
917 * \brief Compute SHA-512 output.
918 *
919 * The SHA-512 output for the concatenation of all bytes injected in the
920 * provided context since the last initialisation or reset call, is
921 * computed and written in the buffer pointed to by `out`. The context
922 * itself is not modified, so extra bytes may be injected afterwards
923 * to continue that computation.
924 *
925 * \param ctx pointer to the context structure.
926 * \param out destination buffer for the hash output.
927 */
928 void br_sha512_out(const br_sha512_context *ctx, void *out);
929
930 #ifdef BR_DOXYGEN_IGNORE
931 /**
932 * \brief Save SHA-512 running state.
933 *
934 * The running state for SHA-512 (output of the last internal block
935 * processing) is written in the buffer pointed to by `out`. The
936 * number of bytes injected since the last initialisation or reset
937 * call is returned. The context is not modified.
938 *
939 * \param ctx pointer to the context structure.
940 * \param out destination buffer for the running state.
941 * \return the injected total byte length.
942 */
943 uint64_t br_sha512_state(const br_sha512_context *ctx, void *out);
944 #else
945 #define br_sha512_state br_sha384_state
946 #endif
947
948 #ifdef BR_DOXYGEN_IGNORE
949 /**
950 * \brief Restore SHA-512 running state.
951 *
952 * The running state for SHA-512 is set to the provided values.
953 *
954 * \param ctx pointer to the context structure.
955 * \param stb source buffer for the running state.
956 * \param count the injected total byte length.
957 */
958 void br_sha512_set_state(br_sha512_context *ctx,
959 const void *stb, uint64_t count);
960 #else
961 #define br_sha512_set_state br_sha384_set_state
962 #endif
963
964 /*
965 * "md5sha1" is a special hash function that computes both MD5 and SHA-1
966 * on the same input, and produces a 36-byte output (MD5 and SHA-1
967 * concatenation, in that order). State size is also 36 bytes.
968 */
969
970 /**
971 * \brief Symbolic identifier for MD5+SHA-1.
972 *
973 * MD5+SHA-1 is the concatenation of MD5 and SHA-1, computed over the
974 * same input. It is not one of the functions identified in TLS, so
975 * we give it a symbolic identifier of value 0.
976 */
977 #define br_md5sha1_ID 0
978
979 /**
980 * \brief MD5+SHA-1 output size (in bytes).
981 */
982 #define br_md5sha1_SIZE 36
983
984 /**
985 * \brief Constant vtable for MD5+SHA-1.
986 */
987 extern const br_hash_class br_md5sha1_vtable;
988
989 /**
990 * \brief MD5+SHA-1 context.
991 *
992 * First field is a pointer to the vtable; it is set by the initialisation
993 * function. Other fields are not supposed to be accessed by user code.
994 */
995 typedef struct {
996 /**
997 * \brief Pointer to vtable for this context.
998 */
999 const br_hash_class *vtable;
1000 #ifndef BR_DOXYGEN_IGNORE
1001 unsigned char buf[64];
1002 uint64_t count;
1003 uint32_t val_md5[4];
1004 uint32_t val_sha1[5];
1005 #endif
1006 } br_md5sha1_context;
1007
1008 /**
1009 * \brief MD5+SHA-1 context initialisation.
1010 *
1011 * This function initialises or resets a context for a new SHA-512
1012 * computation. It also sets the vtable pointer.
1013 *
1014 * \param ctx pointer to the context structure.
1015 */
1016 void br_md5sha1_init(br_md5sha1_context *ctx);
1017
1018 /**
1019 * \brief Inject some data bytes in a running MD5+SHA-1 computation.
1020 *
1021 * The provided context is updated with some data bytes. If the number
1022 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
1023 * and may be `NULL`, and this function does nothing.
1024 *
1025 * \param ctx pointer to the context structure.
1026 * \param data pointer to the injected data.
1027 * \param len injected data length (in bytes).
1028 */
1029 void br_md5sha1_update(br_md5sha1_context *ctx, const void *data, size_t len);
1030
1031 /**
1032 * \brief Compute MD5+SHA-1 output.
1033 *
1034 * The MD5+SHA-1 output for the concatenation of all bytes injected in the
1035 * provided context since the last initialisation or reset call, is
1036 * computed and written in the buffer pointed to by `out`. The context
1037 * itself is not modified, so extra bytes may be injected afterwards
1038 * to continue that computation.
1039 *
1040 * \param ctx pointer to the context structure.
1041 * \param out destination buffer for the hash output.
1042 */
1043 void br_md5sha1_out(const br_md5sha1_context *ctx, void *out);
1044
1045 /**
1046 * \brief Save MD5+SHA-1 running state.
1047 *
1048 * The running state for MD5+SHA-1 (output of the last internal block
1049 * processing) is written in the buffer pointed to by `out`. The
1050 * number of bytes injected since the last initialisation or reset
1051 * call is returned. The context is not modified.
1052 *
1053 * \param ctx pointer to the context structure.
1054 * \param out destination buffer for the running state.
1055 * \return the injected total byte length.
1056 */
1057 uint64_t br_md5sha1_state(const br_md5sha1_context *ctx, void *out);
1058
1059 /**
1060 * \brief Restore MD5+SHA-1 running state.
1061 *
1062 * The running state for MD5+SHA-1 is set to the provided values.
1063 *
1064 * \param ctx pointer to the context structure.
1065 * \param stb source buffer for the running state.
1066 * \param count the injected total byte length.
1067 */
1068 void br_md5sha1_set_state(br_md5sha1_context *ctx,
1069 const void *stb, uint64_t count);
1070
1071 /**
1072 * \brief Aggregate context for configurable hash function support.
1073 *
1074 * The `br_hash_compat_context` type is a type which is large enough to
1075 * serve as context for all standard hash functions defined above.
1076 */
1077 typedef union {
1078 const br_hash_class *vtable;
1079 br_md5_context md5;
1080 br_sha1_context sha1;
1081 br_sha224_context sha224;
1082 br_sha256_context sha256;
1083 br_sha384_context sha384;
1084 br_sha512_context sha512;
1085 br_md5sha1_context md5sha1;
1086 } br_hash_compat_context;
1087
1088 /*
1089 * The multi-hasher is a construct that handles hashing of the same input
1090 * data with several hash functions, with a single shared input buffer.
1091 * It can handle MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512
1092 * simultaneously, though which functions are activated depends on
1093 * the set implementation pointers.
1094 */
1095
1096 /**
1097 * \brief Multi-hasher context structure.
1098 *
1099 * The multi-hasher runs up to six hash functions in the standard TLS list
1100 * (MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512) in parallel, over
1101 * the same input.
1102 *
1103 * The multi-hasher does _not_ follow the OOP structure with a vtable.
1104 * Instead, it is configured with the vtables of the hash functions it
1105 * should run. Structure fields are not supposed to be accessed directly.
1106 */
1107 typedef struct {
1108 #ifndef BR_DOXYGEN_IGNORE
1109 unsigned char buf[128];
1110 uint64_t count;
1111 uint32_t val_32[25];
1112 uint64_t val_64[16];
1113 const br_hash_class *impl[6];
1114 #endif
1115 } br_multihash_context;
1116
1117 /**
1118 * \brief Clear a multi-hasher context.
1119 *
1120 * This should always be called once on a given context, _before_ setting
1121 * the implementation pointers.
1122 *
1123 * \param ctx the multi-hasher context.
1124 */
1125 void br_multihash_zero(br_multihash_context *ctx);
1126
1127 /**
1128 * \brief Set a hash function implementation.
1129 *
1130 * Implementations shall be set _after_ clearing the context (with
1131 * `br_multihash_zero()`) but _before_ initialising the computation
1132 * (with `br_multihash_init()`). The hash function implementation
1133 * MUST be one of the standard hash functions (MD5, SHA-1, SHA-224,
1134 * SHA-256, SHA-384 or SHA-512); it may also be `NULL` to remove
1135 * an implementation from the multi-hasher.
1136 *
1137 * \param ctx the multi-hasher context.
1138 * \param id the hash function symbolic identifier.
1139 * \param impl the hash function vtable, or `NULL`.
1140 */
1141 static inline void
1142 br_multihash_setimpl(br_multihash_context *ctx,
1143 int id, const br_hash_class *impl)
1144 {
1145 /*
1146 * This code relies on hash functions ID being values 1 to 6,
1147 * in the MD5 to SHA-512 order.
1148 */
1149 ctx->impl[id - 1] = impl;
1150 }
1151
1152 /**
1153 * \brief Get a hash function implementation.
1154 *
1155 * This function returns the currently configured vtable for a given
1156 * hash function (by symbolic ID). If no such function was configured in
1157 * the provided multi-hasher context, then this function returns `NULL`.
1158 *
1159 * \param ctx the multi-hasher context.
1160 * \param id the hash function symbolic identifier.
1161 * \return the hash function vtable, or `NULL`.
1162 */
1163 static inline const br_hash_class *
1164 br_multihash_getimpl(const br_multihash_context *ctx, int id)
1165 {
1166 return ctx->impl[id - 1];
1167 }
1168
1169 /**
1170 * \brief Reset a multi-hasher context.
1171 *
1172 * This function prepares the context for a new hashing computation,
1173 * for all implementations configured at that point.
1174 *
1175 * \param ctx the multi-hasher context.
1176 */
1177 void br_multihash_init(br_multihash_context *ctx);
1178
1179 /**
1180 * \brief Inject some data bytes in a running multi-hashing computation.
1181 *
1182 * The provided context is updated with some data bytes. If the number
1183 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
1184 * and may be `NULL`, and this function does nothing.
1185 *
1186 * \param ctx pointer to the context structure.
1187 * \param data pointer to the injected data.
1188 * \param len injected data length (in bytes).
1189 */
1190 void br_multihash_update(br_multihash_context *ctx,
1191 const void *data, size_t len);
1192
1193 /**
1194 * \brief Compute a hash output from a multi-hasher.
1195 *
1196 * The hash output for the concatenation of all bytes injected in the
1197 * provided context since the last initialisation or reset call, is
1198 * computed and written in the buffer pointed to by `dst`. The hash
1199 * function to use is identified by `id` and must be one of the standard
1200 * hash functions. If that hash function was indeed configured in the
1201 * multi-hasher context, the corresponding hash value is written in
1202 * `dst` and its length (in bytes) is returned. If the hash function
1203 * was _not_ configured, then nothing is written in `dst` and 0 is
1204 * returned.
1205 *
1206 * The context itself is not modified, so extra bytes may be injected
1207 * afterwards to continue the hash computations.
1208 *
1209 * \param ctx pointer to the context structure.
1210 * \param id the hash function symbolic identifier.
1211 * \param dst destination buffer for the hash output.
1212 * \return the hash output length (in bytes), or 0.
1213 */
1214 size_t br_multihash_out(const br_multihash_context *ctx, int id, void *dst);
1215
1216 /**
1217 * \brief Type for a GHASH implementation.
1218 *
1219 * GHASH is a sort of keyed hash meant to be used to implement GCM in
1220 * combination with a block cipher (with 16-byte blocks).
1221 *
1222 * The `y` array has length 16 bytes and is used for input and output; in
1223 * a complete GHASH run, it starts with an all-zero value. `h` is a 16-byte
1224 * value that serves as key (it is derived from the encryption key in GCM,
1225 * using the block cipher). The data length (`len`) is expressed in bytes.
1226 * The `y` array is updated.
1227 *
1228 * If the data length is not a multiple of 16, then the data is implicitly
1229 * padded with zeros up to the next multiple of 16. Thus, when using GHASH
1230 * in GCM, this method may be called twice, for the associated data and
1231 * for the ciphertext, respectively; the zero-padding implements exactly
1232 * the GCM rules.
1233 *
1234 * \param y the array to update.
1235 * \param h the GHASH key.
1236 * \param data the input data (may be `NULL` if `len` is zero).
1237 * \param len the input data length (in bytes).
1238 */
1239 typedef void (*br_ghash)(void *y, const void *h, const void *data, size_t len);
1240
1241 /**
1242 * \brief GHASH implementation using multiplications (mixed 32-bit).
1243 *
1244 * This implementation uses multiplications of 32-bit values, with a
1245 * 64-bit result. It is constant-time (if multiplications are
1246 * constant-time).
1247 *
1248 * \param y the array to update.
1249 * \param h the GHASH key.
1250 * \param data the input data (may be `NULL` if `len` is zero).
1251 * \param len the input data length (in bytes).
1252 */
1253 void br_ghash_ctmul(void *y, const void *h, const void *data, size_t len);
1254
1255 /**
1256 * \brief GHASH implementation using multiplications (strict 32-bit).
1257 *
1258 * This implementation uses multiplications of 32-bit values, with a
1259 * 32-bit result. It is usually somewhat slower than `br_ghash_ctmul()`,
1260 * but it is expected to be faster on architectures for which the
1261 * 32-bit multiplication opcode does not yield the upper 32 bits of the
1262 * product. It is constant-time (if multiplications are constant-time).
1263 *
1264 * \param y the array to update.
1265 * \param h the GHASH key.
1266 * \param data the input data (may be `NULL` if `len` is zero).
1267 * \param len the input data length (in bytes).
1268 */
1269 void br_ghash_ctmul32(void *y, const void *h, const void *data, size_t len);
1270
1271 /**
1272 * \brief GHASH implementation using multiplications (64-bit).
1273 *
1274 * This implementation uses multiplications of 64-bit values, with a
1275 * 64-bit result. It is constant-time (if multiplications are
1276 * constant-time). It is substantially faster than `br_ghash_ctmul()`
1277 * and `br_ghash_ctmul32()` on most 64-bit architectures.
1278 *
1279 * \param y the array to update.
1280 * \param h the GHASH key.
1281 * \param data the input data (may be `NULL` if `len` is zero).
1282 * \param len the input data length (in bytes).
1283 */
1284 void br_ghash_ctmul64(void *y, const void *h, const void *data, size_t len);
1285
1286 /**
1287 * \brief GHASH implementation using the `pclmulqdq` opcode (part of the
1288 * AES-NI instructions).
1289 *
1290 * This implementation is available only on x86 platforms where the
1291 * compiler supports the relevant intrinsic functions. Even if the
1292 * compiler supports these functions, the local CPU might not support
1293 * the `pclmulqdq` opcode, meaning that a call will fail with an
1294 * illegal instruction exception. To safely obtain a pointer to this
1295 * function when supported (or 0 otherwise), use `br_ghash_pclmul_get()`.
1296 *
1297 * \param y the array to update.
1298 * \param h the GHASH key.
1299 * \param data the input data (may be `NULL` if `len` is zero).
1300 * \param len the input data length (in bytes).
1301 */
1302 void br_ghash_pclmul(void *y, const void *h, const void *data, size_t len);
1303
1304 /**
1305 * \brief Obtain the `pclmul` GHASH implementation, if available.
1306 *
1307 * If the `pclmul` implementation was compiled in the library (depending
1308 * on the compiler abilities) _and_ the local CPU appears to support the
1309 * opcode, then this function will return a pointer to the
1310 * `br_ghash_pclmul()` function. Otherwise, it will return `0`.
1311 *
1312 * \return the `pclmul` GHASH implementation, or `0`.
1313 */
1314 br_ghash br_ghash_pclmul_get(void);
1315
1316 /**
1317 * \brief GHASH implementation using the POWER8 opcodes.
1318 *
1319 * This implementation is available only on POWER8 platforms (and later).
1320 * To safely obtain a pointer to this function when supported (or 0
1321 * otherwise), use `br_ghash_pwr8_get()`.
1322 *
1323 * \param y the array to update.
1324 * \param h the GHASH key.
1325 * \param data the input data (may be `NULL` if `len` is zero).
1326 * \param len the input data length (in bytes).
1327 */
1328 void br_ghash_pwr8(void *y, const void *h, const void *data, size_t len);
1329
1330 /**
1331 * \brief Obtain the `pwr8` GHASH implementation, if available.
1332 *
1333 * If the `pwr8` implementation was compiled in the library (depending
1334 * on the compiler abilities) _and_ the local CPU appears to support the
1335 * opcode, then this function will return a pointer to the
1336 * `br_ghash_pwr8()` function. Otherwise, it will return `0`.
1337 *
1338 * \return the `pwr8` GHASH implementation, or `0`.
1339 */
1340 br_ghash br_ghash_pwr8_get(void);
1341
1342 #ifdef __cplusplus
1343 }
1344 #endif
1345
1346 #endif