Line data    Source code

       1             : #ifndef HEADER_fd_src_ballet_keccak256_fd_keccak256_h
       2             : #define HEADER_fd_src_ballet_keccak256_fd_keccak256_h
       3             : 
       4             : /* fd_keccak256 provides APIs for Keccak256 hashing of messages. */
       5             : 
       6             : #include "../fd_ballet_base.h"
       7             : 
       8             : /* FD_KECCAK256_{ALIGN,FOOTPRINT} describe the alignment and footprint needed
       9             :    for a memory region to hold a fd_keccak256_t.  ALIGN is a positive
      10             :    integer power of 2.  FOOTPRINT is a multiple of align.  ALIGN is
      11             :    recommended to be at least double cache line to mitigate various
      12             :    kinds of false sharing.  These are provided to facilitate compile
      13             :    time declarations. */
      14             : 
      15             : #define FD_KECCAK256_ALIGN     (128UL)
      16             : #define FD_KECCAK256_FOOTPRINT (256UL)
      17             : 
      18             : /* FD_KECCAK256_HASH_SZ describe the size of a KECCAK256 hash in bytes. */
      19             : 
      20             : #define FD_KECCAK256_HASH_SZ    (32UL) /* == 2^FD_KECCAK256_LG_HASH_SZ, explicit to workaround compiler limitations */
      21             : 
      22             : /* A fd_keccak256_t should be treated as an opaque handle of a keccak256
      23             :    calculation state.  (It technically isn't here facilitate compile
      24             :    time declarations of fd_keccak256_t memory.) */
      25             : 
      26      958072 : #define FD_KECCAK256_STATE_SZ (25UL)
      27      962693 : #define FD_KECCAK256_OUT_SZ (32UL)
      28      958072 : #define FD_KECCAK256_RATE ((sizeof(ulong)*FD_KECCAK256_STATE_SZ) - (2*FD_KECCAK256_OUT_SZ))
      29             : 
      30             : struct __attribute__((aligned(FD_KECCAK256_ALIGN))) fd_keccak256_private {
      31             : 
      32             :   /* This point is 128-byte aligned */
      33             : 
      34             :   /* This point is 64-byte aligned */
      35             : 
      36             :   ulong state[ 25 ];
      37             : 
      38             :   /* This point is 32-byte aligned */
      39             : 
      40             :   ulong padding_start; /* Number of buffered bytes, in [0,FD_KECCAK256_RATE) */
      41             : 
      42             :   /* Padding to 128-byte here */
      43             : };
      44             : 
      45             : typedef struct fd_keccak256_private fd_keccak256_t;
      46             : 
      47             : FD_PROTOTYPES_BEGIN
      48             : 
      49             : /* fd_keccak256_init starts a keccak256 calculation.  sha is assumed to be a
      50             :    current local join to a keccak256 calculation state with no other
      51             :    concurrent operation that would modify the state while this is
      52             :    executing.  Any preexisting state for an in-progress or recently
      53             :    completed calculation will be discarded.  Returns sha (on return, sha
      54             :    will have the state of a new in-progress calculation). */
      55             : 
      56             : fd_keccak256_t *
      57             : fd_keccak256_init( fd_keccak256_t * sha );
      58             : 
      59             : /* fd_keccak256_append adds sz bytes locally pointed to by data an
      60             :    in-progress keccak256 calculation.  sha, data and sz are assumed to be
      61             :    valid (i.e. sha is a current local join to a keccak256 calculation state
      62             :    with no other concurrent operations that would modify the state while
      63             :    this is executing, data points to the first of the sz bytes and will
      64             :    be unmodified while this is running with no interest retained after
      65             :    return ... data==NULL is fine if sz==0).  Returns sha (on return, sha
      66             :    will have the updated state of the in-progress calculation).
      67             : 
      68             :    It does not matter how the user groups data bytes for a keccak256
      69             :    calculation; the final hash will be identical. */
      70             : 
      71             : fd_keccak256_t *
      72             : fd_keccak256_append( fd_keccak256_t * sha,
      73             :                      void const *     data,
      74             :                      ulong            sz );
      75             : 
      76             : /* fd_keccak256_fini finishes a a keccak256 calculation.  sha and hash are
      77             :    assumed to be valid (i.e. sha is a local join to a keccak256 calculation
      78             :    state that has an in-progress calculation with no other concurrent
      79             :    operations that would modify the state while this is executing and
      80             :    hash points to the first byte of a 32-byte memory region where the
      81             :    result of the calculation should be stored).  Returns hash (on
      82             :    return, there will be no calculation in-progress on sha and 32-byte
      83             :    buffer pointed to by hash will be populated with the calculation
      84             :    result). */
      85             : 
      86             : void *
      87             : fd_keccak256_fini( fd_keccak256_t * sha,
      88             :                    void *           hash );
      89             : 
      90             : /* fd_keccak256_hash is a convenience implementation of:
      91             : 
      92             :      fd_keccak256_t keccak[1];
      93             :      return fd_keccak256_fini( fd_keccak256_append( fd_keccak256_init( keccak ), data, sz ), hash )
      94             : 
      95             :   It may eventually be streamlined. */
      96             : 
      97             : void *
      98             : fd_keccak256_hash( void const * data,
      99             :                    ulong        sz,
     100             :                    void *       hash );
     101             : 
     102             : FD_PROTOTYPES_END
     103             : 
     104             : #endif /* HEADER_fd_src_ballet_keccak256_fd_keccak256_h */