Line data    Source code

       1             : #ifndef HEADER_fd_src_ballet_blake3_fd_blake3_h
       2             : #define HEADER_fd_src_ballet_blake3_fd_blake3_h
       3             : 
       4             : /* fd_blake3 provides APIs for BLAKE3 hashing of messages. */
       5             : 
       6             : #include "../fd_ballet_base.h"
       7             : #include "blake3.h"
       8             : 
       9             : /* FD_BLAKE3_{ALIGN,FOOTPRINT} describe the alignment and footprint needed
      10             :    for a memory region to hold a fd_blake3_t.  ALIGN is a positive
      11             :    integer power of 2.  FOOTPRINT is a multiple of align.  ALIGN is
      12             :    recommended to be at least double cache line to mitigate various
      13             :    kinds of false sharing.  These are provided to facilitate compile
      14             :    time declarations. */
      15             : 
      16           0 : #define FD_BLAKE3_ALIGN     (128UL)
      17           0 : #define FD_BLAKE3_FOOTPRINT (1920UL)
      18             : 
      19             : /* A fd_blake3_t should be treated as an opaque handle of a blake3
      20             :    calculation state.  (It technically isn't here facilitate compile
      21             :    time declarations of fd_blake3_t memory.) */
      22             : 
      23           0 : #define FD_BLAKE3_MAGIC (0xF17EDA2CEB1A4E30) /* FIREDANCE BLAKE3 V0 */
      24             : 
      25             : struct __attribute__((aligned(FD_BLAKE3_ALIGN))) fd_blake3_private {
      26             :   blake3_hasher hasher;
      27             : 
      28             :   ulong magic;    /* ==FD_BLAKE3_MAGIC */
      29             : };
      30             : 
      31             : typedef struct fd_blake3_private fd_blake3_t;
      32             : 
      33             : FD_PROTOTYPES_BEGIN
      34             : 
      35             : /* fd_blake3_{align,footprint,new,join,leave,delete} usage is identical to
      36             :    that of their fd_sha512 counterparts.  See ../sha512/fd_sha512.h */
      37             : 
      38             : FD_FN_CONST ulong
      39             : fd_blake3_align( void );
      40             : 
      41             : FD_FN_CONST ulong
      42             : fd_blake3_footprint( void );
      43             : 
      44             : void *
      45             : fd_blake3_new( void * shmem );
      46             : 
      47             : fd_blake3_t *
      48             : fd_blake3_join( void * shsha );
      49             : 
      50             : void *
      51             : fd_blake3_leave( fd_blake3_t * sha );
      52             : 
      53             : void *
      54             : fd_blake3_delete( void * shsha );
      55             : 
      56             : /* fd_blake3_init starts a blake3 calculation.  sha is assumed to be a
      57             :    current local join to a blake3 calculation state with no other
      58             :    concurrent operation that would modify the state while this is
      59             :    executing.  Any preexisting state for an in-progress or recently
      60             :    completed calculation will be discarded.  Returns sha (on return, sha
      61             :    will have the state of a new in-progress calculation). */
      62             : 
      63             : fd_blake3_t *
      64             : fd_blake3_init( fd_blake3_t * sha );
      65             : 
      66             : /* fd_blake3_append adds sz bytes locally pointed to by data an
      67             :    in-progress blake3 calculation.  sha, data and sz are assumed to be
      68             :    valid (i.e. sha is a current local join to a blake3 calculation state
      69             :    with no other concurrent operations that would modify the state while
      70             :    this is executing, data points to the first of the sz bytes and will
      71             :    be unmodified while this is running with no interest retained after
      72             :    return ... data==NULL is fine if sz==0).  Returns sha (on return, sha
      73             :    will have the updated state of the in-progress calculation).
      74             : 
      75             :    It does not matter how the user group data bytes for a blake3
      76             :    calculation; the final hash will be identical.  It is preferable for
      77             :    performance to try to append as many bytes as possible as a time
      78             :    though.  It is also preferable for performance if sz is a multiple of
      79             :    64 for all but the last append (it is also preferable if sz is less
      80             :    than 56 for the last append). */
      81             : 
      82             : fd_blake3_t *
      83             : fd_blake3_append( fd_blake3_t * sha,
      84             :                   void const *  data,
      85             :                   ulong         sz );
      86             : 
      87             : /* fd_blake3_fini finishes a a blake3 calculation.  sha and hash are
      88             :    assumed to be valid (i.e. sha is a local join to a blake3 calculation
      89             :    state that has an in-progress calculation with no other concurrent
      90             :    operations that would modify the state while this is executing and
      91             :    hash points to the first byte of a 32-byte memory region where the
      92             :    result of the calculation should be stored).  Returns hash (on
      93             :    return, there will be no calculation in-progress on sha and 32-byte
      94             :    buffer pointed to by hash will be populated with the calculation
      95             :    result). */
      96             : 
      97             : void *
      98             : fd_blake3_fini( fd_blake3_t * sha,
      99             :                 void *        hash );
     100             : 
     101             : /* fd_blake3_fini_512 is the same as fd_blake3_fini, but returns
     102             :    a 512-bit hash value instead of 256-bit. */
     103             : 
     104             : void *
     105             : fd_blake3_fini_512( fd_blake3_t * sha,
     106             :                     void *        hash );
     107             : 
     108             : /* fd_blake3_fini_varlen is the same as fd_blake3_fini, but returns
     109             :    hash_len bytes instead of 256-bit. */
     110             : 
     111             : void *
     112             : fd_blake3_fini_varlen( fd_blake3_t * sha,
     113             :                        void *        hash, 
     114             :                        ulong         hash_len );
     115             : 
     116             : FD_PROTOTYPES_END
     117             : 
     118             : #endif /* HEADER_fd_src_ballet_blake3_fd_blake3_h */