.TH LIBHASHSUM_INIT_KECCAK_HASHER 3 libhashsum .SH NAME libhashsum_init_keccak_hasher - initialise state for Keccak hashing .SH SYNOPSIS .nf #include \fBstruct libhashsum_hasher\fP { enum libhashsum_algorithm \fIalgorithm\fP; const char *\fIalgorithm_string\fP; size_t \fIinput_block_size\fP; size_t \fIhash_size\fP; unsigned char *\fIhash_output\fP; unsigned char \fIsupports_non_whole_bytes\fP; size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); union libhashsum_state { /* definition omitted */ } \fIstate\fP; }; int \fBlibhashsum_init_keccak_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIratebits\fP, size_t \fIcapbits\fP, size_t \fIhashbits\fP, size_t \fIsqueezes\fP); .fi .PP Link with .I -lhashsum .IR "-lkeccak" . .SH DESCRIPTION The .B libhashsum_init_keccak_hasher function initialises .I *hasher for hashing using the cryptographic hash function Keccak, and stores hash function information and hashing functions for Keccak in .IR *hasher . .PP .I ratebit shall be the rate, in bits per \(dqabsorption\(dq, of the hash function, or 0 if it shall be resolved to an automatically determined value. .PP .I capbits shall be the capacity, in bits, of the hash function's \(dqsponge\(dq, or 0 if it shall be resolved to an automatically determined value. .PP .I hashbits shall be the hash size, in bits or 0 if it shall be resolved to an automatically determined value. .PP .I squeezes shall be the number of \(dqsponge squeezes\(dq to perform at the end phase when producing the hash, or 0 if it shall be resolved to an automatically determined value (which will always be 1). .PP .I hasher->algorithm will be set to .I LIBHASHSUM_KECCAK_224 (if .I (ratebits, capbits, hashbits, squeezes) have the values (1152, 448, 224, 1) after zeroes have been resolved), .I LIBHASHSUM_KECCAK_256 (if .I (ratebits, capbits, hashbits, squeezes) have the values (1088, 512, 256, 1) after zeroes have been resolved), .I LIBHASHSUM_KECCAK_384 (if .I (ratebits, capbits, hashbits, squeezes) have the values (832, 768, 384, 1) after zeroes have been resolved), .I LIBHASHSUM_KECCAK_512 (if .I (ratebits, capbits, hashbits, squeezes) have the values (576, 1024, 512, 1) after zeroes have been resolved), or .I LIBHASHSUM_KECCAK (otherwise). .PP .I hasher->algorithm_string will be set to .RB \(dq Keccak-224 \(dq if .I hasher->algorithm was set to .IR LIBHASHSUM_KECCAK_224 , .RB \(dq Keccak-256 \(dq if .I hasher->algorithm was set to .IR LIBHASHSUM_KECCAK_256 , .RB \(dq Keccak-384 \(dq if .I hasher->algorithm was set to .IR LIBHASHSUM_KECCAK_384 , .RB \(dq Keccak-512 \(dq if .I hasher->algorithm was set to .IR LIBHASHSUM_KECCAK_512 , and otherwise to .RB \(dq Keccak[r= \fIratebits\fP ,c= \fIcapbits\fP ,n= \fIhashbits\fP ] \(dq if .I squeezes<2 or .RB \(dq Keccak[r= \fIratebits\fP ,c= \fIcapbits\fP ,n= \fIhashbits\fP z= \fIsqueezes\fP ] \(dq (if .IR squeezes>1 ), where .IR ratebits , .IR capbits , and .I hashbits have their resolved non-zero values. For the later two cases, .I hasher->algorithm_string will be a pointer to a buffer in .IR hasher->state . .PP .I hasher->input_block_size will be set to the block size, in bytes .RI ( ratebits/8 unless .IR ratebits==0 ). .PP .I hasher->hash_size will be set to the hash size, in bytes .RI ( (hashbits+7)/8 unless .IR hashbits==0 ). .PP .I hasher->hash_output will be set to .IR NULL . .PP .I hasher->supports_non_whole_bytes will be set to 1 to indicate that the .I *hasher->finalise and .I *hasher->finalise_const functions support non-zero values in their .I extra_bits parameter. .PP .I hasher->process will be set to a pointer to the function to call to feed, and process, data into the hash function. Its parameter .I this shall be set to .IR hasher . Its parameter .I data parameter shall be set to the buffer of data to process, and its parameter .I bytes shall set to the number of bytes to process from .IR data . .I *hasher->process will return the number of bytes processed, which will be a multiple of .IR hasher->input_block_size no greater than .IR bytes . .PP .I hasher->finalise_const will be set to a pointer to the function to call once the entire text being hashed has been loaded, and to get the hash of the text. It's parameter .I this shall be set to .IR hasher . Its parameter .I data shall be set to the beginning of any yet unprocessed data, and its parameter .I bytes shall be set to the number of bytes to process from .IR data . Its parameter .I extra_bits shall be set to the number of bits to process from the lower bits of the incomplete byte .IR data[bytes] . The .I *hasher->finalise_const function will return 0 upon successful completion, and set .I hasher->hash_output to a pointer to a buffer in .I hasher->state containing the binary hash of the processed data. Otherwise, the function will return -1, and set .I errno to indicate the error. The function will failure if: .RS .TP .B EINVAL .I extra_bits is 8 or greater. .RE .PP .I hasher->finalise will be set to the pointer to a function that is an alternative to .I *hasher->finalise_const that can support zero-copy provided that the buffer input as the argument .I data is sufficiently large. The .I *hasher->finalise function may rewrite .I data and shall is does not safe to use for multiple hashers (if the same text is hashed using multiple hashers, .I *hasher->finalise_const must be used). The function's parameter .I size shall be set to the size of the buffer .IR data . .I *hasher->finalise is otherwise identical to .IR *hasher->finalise_const . .PP .I hasher->destroy will be set to a pointer to a function to to call, with .I hasher as the argument, deallocate dynamically allocated data, which may invalidate any pointer in .IR *hasher . .PP .I hasher->state will be initialised, it shall be treated as internal to the library's implementation, and may change between versions. .PP .I hasher must not be .IR NULL . .SH RETURN VALUE Upon successful completion, the .B libhashsum_init_keccak_hasher function returns 0. Otherwise, the function returns -1 and sets .I errno to indicate the error. If -1 is returned, the state of .I *hasher is undefined. .SH ERRORS The .B libhashsum_init_keccak_hasher function fails if: .TP .B ENOSYS Support was excluded at compile time. .TP .B ENOMEM Insufficient memory available. .TP .B EINVAL The combination of the values .IR ratebits , .IR capbits , and .I hashbits is invalid (possibly any single value is invalid). .SH HISTORY libhashsum 1.0. .SH SEE ALSO .BR libhashsum (7), .BR libhashsum_init_keccak_224_hasher (3), .BR libhashsum_init_keccak_256_hasher (3), .BR libhashsum_init_keccak_384_hasher (3), .BR libhashsum_init_keccak_512_hasher (3)