.TH LIBHASHSUM_INIT_BLAKE2S_HASHER 3 libhashsum .SH NAME libhashsum_init_blake2s_hasher - initialise state for BLAKE2s 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; unsigned char \fIstandard_partial_byte_input_encoding\fP; unsigned char \fIstandard_partial_byte_output_encoding\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_blake2s_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP, const void *\fIsalt\fP, const void *\fIpepper\fP, const void *\fIkey\fP, size_t \fIkeybits\fP); .fi .PP Link with .I -lhashsum .IR "-lblake" . .SH DESCRIPTION The .B libhashsum_init_blake2s_hasher function initialises .I *hasher for hashing using the cryptographic hash function BLAKE2s (a version of BLAKE2), and stores hash function information and hashing functions for BLAKE2s in .IR *hasher . .PP .I hashbits shall be the hash size, in bits, which must be a multiple of 8, and must not be greater than 256. If .I hashbits is 0, the maximum value (256) will be used. .PP .I salt shall be .I NULL or a buffer of 8 bytes that shall be used as a per-hash salt .RI ( NULL is equivalent to all zeroes). .PP .I pepper shall be .I NULL or a buffer of 8 bytes that shall be used as a (secret) per-application salt (pepper, or \(dqpersonalisation\(dq). .RI ( NULL is equivalent to all zeroes). .PP .I key shall be .I NULL or the key for hashing in keyed mode. .PP .I keybits shall be the number of bits in .I key (or 0 if .I key is .IR NULL ), and must be a multiple of 8, no greater than 256. .PP .I hasher->algorithm will be set to .IR LIBHASHSUM_BLAKE2S . .PP .I hasher->algorithm_string will be set to .RB \(dq BLAKE2s \(dq, or (if .I salt or .I pepper is neither .I NULL nor all zeroes or if .I keybits is non-zero or .I hashbits is non-zero but not 256) .RB \(dq BLAKE2s[n= \fIhashbits\fP ,salt= \fIlowercase_hexadecimal(salt,8)\fP ,pepper= \fIlowercase_hexadecimal(pepper,8)\fP ,key= \fIlowercase_hexadecimal(key,keybits/8)\fP ] \(dq (which will be stored in a buffer in .IR hasher->state ), where .RB \(dq n= \fIhashbits\fP , \(dq is omitted if .I hashbits is 0 or 256, .RB \(dq salt= \fIlowercase_hexadecimal(salt,8)\fP , \(dq is omitted if .I salt is .I NULL or all zeroes, .RB \(dq pepper= \fIlowercase_hexadecimal(pepper,8)\fP , \(dq is omitted if .I pepper is .I NULL or all zeroes, and .RB \(dq key= \fIlowercase_hexadecimal(key,keybits/8)\fP \(dq (with immediately proceeding comma .RB (' , ') if any) is ommited if .I keybits is 0. .PP .I hasher->input_block_size will be set to the block size BLAKE2s uses, in bytes. .PP .I hasher->hash_size will be set to the hash size, in bytes: .I hashbits/8 unless .IR hashbits==0 , .I LIBHASHSUM_BLAKE2S_HASH_SIZE otherwise. .PP .I hasher->hash_output will be set to .IR NULL . .PP .I hasher->supports_non_whole_bytes will be set to 0 to indicate that the .I *hasher->finalise and .I *hasher->finalise_const functions will fail unless their .I extra_bits parameter is 0. .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 not 0. .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 . .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_blake2s_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_blake2s_hasher function fails if: .TP .B ENOSYS Support was excluded at compile time. .TP .B EINVAL .I hashbits is not divisible by 8. .TP .B EINVAL .I hashbits is greater than 256. .TP .B EINVAL .I keybits is not divisible by 8. .TP .B EINVAL .I keybits is greater than 256. .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 BLAKE2s does not support non-whole octets, so .I this->standard_partial_byte_input_encoding and .I this->standard_partial_byte_output_encoding will be set to .IR LIBHASHSUM_UNSUPPORTED . .SH HISTORY libhashsum 1.0. .SH SEE ALSO .BR libhashsum (7)