diff options
Diffstat (limited to '')
| -rw-r--r-- | libhashsum_init_keccak_hasher2.3 | 434 |
1 files changed, 434 insertions, 0 deletions
diff --git a/libhashsum_init_keccak_hasher2.3 b/libhashsum_init_keccak_hasher2.3 new file mode 100644 index 0000000..01a5602 --- /dev/null +++ b/libhashsum_init_keccak_hasher2.3 @@ -0,0 +1,434 @@ +.TH LIBHASHSUM_INIT_KECCAK_HASHER2 3 libhashsum +.SH NAME +libhashsum_init_keccak_hasher2 - initialise state for Keccak hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_keccak_params\fP { + size_t \fIratebits\fP; + size_t \fIcapbits\fP; + size_t \fIhashbits\fP; + size_t \fIstatebits\fP; + size_t \fIwordbits\fP; + size_t \fIsqueezes\fP; +}; + +\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; + unsigned char \fIstandard_partial_byte_input_encoding\fP; + unsigned char \fIstandard_partial_byte_output_encoding\fP; + unsigned char \fIhash_excess_bits\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 (*\fIstretch\fP)(struct libhashsum_hasher *\fPthis\fP, int \fPskip\fP, void *\fPbuffer\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_keccak_hasher2\fP(struct libhashsum_hasher *\fIhasher\fP, struct libhashsum_keccak_params \fIparams\fP); +.fi +.PP +Link with +.I -lhashsum +.IR -lkeccak . + +.SH DESCRIPTION +The +.B libhashsum_init_keccak_hasher2 +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 params->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 params->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 params->hashbits +shall be the hash size, in bits or 0 if it shall be resolved to +an automatically determined value. +.PP +.I params->statebits +shall be the state size, in bits or 0 if it shall be resolved to +an automatically determined value. +.PP +.I params->wordbits +shall be the word size, in bits or 0 if it shall be resolved to +an automatically determined value. +.PP +.I params->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 +Once the values in +.I *params +have been resolved, the following must be true, or the function +will fail: +.IR "params->statebits==25*params->wordbits" , +.IR "params->statebits==params->capbits+params->ratebit" , +.IR "params->ratebits%8==0" , +.IR "params->capbits%8==0" , +.IR "params->ratebits>0" , +.IR "params->capbits>0" , +and +.IR "params->hashbits>0" , +and +.IR "params->wordsize" +must be 8, 16, 32, or 64 (future versions may allow higher powers of 2). +.PP +.I hasher->algorithm +will be set to +.I LIBHASHSUM_KECCAK_224 +(if +.I (params->ratebits, params->capbits, params->hashbits, params->squeezes) +have the values (1152, 448, 224, 1) +after zeroes have been resolved), +.I LIBHASHSUM_KECCAK_256 +(if +.I (params->ratebits, params->capbits, params->hashbits, params->squeezes) +have the values (1088, 512, 256, 1) +after zeroes have been resolved), +.I LIBHASHSUM_KECCAK_384 +(if +.I (params->ratebits, params->capbits, params->hashbits, params->squeezes) +have the values (832, 768, 384, 1) +after zeroes have been resolved), +.I LIBHASHSUM_KECCAK_512 +(if +.I (params->ratebits, params->capbits, params->hashbits, params->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= \fIparams->ratebits\fP ,c= \fIparams->capbits\fP ,n= \fIparams->hashbits\fP ] \(dq +if +.I params->squeezes<2 +or +.RB \(dq Keccak[r= \fIparams->ratebits\fP ,c= \fIparams->capbits\fP ,n= \fIparams->hashbits\fP, z= \fIparams->squeezes\fP ] \(dq +(if +.IR params->squeezes>1 ), +where +.IR params->ratebits , +.IR params->capbits , +and +.I params->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 ( params->ratebits/8 +unless +.IR params->ratebits==0 ). +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( (params->hashbits+7)/8 +unless +.IR params->hashbits==0 ). +.PP +.I hasher->hash_excess_bits +will be set to number of bits the last byte in +the hash is padded with (it will be padded with +cleared bits in its most significant part). As +long as +.I params->hashbits +is a multiple of 8, this number will be 0 (the +entire last byte is used), otherwise, it will be +.IR 8-(params->hashbits&7) . +.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. Its 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. However, if the user has +already set +.I hasher->hash_output +to a +.RI non- NULL +pointer, the function will output the binary hash +to that pointer instead without redirecting +.I hasher->hash_output +(the application must make sure this buffer is +sufficiently large). 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->stretch +will be set to +.IR NULL , +however upon successful completion of +.I *hasher->finalise +or +.IR *hasher->finalise_const , +.I hasher->stretch +will be set to point to a function that can be +used to extend the hash by +.I hasher->hash_size +bytes, and can be called repeated without limitation. +The hash extent will be written to a buffer in +.I hasher->state +(which +.I *hasher->finalize +and +.I *hasher->finalize_const +also write the hash to), and +.I hasher->hash_output +will be set to point to this buffer. +.IR *hasher->stretch 's +parameter +.I this +shall be +.IR hasher . +Its parameter +.I skip +can be set to non-zero if the hash extent should +be discarded +.RI ( hasher->hash_output +will not be set in this case). +Its parameter +.I buffer +shall be +.I NULL +for the above described behaviour, or an sufficiently +large buffer the function shall output the hash extent +to. If +.I buffer +is +.RI non- NULL , +.I hasher->hash_output +will be set to +.IR NULL ). +.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 . +.PP +.I params +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_keccak_hasher2 +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_hasher2 +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +At least one value in, or a combination +of values in, +.I *params +is invalid. + +.SH EXTENDED DESCRIPTION +libhashsum has normalises the all implemented hash +functions to always use the least significant bits +in non-whole octets, however each hash function has +its unstandarded. To make it easier to create an +application the use the same encoding of partial +octets as other application using any particular +hash function, +.B struct libhashsum_hasher +contains two fields: +.I standard_partial_byte_input_encoding +and +.IR standard_partial_byte_output_encoding ; +which are merely informtional. They are not set to +specify how libhashsum expects and encodes non-whole +octets, but rather specify how partial bytes are +encoded in the reference implementation or +specification of a hash function. +.PP +Keccak supports non-whole octet both in its +input and its output, and in its standard uses +the least significant bits of non-whole octets +both in the input and in the output, thus +.I this->standard_partial_byte_input_encoding +and +.I this->standard_partial_byte_output_encoding +will both be set to +.IR LIBHASHSUM_LEAST_SIGNIFICANT , +which the same behaviour as libhashsum implements. +.PP +The +.BR libhashsum_init_hasher_from_string (3) +function will recognise +.RB \(dq o= \(dq +as an alternative to +.RB \(dq n= \(dq. +Furthermore, the +.BR libhashsum_init_hasher_from_string (3) +function also recognise +.RB \(dq s= \(dq +(with the alternative +.RB \(dq b= \(dq) +for the state size and +.RB \(dq s= \(dq +for the word size. + +.SH HISTORY +Introduced in libhashsum 1.1. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_keccak_hasher (3) |