/
KeccakDuplex-documentation.h
189 lines (175 loc) · 9.96 KB
/
KeccakDuplex-documentation.h
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
/*
The eXtended Keccak Code Package (XKCP)
https://github.com/XKCP/XKCP
Keccak, designed by Guido Bertoni, Joan Daemen, Michaël Peeters and Gilles Van Assche.
Implementation by the designers, hereby denoted as "the implementer".
For more information, feedback or questions, please refer to the Keccak Team website:
https://keccak.team/
To the extent possible under law, the implementer has waived all copyright
and related or neighboring rights to the source code in this file.
http://creativecommons.org/publicdomain/zero/1.0/
*/
/** General information
*
* The following type and functions are not actually implemented. Their
* documentation is generic, with the prefix Prefix replaced by
* - KeccakWidth200 for a duplex object based on Keccak-f[200]
* - KeccakWidth400 for a duplex object based on Keccak-f[400]
* - KeccakWidth800 for a duplex object based on Keccak-f[800]
* - KeccakWidth1600 for a duplex object based on Keccak-f[1600]
*
* In all these functions, the rate and capacity must sum to the width of the
* chosen permutation. For instance, to use the duplex object
* Keccak[r=1346, c=254], one must use the KeccakWidth1600_Duplex* functions.
*
* The Prefix_DuplexInstance contains the duplex instance attributes for use
* with the Prefix_Duplex* functions.
* It gathers the state processed by the permutation as well as the rate,
* the position of input/output bytes in the state in case of partial
* input or output.
*/
#ifdef DontReallyInclude_DocumentationOnly
/**
* Structure that contains the duplex instance for use with the
* Prefix_Duplex* functions.
* It gathers the state processed by the permutation as well as
* the rate.
*/
typedef struct Prefix_DuplexInstanceStruct {
/** The state processed by the permutation. */
unsigned char state[SnP_stateSizeInBytes];
/** The value of the rate in bits.*/
unsigned int rate;
/** The position in the state of the next byte to be input. */
unsigned int byteInputIndex;
/** The position in the state of the next byte to be output. */
unsigned int byteOutputIndex;
} Prefix_DuplexInstance;
/**
* Function to initialize a duplex object Duplex[Keccak-f[r+c], pad10*1, r].
* @param duplexInstance Pointer to the duplex instance to be initialized.
* @param rate The value of the rate r.
* @param capacity The value of the capacity c.
* @pre One must have r+c equal to the supported width of this implementation.
* @pre 3 ≤ @a rate ≤ width, and otherwise the value of the rate is unrestricted.
* @return Zero if successful, 1 otherwise.
*/
int Prefix_DuplexInitialize(Prefix_DuplexInstance *duplexInstance, unsigned int rate, unsigned int capacity);
/**
* Function to make a duplexing call to the duplex object initialized
* with Prefix_DuplexInitialize().
* @param duplexInstance Pointer to the duplex instance initialized
* by Prefix_DuplexInitialize().
* @param sigmaBegin Pointer to the first part of the input σ given as bytes.
* Trailing bits are given in @a delimitedSigmaEnd.
* @param sigmaBeginByteLen The number of input bytes provided in @a sigmaBegin.
* @param Z Pointer to the buffer where to store the output data Z.
* @param ZByteLen The number of output bytes desired for Z.
* If @a ZByteLen*8 is greater than the rate r,
* the last byte contains only r modulo 8 bits,
* in the least significant bits.
* @param delimitedSigmaEnd Byte containing from 0 to 7 trailing bits that must be
* appended to the input data in @a sigmaBegin.
* These <i>n</i>=|σ| mod 8 bits must be in the least significant bit positions.
* These bits must be delimited with a bit 1 at position <i>n</i>
* (counting from 0=LSB to 7=MSB) and followed by bits 0
* from position <i>n</i>+1 to position 7.
* Some examples:
* - If |σ| is a multiple of 8, then @a delimitedSigmaEnd must be 0x01.
* - If |σ| mod 8 is 1 and the last bit is 1 then @a delimitedSigmaEnd must be 0x03.
* - If |σ| mod 8 is 4 and the last 4 bits are 0,0,0,1 then @a delimitedSigmaEnd must be 0x18.
* - If |σ| mod 8 is 6 and the last 6 bits are 1,1,1,0,0,1 then @a delimitedSigmaEnd must be 0x67.
* .
* @note The input bits σ are the result of the concatenation of
* the bytes given in Prefix_DuplexingFeedPartialInput()
* calls since the last call to Prefix_Duplexing(),
* the bytes in @a sigmaBegin
* and the bits in @a delimitedSigmaEnd before the delimiter.
* @pre @a delimitedSigmaEnd ≠ 0x00
* @pre @a sigmaBeginByteLen*8+<i>n</i> (+ length of previously queued data) ≤ (r-2)
* @pre @a ZByteLen ≤ ceil(r/8)
* @return Zero if successful, 1 otherwise.
*/
int Prefix_Duplexing(Prefix_DuplexInstance *duplexInstance, const unsigned char *sigmaBegin, unsigned int sigmaBeginByteLen, unsigned char *Z, unsigned int ZByteLen, unsigned char delimitedSigmaEnd);
/**
* Function to queue input data that will subsequently used in the next
* call to Prefix_Duplexing().
* @param duplexInstance Pointer to the duplex instance initialized
* by Prefix_DuplexInitialize().
* @param input Pointer to the bytes to queue.
* @param inputByteLen The number of input bytes provided in @a input.
* @pre The total number of input bytes since the last Prefix_Duplexing()
* call must not be higher than floor((r-2)/8).
* @return Zero if successful, 1 otherwise.
*/
int Prefix_DuplexingFeedPartialInput(Prefix_DuplexInstance *duplexInstance, const unsigned char *input, unsigned int inputByteLen);
/**
* Function to queue input data that will subsequently used in the next
* call to Prefix_Duplexing(), where the data here consist of all-zero bytes.
* @param duplexInstance Pointer to the duplex instance initialized
* by Prefix_DuplexInitialize().
* @param inputByteLen The number of input bytes 0x00 to feed.
* @pre The total number of input bytes since the last Prefix_Duplexing()
* call must not be higher than floor((r-2)/8).
* @return Zero if successful, 1 otherwise.
*/
int Prefix_DuplexingFeedZeroes(Prefix_DuplexInstance *duplexInstance, unsigned int inputByteLen);
/**
* Function to queue input data that will subsequently used in the next
* call to Prefix_Duplexing(), with the additional pre-processing that
* the input data is first bitwise added with the output data of the previous duplexing
* call at the same offset.
* In practice, this comes down to overwriting the input data in the state
* of the duplex object.
* @param duplexInstance Pointer to the duplex instance initialized
* by Prefix_DuplexInitialize().
* @param input Pointer to the bytes to queue, before they are XORed.
* @param inputByteLen The number of input bytes provided in @a input.
* @pre The total number of input bytes since the last Prefix_Duplexing()
* call must not be higher than floor((r-2)/8).
* @return Zero if successful, 1 otherwise.
*/
int Prefix_DuplexingOverwritePartialInput(Prefix_DuplexInstance *duplexInstance, const unsigned char *input, unsigned int inputByteLen);
/**
* Function to queue input data for the next call to Prefix_Duplexing() that
* is equal to the output data of the previous duplexing call at the same offset.
* In practice, this comes down to overwriting with zeroes the state
* of the duplex object.
* @param duplexInstance Pointer to the duplex instance initialized
* by Prefix_DuplexInitialize().
* @param inputByteLen The number of bytes to overwrite with zeroes.
* @pre No input data may have been queued since the last call
* to Prefix_Duplexing().
* @pre The total number of input bytes since the last Prefix_Duplexing()
* call must not be higher than floor((r-2)/8).
* @return Zero if successful, 1 otherwise.
*/
int Prefix_DuplexingOverwriteWithZeroes(Prefix_DuplexInstance *duplexInstance, unsigned int inputByteLen);
/**
* Function to fetch output data beyond those that were already output since
* the last call to Prefix_Duplexing().
* @param duplexInstance Pointer to the duplex instance initialized
* by Prefix_DuplexInitialize().
* @param output Pointer to the buffer where to store the output data.
* @param outputByteLen The number of output bytes desired.
* @pre The total number of output bytes, taken since (and including in)
* the last call to Prefix_Duplexing() cannot be higher than ceil(r/8).
* @return Zero if successful, 1 otherwise.
*/
int Prefix_DuplexingGetFurtherOutput(Prefix_DuplexInstance *duplexInstance, unsigned char *out, unsigned int outByteLen);
/**
* Function to fetch output data beyond those that were already output since
* the last call to Prefix_Duplexing(), with the additional post-processing
* that this data is bitwise added with the given input buffer
* before it is stored into the given output buffer.
* @param duplexInstance Pointer to the duplex instance initialized
* by Prefix_DuplexInitialize().
* @param input Pointer to the input buffer.
* @param output Pointer to the output buffer, which may be equal to @a input.
* @param outputByteLen The number of output bytes desired.
* @pre The total number of output bytes, taken since (and including in)
* the last call to Prefix_Duplexing() cannot be higher than ceil(r/8).
* @return Zero if successful, 1 otherwise.
*/
int Prefix_DuplexingGetFurtherOutputAndAdd(Prefix_DuplexInstance *duplexInstance, const unsigned char *input, unsigned char *output, unsigned int outputByteLen);
#endif