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__
32 /** \file bearssl_hash.h
36 * This file documents the API for hash functions.
41 * For each implemented hash function, of name "`xxx`", the following
42 * elements are defined:
46 * An externally defined instance of `br_hash_class`.
50 * A macro that evaluates to the output size (in bytes) of the
55 * A macro that evaluates to a symbolic identifier for the hash
56 * function. Such identifiers are used with HMAC and signature
57 * algorithm implementations.
59 * NOTE: for the "standard" hash functions defined in [the TLS
60 * standard](https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1),
61 * the symbolic identifiers match the constants used in TLS, i.e.
62 * 1 to 6 for MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512,
67 * Context for an ongoing computation. It is allocated by the
68 * caller, and a pointer to it is passed to all functions. A
69 * context contains no interior pointer, so it can be moved around
70 * and cloned (with a simple `memcpy()` or equivalent) in order to
71 * capture the function state at some point. Computations that use
72 * distinct context structures are independent of each other. The
73 * first field of `br_xxx_context` is always a pointer to the
74 * `br_xxx_vtable` structure; `br_xxx_init()` sets that pointer.
76 * - `br_xxx_init(br_xxx_context *ctx)`
78 * Initialise the provided context. Previous contents of the structure
79 * are ignored. This calls resets the context to the start of a new
80 * hash computation; it also sets the first field of the context
81 * structure (called `vtable`) to a pointer to the statically
82 * allocated constant `br_xxx_vtable` structure.
84 * - `br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)`
86 * Add some more bytes to the hash computation represented by the
89 * - `br_xxx_out(const br_xxx_context *ctx, void *out)`
91 * Complete the hash computation and write the result in the provided
92 * buffer. The output buffer MUST be large enough to accomodate the
93 * result. The context is NOT modified by this operation, so this
94 * function can be used to get a "partial hash" while still keeping
95 * the possibility of adding more bytes to the input.
97 * - `br_xxx_state(const br_xxx_context *ctx, void *out)`
99 * Get a copy of the "current state" for the computation so far. For
100 * MD functions (MD5, SHA-1, SHA-2 family), this is the running state
101 * resulting from the processing of the last complete input block.
102 * Returned value is the current input length (in bytes).
104 * - `br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)`
106 * Set the internal state to the provided values. The 'stb' and
107 * 'count' values shall match that which was obtained from
108 * `br_xxx_state()`. This restores the hash state only if the state
109 * values were at an appropriate block boundary. This does NOT set
110 * the `vtable` pointer in the context.
112 * Context structures can be discarded without any explicit deallocation.
113 * Hash function implementations are purely software and don't reserve
114 * any resources outside of the context structure itself.
117 * ## Object-Oriented API
119 * For each hash function that follows the procedural API described
120 * above, an object-oriented API is also provided. In that API, function
121 * pointers from the vtable (`br_xxx_vtable`) are used. The vtable
122 * incarnates object-oriented programming. An introduction on the OOP
123 * concept used here can be read on the BearSSL Web site:<br />
124 * [https://www.bearssl.org/oop.html](https://www.bearssl.org/oop.html)
126 * The vtable offers functions called `init()`, `update()`, `out()`,
127 * `set()` and `set_state()`, which are in fact the functions from
128 * the procedural API. That vtable also contains two informative fields:
132 * The size of the context structure (`br_xxx_context`), in bytes.
133 * This can be used by generic implementations to perform dynamic
134 * context allocation.
138 * A "descriptor" field that encodes some information on the hash
139 * function: symbolic identifier, output size, state size,
140 * internal block size, details on the padding.
142 * Users of this object-oriented API (in particular generic HMAC
143 * implementations) may make the following assumptions:
145 * - Hash output size is no more than 64 bytes.
146 * - Hash internal state size is no more than 64 bytes.
147 * - Internal block size is a power of two, no less than 16 and no more
151 * ## Implemented Hash Functions
153 * Implemented hash functions are:
155 * | Function | Name | Output length | State length |
156 * | :-------- | :------ | :-----------: | :----------: |
157 * | MD5 | md5 | 16 | 16 |
158 * | SHA-1 | sha1 | 20 | 20 |
159 * | SHA-224 | sha224 | 28 | 32 |
160 * | SHA-256 | sha256 | 32 | 32 |
161 * | SHA-384 | sha384 | 48 | 64 |
162 * | SHA-512 | sha512 | 64 | 64 |
163 * | MD5+SHA-1 | md5sha1 | 36 | 36 |
165 * (MD5+SHA-1 is the concatenation of MD5 and SHA-1 computed over the
166 * same input; in the implementation, the internal data buffer is
167 * shared, thus making it more memory-efficient than separate MD5 and
168 * SHA-1. It can be useful in implementing SSL 3.0, TLS 1.0 and TLS
174 * An aggregate hasher is provided, that can compute several standard
175 * hash functions in parallel. It uses `br_multihash_context` and a
176 * procedural API. It is configured with the implementations (the vtables)
177 * that it should use; it will then compute all these hash functions in
178 * parallel, on the same input. It is meant to be used in cases when the
179 * hash of an object will be used, but the exact hash function is not
180 * known yet (typically, streamed processing on X.509 certificates).
182 * Only the standard hash functions (MD5, SHA-1, SHA-224, SHA-256, SHA-384
183 * and SHA-512) are supported by the multi-hasher.
188 * GHASH is not a generic hash function; it is a _universal_ hash function,
189 * which, as the name does not say, means that it CANNOT be used in most
190 * places where a hash function is needed. GHASH is used within the GCM
191 * encryption mode, to provide the checked integrity functionality.
193 * A GHASH implementation is basically a function that uses the type defined
194 * in this file under the name `br_ghash`:
196 * typedef void (*br_ghash)(void *y, const void *h, const void *data, size_t len);
198 * The `y` pointer refers to a 16-byte value which is used as input, and
199 * receives the output of the GHASH invocation. `h` is a 16-byte secret
200 * value (that serves as key). `data` and `len` define the input data.
202 * Three GHASH implementations are provided, all constant-time, based on
203 * the use of integer multiplications with appropriate masking to cancel
208 * \brief Class type for hash function implementations.
210 * A `br_hash_class` instance references the methods implementing a hash
211 * function. Constant instances of this structure are defined for each
212 * implemented hash function. Such instances are also called "vtables".
214 * Vtables are used to support object-oriented programming, as
215 * described on [the BearSSL Web site](https://www.bearssl.org/oop.html).
217 typedef struct br_hash_class_ br_hash_class
;
218 struct br_hash_class_
{
220 * \brief Size (in bytes) of the context structure appropriate for
221 * computing this hash function.
226 * \brief Descriptor word that contains information about the hash
229 * For each word `xxx` described below, use `BR_HASHDESC_xxx_OFF`
230 * and `BR_HASHDESC_xxx_MASK` to access the specific value, as
233 * (hf->desc >> BR_HASHDESC_xxx_OFF) & BR_HASHDESC_xxx_MASK
235 * The defined elements are:
237 * - `ID`: the symbolic identifier for the function, as defined
238 * in [TLS](https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1)
239 * (MD5 = 1, SHA-1 = 2,...).
241 * - `OUT`: hash output size, in bytes.
243 * - `STATE`: internal running state size, in bytes.
245 * - `LBLEN`: base-2 logarithm for the internal block size, as
246 * defined for HMAC processing (this is 6 for MD5, SHA-1, SHA-224
247 * and SHA-256, since these functions use 64-byte blocks; for
248 * SHA-384 and SHA-512, this is 7, corresponding to their
251 * The descriptor may contain a few other flags.
256 * \brief Initialisation method.
258 * This method takes as parameter a pointer to a context area,
259 * that it initialises. The first field of the context is set
260 * to this vtable; other elements are initialised for a new hash
263 * \param ctx pointer to (the first field of) the context.
265 void (*init
)(const br_hash_class
**ctx
);
268 * \brief Data injection method.
270 * The `len` bytes starting at address `data` are injected into
271 * the running hash computation incarnated by the specified
272 * context. The context is updated accordingly. It is allowed
273 * to have `len == 0`, in which case `data` is ignored (and could
274 * be `NULL`), and nothing happens.
277 * \param ctx pointer to (the first field of) the context.
278 * \param data pointer to the first data byte to inject.
279 * \param len number of bytes to inject.
281 void (*update
)(const br_hash_class
**ctx
, const void *data
, size_t len
);
284 * \brief Produce hash output.
286 * The hash output corresponding to all data bytes injected in the
287 * context since the last `init()` call is computed, and written
288 * in the buffer pointed to by `dst`. The hash output size depends
289 * on the implemented hash function (e.g. 16 bytes for MD5).
290 * The context is _not_ modified by this call, so further bytes
291 * may be afterwards injected to continue the current computation.
293 * \param ctx pointer to (the first field of) the context.
294 * \param dst destination buffer for the hash output.
296 void (*out
)(const br_hash_class
*const *ctx
, void *dst
);
299 * \brief Get running state.
301 * This method saves the current running state into the `dst`
302 * buffer. What constitutes the "running state" depends on the
303 * hash function; for Merkle-Damgård hash functions (like
304 * MD5 or SHA-1), this is the output obtained after processing
305 * each block. The number of bytes injected so far is returned.
306 * The context is not modified by this call.
308 * \param ctx pointer to (the first field of) the context.
309 * \param dst destination buffer for the state.
310 * \return the injected total byte length.
312 uint64_t (*state
)(const br_hash_class
*const *ctx
, void *dst
);
315 * \brief Set running state.
317 * This methods replaces the running state for the function.
319 * \param ctx pointer to (the first field of) the context.
320 * \param stb source buffer for the state.
321 * \param count injected total byte length.
323 void (*set_state
)(const br_hash_class
**ctx
,
324 const void *stb
, uint64_t count
);
327 #ifndef BR_DOXYGEN_IGNORE
328 #define BR_HASHDESC_ID(id) ((uint32_t)(id) << BR_HASHDESC_ID_OFF)
329 #define BR_HASHDESC_ID_OFF 0
330 #define BR_HASHDESC_ID_MASK 0xFF
332 #define BR_HASHDESC_OUT(size) ((uint32_t)(size) << BR_HASHDESC_OUT_OFF)
333 #define BR_HASHDESC_OUT_OFF 8
334 #define BR_HASHDESC_OUT_MASK 0x7F
336 #define BR_HASHDESC_STATE(size) ((uint32_t)(size) << BR_HASHDESC_STATE_OFF)
337 #define BR_HASHDESC_STATE_OFF 15
338 #define BR_HASHDESC_STATE_MASK 0xFF
340 #define BR_HASHDESC_LBLEN(ls) ((uint32_t)(ls) << BR_HASHDESC_LBLEN_OFF)
341 #define BR_HASHDESC_LBLEN_OFF 23
342 #define BR_HASHDESC_LBLEN_MASK 0x0F
344 #define BR_HASHDESC_MD_PADDING ((uint32_t)1 << 28)
345 #define BR_HASHDESC_MD_PADDING_128 ((uint32_t)1 << 29)
346 #define BR_HASHDESC_MD_PADDING_BE ((uint32_t)1 << 30)
350 * Specific hash functions.
352 * Rules for contexts:
353 * -- No interior pointer.
354 * -- No pointer to external dynamically allocated resources.
355 * -- First field is called 'vtable' and is a pointer to a
356 * const-qualified br_hash_class instance (pointer is set by init()).
357 * -- SHA-224 and SHA-256 contexts are identical.
358 * -- SHA-384 and SHA-512 contexts are identical.
360 * Thus, contexts can be moved and cloned to capture the hash function
361 * current state; and there is no need for any explicit "release" function.
365 * \brief Symbolic identifier for MD5.
370 * \brief MD5 output size (in bytes).
372 #define br_md5_SIZE 16
375 * \brief Constant vtable for MD5.
377 extern const br_hash_class br_md5_vtable
;
380 * \brief MD5 context.
382 * First field is a pointer to the vtable; it is set by the initialisation
383 * function. Other fields are not supposed to be accessed by user code.
387 * \brief Pointer to vtable for this context.
389 const br_hash_class
*vtable
;
390 #ifndef BR_DOXYGEN_IGNORE
391 unsigned char buf
[64];
398 * \brief MD5 context initialisation.
400 * This function initialises or resets a context for a new MD5
401 * computation. It also sets the vtable pointer.
403 * \param ctx pointer to the context structure.
405 void br_md5_init(br_md5_context
*ctx
);
408 * \brief Inject some data bytes in a running MD5 computation.
410 * The provided context is updated with some data bytes. If the number
411 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
412 * and may be `NULL`, and this function does nothing.
414 * \param ctx pointer to the context structure.
415 * \param data pointer to the injected data.
416 * \param len injected data length (in bytes).
418 void br_md5_update(br_md5_context
*ctx
, const void *data
, size_t len
);
421 * \brief Compute MD5 output.
423 * The MD5 output for the concatenation of all bytes injected in the
424 * provided context since the last initialisation or reset call, is
425 * computed and written in the buffer pointed to by `out`. The context
426 * itself is not modified, so extra bytes may be injected afterwards
427 * to continue that computation.
429 * \param ctx pointer to the context structure.
430 * \param out destination buffer for the hash output.
432 void br_md5_out(const br_md5_context
*ctx
, void *out
);
435 * \brief Save MD5 running state.
437 * The running state for MD5 (output of the last internal block
438 * processing) is written in the buffer pointed to by `out`. The
439 * number of bytes injected since the last initialisation or reset
440 * call is returned. The context is not modified.
442 * \param ctx pointer to the context structure.
443 * \param out destination buffer for the running state.
444 * \return the injected total byte length.
446 uint64_t br_md5_state(const br_md5_context
*ctx
, void *out
);
449 * \brief Restore MD5 running state.
451 * The running state for MD5 is set to the provided values.
453 * \param ctx pointer to the context structure.
454 * \param stb source buffer for the running state.
455 * \param count the injected total byte length.
457 void br_md5_set_state(br_md5_context
*ctx
, const void *stb
, uint64_t count
);
460 * \brief Symbolic identifier for SHA-1.
465 * \brief SHA-1 output size (in bytes).
467 #define br_sha1_SIZE 20
470 * \brief Constant vtable for SHA-1.
472 extern const br_hash_class br_sha1_vtable
;
475 * \brief SHA-1 context.
477 * First field is a pointer to the vtable; it is set by the initialisation
478 * function. Other fields are not supposed to be accessed by user code.
482 * \brief Pointer to vtable for this context.
484 const br_hash_class
*vtable
;
485 #ifndef BR_DOXYGEN_IGNORE
486 unsigned char buf
[64];
493 * \brief SHA-1 context initialisation.
495 * This function initialises or resets a context for a new SHA-1
496 * computation. It also sets the vtable pointer.
498 * \param ctx pointer to the context structure.
500 void br_sha1_init(br_sha1_context
*ctx
);
503 * \brief Inject some data bytes in a running SHA-1 computation.
505 * The provided context is updated with some data bytes. If the number
506 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
507 * and may be `NULL`, and this function does nothing.
509 * \param ctx pointer to the context structure.
510 * \param data pointer to the injected data.
511 * \param len injected data length (in bytes).
513 void br_sha1_update(br_sha1_context
*ctx
, const void *data
, size_t len
);
516 * \brief Compute SHA-1 output.
518 * The SHA-1 output for the concatenation of all bytes injected in the
519 * provided context since the last initialisation or reset call, is
520 * computed and written in the buffer pointed to by `out`. The context
521 * itself is not modified, so extra bytes may be injected afterwards
522 * to continue that computation.
524 * \param ctx pointer to the context structure.
525 * \param out destination buffer for the hash output.
527 void br_sha1_out(const br_sha1_context
*ctx
, void *out
);
530 * \brief Save SHA-1 running state.
532 * The running state for SHA-1 (output of the last internal block
533 * processing) is written in the buffer pointed to by `out`. The
534 * number of bytes injected since the last initialisation or reset
535 * call is returned. The context is not modified.
537 * \param ctx pointer to the context structure.
538 * \param out destination buffer for the running state.
539 * \return the injected total byte length.
541 uint64_t br_sha1_state(const br_sha1_context
*ctx
, void *out
);
544 * \brief Restore SHA-1 running state.
546 * The running state for SHA-1 is set to the provided values.
548 * \param ctx pointer to the context structure.
549 * \param stb source buffer for the running state.
550 * \param count the injected total byte length.
552 void br_sha1_set_state(br_sha1_context
*ctx
, const void *stb
, uint64_t count
);
555 * \brief Symbolic identifier for SHA-224.
557 #define br_sha224_ID 3
560 * \brief SHA-224 output size (in bytes).
562 #define br_sha224_SIZE 28
565 * \brief Constant vtable for SHA-224.
567 extern const br_hash_class br_sha224_vtable
;
570 * \brief SHA-224 context.
572 * First field is a pointer to the vtable; it is set by the initialisation
573 * function. Other fields are not supposed to be accessed by user code.
577 * \brief Pointer to vtable for this context.
579 const br_hash_class
*vtable
;
580 #ifndef BR_DOXYGEN_IGNORE
581 unsigned char buf
[64];
588 * \brief SHA-224 context initialisation.
590 * This function initialises or resets a context for a new SHA-224
591 * computation. It also sets the vtable pointer.
593 * \param ctx pointer to the context structure.
595 void br_sha224_init(br_sha224_context
*ctx
);
598 * \brief Inject some data bytes in a running SHA-224 computation.
600 * The provided context is updated with some data bytes. If the number
601 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
602 * and may be `NULL`, and this function does nothing.
604 * \param ctx pointer to the context structure.
605 * \param data pointer to the injected data.
606 * \param len injected data length (in bytes).
608 void br_sha224_update(br_sha224_context
*ctx
, const void *data
, size_t len
);
611 * \brief Compute SHA-224 output.
613 * The SHA-224 output for the concatenation of all bytes injected in the
614 * provided context since the last initialisation or reset call, is
615 * computed and written in the buffer pointed to by `out`. The context
616 * itself is not modified, so extra bytes may be injected afterwards
617 * to continue that computation.
619 * \param ctx pointer to the context structure.
620 * \param out destination buffer for the hash output.
622 void br_sha224_out(const br_sha224_context
*ctx
, void *out
);
625 * \brief Save SHA-224 running state.
627 * The running state for SHA-224 (output of the last internal block
628 * processing) is written in the buffer pointed to by `out`. The
629 * number of bytes injected since the last initialisation or reset
630 * call is returned. The context is not modified.
632 * \param ctx pointer to the context structure.
633 * \param out destination buffer for the running state.
634 * \return the injected total byte length.
636 uint64_t br_sha224_state(const br_sha224_context
*ctx
, void *out
);
639 * \brief Restore SHA-224 running state.
641 * The running state for SHA-224 is set to the provided values.
643 * \param ctx pointer to the context structure.
644 * \param stb source buffer for the running state.
645 * \param count the injected total byte length.
647 void br_sha224_set_state(br_sha224_context
*ctx
,
648 const void *stb
, uint64_t count
);
651 * \brief Symbolic identifier for SHA-256.
653 #define br_sha256_ID 4
656 * \brief SHA-256 output size (in bytes).
658 #define br_sha256_SIZE 32
661 * \brief Constant vtable for SHA-256.
663 extern const br_hash_class br_sha256_vtable
;
665 #ifdef BR_DOXYGEN_IGNORE
667 * \brief SHA-256 context.
669 * First field is a pointer to the vtable; it is set by the initialisation
670 * function. Other fields are not supposed to be accessed by user code.
674 * \brief Pointer to vtable for this context.
676 const br_hash_class
*vtable
;
679 typedef br_sha224_context br_sha256_context
;
683 * \brief SHA-256 context initialisation.
685 * This function initialises or resets a context for a new SHA-256
686 * computation. It also sets the vtable pointer.
688 * \param ctx pointer to the context structure.
690 void br_sha256_init(br_sha256_context
*ctx
);
692 #ifdef BR_DOXYGEN_IGNORE
694 * \brief Inject some data bytes in a running SHA-256 computation.
696 * The provided context is updated with some data bytes. If the number
697 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
698 * and may be `NULL`, and this function does nothing.
700 * \param ctx pointer to the context structure.
701 * \param data pointer to the injected data.
702 * \param len injected data length (in bytes).
704 void br_sha256_update(br_sha256_context
*ctx
, const void *data
, size_t len
);
706 #define br_sha256_update br_sha224_update
710 * \brief Compute SHA-256 output.
712 * The SHA-256 output for the concatenation of all bytes injected in the
713 * provided context since the last initialisation or reset call, is
714 * computed and written in the buffer pointed to by `out`. The context
715 * itself is not modified, so extra bytes may be injected afterwards
716 * to continue that computation.
718 * \param ctx pointer to the context structure.
719 * \param out destination buffer for the hash output.
721 void br_sha256_out(const br_sha256_context
*ctx
, void *out
);
723 #if BR_DOXYGEN_IGNORE
725 * \brief Save SHA-256 running state.
727 * The running state for SHA-256 (output of the last internal block
728 * processing) is written in the buffer pointed to by `out`. The
729 * number of bytes injected since the last initialisation or reset
730 * call is returned. The context is not modified.
732 * \param ctx pointer to the context structure.
733 * \param out destination buffer for the running state.
734 * \return the injected total byte length.
736 uint64_t br_sha256_state(const br_sha256_context
*ctx
, void *out
);
738 #define br_sha256_state br_sha224_state
741 #if BR_DOXYGEN_IGNORE
743 * \brief Restore SHA-256 running state.
745 * The running state for SHA-256 is set to the provided values.
747 * \param ctx pointer to the context structure.
748 * \param stb source buffer for the running state.
749 * \param count the injected total byte length.
751 void br_sha256_set_state(br_sha256_context
*ctx
,
752 const void *stb
, uint64_t count
);
754 #define br_sha256_set_state br_sha224_set_state
758 * \brief Symbolic identifier for SHA-384.
760 #define br_sha384_ID 5
763 * \brief SHA-384 output size (in bytes).
765 #define br_sha384_SIZE 48
768 * \brief Constant vtable for SHA-384.
770 extern const br_hash_class br_sha384_vtable
;
773 * \brief SHA-384 context.
775 * First field is a pointer to the vtable; it is set by the initialisation
776 * function. Other fields are not supposed to be accessed by user code.
780 * \brief Pointer to vtable for this context.
782 const br_hash_class
*vtable
;
783 #ifndef BR_DOXYGEN_IGNORE
784 unsigned char buf
[128];
791 * \brief SHA-384 context initialisation.
793 * This function initialises or resets a context for a new SHA-384
794 * computation. It also sets the vtable pointer.
796 * \param ctx pointer to the context structure.
798 void br_sha384_init(br_sha384_context
*ctx
);
801 * \brief Inject some data bytes in a running SHA-384 computation.
803 * The provided context is updated with some data bytes. If the number
804 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
805 * and may be `NULL`, and this function does nothing.
807 * \param ctx pointer to the context structure.
808 * \param data pointer to the injected data.
809 * \param len injected data length (in bytes).
811 void br_sha384_update(br_sha384_context
*ctx
, const void *data
, size_t len
);
814 * \brief Compute SHA-384 output.
816 * The SHA-384 output for the concatenation of all bytes injected in the
817 * provided context since the last initialisation or reset call, is
818 * computed and written in the buffer pointed to by `out`. The context
819 * itself is not modified, so extra bytes may be injected afterwards
820 * to continue that computation.
822 * \param ctx pointer to the context structure.
823 * \param out destination buffer for the hash output.
825 void br_sha384_out(const br_sha384_context
*ctx
, void *out
);
828 * \brief Save SHA-384 running state.
830 * The running state for SHA-384 (output of the last internal block
831 * processing) is written in the buffer pointed to by `out`. The
832 * number of bytes injected since the last initialisation or reset
833 * call is returned. The context is not modified.
835 * \param ctx pointer to the context structure.
836 * \param out destination buffer for the running state.
837 * \return the injected total byte length.
839 uint64_t br_sha384_state(const br_sha384_context
*ctx
, void *out
);
842 * \brief Restore SHA-384 running state.
844 * The running state for SHA-384 is set to the provided values.
846 * \param ctx pointer to the context structure.
847 * \param stb source buffer for the running state.
848 * \param count the injected total byte length.
850 void br_sha384_set_state(br_sha384_context
*ctx
,
851 const void *stb
, uint64_t count
);
854 * \brief Symbolic identifier for SHA-512.
856 #define br_sha512_ID 6
859 * \brief SHA-512 output size (in bytes).
861 #define br_sha512_SIZE 64
864 * \brief Constant vtable for SHA-512.
866 extern const br_hash_class br_sha512_vtable
;
868 #ifdef BR_DOXYGEN_IGNORE
870 * \brief SHA-512 context.
872 * First field is a pointer to the vtable; it is set by the initialisation
873 * function. Other fields are not supposed to be accessed by user code.
877 * \brief Pointer to vtable for this context.
879 const br_hash_class
*vtable
;
882 typedef br_sha384_context br_sha512_context
;
886 * \brief SHA-512 context initialisation.
888 * This function initialises or resets a context for a new SHA-512
889 * computation. It also sets the vtable pointer.
891 * \param ctx pointer to the context structure.
893 void br_sha512_init(br_sha512_context
*ctx
);
895 #ifdef BR_DOXYGEN_IGNORE
897 * \brief Inject some data bytes in a running SHA-512 computation.
899 * The provided context is updated with some data bytes. If the number
900 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
901 * and may be `NULL`, and this function does nothing.
903 * \param ctx pointer to the context structure.
904 * \param data pointer to the injected data.
905 * \param len injected data length (in bytes).
907 void br_sha512_update(br_sha512_context
*ctx
, const void *data
, size_t len
);
909 #define br_sha512_update br_sha384_update
913 * \brief Compute SHA-512 output.
915 * The SHA-512 output for the concatenation of all bytes injected in the
916 * provided context since the last initialisation or reset call, is
917 * computed and written in the buffer pointed to by `out`. The context
918 * itself is not modified, so extra bytes may be injected afterwards
919 * to continue that computation.
921 * \param ctx pointer to the context structure.
922 * \param out destination buffer for the hash output.
924 void br_sha512_out(const br_sha512_context
*ctx
, void *out
);
926 #ifdef BR_DOXYGEN_IGNORE
928 * \brief Save SHA-512 running state.
930 * The running state for SHA-512 (output of the last internal block
931 * processing) is written in the buffer pointed to by `out`. The
932 * number of bytes injected since the last initialisation or reset
933 * call is returned. The context is not modified.
935 * \param ctx pointer to the context structure.
936 * \param out destination buffer for the running state.
937 * \return the injected total byte length.
939 uint64_t br_sha512_state(const br_sha512_context
*ctx
, void *out
);
941 #define br_sha512_state br_sha384_state
944 #ifdef BR_DOXYGEN_IGNORE
946 * \brief Restore SHA-512 running state.
948 * The running state for SHA-512 is set to the provided values.
950 * \param ctx pointer to the context structure.
951 * \param stb source buffer for the running state.
952 * \param count the injected total byte length.
954 void br_sha512_set_state(br_sha512_context
*ctx
,
955 const void *stb
, uint64_t count
);
957 #define br_sha512_set_state br_sha384_set_state
961 * "md5sha1" is a special hash function that computes both MD5 and SHA-1
962 * on the same input, and produces a 36-byte output (MD5 and SHA-1
963 * concatenation, in that order). State size is also 36 bytes.
967 * \brief Symbolic identifier for MD5+SHA-1.
969 * MD5+SHA-1 is the concatenation of MD5 and SHA-1, computed over the
970 * same input. It is not one of the functions identified in TLS, so
971 * we give it a symbolic identifier of value 0.
973 #define br_md5sha1_ID 0
976 * \brief MD5+SHA-1 output size (in bytes).
978 #define br_md5sha1_SIZE 36
981 * \brief Constant vtable for MD5+SHA-1.
983 extern const br_hash_class br_md5sha1_vtable
;
986 * \brief MD5+SHA-1 context.
988 * First field is a pointer to the vtable; it is set by the initialisation
989 * function. Other fields are not supposed to be accessed by user code.
993 * \brief Pointer to vtable for this context.
995 const br_hash_class
*vtable
;
996 #ifndef BR_DOXYGEN_IGNORE
997 unsigned char buf
[64];
1000 uint32_t val_sha1
[5];
1002 } br_md5sha1_context
;
1005 * \brief MD5+SHA-1 context initialisation.
1007 * This function initialises or resets a context for a new SHA-512
1008 * computation. It also sets the vtable pointer.
1010 * \param ctx pointer to the context structure.
1012 void br_md5sha1_init(br_md5sha1_context
*ctx
);
1015 * \brief Inject some data bytes in a running MD5+SHA-1 computation.
1017 * The provided context is updated with some data bytes. If the number
1018 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
1019 * and may be `NULL`, and this function does nothing.
1021 * \param ctx pointer to the context structure.
1022 * \param data pointer to the injected data.
1023 * \param len injected data length (in bytes).
1025 void br_md5sha1_update(br_md5sha1_context
*ctx
, const void *data
, size_t len
);
1028 * \brief Compute MD5+SHA-1 output.
1030 * The MD5+SHA-1 output for the concatenation of all bytes injected in the
1031 * provided context since the last initialisation or reset call, is
1032 * computed and written in the buffer pointed to by `out`. The context
1033 * itself is not modified, so extra bytes may be injected afterwards
1034 * to continue that computation.
1036 * \param ctx pointer to the context structure.
1037 * \param out destination buffer for the hash output.
1039 void br_md5sha1_out(const br_md5sha1_context
*ctx
, void *out
);
1042 * \brief Save MD5+SHA-1 running state.
1044 * The running state for MD5+SHA-1 (output of the last internal block
1045 * processing) is written in the buffer pointed to by `out`. The
1046 * number of bytes injected since the last initialisation or reset
1047 * call is returned. The context is not modified.
1049 * \param ctx pointer to the context structure.
1050 * \param out destination buffer for the running state.
1051 * \return the injected total byte length.
1053 uint64_t br_md5sha1_state(const br_md5sha1_context
*ctx
, void *out
);
1056 * \brief Restore MD5+SHA-1 running state.
1058 * The running state for MD5+SHA-1 is set to the provided values.
1060 * \param ctx pointer to the context structure.
1061 * \param stb source buffer for the running state.
1062 * \param count the injected total byte length.
1064 void br_md5sha1_set_state(br_md5sha1_context
*ctx
,
1065 const void *stb
, uint64_t count
);
1068 * \brief Aggregate context for configurable hash function support.
1070 * The `br_hash_compat_context` type is a type which is large enough to
1071 * serve as context for all standard hash functions defined above.
1074 const br_hash_class
*vtable
;
1076 br_sha1_context sha1
;
1077 br_sha224_context sha224
;
1078 br_sha256_context sha256
;
1079 br_sha384_context sha384
;
1080 br_sha512_context sha512
;
1081 br_md5sha1_context md5sha1
;
1082 } br_hash_compat_context
;
1085 * The multi-hasher is a construct that handles hashing of the same input
1086 * data with several hash functions, with a single shared input buffer.
1087 * It can handle MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512
1088 * simultaneously, though which functions are activated depends on
1089 * the set implementation pointers.
1093 * \brief Multi-hasher context structure.
1095 * The multi-hasher runs up to six hash functions in the standard TLS list
1096 * (MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512) in parallel, over
1099 * The multi-hasher does _not_ follow the OOP structure with a vtable.
1100 * Instead, it is configured with the vtables of the hash functions it
1101 * should run. Structure fields are not supposed to be accessed directly.
1104 #ifndef BR_DOXYGEN_IGNORE
1105 unsigned char buf
[128];
1107 uint32_t val_32
[25];
1108 uint64_t val_64
[16];
1109 const br_hash_class
*impl
[6];
1111 } br_multihash_context
;
1114 * \brief Clear a multi-hasher context.
1116 * This should always be called once on a given context, _before_ setting
1117 * the implementation pointers.
1119 * \param ctx the multi-hasher context.
1121 void br_multihash_zero(br_multihash_context
*ctx
);
1124 * \brief Set a hash function implementation.
1126 * Implementations shall be set _after_ clearing the context (with
1127 * `br_multihash_zero()`) but _before_ initialising the computation
1128 * (with `br_multihash_init()`). The hash function implementation
1129 * MUST be one of the standard hash functions (MD5, SHA-1, SHA-224,
1130 * SHA-256, SHA-384 or SHA-512); it may also be `NULL` to remove
1131 * an implementation from the multi-hasher.
1133 * \param ctx the multi-hasher context.
1134 * \param id the hash function symbolic identifier.
1135 * \param impl the hash function vtable, or `NULL`.
1138 br_multihash_setimpl(br_multihash_context
*ctx
,
1139 int id
, const br_hash_class
*impl
)
1142 * This code relies on hash functions ID being values 1 to 6,
1143 * in the MD5 to SHA-512 order.
1145 ctx
->impl
[id
- 1] = impl
;
1149 * \brief Get a hash function implementation.
1151 * This function returns the currently configured vtable for a given
1152 * hash function (by symbolic ID). If no such function was configured in
1153 * the provided multi-hasher context, then this function returns `NULL`.
1155 * \param ctx the multi-hasher context.
1156 * \param id the hash function symbolic identifier.
1157 * \return the hash function vtable, or `NULL`.
1159 static inline const br_hash_class
*
1160 br_multihash_getimpl(const br_multihash_context
*ctx
, int id
)
1162 return ctx
->impl
[id
- 1];
1166 * \brief Reset a multi-hasher context.
1168 * This function prepares the context for a new hashing computation,
1169 * for all implementations configured at that point.
1171 * \param ctx the multi-hasher context.
1173 void br_multihash_init(br_multihash_context
*ctx
);
1176 * \brief Inject some data bytes in a running multi-hashing computation.
1178 * The provided context is updated with some data bytes. If the number
1179 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
1180 * and may be `NULL`, and this function does nothing.
1182 * \param ctx pointer to the context structure.
1183 * \param data pointer to the injected data.
1184 * \param len injected data length (in bytes).
1186 void br_multihash_update(br_multihash_context
*ctx
,
1187 const void *data
, size_t len
);
1190 * \brief Compute a hash output from a multi-hasher.
1192 * The hash output for the concatenation of all bytes injected in the
1193 * provided context since the last initialisation or reset call, is
1194 * computed and written in the buffer pointed to by `dst`. The hash
1195 * function to use is identified by `id` and must be one of the standard
1196 * hash functions. If that hash function was indeed configured in the
1197 * multi-hasher context, the corresponding hash value is written in
1198 * `dst` and its length (in bytes) is returned. If the hash function
1199 * was _not_ configured, then nothing is written in `dst` and 0 is
1202 * The context itself is not modified, so extra bytes may be injected
1203 * afterwards to continue the hash computations.
1205 * \param ctx pointer to the context structure.
1206 * \param id the hash function symbolic identifier.
1207 * \param dst destination buffer for the hash output.
1208 * \return the hash output length (in bytes), or 0.
1210 size_t br_multihash_out(const br_multihash_context
*ctx
, int id
, void *dst
);
1213 * \brief Type for a GHASH implementation.
1215 * GHASH is a sort of keyed hash meant to be used to implement GCM in
1216 * combination with a block cipher (with 16-byte blocks).
1218 * The `y` array has length 16 bytes and is used for input and output; in
1219 * a complete GHASH run, it starts with an all-zero value. `h` is a 16-byte
1220 * value that serves as key (it is derived from the encryption key in GCM,
1221 * using the block cipher). The data length (`len`) is expressed in bytes.
1222 * The `y` array is updated.
1224 * If the data length is not a multiple of 16, then the data is implicitly
1225 * padded with zeros up to the next multiple of 16. Thus, when using GHASH
1226 * in GCM, this method may be called twice, for the associated data and
1227 * for the ciphertext, respectively; the zero-padding implements exactly
1230 * \param y the array to update.
1231 * \param h the GHASH key.
1232 * \param data the input data (may be `NULL` if `len` is zero).
1233 * \param len the input data length (in bytes).
1235 typedef void (*br_ghash
)(void *y
, const void *h
, const void *data
, size_t len
);
1238 * \brief GHASH implementation using multiplications (mixed 32-bit).
1240 * This implementation uses multiplications of 32-bit values, with a
1241 * 64-bit result. It is constant-time (if multiplications are
1244 * \param y the array to update.
1245 * \param h the GHASH key.
1246 * \param data the input data (may be `NULL` if `len` is zero).
1247 * \param len the input data length (in bytes).
1249 void br_ghash_ctmul(void *y
, const void *h
, const void *data
, size_t len
);
1252 * \brief GHASH implementation using multiplications (strict 32-bit).
1254 * This implementation uses multiplications of 32-bit values, with a
1255 * 32-bit result. It is usually somewhat slower than `br_ghash_ctmul()`,
1256 * but it is expected to be faster on architectures for which the
1257 * 32-bit multiplication opcode does not yield the upper 32 bits of the
1258 * product. It is constant-time (if multiplications are constant-time).
1260 * \param y the array to update.
1261 * \param h the GHASH key.
1262 * \param data the input data (may be `NULL` if `len` is zero).
1263 * \param len the input data length (in bytes).
1265 void br_ghash_ctmul32(void *y
, const void *h
, const void *data
, size_t len
);
1268 * \brief GHASH implementation using multiplications (64-bit).
1270 * This implementation uses multiplications of 64-bit values, with a
1271 * 64-bit result. It is constant-time (if multiplications are
1272 * constant-time). It is substantially faster than `br_ghash_ctmul()`
1273 * and `br_ghash_ctmul32()` on most 64-bit architectures.
1275 * \param y the array to update.
1276 * \param h the GHASH key.
1277 * \param data the input data (may be `NULL` if `len` is zero).
1278 * \param len the input data length (in bytes).
1280 void br_ghash_ctmul64(void *y
, const void *h
, const void *data
, size_t len
);
1283 * \brief GHASH implementation using the `pclmulqdq` opcode (part of the
1284 * AES-NI instructions).
1286 * This implementation is available only on x86 platforms where the
1287 * compiler supports the relevant intrinsic functions. Even if the
1288 * compiler supports these functions, the local CPU might not support
1289 * the `pclmulqdq` opcode, meaning that a call will fail with an
1290 * illegal instruction exception. To safely obtain a pointer to this
1291 * function when supported (or 0 otherwise), use `br_ghash_pclmul_get()`.
1293 * \param y the array to update.
1294 * \param h the GHASH key.
1295 * \param data the input data (may be `NULL` if `len` is zero).
1296 * \param len the input data length (in bytes).
1298 void br_ghash_pclmul(void *y
, const void *h
, const void *data
, size_t len
);
1301 * \brief Obtain the `pclmul` GHASH implementation, if available.
1303 * If the `pclmul` implementation was compiled in the library (depending
1304 * on the compiler abilities) _and_ the local CPU appears to support the
1305 * opcode, then this function will return a pointer to the
1306 * `br_ghash_pclmul()` function. Otherwise, it will return `0`.
1308 * \return the `pclmul` GHASH implementation, or `0`.
1310 br_ghash
br_ghash_pclmul_get(void);