m + add man pages

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

1 files changed, 414 insertions, 0 deletions

diff --git a/libhashsum_init_hasher.3 b/libhashsum_init_hasher.3
new file mode 100644
index 0000000..df8c382
--- /dev/null
+++ b/libhashsum_init_hasher.3
@@ -0,0 +1,414 @@
+.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)