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 #endif 112 113 #endif 114
