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.
38 * Implemented hash functions are MD5, SHA-1, SHA-224, SHA-256, SHA-384
39 * and SHA-512; these are the _standard hash functions_ (as specified in
40 * TLS). Also provided are MD5+SHA-1 (an aggregate hash function that
41 * computes both MD5 and SHA-1 on its input, and provides a 36-byte
42 * output), a multi-hasher system that computes some or all of the
43 * standard hash functions on the same input, and some GHASH
44 * implementations (GHASH is the sort-of keyed hash function used in GCM
47 * For each standard hash function (and also MD5+SHA-1), two similar API
48 * are provided: one consists in direct, named function calls, while the
49 * other uses function pointers through a vtable. The vtable incarnates
50 * object-oriented programming. An introduction on the OOP concept used
51 * here can be read on the BearSSL Web site:<br />
52 * [https://www.bearssl.org/oop.html](https://www.bearssl.org/oop.html)
59 * For hash function 'xxx', the following elements are defined:
62 * An externally defined instance of br_hash_class.
65 * A macro that evaluates to the output size (in bytes) of the
69 * A macro that evaluates to a symbolic identifier for the hash
70 * function. Such identifiers are used with HMAC and signature
71 * algorithm implementations.
72 * NOTE: the numerical value of these identifiers MUST match the
73 * constants for hash function identification in TLS 1.2 (see RFC
74 * 5246, section 7.4.1.4.1). These are values 1 to 6, for MD5,
75 * SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512, respectively.
78 * Context for an ongoing computation. It is allocated by the
79 * caller, and a pointer to it is passed to all functions. A
80 * context contains no interior pointer, so it can be moved around
81 * and cloned (with a simple memcpy() or equivalent) in order to
82 * capture the function state at some point. Computations that use
83 * distinct context structures are independent of each other. The
84 * first field of br_xxx_context is always a pointer to the
85 * br_xxx_vtable structure; br_xxx_init() sets that pointer.
87 * br_xxx_init(br_xxx_context *ctx)
88 * Initialize the provided context. Previous contents of the structure
89 * are ignored. This calls resets the context to the start of a new
92 * br_xxx_update(br_xxx_context *ctx, const void *data, size_t len)
93 * Add some more bytes to the hash computation represented by the
96 * br_xxx_out(const br_xxx_context *ctx, void *out)
97 * Complete the hash computation and write the result in the provided
98 * buffer. The output buffer MUST be large enough to accomodate the
99 * result. The context is NOT modified by this operation, so this
100 * function can be used to get a "partial hash" while still keeping
101 * the possibility of adding more bytes to the input.
103 * br_xxx_state(const br_xxx_context *ctx, void *out)
104 * Get a copy of the "current state" for the computation so far. For
105 * MD functions (MD5, SHA-1, SHA-2 family), this is the running state
106 * resulting from the processing of the last complete input block.
107 * Returned value is the current input length (in bytes).
109 * 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 'count'
111 * values shall match that which was obtained from br_xxx_state(). This
112 * restores the hash state only if the state values were at an
113 * appropriate block boundary. This does NOT set the 'vtable' pointer
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.
120 * Implemented hash functions are:
122 * Function Name Output length State length
126 * SHA-224 sha224 28 32
127 * SHA-256 sha256 32 32
128 * SHA-384 sha384 48 64
129 * SHA-512 sha512 64 64
130 * MD5+SHA-1 md5sha1 36 36
132 * (MD5+SHA-1 is the concatenation of MD5 and SHA-1 computed over the
133 * same input; in the implementation, the internal data buffer is
134 * shared, thus making it more memory-efficient than separate MD5 and
135 * SHA-1. It can be useful in implementing SSL 3.0, TLS 1.0 and TLS
139 * An object-oriented API is also available: the first field of the
140 * context is a pointer to a br_hash_class structure, that has the
141 * following contents:
143 * context_size total size of the required context structure
144 * desc descriptor (see below)
145 * init context initialization or reset (function pointer)
146 * update process some more bytes (function pointer)
147 * out get hash output so far (function pointer)
148 * state get copy of internal state (function pointer)
149 * set_state reset the internal state (function pointer)
151 * The descriptor is a combination of the following elements:
152 * bits 0 to 7 hash algorithm identifier
153 * bits 8 to 14 hash output size (in bytes)
154 * bits 15 to 22 hash internal state size (in bytes)
155 * bits 23 to 26 log (base 2) of hash internal block size (in bytes)
156 * bit 28 1 if using MD padding, 0 otherwise
157 * bit 29 1 if MD padding uses a 128-bit bit length, 0 otherwise
158 * bit 30 1 if MD padding is big-endian, 0 otherwise
160 * For function 'xxx', the br_xxx_init() function sets the first field
161 * to a pointer to the relevant br_hash_class instance (i.e.
164 * Users of this object-oriented API may make the following assumptions:
165 * Hash output size is no more than 64 bytes.
166 * Hash internal state size is no more than 64 bytes.
167 * Internal block size is a power of two, no less than 2^4 and no more
169 * For functions that do not have an internal block size that is a
170 * power of 2, the relevant element is 0.
174 * \brief Class type for hash function implementations.
176 * A `br_hash_class` instance references the methods implementing a hash
177 * function. Constant instances of this structure are defined for each
178 * implemented hash function. Such instances are also called "vtables".
180 * Vtables are used to support object-oriented programming, as
181 * described on [the BearSSL Web site](https://www.bearssl.org/oop.html).
183 typedef struct br_hash_class_ br_hash_class
;
184 struct br_hash_class_
{
186 * \brief Size (in bytes) of the context structure appropriate for
187 * computing this hash function.
192 * \brief Descriptor word that contains information about the hash
195 * For each word `xxx` described below, use `BR_HASHDESC_xxx_OFF`
196 * and `BR_HASHDESC_xxx_MASK` to access the specific value, as
199 * (hf->desc >> BR_HASHDESC_xxx_OFF) & BR_HASHDESC_xxx_MASK
201 * The defined elements are:
203 * - `ID`: the symbolic identifier for the function, as defined
204 * in [TLS](https://tools.ietf.org/html/rfc5246#section-7.4.1.4.1)
205 * (MD5 = 1, SHA-1 = 2,...).
207 * - `OUT`: hash output size, in bytes.
209 * - `STATE`: internal running state size, in bytes.
211 * - `LBLEN`: base-2 logarithm for the internal block size, as
212 * defined for HMAC processing (this is 6 for MD5, SHA-1, SHA-224
213 * and SHA-256, since these functions use 64-byte blocks; for
214 * SHA-384 and SHA-512, this is 7, corresponding to their
217 * The descriptor may contain a few other flags.
222 * \brief Initialisation method.
224 * This method takes as parameter a pointer to a context area,
225 * that it initialises. The first field of the context is set
226 * to this vtable; other elements are initialised for a new hash
229 * \param ctx pointer to (the first field of) the context.
231 void (*init
)(const br_hash_class
**ctx
);
234 * \brief Data injection method.
236 * The `len` bytes starting at address `data` are injected into
237 * the running hash computation incarnated by the specified
238 * context. The context is updated accordingly. It is allowed
239 * to have `len == 0`, in which case `data` is ignored (and could
240 * be `NULL`), and nothing happens.
243 * \param ctx pointer to (the first field of) the context.
244 * \param data pointer to the first data byte to inject.
245 * \param len number of bytes to inject.
247 void (*update
)(const br_hash_class
**ctx
, const void *data
, size_t len
);
250 * \brief Produce hash output.
252 * The hash output corresponding to all data bytes injected in the
253 * context since the last `init()` call is computed, and written
254 * in the buffer pointed to by `dst`. The hash output size depends
255 * on the implemented hash function (e.g. 16 bytes for MD5).
256 * The context is _not_ modified by this call, so further bytes
257 * may be afterwards injected to continue the current computation.
259 * \param ctx pointer to (the first field of) the context.
260 * \param dst destination buffer for the hash output.
262 void (*out
)(const br_hash_class
*const *ctx
, void *dst
);
265 * \brief Get running state.
267 * This method saves the current running state into the `dst`
268 * buffer. What constitutes the "running state" depends on the
269 * hash function; for Merkle-Damgård hash functions (like
270 * MD5 or SHA-1), this is the output obtained after processing
271 * each block. The number of bytes injected so far is returned.
272 * The context is not modified by this call.
274 * \param ctx pointer to (the first field of) the context.
275 * \param dst destination buffer for the state.
276 * \return the injected total byte length.
278 uint64_t (*state
)(const br_hash_class
*const *ctx
, void *dst
);
281 * \brief Set running state.
283 * This methods replaces the running state for the function.
285 * \param ctx pointer to (the first field of) the context.
286 * \param stb source buffer for the state.
287 * \param count injected total byte length.
289 void (*set_state
)(const br_hash_class
**ctx
,
290 const void *stb
, uint64_t count
);
293 #ifndef BR_DOXYGEN_IGNORE
294 #define BR_HASHDESC_ID(id) ((uint32_t)(id) << BR_HASHDESC_ID_OFF)
295 #define BR_HASHDESC_ID_OFF 0
296 #define BR_HASHDESC_ID_MASK 0xFF
298 #define BR_HASHDESC_OUT(size) ((uint32_t)(size) << BR_HASHDESC_OUT_OFF)
299 #define BR_HASHDESC_OUT_OFF 8
300 #define BR_HASHDESC_OUT_MASK 0x7F
302 #define BR_HASHDESC_STATE(size) ((uint32_t)(size) << BR_HASHDESC_STATE_OFF)
303 #define BR_HASHDESC_STATE_OFF 15
304 #define BR_HASHDESC_STATE_MASK 0xFF
306 #define BR_HASHDESC_LBLEN(ls) ((uint32_t)(ls) << BR_HASHDESC_LBLEN_OFF)
307 #define BR_HASHDESC_LBLEN_OFF 23
308 #define BR_HASHDESC_LBLEN_MASK 0x0F
310 #define BR_HASHDESC_MD_PADDING ((uint32_t)1 << 28)
311 #define BR_HASHDESC_MD_PADDING_128 ((uint32_t)1 << 29)
312 #define BR_HASHDESC_MD_PADDING_BE ((uint32_t)1 << 30)
316 * Specific hash functions.
318 * Rules for contexts:
319 * -- No interior pointer.
320 * -- No pointer to external dynamically allocated resources.
321 * -- First field is called 'vtable' and is a pointer to a
322 * const-qualified br_hash_class instance (pointer is set by init()).
323 * -- SHA-224 and SHA-256 contexts are identical.
324 * -- SHA-384 and SHA-512 contexts are identical.
326 * Thus, contexts can be moved and cloned to capture the hash function
327 * current state; and there is no need for any explicit "release" function.
331 * \brief Symbolic identifier for MD5.
336 * \brief MD5 output size (in bytes).
338 #define br_md5_SIZE 16
341 * \brief Constant vtable for MD5.
343 extern const br_hash_class br_md5_vtable
;
346 * \brief MD5 context.
348 * First field is a pointer to the vtable; it is set by the initialisation
349 * function. Other fields are not supposed to be accessed by user code.
353 * \brief Pointer to vtable for this context.
355 const br_hash_class
*vtable
;
356 #ifndef BR_DOXYGEN_IGNORE
357 unsigned char buf
[64];
364 * \brief MD5 context initialisation.
366 * This function initialises or resets a context for a new MD5
367 * computation. It also sets the vtable pointer.
369 * \param ctx pointer to the context structure.
371 void br_md5_init(br_md5_context
*ctx
);
374 * \brief Inject some data bytes in a running MD5 computation.
376 * The provided context is updated with some data bytes. If the number
377 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
378 * and may be `NULL`, and this function does nothing.
380 * \param ctx pointer to the context structure.
381 * \param data pointer to the injected data.
382 * \param len injected data length (in bytes).
384 void br_md5_update(br_md5_context
*ctx
, const void *data
, size_t len
);
387 * \brief Compute MD5 output.
389 * The MD5 output for the concatenation of all bytes injected in the
390 * provided context since the last initialisation or reset call, is
391 * computed and written in the buffer pointed to by `out`. The context
392 * itself is not modified, so extra bytes may be injected afterwards
393 * to continue that computation.
395 * \param ctx pointer to the context structure.
396 * \param out destination buffer for the hash output.
398 void br_md5_out(const br_md5_context
*ctx
, void *out
);
401 * \brief Save MD5 running state.
403 * The running state for MD5 (output of the last internal block
404 * processing) is written in the buffer pointed to by `out`. The
405 * number of bytes injected since the last initialisation or reset
406 * call is returned. The context is not modified.
408 * \param ctx pointer to the context structure.
409 * \param out destination buffer for the running state.
410 * \return the injected total byte length.
412 uint64_t br_md5_state(const br_md5_context
*ctx
, void *out
);
415 * \brief Restore MD5 running state.
417 * The running state for MD5 is set to the provided values.
419 * \param ctx pointer to the context structure.
420 * \param stb source buffer for the running state.
421 * \param count the injected total byte length.
423 void br_md5_set_state(br_md5_context
*ctx
, const void *stb
, uint64_t count
);
426 * \brief Symbolic identifier for SHA-1.
431 * \brief SHA-1 output size (in bytes).
433 #define br_sha1_SIZE 20
436 * \brief Constant vtable for SHA-1.
438 extern const br_hash_class br_sha1_vtable
;
441 * \brief SHA-1 context.
443 * First field is a pointer to the vtable; it is set by the initialisation
444 * function. Other fields are not supposed to be accessed by user code.
448 * \brief Pointer to vtable for this context.
450 const br_hash_class
*vtable
;
451 #ifndef BR_DOXYGEN_IGNORE
452 unsigned char buf
[64];
459 * \brief SHA-1 context initialisation.
461 * This function initialises or resets a context for a new SHA-1
462 * computation. It also sets the vtable pointer.
464 * \param ctx pointer to the context structure.
466 void br_sha1_init(br_sha1_context
*ctx
);
469 * \brief Inject some data bytes in a running SHA-1 computation.
471 * The provided context is updated with some data bytes. If the number
472 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
473 * and may be `NULL`, and this function does nothing.
475 * \param ctx pointer to the context structure.
476 * \param data pointer to the injected data.
477 * \param len injected data length (in bytes).
479 void br_sha1_update(br_sha1_context
*ctx
, const void *data
, size_t len
);
482 * \brief Compute SHA-1 output.
484 * The SHA-1 output for the concatenation of all bytes injected in the
485 * provided context since the last initialisation or reset call, is
486 * computed and written in the buffer pointed to by `out`. The context
487 * itself is not modified, so extra bytes may be injected afterwards
488 * to continue that computation.
490 * \param ctx pointer to the context structure.
491 * \param out destination buffer for the hash output.
493 void br_sha1_out(const br_sha1_context
*ctx
, void *out
);
496 * \brief Save SHA-1 running state.
498 * The running state for SHA-1 (output of the last internal block
499 * processing) is written in the buffer pointed to by `out`. The
500 * number of bytes injected since the last initialisation or reset
501 * call is returned. The context is not modified.
503 * \param ctx pointer to the context structure.
504 * \param out destination buffer for the running state.
505 * \return the injected total byte length.
507 uint64_t br_sha1_state(const br_sha1_context
*ctx
, void *out
);
510 * \brief Restore SHA-1 running state.
512 * The running state for SHA-1 is set to the provided values.
514 * \param ctx pointer to the context structure.
515 * \param stb source buffer for the running state.
516 * \param count the injected total byte length.
518 void br_sha1_set_state(br_sha1_context
*ctx
, const void *stb
, uint64_t count
);
522 #define br_sha1_SIZE 20
523 extern const br_hash_class br_sha1_vtable;
525 const br_hash_class *vtable;
526 unsigned char buf[64];
530 void br_sha1_init(br_sha1_context *ctx);
531 void br_sha1_update(br_sha1_context *ctx, const void *data, size_t len);
532 void br_sha1_out(const br_sha1_context *ctx, void *out);
533 uint64_t br_sha1_state(const br_sha1_context *ctx, void *out);
534 void br_sha1_set_state(br_sha1_context *ctx, const void *stb, uint64_t count);
538 * \brief Symbolic identifier for SHA-224.
540 #define br_sha224_ID 3
543 * \brief SHA-224 output size (in bytes).
545 #define br_sha224_SIZE 28
548 * \brief Constant vtable for SHA-224.
550 extern const br_hash_class br_sha224_vtable
;
553 * \brief SHA-224 context.
555 * First field is a pointer to the vtable; it is set by the initialisation
556 * function. Other fields are not supposed to be accessed by user code.
560 * \brief Pointer to vtable for this context.
562 const br_hash_class
*vtable
;
563 #ifndef BR_DOXYGEN_IGNORE
564 unsigned char buf
[64];
571 * \brief SHA-224 context initialisation.
573 * This function initialises or resets a context for a new SHA-224
574 * computation. It also sets the vtable pointer.
576 * \param ctx pointer to the context structure.
578 void br_sha224_init(br_sha224_context
*ctx
);
581 * \brief Inject some data bytes in a running SHA-224 computation.
583 * The provided context is updated with some data bytes. If the number
584 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
585 * and may be `NULL`, and this function does nothing.
587 * \param ctx pointer to the context structure.
588 * \param data pointer to the injected data.
589 * \param len injected data length (in bytes).
591 void br_sha224_update(br_sha224_context
*ctx
, const void *data
, size_t len
);
594 * \brief Compute SHA-224 output.
596 * The SHA-224 output for the concatenation of all bytes injected in the
597 * provided context since the last initialisation or reset call, is
598 * computed and written in the buffer pointed to by `out`. The context
599 * itself is not modified, so extra bytes may be injected afterwards
600 * to continue that computation.
602 * \param ctx pointer to the context structure.
603 * \param out destination buffer for the hash output.
605 void br_sha224_out(const br_sha224_context
*ctx
, void *out
);
608 * \brief Save SHA-224 running state.
610 * The running state for SHA-224 (output of the last internal block
611 * processing) is written in the buffer pointed to by `out`. The
612 * number of bytes injected since the last initialisation or reset
613 * call is returned. The context is not modified.
615 * \param ctx pointer to the context structure.
616 * \param out destination buffer for the running state.
617 * \return the injected total byte length.
619 uint64_t br_sha224_state(const br_sha224_context
*ctx
, void *out
);
622 * \brief Restore SHA-224 running state.
624 * The running state for SHA-224 is set to the provided values.
626 * \param ctx pointer to the context structure.
627 * \param stb source buffer for the running state.
628 * \param count the injected total byte length.
630 void br_sha224_set_state(br_sha224_context
*ctx
,
631 const void *stb
, uint64_t count
);
634 #define br_sha224_ID 3
635 #define br_sha224_SIZE 28
636 extern const br_hash_class br_sha224_vtable;
638 const br_hash_class *vtable;
639 unsigned char buf[64];
643 void br_sha224_init(br_sha224_context *ctx);
644 void br_sha224_update(br_sha224_context *ctx, const void *data, size_t len);
645 void br_sha224_out(const br_sha224_context *ctx, void *out);
646 uint64_t br_sha224_state(const br_sha224_context *ctx, void *out);
647 void br_sha224_set_state(br_sha224_context *ctx,
648 const void *stb, uint64_t count);
652 * \brief Symbolic identifier for SHA-256.
654 #define br_sha256_ID 4
657 * \brief SHA-256 output size (in bytes).
659 #define br_sha256_SIZE 32
662 * \brief Constant vtable for SHA-256.
664 extern const br_hash_class br_sha256_vtable
;
666 #ifdef BR_DOXYGEN_IGNORE
668 * \brief SHA-256 context.
670 * First field is a pointer to the vtable; it is set by the initialisation
671 * function. Other fields are not supposed to be accessed by user code.
675 * \brief Pointer to vtable for this context.
677 const br_hash_class
*vtable
;
680 typedef br_sha224_context br_sha256_context
;
684 * \brief SHA-256 context initialisation.
686 * This function initialises or resets a context for a new SHA-256
687 * computation. It also sets the vtable pointer.
689 * \param ctx pointer to the context structure.
691 void br_sha256_init(br_sha256_context
*ctx
);
693 #ifdef BR_DOXYGEN_IGNORE
695 * \brief Inject some data bytes in a running SHA-256 computation.
697 * The provided context is updated with some data bytes. If the number
698 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
699 * and may be `NULL`, and this function does nothing.
701 * \param ctx pointer to the context structure.
702 * \param data pointer to the injected data.
703 * \param len injected data length (in bytes).
705 void br_sha256_update(br_sha256_context
*ctx
, const void *data
, size_t len
);
707 #define br_sha256_update br_sha224_update
711 * \brief Compute SHA-256 output.
713 * The SHA-256 output for the concatenation of all bytes injected in the
714 * provided context since the last initialisation or reset call, is
715 * computed and written in the buffer pointed to by `out`. The context
716 * itself is not modified, so extra bytes may be injected afterwards
717 * to continue that computation.
719 * \param ctx pointer to the context structure.
720 * \param out destination buffer for the hash output.
722 void br_sha256_out(const br_sha256_context
*ctx
, void *out
);
724 #if BR_DOXYGEN_IGNORE
726 * \brief Save SHA-256 running state.
728 * The running state for SHA-256 (output of the last internal block
729 * processing) is written in the buffer pointed to by `out`. The
730 * number of bytes injected since the last initialisation or reset
731 * call is returned. The context is not modified.
733 * \param ctx pointer to the context structure.
734 * \param out destination buffer for the running state.
735 * \return the injected total byte length.
737 uint64_t br_sha256_state(const br_sha256_context
*ctx
, void *out
);
739 #define br_sha256_state br_sha224_state
742 #if BR_DOXYGEN_IGNORE
744 * \brief Restore SHA-256 running state.
746 * The running state for SHA-256 is set to the provided values.
748 * \param ctx pointer to the context structure.
749 * \param stb source buffer for the running state.
750 * \param count the injected total byte length.
752 void br_sha256_set_state(br_sha256_context
*ctx
,
753 const void *stb
, uint64_t count
);
755 #define br_sha256_set_state br_sha224_set_state
759 #define br_sha256_ID 4
760 #define br_sha256_SIZE 32
761 extern const br_hash_class br_sha256_vtable;
762 typedef br_sha224_context br_sha256_context;
763 void br_sha256_init(br_sha256_context *ctx);
764 #define br_sha256_update br_sha224_update
765 void br_sha256_out(const br_sha256_context *ctx, void *out);
766 #define br_sha256_state br_sha224_state
767 #define br_sha256_set_state br_sha224_set_state
771 * \brief Symbolic identifier for SHA-384.
773 #define br_sha384_ID 5
776 * \brief SHA-384 output size (in bytes).
778 #define br_sha384_SIZE 48
781 * \brief Constant vtable for SHA-384.
783 extern const br_hash_class br_sha384_vtable
;
786 * \brief SHA-384 context.
788 * First field is a pointer to the vtable; it is set by the initialisation
789 * function. Other fields are not supposed to be accessed by user code.
793 * \brief Pointer to vtable for this context.
795 const br_hash_class
*vtable
;
796 #ifndef BR_DOXYGEN_IGNORE
797 unsigned char buf
[128];
804 * \brief SHA-384 context initialisation.
806 * This function initialises or resets a context for a new SHA-384
807 * computation. It also sets the vtable pointer.
809 * \param ctx pointer to the context structure.
811 void br_sha384_init(br_sha384_context
*ctx
);
814 * \brief Inject some data bytes in a running SHA-384 computation.
816 * The provided context is updated with some data bytes. If the number
817 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
818 * and may be `NULL`, and this function does nothing.
820 * \param ctx pointer to the context structure.
821 * \param data pointer to the injected data.
822 * \param len injected data length (in bytes).
824 void br_sha384_update(br_sha384_context
*ctx
, const void *data
, size_t len
);
827 * \brief Compute SHA-384 output.
829 * The SHA-384 output for the concatenation of all bytes injected in the
830 * provided context since the last initialisation or reset call, is
831 * computed and written in the buffer pointed to by `out`. The context
832 * itself is not modified, so extra bytes may be injected afterwards
833 * to continue that computation.
835 * \param ctx pointer to the context structure.
836 * \param out destination buffer for the hash output.
838 void br_sha384_out(const br_sha384_context
*ctx
, void *out
);
841 * \brief Save SHA-384 running state.
843 * The running state for SHA-384 (output of the last internal block
844 * processing) is written in the buffer pointed to by `out`. The
845 * number of bytes injected since the last initialisation or reset
846 * call is returned. The context is not modified.
848 * \param ctx pointer to the context structure.
849 * \param out destination buffer for the running state.
850 * \return the injected total byte length.
852 uint64_t br_sha384_state(const br_sha384_context
*ctx
, void *out
);
855 * \brief Restore SHA-384 running state.
857 * The running state for SHA-384 is set to the provided values.
859 * \param ctx pointer to the context structure.
860 * \param stb source buffer for the running state.
861 * \param count the injected total byte length.
863 void br_sha384_set_state(br_sha384_context
*ctx
,
864 const void *stb
, uint64_t count
);
867 #define br_sha384_ID 5
868 #define br_sha384_SIZE 48
869 extern const br_hash_class br_sha384_vtable;
871 const br_hash_class *vtable;
872 unsigned char buf[128];
876 void br_sha384_init(br_sha384_context *ctx);
877 void br_sha384_update(br_sha384_context *ctx, const void *data, size_t len);
878 void br_sha384_out(const br_sha384_context *ctx, void *out);
879 uint64_t br_sha384_state(const br_sha384_context *ctx, void *out);
880 void br_sha384_set_state(br_sha384_context *ctx,
881 const void *stb, uint64_t count);
885 * \brief Symbolic identifier for SHA-512.
887 #define br_sha512_ID 6
890 * \brief SHA-512 output size (in bytes).
892 #define br_sha512_SIZE 64
895 * \brief Constant vtable for SHA-512.
897 extern const br_hash_class br_sha512_vtable
;
899 #ifdef BR_DOXYGEN_IGNORE
901 * \brief SHA-512 context.
903 * First field is a pointer to the vtable; it is set by the initialisation
904 * function. Other fields are not supposed to be accessed by user code.
908 * \brief Pointer to vtable for this context.
910 const br_hash_class
*vtable
;
911 unsigned char buf
[128];
916 typedef br_sha384_context br_sha512_context
;
920 * \brief SHA-512 context initialisation.
922 * This function initialises or resets a context for a new SHA-512
923 * computation. It also sets the vtable pointer.
925 * \param ctx pointer to the context structure.
927 void br_sha512_init(br_sha512_context
*ctx
);
929 #ifdef BR_DOXYGEN_IGNORE
931 * \brief Inject some data bytes in a running SHA-512 computation.
933 * The provided context is updated with some data bytes. If the number
934 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
935 * and may be `NULL`, and this function does nothing.
937 * \param ctx pointer to the context structure.
938 * \param data pointer to the injected data.
939 * \param len injected data length (in bytes).
941 void br_sha512_update(br_sha512_context
*ctx
, const void *data
, size_t len
);
943 #define br_sha512_update br_sha384_update
947 * \brief Compute SHA-512 output.
949 * The SHA-512 output for the concatenation of all bytes injected in the
950 * provided context since the last initialisation or reset call, is
951 * computed and written in the buffer pointed to by `out`. The context
952 * itself is not modified, so extra bytes may be injected afterwards
953 * to continue that computation.
955 * \param ctx pointer to the context structure.
956 * \param out destination buffer for the hash output.
958 void br_sha512_out(const br_sha512_context
*ctx
, void *out
);
960 #ifdef BR_DOXYGEN_IGNORE
962 * \brief Save SHA-512 running state.
964 * The running state for SHA-512 (output of the last internal block
965 * processing) is written in the buffer pointed to by `out`. The
966 * number of bytes injected since the last initialisation or reset
967 * call is returned. The context is not modified.
969 * \param ctx pointer to the context structure.
970 * \param out destination buffer for the running state.
971 * \return the injected total byte length.
973 uint64_t br_sha512_state(const br_sha512_context
*ctx
, void *out
);
975 #define br_sha512_state br_sha384_state
978 #ifdef BR_DOXYGEN_IGNORE
980 * \brief Restore SHA-512 running state.
982 * The running state for SHA-512 is set to the provided values.
984 * \param ctx pointer to the context structure.
985 * \param stb source buffer for the running state.
986 * \param count the injected total byte length.
988 void br_sha512_set_state(br_sha512_context
*ctx
,
989 const void *stb
, uint64_t count
);
991 #define br_sha512_set_state br_sha384_set_state
995 #define br_sha512_ID 6
996 #define br_sha512_SIZE 64
997 extern const br_hash_class br_sha512_vtable;
998 typedef br_sha384_context br_sha512_context;
999 void br_sha512_init(br_sha512_context *ctx);
1000 #define br_sha512_update br_sha384_update
1001 void br_sha512_out(const br_sha512_context *ctx, void *out);
1002 #define br_sha512_state br_sha384_state
1003 #define br_sha512_set_state br_sha384_set_state
1007 * "md5sha1" is a special hash function that computes both MD5 and SHA-1
1008 * on the same input, and produces a 36-byte output (MD5 and SHA-1
1009 * concatenation, in that order). State size is also 36 bytes.
1013 * \brief Symbolic identifier for MD5+SHA-1.
1015 * MD5+SHA-1 is the concatenation of MD5 and SHA-1, computed over the
1016 * same input. It is not one of the functions identified in TLS, so
1017 * we give it a symbolic identifier of value 0.
1019 #define br_md5sha1_ID 0
1022 * \brief MD5+SHA-1 output size (in bytes).
1024 #define br_md5sha1_SIZE 36
1027 * \brief Constant vtable for MD5+SHA-1.
1029 extern const br_hash_class br_md5sha1_vtable
;
1032 * \brief MD5+SHA-1 context.
1034 * First field is a pointer to the vtable; it is set by the initialisation
1035 * function. Other fields are not supposed to be accessed by user code.
1039 * \brief Pointer to vtable for this context.
1041 const br_hash_class
*vtable
;
1042 #ifndef BR_DOXYGEN_IGNORE
1043 unsigned char buf
[64];
1045 uint32_t val_md5
[4];
1046 uint32_t val_sha1
[5];
1048 } br_md5sha1_context
;
1051 * \brief MD5+SHA-1 context initialisation.
1053 * This function initialises or resets a context for a new SHA-512
1054 * computation. It also sets the vtable pointer.
1056 * \param ctx pointer to the context structure.
1058 void br_md5sha1_init(br_md5sha1_context
*ctx
);
1061 * \brief Inject some data bytes in a running MD5+SHA-1 computation.
1063 * The provided context is updated with some data bytes. If the number
1064 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
1065 * and may be `NULL`, and this function does nothing.
1067 * \param ctx pointer to the context structure.
1068 * \param data pointer to the injected data.
1069 * \param len injected data length (in bytes).
1071 void br_md5sha1_update(br_md5sha1_context
*ctx
, const void *data
, size_t len
);
1074 * \brief Compute MD5+SHA-1 output.
1076 * The MD5+SHA-1 output for the concatenation of all bytes injected in the
1077 * provided context since the last initialisation or reset call, is
1078 * computed and written in the buffer pointed to by `out`. The context
1079 * itself is not modified, so extra bytes may be injected afterwards
1080 * to continue that computation.
1082 * \param ctx pointer to the context structure.
1083 * \param out destination buffer for the hash output.
1085 void br_md5sha1_out(const br_md5sha1_context
*ctx
, void *out
);
1088 * \brief Save MD5+SHA-1 running state.
1090 * The running state for MD5+SHA-1 (output of the last internal block
1091 * processing) is written in the buffer pointed to by `out`. The
1092 * number of bytes injected since the last initialisation or reset
1093 * call is returned. The context is not modified.
1095 * \param ctx pointer to the context structure.
1096 * \param out destination buffer for the running state.
1097 * \return the injected total byte length.
1099 uint64_t br_md5sha1_state(const br_md5sha1_context
*ctx
, void *out
);
1102 * \brief Restore MD5+SHA-1 running state.
1104 * The running state for MD5+SHA-1 is set to the provided values.
1106 * \param ctx pointer to the context structure.
1107 * \param stb source buffer for the running state.
1108 * \param count the injected total byte length.
1110 void br_md5sha1_set_state(br_md5sha1_context
*ctx
,
1111 const void *stb
, uint64_t count
);
1114 * \brief Aggregate context for configurable hash function support.
1116 * The `br_hash_compat_context` type is a type which is large enough to
1117 * serve as context for all standard hash functions defined above.
1120 const br_hash_class
*vtable
;
1122 br_sha1_context sha1
;
1123 br_sha224_context sha224
;
1124 br_sha256_context sha256
;
1125 br_sha384_context sha384
;
1126 br_sha512_context sha512
;
1127 br_md5sha1_context md5sha1
;
1128 } br_hash_compat_context
;
1131 * The multi-hasher is a construct that handles hashing of the same input
1132 * data with several hash functions, with a single shared input buffer.
1133 * It can handle MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512
1134 * simultaneously, though which functions are activated depends on
1135 * the set implementation pointers.
1139 * \brief Multi-hasher context structure.
1141 * The multi-hasher runs up to six hash functions in the standard TLS list
1142 * (MD5, SHA-1, SHA-224, SHA-256, SHA-384 and SHA-512) in parallel, over
1145 * The multi-hasher does _not_ follow the OOP structure with a vtable.
1146 * Instead, it is configured with the vtables of the hash functions it
1147 * should run. Structure fields are not supposed to be accessed directly.
1150 #ifndef BR_DOXYGEN_IGNORE
1151 unsigned char buf
[128];
1153 uint32_t val_32
[25];
1154 uint64_t val_64
[16];
1155 const br_hash_class
*impl
[6];
1157 } br_multihash_context
;
1160 * \brief Clear a multi-hasher context.
1162 * This should always be called once on a given context, _before_ setting
1163 * the implementation pointers.
1165 * \param ctx the multi-hasher context.
1167 void br_multihash_zero(br_multihash_context
*ctx
);
1170 * \brief Set a hash function implementation.
1172 * Implementations shall be set _after_ clearing the context (with
1173 * `br_multihash_zero()`) but _before_ initialising the computation
1174 * (with `br_multihash_init()`). The hash function implementation
1175 * MUST be one of the standard hash functions (MD5, SHA-1, SHA-224,
1176 * SHA-256, SHA-384 or SHA-512); it may also be `NULL` to remove
1177 * an implementation from the multi-hasher.
1179 * \param ctx the multi-hasher context.
1180 * \param id the hash function symbolic identifier.
1181 * \param impl the hash function vtable, or `NULL`.
1184 br_multihash_setimpl(br_multihash_context
*ctx
,
1185 int id
, const br_hash_class
*impl
)
1188 * This code relies on hash functions ID being values 1 to 6,
1189 * in the MD5 to SHA-512 order.
1191 ctx
->impl
[id
- 1] = impl
;
1195 * \brief Get a hash function implementation.
1197 * This function returns the currently configured vtable for a given
1198 * hash function (by symbolic ID). If no such function was configured in
1199 * the provided multi-hasher context, then this function returns `NULL`.
1201 * \param ctx the multi-hasher context.
1202 * \param id the hash function symbolic identifier.
1203 * \return the hash function vtable, or `NULL`.
1205 static inline const br_hash_class
*
1206 br_multihash_getimpl(const br_multihash_context
*ctx
, int id
)
1208 return ctx
->impl
[id
- 1];
1212 * \brief Reset a multi-hasher context.
1214 * This function prepares the context for a new hashing computation,
1215 * for all implementations configured at that point.
1217 * \param ctx the multi-hasher context.
1219 void br_multihash_init(br_multihash_context
*ctx
);
1222 * \brief Inject some data bytes in a running multi-hashing computation.
1224 * The provided context is updated with some data bytes. If the number
1225 * of bytes (`len`) is zero, then the data pointer (`data`) is ignored
1226 * and may be `NULL`, and this function does nothing.
1228 * \param ctx pointer to the context structure.
1229 * \param data pointer to the injected data.
1230 * \param len injected data length (in bytes).
1232 void br_multihash_update(br_multihash_context
*ctx
,
1233 const void *data
, size_t len
);
1236 * \brief Compute a hash output from a multi-hasher.
1238 * The hash output for the concatenation of all bytes injected in the
1239 * provided context since the last initialisation or reset call, is
1240 * computed and written in the buffer pointed to by `dst`. The hash
1241 * function to use is identified by `id` and must be one of the standard
1242 * hash functions. If that hash function was indeed configured in the
1243 * multi-hasher context, the corresponding hash value is written in
1244 * `dst` and its length (in bytes) is returned. If the hash function
1245 * was _not_ configured, then nothing is written in `dst` and 0 is
1248 * The context itself is not modified, so extra bytes may be injected
1249 * afterwards to continue the hash computations.
1251 * \param ctx pointer to the context structure.
1252 * \param id the hash function symbolic identifier.
1253 * \param dst destination buffer for the hash output.
1254 * \return the hash output length (in bytes), or 0.
1256 size_t br_multihash_out(const br_multihash_context
*ctx
, int id
, void *dst
);
1259 * \brief Type for a GHASH implementation.
1261 * GHASH is a sort of keyed hash meant to be used to implement GCM in
1262 * combination with a block cipher (with 16-byte blocks).
1264 * The `y` array has length 16 bytes and is used for input and output; in
1265 * a complete GHASH run, it starts with an all-zero value. `h` is a 16-byte
1266 * value that serves as key (it is derived from the encryption key in GCM,
1267 * using the block cipher). The data length (`len`) is expressed in bytes.
1268 * The `y` array is updated.
1270 * If the data length is not a multiple of 16, then the data is implicitly
1271 * padded with zeros up to the next multiple of 16. Thus, when using GHASH
1272 * in GCM, this method may be called twice, for the associated data and
1273 * for the ciphertext, respectively; the zero-padding implements exactly
1276 * \param y the array to update.
1277 * \param h the GHASH key.
1278 * \param data the input data (may be `NULL` if `len` is zero).
1279 * \param len the input data length (in bytes).
1281 typedef void (*br_ghash
)(void *y
, const void *h
, const void *data
, size_t len
);
1284 * \brief GHASH implementation using multiplications (mixed 32-bit).
1286 * This implementation uses multiplications of 32-bit values, with a
1287 * 64-bit result. It is constant-time (if multiplications are
1290 * \param y the array to update.
1291 * \param h the GHASH key.
1292 * \param data the input data (may be `NULL` if `len` is zero).
1293 * \param len the input data length (in bytes).
1295 void br_ghash_ctmul(void *y
, const void *h
, const void *data
, size_t len
);
1298 * \brief GHASH implementation using multiplications (strict 32-bit).
1300 * This implementation uses multiplications of 32-bit values, with a
1301 * 32-bit result. It is usually somewhat slower than `br_ghash_ctmul()`,
1302 * but it is expected to be faster on architectures for which the
1303 * 32-bit multiplication opcode does not yield the upper 32 bits of the
1304 * product. It is constant-time (if multiplications are constant-time).
1306 * \param y the array to update.
1307 * \param h the GHASH key.
1308 * \param data the input data (may be `NULL` if `len` is zero).
1309 * \param len the input data length (in bytes).
1311 void br_ghash_ctmul32(void *y
, const void *h
, const void *data
, size_t len
);
1314 * \brief GHASH implementation using multiplications (64-bit).
1316 * This implementation uses multiplications of 64-bit values, with a
1317 * 64-bit result. It is constant-time (if multiplications are
1318 * constant-time). It is substantially faster than `br_ghash_ctmul()`
1319 * and `br_ghash_ctmul32()` on most 64-bit architectures.
1321 * \param y the array to update.
1322 * \param h the GHASH key.
1323 * \param data the input data (may be `NULL` if `len` is zero).
1324 * \param len the input data length (in bytes).
1326 void br_ghash_ctmul64(void *y
, const void *h
, const void *data
, size_t len
);