Document standard_partial_byte_{in,out}put_encoding in man pages1.0

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

1 files changed, 74 insertions, 1 deletions

diff --git a/libhashsum_init_hasher.3 b/libhashsum_init_hasher.3
index a61b00e..5bb2b62 100644
--- a/libhashsum_init_hasher.3
+++ b/libhashsum_init_hasher.3
@@ -15,6 +15,8 @@ libhashsum_init_hasher - initialise state for hashing
 	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;
 	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);
@@ -239,7 +241,7 @@ Selects BLAKE2s (BLAKE2). See
 for more information.
 .TP
 .B LIBHASHSUM_BLAKE2B
-Selects BLAKE2b (BLAKE). See
+Selects BLAKE2b (BLAKE2). See
 .BR libhashsum_init_blake2b_hasher (3)
 for more information.
 .PP
@@ -487,6 +489,77 @@ is unrecognised or unsupported.
 .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
 libhashsum 1.0.