Add libhashsum_init_keccak_hasher2.31.1

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

3 files changed, 462 insertions, 2 deletions

diff --git a/libhashsum.h b/libhashsum.h
index b57493e..cdd6d00 100644
--- a/libhashsum.h
+++ b/libhashsum.h
@@ -1087,7 +1087,7 @@ int libhashsum_init_keccak_hasher(struct libhashsum_hasher *this, size_t ratebit
  * @since  1.1
  */
 LIBHASHSUM_NONNULL_
-int libhashsum_init_keccak_hasher2(struct libhashsum_hasher *this, const struct libhashsum_keccak_params *params); /* TODO man, test */
+int libhashsum_init_keccak_hasher2(struct libhashsum_hasher *this, const struct libhashsum_keccak_params *params); /* TODO test */
 
 /**
  * Create an initialised state for SHA3-224
diff --git a/libhashsum_init_keccak_hasher.3 b/libhashsum_init_keccak_hasher.3
index cf998bc..9b70187 100644
--- a/libhashsum_init_keccak_hasher.3
+++ b/libhashsum_init_keccak_hasher.3
@@ -111,7 +111,7 @@ and otherwise to
 if
 .I squeezes<2
 or
-.RB \(dq Keccak[r= \fIratebits\fP ,c= \fIcapbits\fP ,n= \fIhashbits\fP z= \fIsqueezes\fP ] \(dq
+.RB \(dq Keccak[r= \fIratebits\fP ,c= \fIcapbits\fP ,n= \fIhashbits\fP, z= \fIsqueezes\fP ] \(dq
 (if
 .IR squeezes>1 ),
 where
@@ -376,6 +376,24 @@ and
 will both be set to
 .IR LIBHASHSUM_LEAST_SIGNIFICANT ,
 which the same behaviour as libhashsum implements.
+.PP
+The
+.BR libhashsum_init_hasher_from_string (3)
+function will recognise
+.RB \(dq o= \(dq
+as an alternative to
+.RB \(dq n= \(dq.
+Furthermore, the
+.BR libhashsum_init_hasher_from_string (3)
+function also recognise
+.RB \(dq s= \(dq
+(with the alternative
+.RB \(dq b= \(dq)
+for the state size and
+.RB \(dq s= \(dq
+for the word size. See
+.BR libhashsum_init_keccak_hasher2 (3)
+for more information.
 
 .SH HISTORY
 Introduced in libhashsum 1.0.
@@ -383,9 +401,17 @@ Introduced in libhashsum 1.0.
 The
 .I hash_excess_bits
 field was added in libhashsum 1.1.
+.PP
+.RB \(dq o= \(dq,
+.RB \(dq s= \(dq,
+.RB \(dq b= \(dq,
+and
+.RB \(dq w= \(dq,
+was added in libhashsum 1.1.
 
 .SH SEE ALSO
 .BR libhashsum (7),
+.BR libhashsum_init_keccak_hasher2 (3),
 .BR libhashsum_init_keccak_224_hasher (3),
 .BR libhashsum_init_keccak_256_hasher (3),
 .BR libhashsum_init_keccak_384_hasher (3),
diff --git a/libhashsum_init_keccak_hasher2.3 b/libhashsum_init_keccak_hasher2.3
new file mode 100644
index 0000000..01a5602
--- /dev/null
+++ b/libhashsum_init_keccak_hasher2.3
@@ -0,0 +1,434 @@
+.TH LIBHASHSUM_INIT_KECCAK_HASHER2 3 libhashsum
+.SH NAME
+libhashsum_init_keccak_hasher2 - initialise state for Keccak hashing
+
+.SH SYNOPSIS
+.nf
+#include <libhashsum.h>
+
+\fBstruct libhashsum_keccak_params\fP {
+	size_t \fIratebits\fP;
+	size_t \fIcapbits\fP;
+	size_t \fIhashbits\fP;
+	size_t \fIstatebits\fP;
+	size_t \fIwordbits\fP;
+	size_t \fIsqueezes\fP;
+};
+
+\fBstruct libhashsum_hasher\fP {
+	enum libhashsum_algorithm \fIalgorithm\fP;
+	const char *\fIalgorithm_string\fP;
+	size_t \fIinput_block_size\fP;
+	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;
+	unsigned char \fIhash_excess_bits\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);
+	void (*\fIstretch\fP)(struct libhashsum_hasher *\fPthis\fP, int \fPskip\fP, void *\fPbuffer\fP);
+	void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP);
+	union libhashsum_state { /* definition omitted */ } \fIstate\fP;
+};
+
+int \fBlibhashsum_init_keccak_hasher2\fP(struct libhashsum_hasher *\fIhasher\fP, struct libhashsum_keccak_params \fIparams\fP);
+.fi
+.PP
+Link with
+.I -lhashsum
+.IR -lkeccak .
+
+.SH DESCRIPTION
+The
+.B libhashsum_init_keccak_hasher2
+function initialises
+.I *hasher
+for hashing using the cryptographic hash function Keccak,
+and stores hash function information and hashing functions
+for Keccak in
+.IR *hasher .
+.PP
+.I params->ratebit
+shall be the rate, in bits per \(dqabsorption\(dq, of the hash function,
+or 0 if it shall be resolved to an automatically determined value.
+.PP
+.I params->capbits
+shall be the capacity, in bits, of the hash function's \(dqsponge\(dq,
+or 0 if it shall be resolved to an automatically determined value.
+.PP
+.I params->hashbits
+shall be the hash size, in bits or 0 if it shall be resolved to
+an automatically determined value.
+.PP
+.I params->statebits
+shall be the state size, in bits or 0 if it shall be resolved to
+an automatically determined value.
+.PP
+.I params->wordbits
+shall be the word size, in bits or 0 if it shall be resolved to
+an automatically determined value.
+.PP
+.I params->squeezes
+shall be the number of \(dqsponge squeezes\(dq to perform at the
+end phase when producing the hash, or 0 if it shall be resolved
+to an automatically determined value (which will always be 1).
+.PP
+Once the values in
+.I *params
+have been resolved, the following must be true, or the function
+will fail:
+.IR "params->statebits==25*params->wordbits" ,
+.IR "params->statebits==params->capbits+params->ratebit" ,
+.IR "params->ratebits%8==0" ,
+.IR "params->capbits%8==0" ,
+.IR "params->ratebits>0" ,
+.IR "params->capbits>0" ,
+and
+.IR "params->hashbits>0" ,
+and
+.IR "params->wordsize"
+must be 8, 16, 32, or 64 (future versions may allow higher powers of 2).
+.PP
+.I hasher->algorithm
+will be set to
+.I LIBHASHSUM_KECCAK_224
+(if
+.I (params->ratebits, params->capbits, params->hashbits, params->squeezes)
+have the values (1152, 448, 224, 1)
+after zeroes have been resolved),
+.I LIBHASHSUM_KECCAK_256
+(if
+.I (params->ratebits, params->capbits, params->hashbits, params->squeezes)
+have the values (1088, 512, 256, 1)
+after zeroes have been resolved),
+.I LIBHASHSUM_KECCAK_384
+(if
+.I (params->ratebits, params->capbits, params->hashbits, params->squeezes)
+have the values (832, 768, 384, 1)
+after zeroes have been resolved),
+.I LIBHASHSUM_KECCAK_512
+(if
+.I (params->ratebits, params->capbits, params->hashbits, params->squeezes)
+have the values (576, 1024, 512, 1)
+after zeroes have been resolved), or
+.I LIBHASHSUM_KECCAK
+(otherwise).
+.PP
+.I hasher->algorithm_string
+will be set to
+.RB \(dq Keccak-224 \(dq
+if
+.I hasher->algorithm
+was set to
+.IR LIBHASHSUM_KECCAK_224 ,
+.RB \(dq Keccak-256 \(dq
+if
+.I hasher->algorithm
+was set to
+.IR LIBHASHSUM_KECCAK_256 ,
+.RB \(dq Keccak-384 \(dq
+if
+.I hasher->algorithm
+was set to
+.IR LIBHASHSUM_KECCAK_384 ,
+.RB \(dq Keccak-512 \(dq
+if
+.I hasher->algorithm
+was set to
+.IR LIBHASHSUM_KECCAK_512 ,
+and otherwise to
+.RB \(dq Keccak[r= \fIparams->ratebits\fP ,c= \fIparams->capbits\fP ,n= \fIparams->hashbits\fP ] \(dq
+if
+.I params->squeezes<2
+or
+.RB \(dq Keccak[r= \fIparams->ratebits\fP ,c= \fIparams->capbits\fP ,n= \fIparams->hashbits\fP, z= \fIparams->squeezes\fP ] \(dq
+(if
+.IR params->squeezes>1 ),
+where
+.IR params->ratebits ,
+.IR params->capbits ,
+and
+.I params->hashbits
+have their resolved non-zero values.
+For the later two cases,
+.I hasher->algorithm_string
+will be a pointer to a buffer in
+.IR hasher->state .
+.PP
+.I hasher->input_block_size
+will be set to the block size, in bytes
+.RI ( params->ratebits/8
+unless
+.IR params->ratebits==0 ).
+.PP
+.I hasher->hash_size
+will be set to the hash size, in bytes
+.RI ( (params->hashbits+7)/8
+unless
+.IR params->hashbits==0 ).
+.PP
+.I hasher->hash_excess_bits
+will be set to number of bits the last byte in
+the hash is padded with (it will be padded with
+cleared bits in its most significant part). As
+long as
+.I params->hashbits
+is a multiple of 8, this number will be 0 (the
+entire last byte is used), otherwise, it will be
+.IR 8-(params->hashbits&7) .
+.PP
+.I hasher->hash_output
+will be set to
+.IR NULL .
+.PP
+.I hasher->supports_non_whole_bytes
+will be set to 1
+to indicate that the
+.I *hasher->finalise
+and
+.I *hasher->finalise_const
+functions support non-zero values in their
+.I extra_bits
+parameter.
+.PP
+.I hasher->process
+will be set to a pointer to the function to call
+to feed, and process, data into the hash function.
+Its parameter
+.I this
+shall be set to
+.IR hasher .
+Its parameter
+.I data
+parameter shall be set to the buffer of data to
+process, and its parameter
+.I bytes
+shall set to the number of bytes to process from
+.IR data .
+.I *hasher->process
+will return the number of bytes processed, which
+will be a multiple of
+.IR hasher->input_block_size
+no greater than
+.IR bytes .
+.PP
+.I hasher->finalise_const
+will be set to a pointer to the function to call
+once the entire text being hashed has been loaded,
+and to get the hash of the text. Its parameter
+.I this
+shall be set to
+.IR hasher .
+Its parameter
+.I data
+shall be set to the beginning of any yet unprocessed
+data, and its parameter
+.I bytes
+shall be set to the number of bytes to process from
+.IR data .
+Its parameter
+.I extra_bits
+shall be set to the number of bits to process from
+the lower bits of the incomplete byte
+.IR data[bytes] .
+The
+.I *hasher->finalise_const
+function will return 0 upon successful completion,
+and set
+.I hasher->hash_output
+to a pointer to a buffer in
+.I hasher->state
+containing the binary hash of the processed data.
+Otherwise, the function will return -1, and set
+.I errno
+to indicate the error. However, if the user has
+already set
+.I hasher->hash_output
+to a
+.RI non- NULL
+pointer, the function will output the binary hash
+to that pointer instead without redirecting
+.I hasher->hash_output
+(the application must make sure this buffer is
+sufficiently large). The function will failure if:
+.RS
+.TP
+.B EINVAL
+.I extra_bits
+is 8 or greater.
+.RE
+.PP
+.I hasher->finalise
+will be set to the pointer to a function that
+is an alternative to
+.I *hasher->finalise_const
+that can support zero-copy provided that the
+buffer input as the argument
+.I data
+is sufficiently large. The
+.I *hasher->finalise
+function may rewrite
+.I data
+and shall is does not safe to use for multiple
+hashers (if the same text is hashed using multiple
+hashers,
+.I *hasher->finalise_const
+must be used). The
+function's parameter
+.I size
+shall be set to the size of the buffer
+.IR data .
+.I *hasher->finalise
+is otherwise identical to
+.IR *hasher->finalise_const .
+.PP
+.I hasher->stretch
+will be set to
+.IR NULL ,
+however upon successful completion of
+.I *hasher->finalise
+or
+.IR *hasher->finalise_const ,
+.I hasher->stretch
+will be set to point to a function that can be
+used to extend the hash by
+.I hasher->hash_size
+bytes, and can be called repeated without limitation.
+The hash extent will be written to a buffer in
+.I hasher->state
+(which
+.I *hasher->finalize
+and
+.I *hasher->finalize_const
+also write the hash to), and
+.I hasher->hash_output
+will be set to point to this buffer.
+.IR *hasher->stretch 's
+parameter
+.I this
+shall be
+.IR hasher .
+Its parameter
+.I skip
+can be set to non-zero if the hash extent should
+be discarded
+.RI ( hasher->hash_output
+will not be set in this case).
+Its parameter
+.I buffer
+shall be
+.I NULL
+for the above described behaviour, or an sufficiently
+large buffer the function shall output the hash extent
+to. If
+.I buffer
+is
+.RI non- NULL ,
+.I hasher->hash_output
+will be set to
+.IR NULL ).
+.PP
+.I hasher->destroy
+will be set to a pointer to a function to to
+call, with
+.I hasher
+as the argument, deallocate dynamically
+allocated data, which may invalidate any
+pointer in
+.IR *hasher .
+.PP
+.I hasher->state
+will be initialised, it shall be treated as
+internal to the library's implementation, and
+may change between versions.
+.PP
+.I hasher
+must not be
+.IR NULL .
+.PP
+.I params
+must not be
+.IR NULL .
+
+.SH RETURN VALUE
+Upon successful completion, the
+.B libhashsum_init_keccak_hasher2
+function returns 0. Otherwise,
+the function returns -1 and sets
+.I errno
+to indicate the error. If -1
+is returned, the state of
+.I *hasher
+is undefined.
+
+.SH ERRORS
+The
+.B libhashsum_init_keccak_hasher2
+function fails if:
+.TP
+.B ENOSYS
+Support was excluded at compile time.
+.TP
+.B ENOMEM
+Insufficient memory available.
+.TP
+.B EINVAL
+At least one value in, or a combination
+of values in,
+.I *params
+is invalid.
+
+.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
+Keccak supports non-whole octet both in its
+input and its output, and in its standard uses
+the least significant bits of non-whole octets
+both in the input and in the output, thus
+.I this->standard_partial_byte_input_encoding
+and
+.I this->standard_partial_byte_output_encoding
+will both be set to
+.IR LIBHASHSUM_LEAST_SIGNIFICANT ,
+which the same behaviour as libhashsum implements.
+.PP
+The
+.BR libhashsum_init_hasher_from_string (3)
+function will recognise
+.RB \(dq o= \(dq
+as an alternative to
+.RB \(dq n= \(dq.
+Furthermore, the
+.BR libhashsum_init_hasher_from_string (3)
+function also recognise
+.RB \(dq s= \(dq
+(with the alternative
+.RB \(dq b= \(dq)
+for the state size and
+.RB \(dq s= \(dq
+for the word size.
+
+.SH HISTORY
+Introduced in libhashsum 1.1.
+
+.SH SEE ALSO
+.BR libhashsum (7),
+.BR libhashsum_init_keccak_hasher (3)