1 /* 2 Implementation by the Keccak, Keyak and Ketje Teams, namely, Guido Bertoni, 3 Joan Daemen, Michal 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
