path: root/libhashsum_init_blake2b_hasher.3

.TH LIBHASHSUM_INIT_BLAKE2B_HASHER 3 libhashsum
.SH NAME
libhashsum_init_blake2b_hasher - initialise state for BLAKE2b hashing

.SH SYNOPSIS
.nf
#include <libhashsum.h>

\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_blake2b_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_blake2b_hasher
function initialises
.I *hasher
for hashing using the cryptographic hash function BLAKE2b
(a version of BLAKE2), and stores hash function information
and hashing functions for BLAKE2b 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 512. If
.I hashbits
is 0, the maximum value (512) will be used.
.PP
.I salt
shall be
.I NULL
or a buffer of 16 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 16 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 512.
.PP
.I hasher->algorithm
will be set to
.IR LIBHASHSUM_BLAKE2B .
.PP
.I hasher->algorithm_string
will be set to
.RB \(dq BLAKE2b \(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 512)
.RB \(dq BLAKE2b[n= \fIhashbits\fP ,salt= \fIlowercase_hexadecimal(salt,16)\fP ,pepper= \fIlowercase_hexadecimal(pepper,16)\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 512,
.RB \(dq salt= \fIlowercase_hexadecimal(salt,16)\fP , \(dq
is omitted if
.I salt
is
.I NULL
or all zeroes,
.RB \(dq pepper= \fIlowercase_hexadecimal(pepper,16)\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 BLAKE2b 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_BLAKE2B_HASH_SIZE
otherwise.
.PP
.I hasher->hash_excess_bits
will be set to 0 to indicate that the hash size
is a whole number of bytes.
.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_blake2b_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_blake2b_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 512.
.TP
.B EINVAL
.I keybits
is not divisible by 8.
.TP
.B EINVAL
.I keybits
is greater than 512.

.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
BLAKE2b 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
Introduced in libhashsum 1.0.
.PP
The
.I hash_excess_bits
field was added in libhashsum 1.1.

.SH SEE ALSO
.BR libhashsum (7)