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 /** \file bearssl_hash.h
40 * This file documents the API for hash functions.
45 * For each implemented hash function, of name "`xxx`", the following
46 * elements are defined:
50 * An externally defined instance of `br_hash_class`.
54 * A macro that evaluates to the output size (in bytes) of the
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.
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,
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.
80 * - `br_xxx_init(br_xxx_context *ctx)`
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.
88 * - `br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)`
90 * Add some more bytes to the hash computation represented by the
93 * - `br_xxx_out(const br_xxx_context *ctx, void *out)`
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.
101 * - `br_xxx_state(const br_xxx_context *ctx, void *out)`
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).
108 * - `br_xxx_set_state(br_xxx_context *ctx, const void *stb, uint64_t count)`
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.
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.
121 * ## Object-Oriented API
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 * [https://www.bearssl.org/oop.html](https://www.bearssl.org/oop.html)
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:
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.
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.
146 * Users of this object-oriented API (in particular generic HMAC
147 * implementations) may make the following assumptions:
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
155 * ## Implemented Hash Functions
157 * Implemented hash functions are:
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 |
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
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).
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.
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.
197 * A GHASH implementation is basically a function that uses the type defined
198 * in this file under the name `br_ghash`:
200 * typedef void (*br_ghash)(void *y, const void *h, const void *data, size_t len);
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.
206 * Three GHASH implementations are provided, all constant-time, based on
207 * the use of integer multiplications with appropriate masking to cancel
212 * \brief Class type for hash function implementations.
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".
218 * Vtables are used to support object-oriented programming, as
219 * described on [the BearSSL Web site](https://www.bearssl.org/oop.html).
221 typedef struct br_hash_class_ br_hash_class
;
222 struct br_hash_class_
{
224 * \brief Size (in bytes) of the context structure appropriate for
225 * computing this hash function.
230 * \brief Descriptor word that contains information about the hash
233 * For each word `xxx` described below, use `BR_HASHDESC_xxx_OFF`
234 * and `BR_HASHDESC_xxx_MASK` to access the specific value, as
237 * (hf->desc >> BR_HASHDESC_xxx_OFF) & BR_HASHDESC_xxx_MASK
239 * The defined elements are:
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,...).
245 * - `OUT`: hash output size, in bytes.
247 * - `STATE`: internal running state size, in bytes.
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
255 * The descriptor may contain a few other flags.
260 * \brief Initialisation method.
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
267 * \param ctx pointer to (the first field of) the context.
269 void (*init
)(const br_hash_class
**ctx
);
272 * \brief Data injection method.
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.
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.
285 void (*update
)(const br_hash_class
**ctx
, const void *data
, size_t len
);
288 * \brief Produce hash output.
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.
297 * \param ctx pointer to (the first field of) the context.
298 * \param dst destination buffer for the hash output.
300 void (*out
)(const br_hash_class
*const *ctx
, void *dst
);
303 * \brief Get running state.
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.
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.
316 uint64_t (*state
)(const br_hash_class
*const *ctx
, void *dst
);
319 * \brief Set running state.
321 * This methods replaces the running state for the function.
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.
327 void (*set_state
)(const br_hash_class
**ctx
,
328 const void *stb
, uint64_t count
);
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
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
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
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
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)
354 * Specific hash functions.
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.
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.
369 * \brief Symbolic identifier for MD5.
374 * \brief MD5 output size (in bytes).
376 #define br_md5_SIZE 16
379 * \brief Constant vtable for MD5.
381 extern const br_hash_class br_md5_vtable
;
384 * \brief MD5 context.
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.
391 * \brief Pointer to vtable for this context.
393 const br_hash_class
*vtable
;
394 #ifndef BR_DOXYGEN_IGNORE
395 unsigned char buf
[64];
402 * \brief MD5 context initialisation.
404 * This function initialises or resets a context for a new MD5
405 * computation. It also sets the vtable pointer.
407 * \param ctx pointer to the context structure.
409 void br_md5_init(br_md5_context
*ctx
);
412 * \brief Inject some data bytes in a running MD5 computation.
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.
418 * \param ctx pointer to the context structure.
419 * \param data pointer to the injected data.
420 * \param len injected data length (in bytes).
422 void br_md5_update(br_md5_context
*ctx
, const void *data
, size_t len
);
425 * \brief Compute MD5 output.
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.
433 * \param ctx pointer to the context structure.
434 * \param out destination buffer for the hash output.
436 void br_md5_out(const br_md5_context
*ctx
, void *out
);
439 * \brief Save MD5 running state.
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.
446 * \param ctx pointer to the context structure.
447 * \param out destination buffer for the running state.
448 * \return the injected total byte length.
450 uint64_t br_md5_state(const br_md5_context
*ctx
, void *out
);
453 * \brief Restore MD5 running state.
455 * The running state for MD5 is set to the provided values.
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.
461 void br_md5_set_state(br_md5_context
*ctx
, const void *stb
, uint64_t count
);
464 * \brief Symbolic identifier for SHA-1.
469 * \brief SHA-1 output size (in bytes).
471 #define br_sha1_SIZE 20
474 * \brief Constant vtable for SHA-1.
476 extern const br_hash_class br_sha1_vtable
;
479 * \brief SHA-1 context.
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.
486 * \brief Pointer to vtable for this context.
488 const br_hash_class
*vtable
;
489 #ifndef BR_DOXYGEN_IGNORE
490 unsigned char buf
[64];
497 * \brief SHA-1 context initialisation.
499 * This function initialises or resets a context for a new SHA-1
500 * computation. It also sets the vtable pointer.
502 * \param ctx pointer to the context structure.
504 void br_sha1_init(br_sha1_context
*ctx
);
507 * \brief Inject some data bytes in a running SHA-1 computation.
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.
513 * \param ctx pointer to the context structure.
514 * \param data pointer to the injected data.
515 * \param len injected data length (in bytes).
517 void br_sha1_update(br_sha1_context
*ctx
, const void *data
, size_t len
);
520 * \brief Compute SHA-1 output.
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.
528 * \param ctx pointer to the context structure.
529 * \param out destination buffer for the hash output.
531 void br_sha1_out(const br_sha1_context
*ctx
, void *out
);
534 * \brief Save SHA-1 running state.
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.
541 * \param ctx pointer to the context structure.
542 * \param out destination buffer for the running state.
543 * \return the injected total byte length.
545 uint64_t br_sha1_state(const br_sha1_context
*ctx
, void *out
);
548 * \brief Restore SHA-1 running state.
550 * The running state for SHA-1 is set to the provided values.
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.
556 void br_sha1_set_state(br_sha1_context
*ctx
, const void *stb
, uint64_t count
);
559 * \brief Symbolic identifier for SHA-224.
561 #define br_sha224_ID 3
564 * \brief SHA-224 output size (in bytes).
566 #define br_sha224_SIZE 28
569 * \brief Constant vtable for SHA-224.
571 extern const br_hash_class br_sha224_vtable
;
574 * \brief SHA-224 context.
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.
581 * \brief Pointer to vtable for this context.
583 const br_hash_class
*vtable
;
584 #ifndef BR_DOXYGEN_IGNORE
585 unsigned char buf
[64];
592 * \brief SHA-224 context initialisation.
594 * This function initialises or resets a context for a new SHA-224
595 * computation. It also sets the vtable pointer.
597 * \param ctx pointer to the context structure.
599 void br_sha224_init(br_sha224_context
*ctx
);
602 * \brief Inject some data bytes in a running SHA-224 computation.
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.
608 * \param ctx pointer to the context structure.
609 * \param data pointer to the injected data.
610 * \param len injected data length (in bytes).
612 void br_sha224_update(br_sha224_context
*ctx
, const void *data
, size_t len
);
615 * \brief Compute SHA-224 output.
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.
623 * \param ctx pointer to the context structure.
624 * \param out destination buffer for the hash output.
626 void br_sha224_out(const br_sha224_context
*ctx
, void *out
);
629 * \brief Save SHA-224 running state.
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.
636 * \param ctx pointer to the context structure.
637 * \param out destination buffer for the running state.
638 * \return the injected total byte length.
640 uint64_t br_sha224_state(const br_sha224_context
*ctx
, void *out
);
643 * \brief Restore SHA-224 running state.
645 * The running state for SHA-224 is set to the provided values.
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.
651 void br_sha224_set_state(br_sha224_context
*ctx
,
652 const void *stb
, uint64_t count
);
655 * \brief Symbolic identifier for SHA-256.
657 #define br_sha256_ID 4
660 * \brief SHA-256 output size (in bytes).
662 #define br_sha256_SIZE 32
665 * \brief Constant vtable for SHA-256.
667 extern const br_hash_class br_sha256_vtable
;
669 #ifdef BR_DOXYGEN_IGNORE
671 * \brief SHA-256 context.
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.
678 * \brief Pointer to vtable for this context.
680 const br_hash_class
*vtable
;
683 typedef br_sha224_context br_sha256_context
;
687 * \brief SHA-256 context initialisation.
689 * This function initialises or resets a context for a new SHA-256
690 * computation. It also sets the vtable pointer.
692 * \param ctx pointer to the context structure.
694 void br_sha256_init(br_sha256_context
*ctx
);
696 #ifdef BR_DOXYGEN_IGNORE
698 * \brief Inject some data bytes in a running SHA-256 computation.
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.
704 * \param ctx pointer to the context structure.
705 * \param data pointer to the injected data.
706 * \param len injected data length (in bytes).
708 void br_sha256_update(br_sha256_context
*ctx
, const void *data
, size_t len
);
710 #define br_sha256_update br_sha224_update
714 * \brief Compute SHA-256 output.
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.
722 * \param ctx pointer to the context structure.
723 * \param out destination buffer for the hash output.
725 void br_sha256_out(const br_sha256_context
*ctx
, void *out
);
727 #ifdef BR_DOXYGEN_IGNORE
729 * \brief Save SHA-256 running state.
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.
736 * \param ctx pointer to the context structure.
737 * \param out destination buffer for the running state.
738 * \return the injected total byte length.
740 uint64_t br_sha256_state(const br_sha256_context
*ctx
, void *out
);
742 #define br_sha256_state br_sha224_state
745 #ifdef BR_DOXYGEN_IGNORE
747 * \brief Restore SHA-256 running state.
749 * The running state for SHA-256 is set to the provided values.
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.
755 void br_sha256_set_state(br_sha256_context
*ctx
,
756 const void *stb
, uint64_t count
);
758 #define br_sha256_set_state br_sha224_set_state
762 * \brief Symbolic identifier for SHA-384.
764 #define br_sha384_ID 5
767 * \brief SHA-384 output size (in bytes).
769 #define br_sha384_SIZE 48
772 * \brief Constant vtable for SHA-384.
774 extern const br_hash_class br_sha384_vtable
;
777 * \brief SHA-384 context.
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.
784 * \brief Pointer to vtable for this context.
786 const br_hash_class
*vtable
;
787 #ifndef BR_DOXYGEN_IGNORE
788 unsigned char buf
[128];
795 * \brief SHA-384 context initialisation.
797 * This function initialises or resets a context for a new SHA-384
798 * computation. It also sets the vtable pointer.
800 * \param ctx pointer to the context structure.
802 void br_sha384_init(br_sha384_context
*ctx
);
805 * \brief Inject some data bytes in a running SHA-384 computation.
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.
811 * \param ctx pointer to the context structure.
812 * \param data pointer to the injected data.
813 * \param len injected data length (in bytes).
815 void br_sha384_update(br_sha384_context
*ctx
, const void *data
, size_t len
);
818 * \brief Compute SHA-384 output.
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.
826 * \param ctx pointer to the context structure.
827 * \param out destination buffer for the hash output.
829 void br_sha384_out(const br_sha384_context
*ctx
, void *out
);
832 * \brief Save SHA-384 running state.
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.
839 * \param ctx pointer to the context structure.
840 * \param out destination buffer for the running state.
841 * \return the injected total byte length.
843 uint64_t br_sha384_state(const br_sha384_context
*ctx
, void *out
);
846 * \brief Restore SHA-384 running state.
848 * The running state for SHA-384 is set to the provided values.
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.
854 void br_sha384_set_state(br_sha384_context
*ctx
,
855 const void *stb
, uint64_t count
);
858 * \brief Symbolic identifier for SHA-512.
860 #define br_sha512_ID 6
863 * \brief SHA-512 output size (in bytes).
865 #define br_sha512_SIZE 64
868 * \brief Constant vtable for SHA-512.
870 extern const br_hash_class br_sha512_vtable
;
872 #ifdef BR_DOXYGEN_IGNORE
874 * \brief SHA-512 context.
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.
881 * \brief Pointer to vtable for this context.
883 const br_hash_class
*vtable
;
886 typedef br_sha384_context br_sha512_context
;
890 * \brief SHA-512 context initialisation.
892 * This function initialises or resets a context for a new SHA-512
893 * computation. It also sets the vtable pointer.
895 * \param ctx pointer to the context structure.
897 void br_sha512_init(br_sha512_context
*ctx
);
899 #ifdef BR_DOXYGEN_IGNORE
901 * \brief Inject some data bytes in a running SHA-512 computation.
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.
907 * \param ctx pointer to the context structure.
908 * \param data pointer to the injected data.
909 * \param len injected data length (in bytes).
911 void br_sha512_update(br_sha512_context
*ctx
, const void *data
, size_t len
);
913 #define br_sha512_update br_sha384_update
917 * \brief Compute SHA-512 output.
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.
925 * \param ctx pointer to the context structure.
926 * \param out destination buffer for the hash output.
928 void br_sha512_out(const br_sha512_context
*ctx
, void *out
);
930 #ifdef BR_DOXYGEN_IGNORE
932 * \brief Save SHA-512 running state.
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.
939 * \param ctx pointer to the context structure.
940 * \param out destination buffer for the running state.
941 * \return the injected total byte length.
943 uint64_t br_sha512_state(const br_sha512_context
*ctx
, void *out
);
945 #define br_sha512_state br_sha384_state
948 #ifdef BR_DOXYGEN_IGNORE
950 * \brief Restore SHA-512 running state.
952 * The running state for SHA-512 is set to the provided values.
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.
958 void br_sha512_set_state(br_sha512_context
*ctx
,
959 const void *stb
, uint64_t count
);
961 #define br_sha512_set_state br_sha384_set_state
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.
971 * \brief Symbolic identifier for MD5+SHA-1.
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.
977 #define br_md5sha1_ID 0
980 * \brief MD5+SHA-1 output size (in bytes).
982 #define br_md5sha1_SIZE 36
985 * \brief Constant vtable for MD5+SHA-1.
987 extern const br_hash_class br_md5sha1_vtable
;
990 * \brief MD5+SHA-1 context.
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.
997 * \brief Pointer to vtable for this context.
999 const br_hash_class
*vtable
;
1000 #ifndef BR_DOXYGEN_IGNORE
1001 unsigned char buf
[64];
1003 uint32_t val_md5
[4];
1004 uint32_t val_sha1
[5];
1006 } br_md5sha1_context
;
1009 * \brief MD5+SHA-1 context initialisation.
1011 * This function initialises or resets a context for a new SHA-512
1012 * computation. It also sets the vtable pointer.
1014 * \param ctx pointer to the context structure.
1016 void br_md5sha1_init(br_md5sha1_context
*ctx
);
1019 * \brief Inject some data bytes in a running MD5+SHA-1 computation.
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.
1025 * \param ctx pointer to the context structure.
1026 * \param data pointer to the injected data.
1027 * \param len injected data length (in bytes).
1029 void br_md5sha1_update(br_md5sha1_context
*ctx
, const void *data
, size_t len
);
1032 * \brief Compute MD5+SHA-1 output.
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.
1040 * \param ctx pointer to the context structure.
1041 * \param out destination buffer for the hash output.
1043 void br_md5sha1_out(const br_md5sha1_context
*ctx
, void *out
);
1046 * \brief Save MD5+SHA-1 running state.
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.
1053 * \param ctx pointer to the context structure.
1054 * \param out destination buffer for the running state.
1055 * \return the injected total byte length.
1057 uint64_t br_md5sha1_state(const br_md5sha1_context
*ctx
, void *out
);
1060 * \brief Restore MD5+SHA-1 running state.
1062 * The running state for MD5+SHA-1 is set to the provided values.
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.
1068 void br_md5sha1_set_state(br_md5sha1_context
*ctx
,
1069 const void *stb
, uint64_t count
);
1072 * \brief Aggregate context for configurable hash function support.
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.
1078 const br_hash_class
*vtable
;
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
;
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.
1097 * \brief Multi-hasher context structure.
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
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.
1108 #ifndef BR_DOXYGEN_IGNORE
1109 unsigned char buf
[128];
1111 uint32_t val_32
[25];
1112 uint64_t val_64
[16];
1113 const br_hash_class
*impl
[6];
1115 } br_multihash_context
;
1118 * \brief Clear a multi-hasher context.
1120 * This should always be called once on a given context, _before_ setting
1121 * the implementation pointers.
1123 * \param ctx the multi-hasher context.
1125 void br_multihash_zero(br_multihash_context
*ctx
);
1128 * \brief Set a hash function implementation.
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.
1137 * \param ctx the multi-hasher context.
1138 * \param id the hash function symbolic identifier.
1139 * \param impl the hash function vtable, or `NULL`.
1142 br_multihash_setimpl(br_multihash_context
*ctx
,
1143 int id
, const br_hash_class
*impl
)
1146 * This code relies on hash functions ID being values 1 to 6,
1147 * in the MD5 to SHA-512 order.
1149 ctx
->impl
[id
- 1] = impl
;
1153 * \brief Get a hash function implementation.
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`.
1159 * \param ctx the multi-hasher context.
1160 * \param id the hash function symbolic identifier.
1161 * \return the hash function vtable, or `NULL`.
1163 static inline const br_hash_class
*
1164 br_multihash_getimpl(const br_multihash_context
*ctx
, int id
)
1166 return ctx
->impl
[id
- 1];
1170 * \brief Reset a multi-hasher context.
1172 * This function prepares the context for a new hashing computation,
1173 * for all implementations configured at that point.
1175 * \param ctx the multi-hasher context.
1177 void br_multihash_init(br_multihash_context
*ctx
);
1180 * \brief Inject some data bytes in a running multi-hashing computation.
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.
1186 * \param ctx pointer to the context structure.
1187 * \param data pointer to the injected data.
1188 * \param len injected data length (in bytes).
1190 void br_multihash_update(br_multihash_context
*ctx
,
1191 const void *data
, size_t len
);
1194 * \brief Compute a hash output from a multi-hasher.
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
1206 * The context itself is not modified, so extra bytes may be injected
1207 * afterwards to continue the hash computations.
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.
1214 size_t br_multihash_out(const br_multihash_context
*ctx
, int id
, void *dst
);
1217 * \brief Type for a GHASH implementation.
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).
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.
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
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).
1239 typedef void (*br_ghash
)(void *y
, const void *h
, const void *data
, size_t len
);
1242 * \brief GHASH implementation using multiplications (mixed 32-bit).
1244 * This implementation uses multiplications of 32-bit values, with a
1245 * 64-bit result. It is constant-time (if multiplications are
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).
1253 void br_ghash_ctmul(void *y
, const void *h
, const void *data
, size_t len
);
1256 * \brief GHASH implementation using multiplications (strict 32-bit).
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).
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).
1269 void br_ghash_ctmul32(void *y
, const void *h
, const void *data
, size_t len
);
1272 * \brief GHASH implementation using multiplications (64-bit).
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.
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).
1284 void br_ghash_ctmul64(void *y
, const void *h
, const void *data
, size_t len
);
1287 * \brief GHASH implementation using the `pclmulqdq` opcode (part of the
1288 * AES-NI instructions).
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()`.
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).
1302 void br_ghash_pclmul(void *y
, const void *h
, const void *data
, size_t len
);
1305 * \brief Obtain the `pclmul` GHASH implementation, if available.
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`.
1312 * \return the `pclmul` GHASH implementation, or `0`.
1314 br_ghash
br_ghash_pclmul_get(void);
1317 * \brief GHASH implementation using the POWER8 opcodes.
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()`.
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).
1328 void br_ghash_pwr8(void *y
, const void *h
, const void *data
, size_t len
);
1331 * \brief Obtain the `pwr8` GHASH implementation, if available.
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`.
1338 * \return the `pwr8` GHASH implementation, or `0`.
1340 br_ghash
br_ghash_pwr8_get(void);