diff options
Diffstat (limited to 'libhashsum.h')
| -rw-r--r-- | libhashsum.h | 82 |
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 * |