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

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

1 files changed, 34 insertions, 0 deletions

diff --git a/libhashsum_init_sha3_256_hasher.3 b/libhashsum_init_sha3_256_hasher.3
index 8e862d2..41f4eb0 100644
--- a/libhashsum_init_sha3_256_hasher.3
+++ b/libhashsum_init_sha3_256_hasher.3
@@ -13,6 +13,8 @@ libhashsum_init_sha3_256_hasher - initialise state for SHA-3-256 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);
@@ -244,6 +246,38 @@ Support was excluded at compile time.
 .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
+SHA3-256 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 least
+significant bits of non-whole octets, thus
+.I this->standard_partial_byte_input_encoding
+will be set to
+.IR LIBHASHSUM_LEAST_SIGNIFICANT ,
+which the same behaviour as libhashsum implements.
+
 .SH HISTORY
 libhashsum 1.0.