1  /*
 2  The Keccak sponge function, designed by Guido Bertoni, Joan Daemen,
 3  Michaël Peeters and Gilles Van Assche. For more information, feedback or
 4  questions, please refer to our website: http://keccak.noekeon.org/
 5  
 6  Implementation by the designers,
 7  hereby denoted as "the implementer".
 8  
 9  To the extent possible under law, the implementer has waived all copyright
10  and related or neighboring rights to the source code in this file.
11  http://creativecommons.org/publicdomain/zero/1.0/
12  */
13  
14  #ifndef _KeccakNISTInterface_h_
15  #define _KeccakNISTInterface_h_
16  
17  #include "KeccakSponge.h"
18  
19  typedef unsigned char BitSequence;
20  typedef unsigned long long DataLength;
21  typedef enum { SUCCESS = 0, FAIL = 1, BAD_HASHLEN = 2 } HashReturn;
22  
23  typedef spongeState hashState;
24  
25  /**
26    * Function to initialize the state of the Keccak[r, c] sponge function.
27    * The rate r and capacity c values are determined from @a hashbitlen.
28    * @param  state       Pointer to the state of the sponge function to be initialized.
29    * @param  hashbitlen  The desired number of output bits, 
30    *                     or 0 for Keccak[] with default parameters
31    *                     and arbitrarily-long output.
32    * @pre    The value of hashbitlen must be one of 0, 224, 256, 384 and 512.
33    * @return SUCCESS if successful, BAD_HASHLEN if the value of hashbitlen is incorrect.
34    */
35  HashReturn Init(hashState *state, int hashbitlen);
36  /**
37    * Function to give input data for the sponge function to absorb.
38    * @param  state       Pointer to the state of the sponge function initialized by Init().
39    * @param  data        Pointer to the input data. 
40    *                     When @a databitLen is not a multiple of 8, the last bits of data must be
41    *                     in the most significant bits of the last byte.
42    * @param  databitLen  The number of input bits provided in the input data.
43    * @pre    In the previous call to Absorb(), databitLen was a multiple of 8.
44    * @return SUCCESS if successful, FAIL otherwise.
45    */
46  HashReturn Update(hashState *state, const BitSequence *data, DataLength databitlen);
47  /**
48    * Function to squeeze output data from the sponge function.
49    * If @a hashbitlen was not 0 in the call to Init(), the number of output bits is equal to @a hashbitlen.
50    * If @a hashbitlen was 0 in the call to Init(), the output bits must be extracted using the Squeeze() function.
51    * @param  state       Pointer to the state of the sponge function initialized by Init().
52    * @param  hashval     Pointer to the buffer where to store the output data.
53    * @return SUCCESS if successful, FAIL otherwise.
54    */
55  HashReturn Final(hashState *state, BitSequence *hashval);
56  /**
57    * Function to compute a hash using the Keccak[r, c] sponge function.
58    * The rate r and capacity c values are determined from @a hashbitlen.
59    * @param  hashbitlen  The desired number of output bits.
60    * @param  data        Pointer to the input data. 
61    *                     When @a databitLen is not a multiple of 8, the last bits of data must be
62    *                     in the most significant bits of the last byte.
63    * @param  databitLen  The number of input bits provided in the input data.
64    * @param  hashval     Pointer to the buffer where to store the output data.
65    * @pre    The value of hashbitlen must be one of 224, 256, 384 and 512.
66    * @return SUCCESS if successful, BAD_HASHLEN if the value of hashbitlen is incorrect.
67    */
68  HashReturn Hash(int hashbitlen, const BitSequence *data, DataLength databitlen, BitSequence *hashval);
69  
70  #endif