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   892936143 : #define FD_KECCAK256_STATE_SZ (25UL)
      27   894136395 : #define FD_KECCAK256_OUT_SZ (32UL)
      28   892936143 : #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_BUF_MAX) */
      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 group data bytes for a keccak256
      69             :    calculation; the final hash will be identical.  It is preferable for
      70             :    performance to try to append as many bytes as possible as a time
      71             :    though.  It is also preferable for performance if sz is a multiple of
      72             :    64. */
      73             : 
      74             : fd_keccak256_t *
      75             : fd_keccak256_append( fd_keccak256_t * sha,
      76             :                      void const *     data,
      77             :                      ulong            sz );
      78             : 
      79             : /* fd_keccak256_fini finishes a a keccak256 calculation.  sha and hash are
      80             :    assumed to be valid (i.e. sha is a local join to a keccak256 calculation
      81             :    state that has an in-progress calculation with no other concurrent
      82             :    operations that would modify the state while this is executing and
      83             :    hash points to the first byte of a 32-byte memory region where the
      84             :    result of the calculation should be stored).  Returns hash (on
      85             :    return, there will be no calculation in-progress on sha and 32-byte
      86             :    buffer pointed to by hash will be populated with the calculation
      87             :    result). */
      88             : 
      89             : void *
      90             : fd_keccak256_fini( fd_keccak256_t * sha,
      91             :                    void *           hash );
      92             : 
      93             : /* fd_keccak256_hash is a convenience implementation of:
      94             : 
      95             :      fd_keccak256_t keccak[1];
      96             :      return fd_keccak256_fini( fd_keccak256_append( fd_keccak256_init( keccak ), data, sz ), hash )
      97             : 
      98             :   It may eventually be streamlined. */
      99             : 
     100             : void *
     101             : fd_keccak256_hash( void const * data,
     102             :                    ulong        sz,
     103             :                    void *       hash );
     104             : 
     105             : FD_PROTOTYPES_END
     106             : 
     107             : #endif /* HEADER_fd_src_ballet_keccak256_fd_keccak256_h */