.TH LIBHASHSUM_INIT_HASHER_FROM_STRING 3 libhashsum
.SH NAME
libhashsum_init_hasher_from_string - initialise state for 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_hasher_from_string\fP(struct libhashsum_hasher *\fIhasher\fP, const char *\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 and BLAKE2 was excluded).

.SH DESCRIPTION
The
.B libhashsum_init_hasher_from_string
function initialises
.I *hasher
for hashing using a cryptographic hash function
and parameters selected
using the parameter
.I algorithm
(see
.BR libhashsum_get_algorithm_from_string (3)
for more information; for the list of valid parameters,
see the output to
.I hasher->algorithm_string
for the dedicated initialiser function for the
selected hash function), and stores hash function
information and hashing functions in
.IR *hasher .
.PP
.I hasher->algorithm
will be set to the algorithm selected by
.I algorithm
(which will be
.I a
after running
.IR "libhashsum_get_algorithm_from_string(&a, 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_excess_bits
will be set to number of bits the last byte in
the hash is padded with (it will be padded with
cleared bits in its most significant part).
.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. 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), provided that the library
supports this behaviour for the selected hash
function, otherwise it will behave as if
.I hasher->hash_output
was set to
.IR NULL .
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->stretch
will be set to
.IR NULL ,
however upon successful completion of
.I *hasher->finalise
or
.IR *hasher->finalise_const ,
.I hasher->stretch
will be set to point to a function that can be
used to extend the hash by
.I hasher->hash_size
bytes, and can be called repeated, provided that the
hash function supports extending the hash. If the
hash extention support is limited,
.I *hasher->stretch
will reset
.I hasher->stretch
to
.I NULL
once the limit has been reached. If the hash
function supports generating hashes at any time,
.I hasher->stretch
will be set to point to a function at immediately.
The hash extent will be written to a buffer in
.I hasher->state
(which
.I *hasher->finalize
and
.I *hasher->finalize_const
also write the hash to), and
.I hasher->hash_output
will be set to point to this buffer.
.IR *hasher->stretch 's
parameter
.I this
shall be
.IR hasher .
Its parameter
.I skip
can be set to non-zero if the hash extent should
be discarded
.RI ( hasher->hash_output
will not be set in this case).
Its parameter
.I buffer
shall be
.I NULL
for the above described behaviour, or an sufficiently
large buffer the function shall output the hash extent
to. If
.I buffer
is
.RI non- NULL ,
.I hasher->hash_output
will be set to
.IR NULL ).
.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
and
.I algorithm
must not be
.IR NULL .

.SH RETURN VALUE
Upon successful completion, the
.B libhashsum_init_hasher_from_string
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_from_string
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 EINVAL
.I algorithm
contains an invalid parameter or
an invalid combination of parameters.
.TP
.B ENOMEM
Insufficient memory available.

.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
If the hash function does not support non-whole
input octets,
.I this->standard_partial_byte_input_encoding
will be set to
.IR LIBHASHSUM_UNSUPPORTED .
.PP
If the hash function supports non-whole input
octets, and uses the least significant bits
in its standard, which is the same behaviour
as implemented by libhashsum,
.I this->standard_partial_byte_input_encoding
will be set to
.IR LIBHASHSUM_LEAST_SIGNIFICANT .
.PP
If the hash function supports non-whole input
octets, and uses the most significant bits
in its standard, which is the opposite behaviour
of what is implemented by libhashsum,
.I this->standard_partial_byte_input_encoding
will be set to
.IR LIBHASHSUM_MOST_SIGNIFICANT .
This means that the partial octet must be
reverted to convert between the libhashsum's
encoding and the hash function's standard's
encoding.
.PP
If the hash function does not support non-whole
octet hashes,
.I this->standard_partial_byte_output_encoding
will be set to
.IR LIBHASHSUM_UNSUPPORTED .
.PP
If the hash function supports non-whole octet
hashes, and uses the least significant bits
in its standard, which is the same behaviour
as implemented by libhashsum,
.I this->standard_partial_byte_output_encoding
will be set to
.IR LIBHASHSUM_LEAST_SIGNIFICANT .
.PP
If the hash function supports non-whole octet
hashes, and uses the most significant bits
in its standard, which is the opposite behaviour
of what is implemented by libhashsum,
.I this->standard_partial_byte_output_encoding
will be set to
.IR LIBHASHSUM_MOST_SIGNIFICANT .
This means that the last octet, if partial,
must be reverted to convert between the
libhashsum's encoding and the hash function's
standard's encoding.

.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),
.BR libhashsum_init_hasher (3),
.BR libhashsum_get_algorithm_from_string (3),
.BR libhashsum_get_relative_performance (3)