Add standard_partial_byte_input_encoding and standard_partial_byte_output_encoding

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

1 files changed, 82 insertions, 0 deletions

diff --git a/libhashsum.h b/libhashsum.h
index 297c62c..cf13a2e 100644
--- a/libhashsum.h
+++ b/libhashsum.h
@@ -325,6 +325,19 @@ enum libhashsum_algorithm {
 
 
 /**
+ * Which bits in non-whole octets are used
+ * 
+ * @since  1.0
+ */
+enum {
+	/* since 1.0 */
+	LIBHASHSUM_UNSUPPORTED = 0,       /**< Non-whole octets are unsupport */
+	LIBHASHSUM_LEAST_SIGNIFICANT = 1, /**< The least significant bits of a non-whole octet are used */
+	LIBHASHSUM_MOST_SIGNIFICANT = 2   /**< The most significant bits of a non-whole octet are used */
+};
+
+
+/**
  * Message hash functions and state
  * 
  * @since  1.0
@@ -384,6 +397,75 @@ struct libhashsum_hasher {
 	unsigned char supports_non_whole_bytes;
 
 	/**
+	 * libhashsum always uses the least significant bits of
+	 * a non-whole octet, however every hash function that
+	 * supports non-whole input octets specify their own standard
+	 * for how non-whole octet are encoded. This field will be
+	 * set to specify the standard used for the hash function.
+	 * 
+	 * If this field is set to `LIBHASHSUM_UNSUPPORTED`,
+	 * `.supports_non_whole_bytes` will be 0, and non-whole
+	 * input bytes are unsupported.
+	 * 
+	 * If this field is set to `LIBHASHSUM_LEAST_SIGNIFICANT`,
+	 * `.supports_non_whole_bytes` will be 1, and the standard
+	 * used by the hash function is the same as in libhashsum
+	 * (the least significant bits are used), and no conversion
+	 * between the hash function's standard and libhashsum's
+	 * standard is required for input messages.
+	 * 
+	 * If this field is set to `LIBHASHSUM_MOST_SIGNIFICANT`,
+	 * `.supports_non_whole_bytes` will be 1, and the standard
+	 * used by the hash function is the opposite of libhashsum's
+	 * standard, thus if you have reference input message with
+	 * a partial final byte (where the most significant bits are
+	 * used, and the least significant bits are discarded), you
+	 * have to reverse the bits in the last octet before
+	 * inputing it to `*.finalise` or `*.finalise_const`.
+	 * 
+	 * If you are creating your own message, you always store
+	 * the used bits, in a non-whole octet, in the least
+	 * significant part of the octet, when inputing it to
+	 * `*.finalise` or `*.finalise_const`.
+	 * 
+	 * @since  1.0
+	 */
+	unsigned char standard_partial_byte_input_encoding; /* TODO man, test */
+
+	/**
+	 * libhashsum always uses the least significant bits of
+	 * a non-while octet, however every hash function that
+	 * supports non-whole output octets specify their own standard
+	 * for how non-whole octets are encoded. This field will be
+	 * set to specify the standard used for the hash function.
+	 * 
+	 * If this field is set to `LIBHASHSUM_UNSUPPORTED`, non-whole
+	 * output bytees are unsupported.
+	 * 
+	 * If this field is set to `LIBHASHSUM_LEAST_SIGNIFICANT`,
+	 * the standard used by the hash function is the same as in
+	 * libhashsum (the least significant bits are used), and no
+	 * conversion between the hash function's standard and
+	 * libhashsum's standard is required for hashes.
+	 * 
+	 * If this field is set to `LIBHASHSUM_MOST_SIGNIFICANT`,
+	 * the standard used by the hash function is the opposite of
+	 * libhashsum's standard, thus if you have reference hash
+	 * with a partial final byte (where the most significant bits
+	 * are used, and the least significant bits are unused), you
+	 * have to reverse the bits in the last octet before comparing
+	 * the reference hash with the output of `*.finalise` and
+	 * `*.finalise_const`.
+	 * 
+	 * The text above assumes that the hash function's standard
+	 * is to always clear unused bits; this is also always done
+	 * by `*.finalise` and `*.finalise_const`.
+	 * 
+	 * @since  1.0
+	 */
+	unsigned char standard_partial_byte_output_encoding; /* TODO man, test */
+
+	/**
 	 * Update the hash state given additional
 	 * input data
 	 *