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

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

1 files changed, 38 insertions, 0 deletions

diff --git a/libhashsum_init_md5_hasher.3 b/libhashsum_init_md5_hasher.3
index 95abd7b..6b3365f 100644
--- a/libhashsum_init_md5_hasher.3
+++ b/libhashsum_init_md5_hasher.3
@@ -13,6 +13,8 @@ libhashsum_init_md5_hasher - initialise state for MD5 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);
@@ -192,6 +194,42 @@ function fails if:
 .B ENOSYS
 Support was excluded at compile time.
 
+.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
+MD5 always output a fixed, whole number of
+octets, so
+.I this->standard_partial_byte_output_encoding
+will be set to
+.IR LIBHASHSUM_UNSUPPORTED ,
+however, the hash function allows non-whole octet
+input, and in its standard uses the most
+significant bits of non-whole octets, thus
+.I this->standard_partial_byte_input_encoding
+will be set to
+.IR LIBHASHSUM_MOST_SIGNIFICANT ,
+which the opposite behaviour of what libhashsum
+implements, meaning that the last octet most be
+reversed when converting between the hash function's
+standard representation and libhashsum's
+representation.
+
 .SH HISTORY
 libhashsum 1.0.