• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
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