From 87437d71b36518dac5086f8cc92480935e4cf60b Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Fri, 30 Aug 2024 17:20:30 +0200 Subject: m + add man pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- libhashsum_init_blake_hasher.3 | 295 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 libhashsum_init_blake_hasher.3 (limited to 'libhashsum_init_blake_hasher.3') diff --git a/libhashsum_init_blake_hasher.3 b/libhashsum_init_blake_hasher.3 new file mode 100644 index 0000000..f6f77bb --- /dev/null +++ b/libhashsum_init_blake_hasher.3 @@ -0,0 +1,295 @@ +.TH LIBHASHSUM_INIT_BLAKE_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blake_hasher - initialise state for BLAKE 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_blake_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP, const void *\fIsalt\fP, size_t \fIsaltbytes\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blake_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKE +(a version of BLAKE), and stores hash function information +and hashing functions for BLAKE in +.IR *hasher . +.PP +.I hashbits +shall be the hash size in bits, which shall be either +224, 256, 384, or 512. +.PP +.I salt +shall be +.I NULL +or a buffer that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I saltbytes +shall be the number bytes in +.IR salt , +which must be 16 if +.I hashbits +is 224 or 256, and 32 if +.I hashbits +is 384 or 512; however +.I saltbytes +is ignored if +.I salt +is +.IR NULL . +.PP +.I hasher->algorithm +will be set to either +.I LIBHASHSUM_BLAKE224 +(if +.I hashbits +is 224), +.I LIBHASHSUM_BLAKE256 +(if +.I hashbits +is 256), +.I LIBHASHSUM_BLAKE384 +(if +.I hashbits +is 384), or +.I LIBHASHSUM_BLAKE512 +if +.I hashbits +is 512). +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE \fIhashbits\fP\(dq +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE \fIhashbits\fP[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKE uses, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( hashbits/8 ). +.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 +.IR NULL . +.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_blake_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_blake_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B EINVAL +.I hashbits +is either 224, 256, 384, nor 384. +.TP +.B EINVAL +.I hashbits +is either 224 or 256 and +.I salt +is +.RI non- NULL +but +.I saltbytes +is not 16. +.TP +.B EINVAL +.I hashbits +is either 384 or 512 and +.I salt +is +.RI non- NULL +but +.I saltbytes +is not 32. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.I libhashsum_init_blake_hasher(hasher, 224, salt, 16) +and +.I libhashsum_init_blake_hasher(hasher, 256, salt, 16) +are equivalent to +.I libhashsum_init_blake224_hasher(hasher, salt) +and +.I libhashsum_init_blake256_hasher(hasher, salt) +respectively as well as to +.I libhashsum_init_blakes_hasher(hasher, 224, salt) +and +.I libhashsum_init_blakes_hasher(hasher, 256, salt) +respectively. +.PP +.I libhashsum_init_blake_hasher(hasher, 384, salt, 32) +and +.I libhashsum_init_blake_hasher(hasher, 512, salt, 32) +are equivalent to +.I libhashsum_init_blake384_hasher(hasher, salt) +and +.I libhashsum_init_blake512_hasher(hasher, salt) +respectively as well as to +.I libhashsum_init_blakeb_hasher(hasher, 384, salt) +and +.I libhashsum_init_blakeb_hasher(hasher, 512, salt) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blake224_hasher (3), +.BR libhashsum_init_blake256_hasher (3), +.BR libhashsum_init_blake384_hasher (3), +.BR libhashsum_init_blake512_hasher (3), +.BR libhashsum_init_blakes_hasher (3), +.BR libhashsum_init_blakeb_hasher (3) -- cgit v1.2.3-70-g09d2