Add libhashsum_init_blake2s_hasher.3 and libhashsum_init_blake2b_hasher.3

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 294 insertions, 0 deletions

diff --git a/libhashsum_init_blake2b_hasher.3 b/libhashsum_init_blake2b_hasher.3
new file mode 100644
index 0000000..7d4ffa4
--- /dev/null
+++ b/libhashsum_init_blake2b_hasher.3
@@ -0,0 +1,294 @@
+.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;
+	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_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 HISTORY
+libhashsum 1.0.
+
+.SH SEE ALSO
+.BR libhashsum (7)