3 * The SHA3 algorithm family
5 * (c) 2017 Straylight/Edgeware
8 /*----- Licensing notice --------------------------------------------------*
10 * This file is part of Catacomb.
12 * Catacomb is free software; you can redistribute it and/or modify
13 * it under the terms of the GNU Library General Public License as
14 * published by the Free Software Foundation; either version 2 of the
15 * License, or (at your option) any later version.
17 * Catacomb is distributed in the hope that it will be useful,
18 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20 * GNU Library General Public License for more details.
22 * You should have received a copy of the GNU Library General Public
23 * License along with Catacomb; if not, write to the Free
24 * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
28 #ifndef CATACOMB_SHA3_H
29 #define CATACOMB_SHA3_H
35 /*----- Notes on the SHA3 algorithm family --------------------------------*
37 * The winner of the SHA3 competition was Keccak, designed by Guido Bertoni,
38 * Joan Daemen, Michaƫl Peeters, and Gilles Van Assche. The algorithm uses
39 * their `sponge construction', based on a fixed attempt to instantiate an
40 * `ideal permutation'. The construction is rather versatile, and NIST has
41 * standardized a number of algorithms based on it.
43 * The basic offerings are the drop-in replacements for the SHA2 family.
44 * These are slower than is ideal, because of the decision to provide O(2^n)
45 * resistance to second-preimage attacks for the n-bit hash function, which
46 * means that, effectively, the capacity parameter is set unnecessarily
47 * large. (There was a major fuss when NIST tried to change this in a draft
48 * of te standard.) All of the obvious hash modes, e.g., HMAC, MGF, can be
49 * applied to the SHA3 hash functions, though I can't really recommend this:
50 * there's almost certainly a better way of doing whatever it is.
52 * Other members of the family are: SHAKE and cSHAKE, `extendable-output
53 * funnctions' which can be used directly in place of MGFs; and KMAC, a
54 * message authentication code with arbitrary-length key, message, and tag,
55 * which can therefore be used as a key-derivation function. The cSHAKE
56 * construction, on which KMAC is based, introduces a personalization string
57 * which can be used for domain separation.
60 /*----- Header files ------------------------------------------------------*/
62 #include <mLib/bits.h>
64 #ifndef CATACOMB_KECCAK1600_H
65 # include "keccak1600.h"
68 #ifndef CATACOMB_GCIPHER_H
72 #ifndef CATACOMB_GHASH_H
76 #ifndef CATACOMB_GMAC_H
80 #ifndef CATACOMB_GRAND_H
84 /*----- The SHA3 hash function family -------------------------------------*/
86 typedef struct sha3_ctx {
91 #define sha3_224_ctx sha3_ctx
92 #define sha3_256_ctx sha3_ctx
93 #define sha3_384_ctx sha3_ctx
94 #define sha3_512_ctx sha3_ctx
96 #define SHA3_224_HASHSZ 28
97 #define SHA3_256_HASHSZ 32
98 #define SHA3_384_HASHSZ 48
99 #define SHA3_512_HASHSZ 64
101 #define SHA3_224_BUFSZ 144
102 #define SHA3_256_BUFSZ 136
103 #define SHA3_384_BUFSZ 104
104 #define SHA3_512_BUFSZ 72
106 #define SHA3_STATESZ (sizeof(sha3_ctx))
107 #define SHA3_224_STATESZ SHA3_STATESZ
108 #define SHA3_256_STATESZ SHA3_STATESZ
109 #define SHA3_384_STATESZ SHA3_STATESZ
110 #define SHA3_512_STATESZ SHA3_STATESZ
112 /* --- @sha3_{224,256,384,512}_init@ --- *
114 * Arguments: @sha3_ctx *ctx@ = pointer to context block to initialize
118 * Use: Initializes a SHA3 hashing context for use.
121 extern void sha3_224_init(sha3_ctx */*ctx*/);
122 extern void sha3_256_init(sha3_ctx */*ctx*/);
123 extern void sha3_384_init(sha3_ctx */*ctx*/);
124 extern void sha3_512_init(sha3_ctx */*ctx*/);
126 /* --- @sha3_hash@ --- *
128 * Arguments: @sha3_ctx *ctx@ = pointer to context bock
129 * @const void *p@ = pointer to data to hash
130 * @size_t sz@ = size of buffer to hash
134 * Use: Hashes a buffer of data. The buffer may be of any size and
138 #define sha3_224_hash sha3_hash
139 #define sha3_256_hash sha3_hash
140 #define sha3_384_hash sha3_hash
141 #define sha3_512_hash sha3_hash
143 extern void sha3_hash(sha3_ctx */*ctx*/, const void */*p*/, size_t /*sz*/);
145 /* --- @sha3_done@ --- *
147 * Arguments: @sha3_ctx *ctx@ = pointer to context block
148 * @void *hash@ = pointer to output buffer
152 * Use: Returns the hash of the data read so far.
155 #define sha3_224_done sha3_done
156 #define sha3_256_done sha3_done
157 #define sha3_384_done sha3_done
158 #define sha3_512_done sha3_done
160 extern void sha3_done(sha3_ctx */*ctx*/, void */*hash*/);
162 /* --- @sha3_{224,256,384,512}_set@ --- *
164 * Arguments: @sha3_ctx *ctx@ = pointer to context block
165 * @const void *buf@ = pointer to state buffer
166 * @unsigned long count@ = current count of bytes processed
170 * Use: Initializes a context block from a given state. This is
171 * something of a kludge for the benefit of HMAC, but there are
172 * better ways to use SHA3 as a MAC.
174 * Furthermore, the @count@ argument is expected to be zero or
175 * be the output of @sha3_state@ below. Doing anything else
176 * won't work properly.
179 extern void sha3_224_set(sha3_ctx */*ctx*/,
180 const void */*buf*/, unsigned long /*count*/);
181 extern void sha3_256_set(sha3_ctx */*ctx*/,
182 const void */*buf*/, unsigned long /*count*/);
183 extern void sha3_384_set(sha3_ctx */*ctx*/,
184 const void */*buf*/, unsigned long /*count*/);
185 extern void sha3_512_set(sha3_ctx */*ctx*/,
186 const void */*buf*/, unsigned long /*count*/);
188 /* --- @sha3_state@ --- *
190 * Arguments: @sha3_ctx *ctx@ = pointer to context block
191 * @void *state@ = pointer to buffer for current state
193 * Returns: A value which is meaningful to @sha3_..._set@.
195 * Use: Returns the current state of the hash function such that it
196 * can be passed to @sha3_..._set@.
199 #define sha3_224_state sha3_state
200 #define sha3_256_state sha3_state
201 #define sha3_384_state sha3_state
202 #define sha3_512_state sha3_state
204 extern unsigned long sha3_state(sha3_ctx */*ctx*/, void */*state*/);
206 /* --- Generic hash interface --- */
208 extern const gchash sha3_224, sha3_256, sha3_384, sha3_512;
210 /*----- The cSHAKE XOF algorithm ------------------------------------------*/
212 typedef struct shake_ctx {
216 #define shake128_ctx shake_ctx
217 #define shake256_ctx shake_ctx
219 #define SHAKE128_KEYSZ 16
220 #define SHAKE256_KEYSZ 32
222 #define SHAKE128_HASHSZ 32 /* Somewhat arbitrary... */
223 #define SHAKE256_HASHSZ 64
225 extern const octet shake128_keysz[], shake256_keysz[];
227 /* --- @cshake{128,256}_init@ --- *
229 * Arguments: @shake_ctx *ctx@ = pointer to context to initialize
230 * @const void *func@ = NIST-allocated function name
231 * @size_t fsz@ = length of function name
232 * @const void *perso@ = user personalization string
233 * @size_t psz@ = length of personalization string
237 * Use: Initializes a cSHAKE context. The context is initially in
238 * the `absorbing' state: feed it data with @shake_hash@.
241 extern void cshake128_init(shake_ctx */*ctx*/,
242 const void */*func*/, size_t /*fsz*/,
243 const void */*perso*/, size_t /*psz*/);
245 extern void cshake256_init(shake_ctx */*ctx*/,
246 const void */*func*/, size_t /*fsz*/,
247 const void */*perso*/, size_t /*psz*/);
249 /* --- @shake{128,256}_init@ --- *
251 * Arguments: @sha3_ctx *ctx@ = pointer to context to initialize
255 * Use: Initializes a SHAKE context. The context is initially in
256 * the `absorbing' state: feed it data with @shake_hash@.
259 extern void shake128_init(shake_ctx */*ctx*/);
260 extern void shake256_init(shake_ctx */*ctx*/);
262 /* --- @shake_hash@ --- *
264 * Arguments: @shake_ctx *ctx@ = context to update
265 * @const void *p@ = input buffer
266 * @size_t sz@ = size of input
270 * Use: Feeds input data into a SHAKE context. The context must be
271 * in `absorbing' state.
274 extern void shake_hash(shake_ctx */*ctx*/, const void */*p*/, size_t /*sz*/);
276 /* --- @shake_xof@ --- *
278 * Arguments: @shake_ctx *ctx@ = context to update
282 * Use: Switches the context into `squeezing' state. Use @shake_get@
283 * or @shake_mask@ to extract data.
286 extern void shake_xof(shake_ctx */*ctx*/);
288 /* --- @shake_get@ --- *
290 * Arguments: @shake_ctx *ctx@ = context to update
291 * @void *p@ = output buffer
292 * @size_t sz@ = size of output
296 * Use: Extracts output from a SHAKE context. The context must be
297 * in `squeezing' state.
300 extern void shake_get(shake_ctx */*ctx*/, void */*p*/, size_t /*sz*/);
302 /* --- @shake_mask@ --- *
304 * Arguments: @shake_ctx *ctx@ = context to update
305 * @const void *src@ = pointer to source data, or null
306 * @void *dest@ = output buffer
307 * @size_t sz@ = size of output
311 * Use: Mask the @src@ data by XORing it with output from the SHAKE
312 * context, writing the result to @dest@. The @src@ and @dest
313 * buffers may be equal but must not otherwise overlap. The
314 * context must be in `squeezing' state.
317 extern void shake_mask(shake_ctx */*ctx*/,
318 const void */*src*/, void */*dest*/, size_t /*sz*/);
320 /* --- @shake_done@ --- *
322 * Arguments: @shake_ctx *ctx@ = context to update
323 * @void *h@ = where to write the hash
324 * @size_t hsz@ = size of the hash to make
328 * Use: Switches the context into `squeezing' state. Use @shake_get@
329 * or @shake_mask@ to extract data.
332 extern void shake_done(shake_ctx */*ctx*/, void */*h*/, size_t /*hsz*/);
334 /* --- @shake{128,256}_rand@ --- *
336 * Arguments: @const void *k@ = pointer to seed material
337 * @size_t sz@ = size of the seed
339 * Returns: A pseudorandom generator with the given seed.
342 extern grand *shake128_rand(const void */*k*/, size_t /*sz*/);
343 extern grand *shake256_rand(const void */*k*/, size_t /*sz*/);
345 /* --- @cshake{128,256}_rand@ --- *
347 * Arguments: @const void *func@ = function name
348 * @size_t fsz@ = length of function name
349 * @const void *perso@ = personalization string
350 * @size_t psz@ = length of personalization string
351 * @const void *k@ = pointer to seed material
352 * @size_t sz@ = size of the seed
354 * Returns: A pseudorandom generator with the given seed.
356 * Use: Note that with null @func@ and @perso@ strings, this is
357 * equivalent to @shake128_rand@ or @shake256_rand@.
360 extern grand *cshake128_rand(const void */*func*/, size_t /*fsz*/,
361 const void */*perso*/, size_t /*psz*/,
362 const void */*k*/, size_t /*sz*/);
364 extern grand *cshake256_rand(const void */*func*/, size_t /*fsz*/,
365 const void */*perso*/, size_t /*psz*/,
366 const void */*k*/, size_t /*sz*/);
368 /* --- Generic cipher interface --- */
370 extern const gccipher shake128_xof, shake256_xof;
371 extern const gchash shake128, shake256;
373 /*----- The KMAC variable-length PRF --------------------------------------*/
375 typedef shake_ctx kmac_ctx;
377 #define KMAC128_KEYSZ SHAKE128_KEYSZ
378 #define KMAC256_KEYSZ SHAKE256_KEYSZ
380 #define KMAC128_TAGSZ 16
381 #define KMAC256_TAGSZ 32
383 #define kmac128_keysz shake128_keysz
384 #define kmac256_keysz shake256_keysz
386 /* --- @kmac{128,256}_init@ --- *
388 * Arguments: @kmac_ctx *ctx@ = pointer to context to fill in
389 * @const void *perso@ = personalization string, or null
390 * @size_t psz@ = length of personalization string
391 * @const void *k@ = pointer to key material
392 * @size_t sz@ = size of key material
396 * Use: Sets up a KMAC context. Set @tsz@ to zero for a flexible-
397 * length tag, which can be read using @kmac_get@. Use
398 * @kmac_hash@ to feed in the input message.
401 extern void kmac128_init(kmac_ctx */*ctx*/,
402 const void */*perso*/, size_t /*psz*/,
403 const void */*k*/, size_t /*sz*/);
404 extern void kmac256_init(kmac_ctx */*ctx*/,
405 const void */*perso*/, size_t /*psz*/,
406 const void */*k*/, size_t /*sz*/);
408 /* --- @kmac_xof@ --- *
410 * Arguments: @kmac_ctx *ctx@ = pointer to context
414 * Use: Marks the end of the message to be processed. The output can
415 * be read using @kmac_get@.
418 void kmac_xof(kmac_ctx */*ctx*/);
420 /* --- @kmac_done@ --- *
422 * Arguments: @kmac_ctx *ctx@ = pointer to context
423 * @void *h@ = where to put the tag
424 * @size_t hsz@ = size of tag to produce
428 * Use: Marks the end of the message to be processed and returns a
429 * tag. Note that the tag value is dependent on the output
433 void kmac_done(kmac_ctx */*ctx*/, void */*h*/, size_t /*hsz*/);
435 /* --- Convenience aliases --- */
437 #define kmac_hash shake_hash
438 #define kmac_get shake_get
439 #define kmac_mask shake_mask
441 /* --- @kmac{128,256}_rand@ --- *
443 * Arguments: @const void *perso@ = personalization string, or null
444 * @size_t psz@ = length of personalization string
445 * @const void *k@ = pointer to seed material
446 * @size_t sz@ = size of the seed
448 * Returns: A pseudorandom generator with the given key.
450 * Use: The generator processes an empty message by default, but this
451 * can be changed by seeding it.
454 extern grand *kmac128_rand(const void */*perso*/, size_t /*psz*/,
455 const void */*k*/, size_t /*sz*/);
456 extern grand *kmac256_rand(const void */*perso*/, size_t /*psz*/,
457 const void */*k*/, size_t /*sz*/);
459 /* --- Generic MAC interface --- */
461 extern const gcmac kmac128, kmac256;
463 /*----- That's all, folks -------------------------------------------------*/