xref: /PHP-8.3/ext/hash/sha3/generic32lc/KeccakHash.h (revision ada776c8)
1 /*
2 Implementation by the Keccak, Keyak and Ketje Teams, namely, Guido Bertoni,
3 Joan Daemen, Michaël Peeters, Gilles Van Assche and Ronny Van Keer, hereby
4 denoted as "the implementer".
5 
6 For more information, feedback or questions, please refer to our websites:
7 http://keccak.noekeon.org/
8 http://keyak.noekeon.org/
9 http://ketje.noekeon.org/
10 
11 To the extent possible under law, the implementer has waived all copyright
12 and related or neighboring rights to the source code in this file.
13 http://creativecommons.org/publicdomain/zero/1.0/
14 */
15 
16 #ifndef _KeccakHashInterface_h_
17 #define _KeccakHashInterface_h_
18 
19 #ifndef KeccakP1600_excluded
20 
21 #include "KeccakSponge.h"
22 #include <string.h>
23 
24 typedef unsigned char BitSequence;
25 typedef size_t DataLength;
26 typedef enum { SUCCESS = 0, FAIL = 1, BAD_HASHLEN = 2 } HashReturn;
27 
28 typedef struct {
29     KeccakWidth1600_SpongeInstance sponge;
30     unsigned int fixedOutputLength;
31     unsigned char delimitedSuffix;
32 } Keccak_HashInstance;
33 
34 /**
35   * Function to initialize the Keccak[r, c] sponge function instance used in sequential hashing mode.
36   * @param  hashInstance    Pointer to the hash instance to be initialized.
37   * @param  rate        The value of the rate r.
38   * @param  capacity    The value of the capacity c.
39   * @param  hashbitlen  The desired number of output bits,
40   *                     or 0 for an arbitrarily-long output.
41   * @param  delimitedSuffix Bits that will be automatically appended to the end
42   *                         of the input message, as in domain separation.
43   *                         This is a byte containing from 0 to 7 bits
44   *                         formatted like the @a delimitedData parameter of
45   *                         the Keccak_SpongeAbsorbLastFewBits() function.
46   * @pre    One must have r+c=1600 and the rate a multiple of 8 bits in this implementation.
47   * @return SUCCESS if successful, FAIL otherwise.
48   */
49 HashReturn Keccak_HashInitialize(Keccak_HashInstance *hashInstance, unsigned int rate, unsigned int capacity, unsigned int hashbitlen, unsigned char delimitedSuffix);
50 
51 /** Macro to initialize a SHAKE128 instance as specified in the FIPS 202 standard.
52   */
53 #define Keccak_HashInitialize_SHAKE128(hashInstance)        Keccak_HashInitialize(hashInstance, 1344,  256,   0, 0x1F)
54 
55 /** Macro to initialize a SHAKE256 instance as specified in the FIPS 202 standard.
56   */
57 #define Keccak_HashInitialize_SHAKE256(hashInstance)        Keccak_HashInitialize(hashInstance, 1088,  512,   0, 0x1F)
58 
59 /** Macro to initialize a SHA3-224 instance as specified in the FIPS 202 standard.
60   */
61 #define Keccak_HashInitialize_SHA3_224(hashInstance)        Keccak_HashInitialize(hashInstance, 1152,  448, 224, 0x06)
62 
63 /** Macro to initialize a SHA3-256 instance as specified in the FIPS 202 standard.
64   */
65 #define Keccak_HashInitialize_SHA3_256(hashInstance)        Keccak_HashInitialize(hashInstance, 1088,  512, 256, 0x06)
66 
67 /** Macro to initialize a SHA3-384 instance as specified in the FIPS 202 standard.
68   */
69 #define Keccak_HashInitialize_SHA3_384(hashInstance)        Keccak_HashInitialize(hashInstance,  832,  768, 384, 0x06)
70 
71 /** Macro to initialize a SHA3-512 instance as specified in the FIPS 202 standard.
72   */
73 #define Keccak_HashInitialize_SHA3_512(hashInstance)        Keccak_HashInitialize(hashInstance,  576, 1024, 512, 0x06)
74 
75 /**
76   * Function to give input data to be absorbed.
77   * @param  hashInstance    Pointer to the hash instance initialized by Keccak_HashInitialize().
78   * @param  data        Pointer to the input data.
79   *                     When @a databitLen is not a multiple of 8, the last bits of data must be
80   *                     in the least significant bits of the last byte (little-endian convention).
81   * @param  databitLen  The number of input bits provided in the input data.
82   * @pre    In the previous call to Keccak_HashUpdate(), databitlen was a multiple of 8.
83   * @return SUCCESS if successful, FAIL otherwise.
84   */
85 HashReturn Keccak_HashUpdate(Keccak_HashInstance *hashInstance, const BitSequence *data, DataLength databitlen);
86 
87 /**
88   * Function to call after all input blocks have been input and to get
89   * output bits if the length was specified when calling Keccak_HashInitialize().
90   * @param  hashInstance    Pointer to the hash instance initialized by Keccak_HashInitialize().
91   * If @a hashbitlen was not 0 in the call to Keccak_HashInitialize(), the number of
92   *     output bits is equal to @a hashbitlen.
93   * If @a hashbitlen was 0 in the call to Keccak_HashInitialize(), the output bits
94   *     must be extracted using the Keccak_HashSqueeze() function.
95   * @param  hashval     Pointer to the buffer where to store the output data.
96   * @return SUCCESS if successful, FAIL otherwise.
97   */
98 HashReturn Keccak_HashFinal(Keccak_HashInstance *hashInstance, BitSequence *hashval);
99 
100  /**
101   * Function to squeeze output data.
102   * @param  hashInstance    Pointer to the hash instance initialized by Keccak_HashInitialize().
103   * @param  data        Pointer to the buffer where to store the output data.
104   * @param  databitlen  The number of output bits desired (must be a multiple of 8).
105   * @pre    Keccak_HashFinal() must have been already called.
106   * @pre    @a databitlen is a multiple of 8.
107   * @return SUCCESS if successful, FAIL otherwise.
108   */
109 HashReturn Keccak_HashSqueeze(Keccak_HashInstance *hashInstance, BitSequence *data, DataLength databitlen);
110 
111 #define Keccak_HashInstance_ImplType 32
112 
113 #endif
114 
115 #endif
116