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           3 : #define FD_KECCAK256_ALIGN     (128UL)
      16           3 : #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           3 : #define FD_KECCAK256_MAGIC (0xF17EDA2CE7EC2560) /* FIREDANCE KEC256 V0 */
      27             : 
      28   892984110 : #define FD_KECCAK256_STATE_SZ (25UL)
      29   894185739 : #define FD_KECCAK256_OUT_SZ (32UL)
      30   892984110 : #define FD_KECCAK256_RATE ((sizeof(ulong)*FD_KECCAK256_STATE_SZ) - (2*FD_KECCAK256_OUT_SZ))
      31             : 
      32             : struct __attribute__((aligned(FD_KECCAK256_ALIGN))) fd_keccak256_private {
      33             : 
      34             :   /* This point is 128-byte aligned */
      35             : 
      36             :   /* This point is 64-byte aligned */
      37             : 
      38             :   ulong state[ 25 ];
      39             : 
      40             :   /* This point is 32-byte aligned */
      41             : 
      42             :   ulong magic;    /* ==FD_KECCAK256_MAGIC */
      43             :   ulong padding_start; /* Number of buffered bytes, in [0,FD_KECCAK256_BUF_MAX) */
      44             : 
      45             :   /* Padding to 128-byte here */
      46             : };
      47             : 
      48             : typedef struct fd_keccak256_private fd_keccak256_t;
      49             : 
      50             : FD_PROTOTYPES_BEGIN
      51             : 
      52             : /* fd_keccak256_{align,footprint,new,join,leave,delete} usage is identical to
      53             :    that of fd_sha256.  See ../sha256/fd_sha256.h */
      54             : 
      55             : FD_FN_CONST ulong
      56             : fd_keccak256_align( void );
      57             : 
      58             : FD_FN_CONST ulong
      59             : fd_keccak256_footprint( void );
      60             : 
      61             : void *
      62             : fd_keccak256_new( void * shmem );
      63             : 
      64             : fd_keccak256_t *
      65             : fd_keccak256_join( void * shsha );
      66             : 
      67             : void *
      68             : fd_keccak256_leave( fd_keccak256_t * sha );
      69             : 
      70             : void *
      71             : fd_keccak256_delete( void * shsha );
      72             : 
      73             : /* fd_keccak256_init starts a keccak256 calculation.  sha is assumed to be a
      74             :    current local join to a keccak256 calculation state with no other
      75             :    concurrent operation that would modify the state while this is
      76             :    executing.  Any preexisting state for an in-progress or recently
      77             :    completed calculation will be discarded.  Returns sha (on return, sha
      78             :    will have the state of a new in-progress calculation). */
      79             : 
      80             : fd_keccak256_t *
      81             : fd_keccak256_init( fd_keccak256_t * sha );
      82             : 
      83             : /* fd_keccak256_append adds sz bytes locally pointed to by data an
      84             :    in-progress keccak256 calculation.  sha, data and sz are assumed to be
      85             :    valid (i.e. sha is a current local join to a keccak256 calculation state
      86             :    with no other concurrent operations that would modify the state while
      87             :    this is executing, data points to the first of the sz bytes and will
      88             :    be unmodified while this is running with no interest retained after
      89             :    return ... data==NULL is fine if sz==0).  Returns sha (on return, sha
      90             :    will have the updated state of the in-progress calculation).
      91             : 
      92             :    It does not matter how the user group data bytes for a keccak256
      93             :    calculation; the final hash will be identical.  It is preferable for
      94             :    performance to try to append as many bytes as possible as a time
      95             :    though.  It is also preferable for performance if sz is a multiple of
      96             :    64. */
      97             : 
      98             : fd_keccak256_t *
      99             : fd_keccak256_append( fd_keccak256_t * sha,
     100             :                      void const *     data,
     101             :                      ulong            sz );
     102             : 
     103             : /* fd_keccak256_fini finishes a a keccak256 calculation.  sha and hash are
     104             :    assumed to be valid (i.e. sha is a local join to a keccak256 calculation
     105             :    state that has an in-progress calculation with no other concurrent
     106             :    operations that would modify the state while this is executing and
     107             :    hash points to the first byte of a 32-byte memory region where the
     108             :    result of the calculation should be stored).  Returns hash (on
     109             :    return, there will be no calculation in-progress on sha and 32-byte
     110             :    buffer pointed to by hash will be populated with the calculation
     111             :    result). */
     112             : 
     113             : void *
     114             : fd_keccak256_fini( fd_keccak256_t * sha,
     115             :                    void *           hash );
     116             : 
     117             : /* fd_keccak256_hash is a convenience implementation of:
     118             : 
     119             :      fd_keccak256_t keccak[1];
     120             :      return fd_keccak256_fini( fd_keccak256_append( fd_keccak256_init( keccak ), data, sz ), hash )
     121             : 
     122             :   It may eventually be streamlined. */
     123             : 
     124             : void *
     125             : fd_keccak256_hash( void const * data,
     126             :                    ulong        sz,
     127             :                    void *       hash );
     128             : 
     129             : FD_PROTOTYPES_END
     130             : 
     131             : #endif /* HEADER_fd_src_ballet_keccak256_fd_keccak256_h */