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 _KeccakSponge_h_ |
17 | #define _KeccakSponge_h_ |
18 | |
19 | /** General information |
20 | * |
21 | * The following type and functions are not actually implemented. Their |
22 | * documentation is generic, with the prefix Prefix replaced by |
23 | * - KeccakWidth200 for a sponge function based on Keccak-f[200] |
24 | * - KeccakWidth400 for a sponge function based on Keccak-f[400] |
25 | * - KeccakWidth800 for a sponge function based on Keccak-f[800] |
26 | * - KeccakWidth1600 for a sponge function based on Keccak-f[1600] |
27 | * |
28 | * In all these functions, the rate and capacity must sum to the width of the |
29 | * chosen permutation. For instance, to use the sponge function |
30 | * Keccak[r=1344, c=256], one must use KeccakWidth1600_Sponge() or a combination |
31 | * of KeccakWidth1600_SpongeInitialize(), KeccakWidth1600_SpongeAbsorb(), |
32 | * KeccakWidth1600_SpongeAbsorbLastFewBits() and |
33 | * KeccakWidth1600_SpongeSqueeze(). |
34 | * |
35 | * The Prefix_SpongeInstance contains the sponge instance attributes for use |
36 | * with the Prefix_Sponge* functions. |
37 | * It gathers the state processed by the permutation as well as the rate, |
38 | * the position of input/output bytes in the state and the phase |
39 | * (absorbing or squeezing). |
40 | */ |
41 | |
42 | #ifdef DontReallyInclude_DocumentationOnly |
43 | /** Function to evaluate the sponge function Keccak[r, c] in a single call. |
44 | * @param rate The value of the rate r. |
45 | * @param capacity The value of the capacity c. |
46 | * @param input Pointer to the input message (before the suffix). |
47 | * @param inputByteLen The length of the input message in bytes. |
48 | * @param suffix Byte containing from 0 to 7 suffix bits |
49 | * that must be absorbed after @a input. |
50 | * These <i>n</i> bits must be in the least significant bit positions. |
51 | * These bits must be delimited with a bit 1 at position <i>n</i> |
52 | * (counting from 0=LSB to 7=MSB) and followed by bits 0 |
53 | * from position <i>n</i>+1 to position 7. |
54 | * Some examples: |
55 | * - If no bits are to be absorbed, then @a suffix must be 0x01. |
56 | * - If the 2-bit sequence 0,0 is to be absorbed, @a suffix must be 0x04. |
57 | * - If the 5-bit sequence 0,1,0,0,1 is to be absorbed, @a suffix must be 0x32. |
58 | * - If the 7-bit sequence 1,1,0,1,0,0,0 is to be absorbed, @a suffix must be 0x8B. |
59 | * . |
60 | * @param output Pointer to the output buffer. |
61 | * @param outputByteLen The desired number of output bytes. |
62 | * @pre One must have r+c equal to the supported width of this implementation |
63 | * and the rate a multiple of 8 bits (one byte) in this implementation. |
64 | * @pre @a suffix ≠ 0x00 |
65 | * @return Zero if successful, 1 otherwise. |
66 | */ |
67 | int Prefix_Sponge(unsigned int rate, unsigned int capacity, const unsigned char *input, size_t inputByteLen, unsigned char suffix, unsigned char *output, size_t outputByteLen); |
68 | |
69 | /** |
70 | * Function to initialize the state of the Keccak[r, c] sponge function. |
71 | * The phase of the sponge function is set to absorbing. |
72 | * @param spongeInstance Pointer to the sponge instance to be initialized. |
73 | * @param rate The value of the rate r. |
74 | * @param capacity The value of the capacity c. |
75 | * @pre One must have r+c equal to the supported width of this implementation |
76 | * and the rate a multiple of 8 bits (one byte) in this implementation. |
77 | * @return Zero if successful, 1 otherwise. |
78 | */ |
79 | int Prefix_SpongeInitialize(Prefix_SpongeInstance *spongeInstance, unsigned int rate, unsigned int capacity); |
80 | |
81 | /** |
82 | * Function to give input data bytes for the sponge function to absorb. |
83 | * @param spongeInstance Pointer to the sponge instance initialized by Prefix_SpongeInitialize(). |
84 | * @param data Pointer to the input data. |
85 | * @param dataByteLen The number of input bytes provided in the input data. |
86 | * @pre The sponge function must be in the absorbing phase, |
87 | * i.e., Prefix_SpongeSqueeze() or Prefix_SpongeAbsorbLastFewBits() |
88 | * must not have been called before. |
89 | * @return Zero if successful, 1 otherwise. |
90 | */ |
91 | int Prefix_SpongeAbsorb(Prefix_SpongeInstance *spongeInstance, const unsigned char *data, size_t dataByteLen); |
92 | |
93 | /** |
94 | * Function to give input data bits for the sponge function to absorb |
95 | * and then to switch to the squeezing phase. |
96 | * @param spongeInstance Pointer to the sponge instance initialized by Prefix_SpongeInitialize(). |
97 | * @param delimitedData Byte containing from 0 to 7 trailing bits |
98 | * that must be absorbed. |
99 | * These <i>n</i> bits must be in the least significant bit positions. |
100 | * These bits must be delimited with a bit 1 at position <i>n</i> |
101 | * (counting from 0=LSB to 7=MSB) and followed by bits 0 |
102 | * from position <i>n</i>+1 to position 7. |
103 | * Some examples: |
104 | * - If no bits are to be absorbed, then @a delimitedData must be 0x01. |
105 | * - If the 2-bit sequence 0,0 is to be absorbed, @a delimitedData must be 0x04. |
106 | * - If the 5-bit sequence 0,1,0,0,1 is to be absorbed, @a delimitedData must be 0x32. |
107 | * - If the 7-bit sequence 1,1,0,1,0,0,0 is to be absorbed, @a delimitedData must be 0x8B. |
108 | * . |
109 | * @pre The sponge function must be in the absorbing phase, |
110 | * i.e., Prefix_SpongeSqueeze() or Prefix_SpongeAbsorbLastFewBits() |
111 | * must not have been called before. |
112 | * @pre @a delimitedData ≠ 0x00 |
113 | * @return Zero if successful, 1 otherwise. |
114 | */ |
115 | int Prefix_SpongeAbsorbLastFewBits(Prefix_SpongeInstance *spongeInstance, unsigned char delimitedData); |
116 | |
117 | /** |
118 | * Function to squeeze output data from the sponge function. |
119 | * If the sponge function was in the absorbing phase, this function |
120 | * switches it to the squeezing phase |
121 | * as if Prefix_SpongeAbsorbLastFewBits(spongeInstance, 0x01) was called. |
122 | * @param spongeInstance Pointer to the sponge instance initialized by Prefix_SpongeInitialize(). |
123 | * @param data Pointer to the buffer where to store the output data. |
124 | * @param dataByteLen The number of output bytes desired. |
125 | * @return Zero if successful, 1 otherwise. |
126 | */ |
127 | int Prefix_SpongeSqueeze(Prefix_SpongeInstance *spongeInstance, unsigned char *data, size_t dataByteLen); |
128 | #endif |
129 | |
130 | #include <string.h> |
131 | #include "align.h" |
132 | |
133 | #define KCP_DeclareSpongeStructure(prefix, size, alignment) \ |
134 | ALIGN(alignment) typedef struct prefix##_SpongeInstanceStruct { \ |
135 | unsigned char state[size]; \ |
136 | unsigned int rate; \ |
137 | unsigned int byteIOIndex; \ |
138 | int squeezing; \ |
139 | } prefix##_SpongeInstance; |
140 | |
141 | #define KCP_DeclareSpongeFunctions(prefix) \ |
142 | int prefix##_Sponge(unsigned int rate, unsigned int capacity, const unsigned char *input, size_t inputByteLen, unsigned char suffix, unsigned char *output, size_t outputByteLen); \ |
143 | int prefix##_SpongeInitialize(prefix##_SpongeInstance *spongeInstance, unsigned int rate, unsigned int capacity); \ |
144 | int prefix##_SpongeAbsorb(prefix##_SpongeInstance *spongeInstance, const unsigned char *data, size_t dataByteLen); \ |
145 | int prefix##_SpongeAbsorbLastFewBits(prefix##_SpongeInstance *spongeInstance, unsigned char delimitedData); \ |
146 | int prefix##_SpongeSqueeze(prefix##_SpongeInstance *spongeInstance, unsigned char *data, size_t dataByteLen); |
147 | |
148 | #ifndef KeccakP200_excluded |
149 | #include "KeccakP-200-SnP.h" |
150 | KCP_DeclareSpongeStructure(KeccakWidth200, KeccakP200_stateSizeInBytes, KeccakP200_stateAlignment) |
151 | KCP_DeclareSpongeFunctions(KeccakWidth200) |
152 | #endif |
153 | |
154 | #ifndef KeccakP400_excluded |
155 | #include "KeccakP-400-SnP.h" |
156 | KCP_DeclareSpongeStructure(KeccakWidth400, KeccakP400_stateSizeInBytes, KeccakP400_stateAlignment) |
157 | KCP_DeclareSpongeFunctions(KeccakWidth400) |
158 | #endif |
159 | |
160 | #ifndef KeccakP800_excluded |
161 | #include "KeccakP-800-SnP.h" |
162 | KCP_DeclareSpongeStructure(KeccakWidth800, KeccakP800_stateSizeInBytes, KeccakP800_stateAlignment) |
163 | KCP_DeclareSpongeFunctions(KeccakWidth800) |
164 | #endif |
165 | |
166 | #ifndef KeccakP1600_excluded |
167 | #include "KeccakP-1600-SnP.h" |
168 | KCP_DeclareSpongeStructure(KeccakWidth1600, KeccakP1600_stateSizeInBytes, KeccakP1600_stateAlignment) |
169 | KCP_DeclareSpongeFunctions(KeccakWidth1600) |
170 | #endif |
171 | |
172 | #endif |
173 | |