path: root/libhashsum_init_hasher.3

.TH LIBHASHSUM_INIT_HASHER 3 libhashsum
.SH NAME
libhashsum_init_hasher - initialise state for hashing

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

\fBenum libhashsum_algorithm\fP { /* see the section DESCRIPTION for a listing of values */ };

\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_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, enum libhashsum_algorithm \fIalgorithm\fP);
.fi
.PP
Link with
.I -lhashsum
.br
.I -lsha1
(unless support for SHA-0 and SHA-1 was excluded)
.br
.I -lsha2
(unless support for SHA-2 was excluded)
.br
.I -lkeccak
(unless support for Keccak, SHA-3, SHAKE, and RawSHAKE was excluded)
.br
.I -lblake
(unless support for BLAKE was excluded).

.SH DESCRIPTION
The
.B libhashsum_init_hasher
function initialises
.I *hasher
for hashing using a cryptographic hash function selected
using the parameter
.IR algorithm ,
and stores hash function information and
hashing functions in
.IR *hasher .
.PP
.I algorithm
shall be one of the following values to select hash function:
.TP
.B LIBHASHSUM_MD2
Selects MD2. See
.BR libhashsum_init_md2_hasher (3)
for more information.
.TP
.B LIBHASHSUM_MD4
Selects MD4. See
.BR libhashsum_init_md4_hasher (3)
for more information.
.TP
.B LIBHASHSUM_MD5
Selects MD5. See
.BR libhashsum_init_md5_hasher (3)
for more information.
.TP
.B LIBHASHSUM_RIPEMD_128
Selects RIPEMD-128. See
.BR libhashsum_init_ripemd_128_hasher (3)
for more information.
.TP
.B LIBHASHSUM_RIPEMD_160
Selects RIPEMD-160. See
.BR libhashsum_init_ripemd_160_hasher (3)
for more information.
.TP
.B LIBHASHSUM_RIPEMD_256
Selects RIPEMD-256. See
.BR libhashsum_init_ripemd_256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_RIPEMD_512
Selects RIPEMD-512. See
.BR libhashsum_init_ripemd_512_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA0
Selects SHA-0. See
.BR libhashsum_init_sha0_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA1
Selects SHA-1. See
.BR libhashsum_init_sha0_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA_224
Selects SHA-224 (SHA-2). See
.BR libhashsum_init_sha_224_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA_256
Selects SHA-256 (SHA-2). See
.BR libhashsum_init_sha_256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA_384
Selects SHA-384 (SHA-2). See
.BR libhashsum_init_sha_384_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA_512
Selects SHA-512 (SHA-2). See
.BR libhashsum_init_sha_512_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA_512_224
Selects SHA-512/224 (SHA-2). See
.BR libhashsum_init_sha_512_224_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA_512_256
Selects SHA-512/256 (SHA-2). See
.BR libhashsum_init_sha_512_256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_KECCAK
Selects Keccak. However, this value is
unsupported, as parameters are expected
(even though they are technically optional),
so the function will return -1 and set
.I errno
to
.IR EINVAL .
See
.BR libhashsum_init_keccak_hasher (3)
for more information.
.TP
.B LIBHASHSUM_KECCAK_224
Selects Keccak-224 (Keccak[n=224]). See
.BR libhashsum_init_keccak_224_hasher (3)
for more information.
.TP
.B LIBHASHSUM_KECCAK_256
Selects Keccak-256 (Keccak[n=256]). See
.BR libhashsum_init_keccak_256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_KECCAK_384
Selects Keccak-384 (Keccak[n=384]). See
.BR libhashsum_init_keccak_384_hasher (3)
for more information.
.TP
.B LIBHASHSUM_KECCAK_512
Selects Keccak-512 (Keccak[n=512]). See
.BR libhashsum_init_keccak_512_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA3_224
Selects SHA-3-224. See
.BR libhashsum_init_sha3_224_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA3_256
Selects SHA-3-256. See
.BR libhashsum_init_sha3_256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA3_384
Selects SHA-3-384. See
.BR libhashsum_init_sha3_384_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHA3_512
Selects SHA-3-512. See
.BR libhashsum_init_sha3_512_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHAKE128
Selects SHAKE128 (SHAKE). See
.BR libhashsum_init_shake128_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHAKE256
Selects SHAKE256 (SHAKE). See
.BR libhashsum_init_shake256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_SHAKE512
Selects SHAKE512 (SHAKE). See
.BR libhashsum_init_shake512_hasher (3)
for more information.
.TP
.B LIBHASHSUM_RAWSHAKE128
Selects RawSHAKE128 (RawSHAKE). See
.BR libhashsum_init_rawshake128_hasher (3)
for more information.
.TP
.B LIBHASHSUM_RAWSHAKE256
Selects RawSHAKE256 (RawSHAKE). See
.BR libhashsum_init_rawshake256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_RAWSHAKE512
Selects RawSHAKE512 (RawSHAKE). See
.BR libhashsum_init_rawshake512_hasher (3)
for more information.
.TP
.B LIBHASHSUM_BLAKE224
Selects BLAKE224 (BLAKE, BLAKEs). See
.BR libhashsum_init_blake224_hasher (3)
for more information.
.TP
.B LIBHASHSUM_BLAKE256
Selects BLAKE256 (BLAKE, BLAKEs). See
.BR libhashsum_init_blake256_hasher (3)
for more information.
.TP
.B LIBHASHSUM_BLAKE384
Selects BLAKE384 (BLAKE, BLAKEb). See
.BR libhashsum_init_blake384_hasher (3)
for more information.
.TP
.B LIBHASHSUM_BLAKE512
Selects BLAKE512 (BLAKE, BLAKEb). See
.BR libhashsum_init_blake512_hasher (3)
for more information.
.PP
.I hasher->algorithm
will be set to
.IR algorithm .
.PP
.I hasher->algorithm_string
will be set to a string representing the hash
function selected using the parameter
.IR algorithm .
.PP
.I hasher->input_block_size
will be set to the block size, in bytes.
.PP
.I hasher->hash_size
will be set to the hash size, in bytes.
.PP
.I hasher->hash_output
will be set to
.IR NULL .
.PP
.I hasher->supports_non_whole_bytes
will be set to 1 if
.I *hasher->finalise
and
.I *hasher->finalise_const
functions support non-zero values in their
.I extra_bits
parameter, or to 0 otherwise.
.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.
.TP
.B EINVAL
.I extra_bits
is not 0 but
.I hasher->supports_non_whole_bytes
was set to 0 by
.BR libhashsum_init_hasher .
.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 either be set to
.I NULL
or 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 .

.SH RETURN VALUE
Upon successful completion, the
.B libhashsum_init_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_hasher
function fails if:
.TP
.B ENOSYS
Support was excluded at compile time.
.TP
.B ENOSYS
The selected algorithm requires a larger
(newer) version
.B union libhashsum_state
(and thus a larger version of
.BR "struct libhashsum_hasher" )
than the application is compiled with.
.TP
.B EINVAL
The value of
.I algorithm
is unrecognised or unsupported.
.TP
.B ENOMEM
Insufficient memory available.

.SH HISTORY
libhashsum 1.0.

.SH SEE ALSO
.BR libhashsum (7),
.BR libhashsum_init_hasher_from_string (3),
.BR libhashsum_init_keccak_hasher (3)