Move man pages into man3/ and man7/

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

58 files changed, 3612 insertions, 0 deletions

diff --git a/man3/libkeccak_behex_lower.3 b/man3/libkeccak_behex_lower.3
new file mode 100644
index 0000000..2078790
--- /dev/null
+++ b/man3/libkeccak_behex_lower.3
@@ -0,0 +1,45 @@
+.TH LIBKECCAK_BEHEX_LOWER 3 LIBKECCAK
+.SH NAME
+libkeccak_behex_lower - Converts a binary hashsum to lower case hexadecimal
+.SH SYNOPSIS
+.LP
+.nf
+#include <libkeccak.h>
+
+void libkeccak_behex_lower(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_behex_lower ()
+function
+converts a binary hashsum, stored in
+.IR hashsum ,
+to lowercase hexadecimal, and stores the
+hexadecimal representation in
+.IR output .
+.PP
+.I output
+will be terminated by a NUL-character.
+.PP
+The
+.I n
+parameter specifies the number of bytes
+the binary hashsum is comprised.
+.I output
+needs an allocation size of (2 *
+.I n
++ 1).
+.SH RETURN VALUES
+The
+.BR libkeccak_behex_lower ()
+function does return any value.
+.SH ERRORS
+The
+.BR libkeccak_behex_lower ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_behex_upper (3),
+.BR libkeccak_unhex (3)
diff --git a/man3/libkeccak_behex_upper.3 b/man3/libkeccak_behex_upper.3
new file mode 100644
index 0000000..b5c67bb
--- /dev/null
+++ b/man3/libkeccak_behex_upper.3
@@ -0,0 +1,44 @@
+.TH LIBKECCAK_BEHEX_UPPER 3 LIBKECCAK
+.SH NAME
+libkeccak_behex_upper - Converts a binary hashsum to upper case hexadecimal
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_behex_upper(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_behex_upper ()
+function
+converts a binary hashsum, stored in
+.IR hashsum ,
+to uppercase hexadecimal, and stores the
+hexadecimal representation in
+.IR output .
+.PP
+.I output
+will be terminated by a NUL-character.
+.PP
+The
+.I n
+parameter specifies the number of bytes
+the binary hashsum is comprised.
+.I output
+needs an allocation size of (2 *
+.I n
++ 1).
+.SH RETURN VALUES
+The
+.BR libkeccak_behex_upper ()
+function does return any value.
+.SH ERRORS
+The
+.BR libkeccak_behex_upper ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_behex_lower (3),
+.BR libkeccak_unhex (3)
diff --git a/man3/libkeccak_cshake_initialise.3 b/man3/libkeccak_cshake_initialise.3
new file mode 100644
index 0000000..a18f1bf
--- /dev/null
+++ b/man3/libkeccak_cshake_initialise.3
@@ -0,0 +1,126 @@
+.TH LIBKECCAK_CSHAKE_INITIALISE 3 LIBKECCAK
+.SH NAME
+libkeccak_cshake_initialise - Initialise a sponge for cSHAKE hashing
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_cshake_initialise(struct libkeccak_state *restrict \fIstate\fP,
+                                 const void *\fIn_text\fP, size_t \fIn_len\fP, size_t \fIn_bits\fP, const char *\fIn_suffix\fP,
+                                 const void *\fIs_text\fP, size_t \fIs_len\fP, size_t \fIs_bits\fP, const char *\fIs_suffix\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_cshake_suffix ()
+function shall be called immediately
+after the
+.BR libkeccak_state_initialise (3)
+function (before
+.BR libkeccak_update (3)
+or
+.BR libkeccak_digest (3),
+or any variant of those functions),
+to provide the initialisation blocks,
+containing customisation data, to the
+Keccak sponge.
+.PP
+The value of the
+.I state
+parameter shall be an initialised state
+to feed the initialisation blocks to.
+.PP
+The value of the
+.I n_text
+parameter shall be the function-name
+bit-string, represented in raw bytes;
+.I n_len
+shall be value no greater than the
+number of whole bytes in
+.I n_text
+and
+.I n_bits
+shall be the number of bits in
+.I n_text
+sans the bytes covered by
+.IR n_len ,
+that is, the number of bits in
+.I n_text
+minus
+.IR (nlen_*8) .
+.I n_suffix
+shall be either
+.I NULL
+or an appendix of bits to
+.I n_suffix
+(neither
+.I n_len
+nor
+.I n_bits
+shall count these), stored as a NUL-terminated
+string of the ASCII digits
+.B 1
+and
+.BR 0 .
+.PP
+The value of the
+.I s_text
+parameter shall be the customisation
+bit-string, represented in raw bytes;
+.I s_len
+shall be value no greater than the
+number of whole bytes in
+.I s_text
+and
+.I s_bits
+shall be the number of bits in
+.I s_text
+sans the bytes covered by
+.IR s_len ,
+that is, the number of bits in
+.I s_text
+minus
+.IR (nles_*8) .
+.I s_suffix
+shall be either
+.I NULL
+or an appendix of bits to
+.I s_suffix
+(neither
+.I s_len
+nor
+.I s_bits
+shall count these), stored as a NUL-terminated
+string of the ASCII digits
+.B 1
+and
+.BR 0 .
+.PP
+For the
+.I n_suffix
+and
+.I s_suffix
+parameters,
+.I NULL
+is treated as the empty string.
+.SH RETURN VALUES
+The
+.BR libkeccak_cshake_suffix ()
+function does not return a value.
+.SH ERRORS
+The
+.BR libkeccak_cshake_suffix ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_update (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_digest (3)
diff --git a/man3/libkeccak_cshake_suffix.3 b/man3/libkeccak_cshake_suffix.3
new file mode 100644
index 0000000..b390134
--- /dev/null
+++ b/man3/libkeccak_cshake_suffix.3
@@ -0,0 +1,45 @@
+.TH LIBKECCAK_CSHAKE_SUFFIX 3 LIBKECCAK
+.SH NAME
+libkeccak_cshake_suffix - Get message suffix for cSHAKE hashing
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+const char *libkeccak_cshake_suffix(size_t \fInlen\fP, size_t \fIslen\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_cshake_suffix ()
+function returns a string of '1':s and '0':s
+representing the bits the the message suffixed
+that shall be used.
+Canonically, the values of the
+.I nlen
+and
+.I slen
+parameters shall be the length of the cSHAKE
+function-name bit-string and the cSHAKE
+customisation bit-string, however, the function
+will only check whether these values are zero
+or non-zero.
+.SH RETURN VALUES
+The
+.BR libkeccak_cshake_suffix ()
+function returns a statically allocated,
+read-only, message suffix bit-string
+that shall be used.
+.SH ERRORS
+The
+.BR libkeccak_cshake_suffix ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_digest (3)
diff --git a/man3/libkeccak_degeneralise_spec.3 b/man3/libkeccak_degeneralise_spec.3
new file mode 100644
index 0000000..e694147
--- /dev/null
+++ b/man3/libkeccak_degeneralise_spec.3
@@ -0,0 +1,123 @@
+.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK
+.SH NAME
+libkeccak_degeneralise_spec - Set all specification parameters to automatic
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_degeneralise_spec(struct libkeccak_generalised_spec *\fIspec\fP, struct libkeccak_spec *\fIoutput_spec\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_degeneralise_spec ()
+function will resolve automatic parameters in
+.I *spec
+and translates the parameters to
+.IR *output_spec ,
+so that it can be used for hashing.
+.PP
+The function will modify both
+.I *spec
+and
+.IR *output_spec .
+.PP
+You should call the
+.BR libkeccak_spec_check (3)
+function after calling
+.BR libkeccak_degeneralise_spec ().
+.PP
+.nf
+struct libkeccak_generalised_spec {
+	long int bitrate;    /* bitrate (in bits) */
+	long int capacity;   /* capacity (in bits) */
+	long int output;     /* output size (in bits) */
+	long int state_size; /* state size (in bits) */
+	long int word_size;  /* word size (in bits) */
+};
+.fi
+.SH RETURN VALUES
+The
+.BR libkeccak_degeneralise_spec ()
+function returns 0 if the settings are usable. Otherwise
+it will return one of the following constants.
+.PP
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE
+The specified state size is non-positive.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE
+The specified state size exceeded the supported limit
+(currently at 1600 bits.)
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25
+The specified state size, in bits, was not equivalent
+to 0 modulus 25. Meaning the state size cannot
+cover all lanes equivalently.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE
+The specified word size is non-positive.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE
+The specified word size exceeded the supported limit
+(currently at 64 bits.)
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY
+The specified state size is not exactly 25 times larger
+than the word size.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE
+The specified capacity was non-positive.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8
+The specified capacity was not equivalent to 0
+modulus 8, that is, it was not in whole bytes.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE
+The specified bitrate was non-positive.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8
+The specified bitrate was not equivalent to 0
+modulus 8, that is, it was not in whole bytes.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE
+The specified output size was non-positive.
+.TP
+.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_BITRATE_CAPACITY_INCONSISTENCY
+The sum of the bitrate and the capacity does not equal
+the state size (25 times the word size).
+.PP
+Note that there may be more than one error. Only the first
+detected is returned.
+.SH ERRORS
+The
+.BR libkeccak_degeneralise_spec ()
+function cannot fail.
+.fi
+.SH EXAMPLE
+This examples configure a
+.B struct libkeccak_spec
+to specify settings for Keccak[c = 512]:
+.PP
+.nf
+int r;
+struct libkeccak_spec spec;
+struct libkeccak_generalised_spec gspec;
+libkeccak_generalised_spec_initialise(&gspec);
+gspec.capacity = 512;
+if ((r = libkeccak_degeneralise_spec(&gspec, &spec)))
+    goto fail_degeneralise_spec;
+if ((r = libkeccak_spec_check(&spec)));
+    goto fail_spec_check;
+.fi
+.SH SEE ALSO
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_digest.3 b/man3/libkeccak_digest.3
new file mode 100644
index 0000000..90c76c5
--- /dev/null
+++ b/man3/libkeccak_digest.3
@@ -0,0 +1,157 @@
+.TH LIBKECCAK_DIGEST 3 LIBKECCAK
+.SH NAME
+libkeccak_digest - Complete the hashing of a message with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_digest(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP,
+                     size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_digest ()
+function absorbs the last part of (or all of) a message,
+and returns the hash of the entire message. The last part
+of the message is specified by the
+.I msg
+parameter, and its byte-size is specified by the
+.I msglen
+parameter. If all of the message has already be processed
+by calls to the
+.BR libkeccak_update (3),
+.BR libkeccak_fast_update (3),
+or
+.BR libkeccak_zerocopy_update (3)
+function (with the same pointer on
+.IR state ,)
+.I msg
+and
+.I msglen
+should be set to
+.I NULL
+and 0, respectively.
+.PP
+If the message is not comprised a whole number of bytes,
+the number of bits, modulus 8, in the message should be
+specified in the
+.I bits
+parameter.
+.I msglen
+must only count the number of whole bytes, that is, the
+floor of the number of bits in the message divided by 8.
+.PP
+.I suffix
+should be a NUL-terminated string of ASCII '1':s
+and '0':s, representing the bits that should be appended to
+the message. If this string is empty,
+.I NULL
+may be used instead. This is used to select hash algorithm.
+For pure Keccak,
+.I NULL
+or \(dq\(dq is used. For the other algorithms the constants
+.B LIBKECCAK_SHA3_SUFFIX
+(for SHA-3),
+.B LIBKECCAK_RAWSHAKE_SUFFIX
+(for RawSHAKE), and
+.B LIBKECCAK_SHAKE_SUFFIX
+(for SHAKE), or the return of the
+.BR libkeccak_cshake_suffix (3)
+function (for cSHAKE), are used.
+.PP
+The hash of the message will be stored to
+.IR hashsum ,
+unless
+.I hashsum
+is
+.I NULL
+(which increases the performance of the call.) A total of
+.RI (( state->n
++ 7) / 8) bytes will be written to the beginning of
+.IR hashsum .
+Therefore,
+.I hashsum
+needs at least an allocation size of that number of bytes.
+.PP
+The
+.BR libkeccak_digest ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as securely as possible,
+rather than as fast as possible.
+.SH RETURN VALUES
+The
+.BR libkeccak_digest ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_digest ()
+function may fail for any reason specified by the function
+.BR malloc (3).
+.SH EXAMPLE
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+.PP
+.nf
+struct libkeccak_state state;
+struct libkeccak_spec spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+char chunk[4 << 10];
+ssize_t len;
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+if (libkeccak_state_initialise(&state, &spec) < 0)
+	goto fail;
+
+for (;;) {
+	len = read(STDIN_FILENO, chunk, sizeof(chunk));
+
+	if ((len < 0) && (errno == EINTR))
+		continue;
+	if (len < 0)
+		goto fail;
+	if (len == 0)
+		break;
+
+	if (libkeccak_update(&state, chunk, (size_t)len) < 0)
+		goto fail;
+}
+if (libkeccak_digest(&state, NULL, 0, 0, \(dq\(dq, binhash) < 0)
+	goto fail;
+
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_destroy(&state);
+.fi
+.SH NOTES
+For cSHAKE, the
+.BR libkeccak_cshake_initialise (3),
+must be called, once, immediately after
+state initialisation; before the first
+call to any of the
+.BR libkeccak_fast_update (),
+.BR libkeccak_zerocopy_update (),
+.BR libkeccak_update (),
+and
+.BR libkeccak_digest ()
+functions.
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_update (3),
+.BR libkeccak_cshake_suffix (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_simple_squeeze (3),
+.BR libkeccak_fast_squeeze (3),
+.BR libkeccak_squeeze (3)
diff --git a/man3/libkeccak_fast_digest.3 b/man3/libkeccak_fast_digest.3
new file mode 100644
index 0000000..c4925e4
--- /dev/null
+++ b/man3/libkeccak_fast_digest.3
@@ -0,0 +1,160 @@
+.TH LIBKECCAK_FAST_DIGEST 3 LIBKECCAK
+.SH NAME
+libkeccak_fast_digest - Complete the hashing of a message without erasure
+.SH SYNOPSIS
+.LP
+.nf
+#include <libkeccak.h>
+
+int libkeccak_fast_digest(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP,
+                          size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP);
+.fi
+.P
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_fast_digest ()
+function absorbs the last part of (or all of) a message,
+and returns the hash of the entire message. The last part
+of the message is specified by the
+.I msg
+parameter, and its byte-size is specified by the
+.I msglen
+parameter. If all of the message has already be processed
+by calls to the
+.BR libkeccak_update (3),
+.BR libkeccak_fast_update (3),
+or
+.BR libkeccak_zerocopy_update (3)
+function (with the same pointer on
+.IR state ,)
+.I msg
+and
+.I msglen
+should be set to
+.I NULL
+and 0, respectively.
+.PP
+If the message is not comprised a whole number of bytes,
+the number of bits, modulus 8, in the message should be
+specified in the
+.I bits
+parameter.
+.I msglen
+must only count the number of whole bytes, that is, the
+floor of the number of bits in the message divided by 8.
+.PP
+.I suffix
+should be a NUL-terminated string of ASCII '1':s and '0':s,
+representing the bits that should be appended to the
+message. If this string is empty,
+.I NULL
+may be used instead. This is used to select hash algorithm.
+For pure Keccak,
+.I NULL
+or \(dq\(dq is used. For the other algorithms the constants
+.B LIBKECCAK_SHA3_SUFFIX
+(for SHA-3),
+.B LIBKECCAK_RAWSHAKE_SUFFIX
+(for RawSHAKE), and
+.B LIBKECCAK_SHAKE_SUFFIX
+(for SHAKE), or the return of the
+.BR libkeccak_cshake_suffix (3)
+function (for cSHAKE), are used.
+.PP
+The hash of the message will be stored to
+.IR hashsum ,
+unless
+.IR hashsum
+is
+.IR NULL
+(which increases the performance of the call.) A total of
+.RI (( state->n
++ 7) / 8) bytes will be written to the beginning of
+.IR hashsum .
+Therefore,
+.I hashsum
+needs at least an allocation size of that number of bytes.
+.PP
+The
+.BR libkeccak_fast_digest ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as quickly as possible,
+rather than ensuring that the information in the old
+allocation is securely removed if a new allocation is required.
+.SH RETURN VALUES
+The
+.BR libkeccak_fast_digest ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_fast_digest ()
+function may fail for any reason specified by the function
+.BR realloc (3).
+.SH EXAMPLE
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+.PP
+.nf
+struct libkeccak_state state;
+struct libkeccak_spec spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+char chunk[4 << 10];
+ssize_t len;
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+if (libkeccak_state_initialise(&state, &spec) < 0)
+	goto fail;
+
+for (;;) {
+	len = read(STDIN_FILENO, chunk, sizeof(chunk));
+
+	if ((len < 0) && (errno == EINTR))
+		continue;
+	if (len < 0)
+		goto fail;
+	if (len == 0)
+		break;
+
+	if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0)
+		goto fail;
+}
+if (libkeccak_fast_digest(&state, NULL, 0, 0, \(dq\(dq, binhash) < 0)
+	goto fail;
+
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_fast_destroy(&state);
+.fi
+.SH NOTES
+For cSHAKE, the
+.BR libkeccak_cshake_initialise (3),
+must be called, once, immediately after
+state initialisation; before the first
+call to any of the
+.BR libkeccak_fast_update (),
+.BR libkeccak_zerocopy_update (),
+.BR libkeccak_update (),
+and
+.BR libkeccak_digest_digest ()
+functions.
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_update (3),
+.BR libkeccak_cshake_suffix (3),
+.BR libkeccak_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_simple_squeeze (3),
+.BR libkeccak_fast_squeeze (3),
+.BR libkeccak_squeeze (3)
diff --git a/man3/libkeccak_fast_squeeze.3 b/man3/libkeccak_fast_squeeze.3
new file mode 100644
index 0000000..5be6cd6
--- /dev/null
+++ b/man3/libkeccak_fast_squeeze.3
@@ -0,0 +1,35 @@
+.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK
+.SH NAME
+libkeccak_fast_squeeze - Runs the squeeze phase a number of times
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_fast_squeeze(struct libkeccak_state *\fIstate\fP, long int \fItimes\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_fast_squeeze ()
+function runs the Keccak squeeze phase, on the the hash
+process described by
+.IR *state ,
+as many times are required to get
+.I times
+additional digests.
+.SH RETURN VALUES
+The
+.BR libkeccak_fast_squeeze ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_fast_squeeze ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_digest (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_simple_squeeze (3),
+.BR libkeccak_squeeze (3)
diff --git a/man3/libkeccak_fast_update.3 b/man3/libkeccak_fast_update.3
new file mode 100644
index 0000000..5d38b0d
--- /dev/null
+++ b/man3/libkeccak_fast_update.3
@@ -0,0 +1,101 @@
+.TH LIBKECCAK_FAST_UPDATE 3 LIBKECCAK
+.SH NAME
+libkeccak_fast_update - Partially hash a message without erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_fast_update(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_fast_update ()
+function continues (or starts) hashing a message.
+The current state of the hashing is stored in
+.IR *state ,
+and will be updated. The message specified by the
+.I msg
+parameter with the byte-size specified by the
+.I msglen
+parameter, will be hashed.
+.PP
+The
+.BR libkeccak_fast_update ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as quickly as possible,
+rather than ensuring that the information in the old
+allocation is securely removed if a new allocation is required.
+.SH RETURN VALUES
+The
+.BR libkeccak_fast_update ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_fast_update ()
+function may fail for any reason specified by the function
+.BR realloc (3).
+.SH NOTES
+Neither parameter by be
+.I NULL
+or 0.
+.SH EXAMPLE
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+.PP
+.nf
+struct libkeccak_state state;
+struct libkeccak_spec spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+char chunk[4 << 10];
+ssize_t len;
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+if (libkeccak_state_initialise(&state, &spec) < 0)
+	goto fail;
+
+for (;;) {
+	len = read(STDIN_FILENO, chunk, sizeof(chunk));
+
+	if ((len < 0) && (errno == EINTR))
+		continue;
+	if (len < 0)
+		goto fail;
+	if (len == 0)
+		break;
+
+	if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0)
+		goto fail;
+}
+if (libkeccak_fast_digest(&state, NULL, 0, 0, \(dq\(dq, binhash) < 0)
+	goto fail;
+
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_fast_destroy(&state);
+.fi
+.SH NOTES
+For cSHAKE, the
+.BR libkeccak_cshake_initialise (3),
+must be called, once, immediately after
+state initialisation; before the first
+call to the
+.BR libkeccak_fast_update ()
+function.
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_update (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_digest (3)
diff --git a/man3/libkeccak_generalised_spec_initialise.3 b/man3/libkeccak_generalised_spec_initialise.3
new file mode 100644
index 0000000..acfa173
--- /dev/null
+++ b/man3/libkeccak_generalised_spec_initialise.3
@@ -0,0 +1,42 @@
+.TH LIBKECCAK_GENERALISED_SPEC_INITIALISE 3 LIBKECCAK
+.SH NAME
+libkeccak_generalised_spec_initialise - Set all specification parameters to automatic
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_generalised_spec_initialise(struct libkeccak_generalised_spec *\fIspec\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_generalised_spec_initialise ()
+function initialises
+.IR *spec ,
+so that all parameters are configured to be
+automatically selected.
+.PP
+Automatic selection means that value will be set
+to the default, which depends on the other settings.
+.PP
+Specifically, all members of
+.IR *spec ,
+will be set to
+.BR LIBKECCAK_GENERALISED_SPEC_AUTOMATIC .
+.SH RETURN VALUES
+The
+.BR libkeccak_generalised_spec_initialise ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_generalised_spec_initialise ()
+function cannot fail.
+.fi
+.SH SEE ALSO
+.BR libkeccak_degeneralise_spec (3),
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_shake (3)
diff --git a/man3/libkeccak_generalised_sum_fd.3 b/man3/libkeccak_generalised_sum_fd.3
new file mode 100644
index 0000000..9f5341a
--- /dev/null
+++ b/man3/libkeccak_generalised_sum_fd.3
@@ -0,0 +1,137 @@
+.TH LIBKECCAK_GENERALISED_SUM_FD 3 LIBKECCAK
+.SH NAME
+libkeccak_generalised_sum_fd - Calculate the hash of a file
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_generalised_sum_fd(int \fIfd\fP, struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\fIspec\fP,
+                                 const char *\fIsuffix\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_generalised_sum_fd ()
+function calculates the hash of a file, whose file desriptor is
+specified by
+.I fd
+(and should be at the beginning of the file.) The hash algorithm
+is specified by
+.I *spec
+and
+.IR suffix ,
+where
+.I *spec
+is the tuning of the algorithm and
+.I suffix
+is the bits append to the message (or
+.I NULL
+if none.)
+.PP
+The hash is stored in binary form to
+.IR hashsum .
+.I hashsum
+should have an allocation size of at least
+.RI ((( spec->output
++ 7) / 8) * sizeof(char)).
+.PP
+.I *state
+should not be initialised unless
+.I spec
+is
+.IR NULL .
+.BR libkeccak_generalised_sum_fd ()
+initialises
+.I *state
+itself unless
+.I spec
+is
+.IR NULL .
+Therefore there would be a memory leak if
+.I *state
+is already initialised and
+.I spec
+is
+.RI non- NULL .
+.SH RETURN VALUES
+The
+.BR libkeccak_generalised_sum_fd ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_generalised_sum_fd ()
+function may fail for any reason, except those resulting
+in
+.I errno
+being set to
+.BR EINTR ,
+specified for the functions
+.BR read (2),
+.BR malloc (3),
+and
+.BR realloc (3).
+.SH NOTES
+Be aware,
+.BR libkeccak_generalised_sum_fd ()
+hashes the file until the end has been reached. For pipes
+and sockets and this means until the file has been closed.
+But for character devices, this usually means never.
+Attempting to hash files in /dev is therefore usually a
+bad idea.
+.BR libkeccak_generalised_sum_fd ()
+does not check for the file length or file type before
+hashing as this could limit what you can do, and make
+the library more complex.
+.PP
+.BR libkeccak_generalised_sum_fd ()
+does not stop if interrupted
+.RB ( read (2)
+returns
+.BR EINTR .)
+.PP
+.BR libkeccak_generalised_sum_fd ()
+assumes all information is non-sensitive, and will
+therefore not perform any secure erasure of information.
+.PP
+.BR libkeccak_generalised_sum_fd ()
+does not validate the tuning of the algorithm.
+.SH EXAMPLE
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+.PP
+.nf
+struct libkeccak_state state;
+struct libkeccak_spec spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+
+if (libkeccak_generalised_sum_fd(STDIN_FILENO, &state, &spec, NULL, binhash) < 0)
+	goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_destroy(&state);
+.fi
+.SH SEE ALSO
+.BR libkeccak_behex_lower (3),
+.BR libkeccak_behex_upper (3),
+.BR libkeccak_keccaksum_fd (3),
+.BR libkeccak_sha3sum_fd (3),
+.BR libkeccak_rawshakesum_fd (3),
+.BR libkeccak_shakesum_fd (3),
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3)
diff --git a/man3/libkeccak_hmac_copy.3 b/man3/libkeccak_hmac_copy.3
new file mode 100644
index 0000000..eb80c6e
--- /dev/null
+++ b/man3/libkeccak_hmac_copy.3
@@ -0,0 +1,38 @@
+.TH LIBKECCAK_HMAC_COPY 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_copy - Copies an HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_copy(struct libkeccak_hmac_state *\fIdest\fP, const struct libkeccak_hmac_state *\fIsrc\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_copy ()
+function initialises
+.I *dest
+to be identical to
+.IR *src .
+This includes all members of the
+.B struct libkeccak_hmac_state
+structure, including the state of the sponge and the
+message chunk buffer.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_copy ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_copy ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_duplicate (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_hmac_create.3 b/man3/libkeccak_hmac_create.3
new file mode 100644
index 0000000..d804f31
--- /dev/null
+++ b/man3/libkeccak_hmac_create.3
@@ -0,0 +1,47 @@
+.TH LIBKECCAK_HMAC_CREATE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_create - Allocate and initialise HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+struct libkeccak_hmac_state *libkeccak_hmac_create(const struct libkeccak_spec *\fIspec\fP, const void *\fIkey\fP, size_t \fIkey_length\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_create ()
+function allocates a new
+.I struct libkeccak_hmac_state *
+with one initialised element, and sets the
+algorithm tuning parameters to those specified by
+.IR *spec ,
+and the key to
+.I key
+of length
+.IR key_length .
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_create ()
+function returns a newly allocated
+.I struct libkeccak_hmac_state *
+(of one initialised element) upon successful completion.
+On error,
+.I NULL
+is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_create ()
+function may fail for any specified for the functions
+.BR malloc (3)
+and
+.BR realloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_free (3),
+.BR libkeccak_hmac_fast_free (3),
+.BR libkeccak_hmac_duplicate (3)
diff --git a/man3/libkeccak_hmac_destroy.3 b/man3/libkeccak_hmac_destroy.3
new file mode 100644
index 0000000..e2d5b1c
--- /dev/null
+++ b/man3/libkeccak_hmac_destroy.3
@@ -0,0 +1,38 @@
+.TH LIBKECCAK_HMAC_DESTROY 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_destroy - Destroys an HMAC-hashing state with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_hmac_destroy(struct libkeccak_hmac_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_destroy ()
+function releases the allocations stored in
+.IR *state ,
+without releasing the allocation of
+.I state
+itself.
+.PP
+The
+.BR libkeccak_hmac_destroy ()
+function securely erases sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_destroy ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_hmac_destroy ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_hmac_free (3),
+.BR libkeccak_hmac_fast_destroy (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_reset (3),
+.BR libkeccak_hmac_wipe (3)
diff --git a/man3/libkeccak_hmac_digest.3 b/man3/libkeccak_hmac_digest.3
new file mode 100644
index 0000000..9c0ee6b
--- /dev/null
+++ b/man3/libkeccak_hmac_digest.3
@@ -0,0 +1,97 @@
+.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_digest(struct libkeccak_hmac_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP,
+                          size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_digest ()
+function absorbes the last part of (or all of) a message,
+and returns the HMAC hash of the entire message. The last
+part of the message is specified by the
+.I msg
+parameter, and its byte-size is specified by the
+.I msglen
+parameter. If all of the message has already be processed
+by calls to the
+.BR libkeccak_hmac_update (3)
+function or the
+.BR libkeccak_hmac_fast_update (3)
+function (with the same pointer on
+.IR state ,)
+.I msg
+and
+.I msglen
+should be set to
+.I NULL
+and 0, respectively.
+.PP
+If the message is not comprised a whole number of bytes,
+the number of bits, modulus 8, in the message should be
+specified in the
+.I bits
+parameter. 
+.I msglen
+must only count the number of whole bytes, that is, the
+floor of the number of bits in the message divided by 8.
+.PP
+.I suffix
+should be a NUL-terminated string of ASCII '1':s
+and '0':s, representing the bits that should be appended
+to the message. If this string is empty,
+.I NULL
+may be used instead. This is used to select hash algorithm.
+For pure Keccak,
+.I NULL
+or \(dq\(dq is used. For the other algorithms the constants
+.B LIBKECCAK_SHA3_SUFFIX
+(for SHA-3),
+.B LIBKECCAK_RAWSHAKE_SUFFIX
+(for RawSHAKE), and
+.B LIBKECCAK_SHAKE_SUFFIX
+(for SHAKE) are used.
+.PP
+The hash of the message will be stored to
+.IR hashsum ,
+unless
+.I hashsum
+is
+.I NULL
+(which increases the performance of the call.) A total of
+.RI (( state->n
++ 7) / 8) bytes will be written to the beginning of
+.IR hashsum .
+Therefore,
+.I hashsum
+needs at least an allocation size of that number of bytes.
+.PP
+The
+.BR libkeccak_hmac_digest ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as securely as possible,
+rather than as fast as possible.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_digest ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_digest ()
+function may fail for any reason specified by the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_update (3),
+.BR libkeccak_hmac_fast_digest (3)
diff --git a/man3/libkeccak_hmac_duplicate.3 b/man3/libkeccak_hmac_duplicate.3
new file mode 100644
index 0000000..b1cdc30
--- /dev/null
+++ b/man3/libkeccak_hmac_duplicate.3
@@ -0,0 +1,41 @@
+.TH LIBKECCAK_HMAC_DUPLICATE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_duplicate - Allocate a duplicate an HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+struct libkeccak_hmac_state *libkeccak_hmac_duplicate(const struct libkeccak_hmac_state *\fIsrc\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_duplicate ()
+function allocates a new hash state and initialises
+it to be identical to
+.IR *src .
+This includes all members of the
+.B struct libkeccak_hmac_state
+structure, including the state of the sponge and the
+message chunk buffer.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_duplicate ()
+function returns a newly allocated
+.I libkeccak_hmac_t*
+(of one initialised element) upon successful completion.
+On error,
+.I NULL
+is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_duplicate ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_copy (3),
+.BR libkeccak_hmac_create (3)
diff --git a/man3/libkeccak_hmac_fast_destroy.3 b/man3/libkeccak_hmac_fast_destroy.3
new file mode 100644
index 0000000..05a8e2e
--- /dev/null
+++ b/man3/libkeccak_hmac_fast_destroy.3
@@ -0,0 +1,38 @@
+.TH LIBKECCAK_HMAC_FAST_DESTROY 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_fast_destroy - Destroys an HMAC-hashing state without erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_hamc_fast_destroy(struct libkeccak_hmac_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_fast_destroy ()
+function releases the allocations stored in
+.IR *state ,
+without releasing the allocation of
+.I state
+itself.
+.PP
+The
+.BR libkeccak_hmac_fast_destroy ()
+function does not securely erase sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_fast_destroy ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_fast_destroy ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_hmac_fast_free (3),
+.BR libkeccak_hmac_destroy (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_reset (3),
+.BR libkeccak_hmac_wipe (3)
diff --git a/man3/libkeccak_hmac_fast_digest.3 b/man3/libkeccak_hmac_fast_digest.3
new file mode 100644
index 0000000..6f21b70
--- /dev/null
+++ b/man3/libkeccak_hmac_fast_digest.3
@@ -0,0 +1,98 @@
+.TH LIBKECCAK_HMAC_FAST_DIGEST 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_fast_digest - Complete the HMAC-hashing of a message without erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_fast_digest(struct libkeccak_hmac_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP,
+                               size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_fast_digest ()
+function absorbes the last part of (or all of) a message,
+and returns the HMAC hash of the entire message. The last
+part of the message is specified by the
+.I msg
+parameter, and its byte-size is specified by the
+.I msglen
+parameter. If all of the message has already be processed
+by calls to the
+.BR libkeccak_hmac_update (3)
+function or the
+.BR libkeccak_hmac_fast_update (3)
+function (with the same pointer on
+.IR state ,)
+.I msg
+and
+.I msglen
+should be set to
+.I NULL
+and 0, respectively.
+.PP
+If the message is not comprised a whole number of bytes,
+the number of bits, modulus 8, in the message should be
+specified in the
+.I bits
+parameter. 
+.I msglen
+must only count the number of whole bytes, that is, the
+floor of the number of bits in the message divided by 8.
+.PP
+.I suffix
+should be a NUL-terminated string of ASCII '1':s
+and '0':s, representing the bits that should be appended
+to the message. If this string is empty,
+.I NULL
+may be used instead. This is used to select hash algorithm.
+For pure Keccak,
+.I NULL
+or \(dq\(dq is used. For the other algorithms the constants
+.B LIBKECCAK_SHA3_SUFFIX
+(for SHA-3),
+.B LIBKECCAK_RAWSHAKE_SUFFIX
+(for RawSHAKE), and
+.B LIBKECCAK_SHAKE_SUFFIX
+(for SHAKE) are used.
+.PP
+The hash of the message will be stored to
+.IR hashsum ,
+unless
+.I hashsum
+is
+.I NULL
+(which increases the performance of the call.) A total of
+.RI (( state->n
++ 7) / 8) bytes will be written to the beginning of
+.IR hashsum .
+Therefore,
+.I hashsum
+needs at least an allocation size of that number of bytes.
+.PP
+The
+.BR libkeccak_hmac_fast_digest ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as quickly as possible,
+rather than ensuring that the information in the old
+allocation is securely removed if a new allocation is required.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_fast_digest ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_fast_digest ()
+function may fail for any reason specified by the function
+.BR realloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_fast_update (3),
+.BR libkeccak_hmac_fast_digest (3)
diff --git a/man3/libkeccak_hmac_fast_free.3 b/man3/libkeccak_hmac_fast_free.3
new file mode 100644
index 0000000..87cb556
--- /dev/null
+++ b/man3/libkeccak_hmac_fast_free.3
@@ -0,0 +1,46 @@
+.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_fast_free - Destroys and deallocates an HMAC-hashing state without erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_hmac_fast_free(struct libkeccak_hmac_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_fast_free ()
+function releases the allocations stored in
+.IR *state ,
+and also released the allocation of
+.IR state .
+.PP
+The
+.BR libkeccak_hmac_fast_free ()
+function does not securely erase sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_fast_free ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_hmac_fast_free ()
+function cannot fail.
+.SH NOTES
+A double call to
+.BR libkeccak_hmac_fast_free ()
+will either result in a double free,
+which is must likely to crash the process,
+or free an allocation (that was created
+between the calls) that was not intended
+to be freed, resulting in undefined behaviour.
+.SH SEE ALSO
+.BR libkeccak_hmac_fast_destroy (3),
+.BR libkeccak_hmac_free (3),
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_reset (3),
+.BR libkeccak_hmac_wipe (3)
diff --git a/man3/libkeccak_hmac_fast_update.3 b/man3/libkeccak_hmac_fast_update.3
new file mode 100644
index 0000000..ca62baf
--- /dev/null
+++ b/man3/libkeccak_hmac_fast_update.3
@@ -0,0 +1,53 @@
+.TH LIBKECCAK_HMAC_FAST_UPDATE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_fast_update - Partially HMAC-hash a message without erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_fast_update(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_fast_update ()
+function continues (or starts) HMAC-hashing a message.
+The current state of the hashing is stored in
+.IR *state ,
+and will be updated. The message specified by the
+.I msg
+parameter with the byte-size specified by the
+.I msglen
+parameter, will be hashed.
+.PP
+The
+.BR libkeccak_hmac_fast_update ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as securely as possible,
+rather than as fast as possible.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_fast_update ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_fast_update ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as quickly as possible,
+rather than ensuring that the information in the old
+allocation is securely removed if a new allocation is required.
+.BR realloc (3).
+.SH NOTES
+Neither parameter by be
+.I NULL
+or 0.
+.SH SEE ALSO
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_fast_digest (3),
+.BR libkeccak_hmac_update (3)
diff --git a/man3/libkeccak_hmac_free.3 b/man3/libkeccak_hmac_free.3
new file mode 100644
index 0000000..91b103e
--- /dev/null
+++ b/man3/libkeccak_hmac_free.3
@@ -0,0 +1,46 @@
+.TH LIBKECCAK_HMAC_FREE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_free - Destroys and deallocates an HMAC-hashing state with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_hmac_free(struct libkeccak_hmac_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_free ()
+function releases the allocations stored in
+.IR *state ,
+and also release the allocation of
+.IR state .
+.PP
+The
+.BR libkeccak_hmac_free ()
+function securely erases sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_free ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_hmac_free ()
+function cannot fail.
+.SH NOTES
+A double call to
+.BR libkeccak_hmac_free ()
+will either result in a double free,
+which is must likely to crash the process,
+or free an allocation (that was created
+between the calls) that was not intended
+to be freed, resulting in undefined behaviour.
+.SH SEE ALSO
+.BR libkeccak_hmac_destroy (3),
+.BR libkeccak_hmac_fast_free (3),
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_reset (3),
+.BR libkeccak_hmac_wipe (3)
diff --git a/man3/libkeccak_hmac_initialise.3 b/man3/libkeccak_hmac_initialise.3
new file mode 100644
index 0000000..db3590f
--- /dev/null
+++ b/man3/libkeccak_hmac_initialise.3
@@ -0,0 +1,51 @@
+.TH LIBKECCAK_HMAC_INITIALISE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_initialise - Initialise HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_initialise(struct libkeccak_hmac_state *\fIstate\fP, const struct libkeccak_spec *\fIspec\fP,
+                              const void *\fIkey\fP, size_t \fIkey_length\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_initialise ()
+function initialises
+.I *state
+and sets the algorithm tuning parameters to
+those specified by
+.IR *spec ,
+and the key to
+.I key
+of length
+.IR key_length .
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_initialise ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_initialise ()
+function may fail for any specified for the functions
+.BR malloc (3)
+and
+.BR realloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_destroy (3),
+.BR libkeccak_hmac_fast_destroy (3),
+.BR libkeccak_hmac_copy (3),
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3)
diff --git a/man3/libkeccak_hmac_marshal.3 b/man3/libkeccak_hmac_marshal.3
new file mode 100644
index 0000000..29ca9ea
--- /dev/null
+++ b/man3/libkeccak_hmac_marshal.3
@@ -0,0 +1,37 @@
+.TH LIBKECCAK_HMAC_MARSHAL 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_marshal - Marshals an HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+size_t libkeccak_hmac_marshal(const struct libkeccak_hmac_state *\fIstate\fP, void *\fIdata\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_marshal ()
+function marshals
+.I *state
+into the beginning of
+.IR data .
+.PP
+Specific
+.I NULL
+as
+.I data
+to get minimum usable allocation size for
+.IR data .
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_marshal ()
+returns the number of bytes written to
+.IR data .
+.SH ERRORS
+The
+.BR libkeccak_hmac_marshal ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_hmac_unmarshal (3)
diff --git a/man3/libkeccak_hmac_reset.3 b/man3/libkeccak_hmac_reset.3
new file mode 100644
index 0000000..963ad4c
--- /dev/null
+++ b/man3/libkeccak_hmac_reset.3
@@ -0,0 +1,45 @@
+.TH LIBKECCAK_HMAC_RESET 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_reset - Reinitialise a HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_reset(struct libkeccak_hmac_state *\fIstate\fP, const void *\fIkey\fP, size_t \fIkey_length\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_reset ()
+function reinitialises an HMAC-hashing state with a new key.
+.I key_length
+is the length of the key in bits. If
+.I key
+is
+.IR NULL ,
+the key remains unchanged.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_reset ()
+function returns 0 successful completion.
+On error -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_reset ()
+function may fail for any specified for the functions
+.BR malloc (3)
+and
+.BR realloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_set_key (3),
+.BR libkeccak_hmac_wipe (3),
+.BR libkeccak_hmac_fast_free (3),
+.BR libkeccak_hmac_free (3),
+.BR libkeccak_hmac_fast_destroy (3),
+.BR libkeccak_hmac_destroy (3)
diff --git a/man3/libkeccak_hmac_set_key.3 b/man3/libkeccak_hmac_set_key.3
new file mode 100644
index 0000000..f961ade
--- /dev/null
+++ b/man3/libkeccak_hmac_set_key.3
@@ -0,0 +1,35 @@
+.TH LIBKECCAK_HMAC_SET_KEY 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_set_key - Changes key for a the HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_set_key(struct libkeccak_hmac_state *\fIstate\fP, const void *\fIkey\fP, size_t \fIkey_length\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_set_key ()
+function sets the key for a HMAC-hashing state without reseting
+the state of the underlaying hashing-algorithm.
+.I key_length
+is the length of the key in bits.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_set_key ()
+function returns 0 successful completion.
+On error -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_set_key ()
+function may fail for any specified for the function
+.BR realloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_reset (3)
diff --git a/man3/libkeccak_hmac_unmarshal.3 b/man3/libkeccak_hmac_unmarshal.3
new file mode 100644
index 0000000..7224282
--- /dev/null
+++ b/man3/libkeccak_hmac_unmarshal.3
@@ -0,0 +1,46 @@
+.TH LIBKECCAK_HMAC_UNMARSHAL 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_unmarshal - Unharshals an HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+size_t libkeccak_hmac_unmarshal(struct libkeccak_hmac_state *\fIstate\fP, const void *\fIdata\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_unmarshal ()
+function unmarshals an HMAC-hashing state from the beginning of
+.IR data .
+and stores it in
+.IR *state .
+.I state
+may be
+.IR NULL .
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_unmarshal ()
+returns the number of bytes reads from
+.I data
+upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+If
+.I state
+is
+.IR NULL ,
+the number the function will always be
+successful and return a positive value,
+this value is the number of bytes that
+make un the marshalled state.
+.SH ERRORS
+The
+.BR libkeccak_hmac_unmarshal ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_hmac_marshal (3)
diff --git a/man3/libkeccak_hmac_update.3 b/man3/libkeccak_hmac_update.3
new file mode 100644
index 0000000..e34bb98
--- /dev/null
+++ b/man3/libkeccak_hmac_update.3
@@ -0,0 +1,50 @@
+.TH LIBKECCAK_HMAC_UPDATE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_update - Partially HMAC-hash a message with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_update(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_update ()
+function continues (or starts) HMAC-hashing a message.
+The current state of the hashing is stored in
+.IR *state ,
+and will be updated. The message specified by the
+.I msg
+parameter with the byte-size specified by the
+.I msglen
+parameter, will be hashed.
+.PP
+The
+.BR libkeccak_hmac_update ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as securely as possible,
+rather than as fast as possible.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_update ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_hmac_update ()
+function may fail for any reason specified by the function
+.BR malloc (3).
+.SH NOTES
+Neither parameter by be
+.I NULL
+or 0.
+.SH SEE ALSO
+.BR libkeccak_hmac_create (3),
+.BR libkeccak_hmac_initialise (3),
+.BR libkeccak_hmac_digest (3),
+.BR libkeccak_hmac_fast_update (3)
diff --git a/man3/libkeccak_hmac_wipe.3 b/man3/libkeccak_hmac_wipe.3
new file mode 100644
index 0000000..ceee5d7
--- /dev/null
+++ b/man3/libkeccak_hmac_wipe.3
@@ -0,0 +1,31 @@
+.TH LIBKECCAK_HMAC_WIPE 3 LIBKECCAK
+.SH NAME
+libkeccak_hmac_wipe - Securely erase sensitive data from a HMAC-hashing state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_hmac_wipe(struct libkeccak_hmac_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_hmac_wipe ()
+function securely erases data that may be
+sensitive: the buffer and the state of the
+underlaying hash-algorithm.
+.SH RETURN VALUES
+The
+.BR libkeccak_hmac_wipe ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_hmac_wipe ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_hmac_fast_free (3),
+.BR libkeccak_hmac_free (3),
+.BR libkeccak_hmac_fast_destroy (3),
+.BR libkeccak_hmac_destroy (3)
diff --git a/man3/libkeccak_keccaksum_fd.3 b/man3/libkeccak_keccaksum_fd.3
new file mode 100644
index 0000000..82d1fb9
--- /dev/null
+++ b/man3/libkeccak_keccaksum_fd.3
@@ -0,0 +1,113 @@
+.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK
+.SH NAME
+libkeccak_keccaksum_fd - Calculate a Keccak hashsum of a file
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_keccaksum_fd(int \fIfd\fP, struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\fIspec\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_keccaksum_fd ()
+function calculates a Keccak hashsum of a file, whose file
+desriptor is specified by
+.I fd
+(and should be at the beginning of the file.) The hash
+algorithm tuning is specified by
+.IR *spec .
+.PP
+The hash is stored in binary form to
+.IR hashsum .
+.I hashsum
+should have an allocation size of at least
+.RI ((( spec->output
++ 7) / 8) * sizeof(char)).
+.PP
+.I *state
+should not be initialised.
+.BR libkeccak_keccaksum_fd ()
+initialises
+.I *state
+itself. Therefore there would be a memory leak if
+.I *state
+is already initialised.
+.SH RETURN VALUES
+The
+.BR libkeccak_keccaksum_fd ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_keccaksum_fd ()
+function may fail for any reason, except those resulting
+in
+.I errno
+being set to
+.BR EINTR ,
+specified for the functions
+.BR read (2),
+.BR malloc (3),
+and
+.BR realloc (3).
+.SH NOTES
+Be aware,
+.BR libkeccak_keccaksum_fd ()
+hashes the file until the end has been reached. For pipes
+and sockets and this means until the file has been closed.
+But for character devices, this usually means never.
+Attempting to hash files in /dev is therefore usually a
+bad idea.
+.BR libkeccak_keccaksum_fd ()
+does not check for the file length or file type before
+hashing as this could limit what you can do, and make
+the library more complex.
+.PP
+.BR libkeccak_keccaksum_fd ()
+does not stop if interrupted
+.RI ( read (2)
+returns
+.BR EINTR .)
+.PP
+.BR libkeccak_keccaksum_fd ()
+assumes all information is non-sensitive, and will
+therefore not perform any secure erasure of information.
+.PP
+.BR libkeccak_keccaksum_fd ()
+does not validate the tuning of the algorithm.
+.SH EXAMPLE
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+.LP
+.nf
+struct libkeccak_state state;
+struct libkeccak_spec spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+
+if (libkeccak_keccaksum_fd(STDIN_FILENO, &state, &spec, binhash) < 0)
+	goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_destroy(&state);
+.fi
+.SH SEE ALSO
+.BR libkeccak_behex_lower (3),
+.BR libkeccak_behex_upper (3),
+.BR libkeccak_generalised_sum_fd (3),
+.BR libkeccak_sha3sum_fd (3),
+.BR libkeccak_rawshakesum_fd (3),
+.BR libkeccak_shakesum_fd (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3)
diff --git a/man3/libkeccak_rawshakesum_fd.3 b/man3/libkeccak_rawshakesum_fd.3
new file mode 100644
index 0000000..5678389
--- /dev/null
+++ b/man3/libkeccak_rawshakesum_fd.3
@@ -0,0 +1,108 @@
+.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK
+.SH NAME
+libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_rawshakesum_fd(int \fIfd\fP, struct libkeccak_state *\fIstate\fP, long int \fIsemicapacity\fP, long int \fIoutput\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_rawshakesum_fd ()
+function calculates a RawSHAKE hashsum of a file, whose
+file desriptor is specified by
+.I fd
+(and should be at the beginning of the file.) The hash
+algorithm is tuned by the
+.I semicapacity
+and
+.I output
+parameters; they specify the half of the capacity and
+the output size, respectively, in bits.
+.PP
+The hash is stored in binary form to
+.IR hashsum .
+.I hashsum
+should have an allocation size of at least
+.RI ((( output
++ 7) / 8) * sizeof(char)).
+.PP
+.I *state
+should not be initialised.
+.BR libkeccak_rawshakesum_fd ()
+initialises
+.I *state
+itself. Therefore there would be a memory leak if
+.I *state
+is already initialised.
+.SH RETURN VALUES
+The
+.BR libkeccak_rawshakesum_fd ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_rawshakesum_fd ()
+function may fail for any reason, except those resulting in
+.I errno
+being set to
+.BR EINTR ,
+specified for the functions
+.BR read (2),
+.BR malloc (3),
+and
+.BR realloc (3).
+.SH NOTES
+Be aware,
+.BR libkeccak_rawshakesum_fd ()
+hashes the file until the end has been reached. For pipes
+and sockets and this means until the file has been closed.
+But for character devices, this usually means never.
+Attempting to hash files in /dev is therefore usually a
+bad idea.
+.BR libkeccak_rawshakesum_fd ()
+does not check for the file length or file type before
+hashing as this could limit what you can do, and make
+the library more complex.
+.PP
+.BR libkeccak_rawshakesum_fd ()
+does not stop if interrupted
+.RB ( read (2)
+returns
+.BR EINTR .)
+.PP
+.BR libkeccak_rawshakesum_fd ()
+assumes all information is non-sensitive, and will
+therefore not perform any secure erasure of information.
+.PP
+.BR libkeccak_rawshakesum_fd ()
+does not validate the tuning of the algorithm.
+.SH EXAMPLE
+This example calculates the RawSHAKE256(, 512) hash of the input
+from stdin, and prints the hash, in hexadecimal form, to stdout.
+.LP
+.nf
+struct libkeccak_state state;
+if (libkeccak_rawshakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0)
+	goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_destroy(&state);
+.fi
+.SH SEE ALSO
+.BR libkeccak_behex_lower (3),
+.BR libkeccak_behex_upper (3),
+.BR libkeccak_generalised_sum_fd (3),
+.BR libkeccak_keccaksum_fd (3),
+.BR libkeccak_sha3sum_fd (3),
+.BR libkeccak_shakesum_fd (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3)
diff --git a/man3/libkeccak_sha3sum_fd.3 b/man3/libkeccak_sha3sum_fd.3
new file mode 100644
index 0000000..d27618d
--- /dev/null
+++ b/man3/libkeccak_sha3sum_fd.3
@@ -0,0 +1,105 @@
+.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK
+.SH NAME
+libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_sha3sum_fd(int \fIfd\fP, struct libkeccak_state *\fIstate\fP, long int \fIoutput\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_sha3sum_fd ()
+function calculates a SHA-3 hashsum of a file, whose file
+desriptor is specified by
+.I fd
+(and should be at the beginning of the file.) The hash
+algorithm is tuned by the
+.I output
+parameter; it specifies the output size, in bits.
+.PP
+The hash is stored in binary form to
+.IR hashsum .
+.I hashsum
+should have an allocation size of at least
+.RI ((( output
++ 7) / 8) * sizeof(char)).
+.PP
+.I *state
+should not be initialised.
+.BR libkeccak_sha3sum_fd ()
+initialises
+.I *state
+itself. Therefore there would be a memory leak if
+.I *state
+is already initialised.
+.SH RETURN VALUES
+The
+.BR libkeccak_sha3sum_fd ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_sha3sum_fd ()
+function may fail for any reason, except those resulting in
+.I errno
+being set to
+.BR EINTR ,
+specified for the functions
+.BR read (2),
+.BR malloc (3),
+and
+.BR realloc (3).
+.SH NOTES
+Be aware,
+.BR libkeccak_sha3sum_fd ()
+hashes the file until the end has been reached. For pipes
+and sockets and this means until the file has been closed.
+But for character devices, this usually means never.
+Attempting to hash files in /dev is therefore usually a
+bad idea.
+.BR libkeccak_sha3sum_fd ()
+does not check for the file length or file type before
+hashing as this could limit what you can do, and make
+the library more complex.
+.PP
+.BR libkeccak_sha3sum_fd ()
+does not stop if interrupted
+.RB ( read (2)
+returns
+.BR EINTR .)
+.PP
+.BR libkeccak_sha3sum_fd ()
+assumes all information is non-sensitive, and will
+therefore not perform any secure erasure of information.
+.PP
+.BR libkeccak_sha3sum_fd ()
+does not validate the tuning of the algorithm.
+.SH EXAMPLE
+This example calculates the SHA3-256 hash of the input
+from stdin, and prints the hash, in hexadecimal form, to stdout.
+.LP
+.nf
+struct libkeccak_state state;
+if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0)
+	goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_destroy(&state);
+.fi
+.SH SEE ALSO
+.BR libkeccak_behex_lower (3),
+.BR libkeccak_behex_upper (3),
+.BR libkeccak_generalised_sum_fd (3),
+.BR libkeccak_keccaksum_fd (3),
+.BR libkeccak_rawshakesum_fd (3),
+.BR libkeccak_shakesum_fd (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3)
diff --git a/man3/libkeccak_shakesum_fd.3 b/man3/libkeccak_shakesum_fd.3
new file mode 100644
index 0000000..58b980d
--- /dev/null
+++ b/man3/libkeccak_shakesum_fd.3
@@ -0,0 +1,108 @@
+.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK
+.SH NAME
+libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_shakesum_fd(int \fIfd\fP, struct libkeccak_state *\fIstate\fP, long int \fIsemicapacity\fP, long int \fIoutput\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_shakesum_fd ()
+function calculates a SHAKE hashsum of a file, whose file
+desriptor is specified by
+.I fd
+(and should be at the beginning of the file.) The hash
+algorithm is tuned by the
+.I semicapacity
+and
+.I output
+parameters; they specify the half of the capacity and the
+output size, respectively, in bits.
+.PP
+The hash is stored in binary form to
+.IR hashsum .
+.I hashsum
+should have an allocation size of at least
+.RI ((( output
++ 7) / 8) * sizeof(char)).
+.PP
+.I *state
+should not be initialised.
+.BR libkeccak_shakesum_fd ()
+initialises
+.I *state
+itself. Therefore there would be a memory leak if
+.I *state
+is already initialised.
+.SH RETURN VALUES
+The
+.BR libkeccak_shakesum_fd ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_shakesum_fd ()
+function may fail for any reason, except those resulting in
+.I errno
+being set to
+.BR EINTR ,
+specified for the functions
+.BR read (2),
+.BR malloc (3),
+and
+.BR realloc (3).
+.SH NOTES
+Be aware,
+.BR libkeccak_shakesum_fd ()
+hashes the file until the end has been reached. For pipes
+and sockets and this means until the file has been closed.
+But for character devices, this usually means never.
+Attempting to hash files in /dev is therefore usually a
+bad idea.
+.BR libkeccak_shakesum_fd ()
+does not check for the file length or file type before
+hashing as this could limit what you can do, and make
+the library more complex.
+.PP
+.BR libkeccak_shakesum_fd ()
+does not stop if interrupted
+.RB ( read (2)
+returns
+.BR EINTR .)
+.PP
+.BR libkeccak_shakesum_fd ()
+assumes all information is non-sensitive, and will
+therefore not perform any secure erasure of information.
+.PP
+.BR libkeccak_shakesum_fd ()
+does not validate the tuning of the algorithm.
+.SH EXAMPLE
+This example calculates the SHAKE256(, 512) hash of the input
+from stdin, and prints the hash, in hexadecimal form, to stdout.
+.LP
+.nf
+struct libkeccak_state state;
+if (libkeccak_shakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0)
+	goto fail;
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_destroy(&state);
+.fi
+.SH SEE ALSO
+.BR libkeccak_behex_lower (3),
+.BR libkeccak_behex_upper (3),
+.BR libkeccak_generalised_sum_fd (3),
+.BR libkeccak_keccaksum_fd (3),
+.BR libkeccak_sha3sum_fd (3),
+.BR libkeccak_rawshakesum_fd (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3)
diff --git a/man3/libkeccak_simple_squeeze.3 b/man3/libkeccak_simple_squeeze.3
new file mode 100644
index 0000000..0ddfaea
--- /dev/null
+++ b/man3/libkeccak_simple_squeeze.3
@@ -0,0 +1,34 @@
+.TH LIBKECCAK_SIMPLE_SQUEEZE 3 LIBKECCAK
+.SH NAME
+libkeccak_simple_squeeze - Runs Keccak-f a number of times
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_simple_squeeze(struct libkeccak_state *\fIstate\fP, long int \fItimes\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_simple_squeeze ()
+function runs Keccak-f
+.I times
+times on the hashing
+process described by
+.IR *state .
+.SH RETURN VALUES
+The
+.BR libkeccak_simple_squeeze ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_simple_squeeze ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_digest (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_fast_squeeze (3),
+.BR libkeccak_squeeze (3)
diff --git a/man3/libkeccak_spec_check.3 b/man3/libkeccak_spec_check.3
new file mode 100644
index 0000000..3b5c9df
--- /dev/null
+++ b/man3/libkeccak_spec_check.3
@@ -0,0 +1,92 @@
+.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK
+.SH NAME
+libkeccak_spec_check - Validate hashing parameters
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_spec_check(const struct libkeccak_spec *\fIspec\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_spec_check ()
+function validates the parameters of
+.IR *spec ,
+so that unusable configurations can be detected.
+It is recommended to call this function after calling
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_shake (3),
+or, especially, after settings the parameters
+manually for Keccak hashing.
+.PP
+.nf
+struct libkeccak_spec {
+	long int bitrate;  /* bitrate (in bits) */
+	long int capacity; /* capacity (in bits) */
+	long int output;   /* output size (in bits) */
+};
+.fi
+.SH RETURN VALUES
+The
+.BR libkeccak_spec_check ()
+function returns 0 if the settings are usable. Otherwise
+it will return one of the following constants.
+.PP
+.TP
+.B LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE
+The specified bitrate was non-positive.
+.TP
+.B LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8
+The specified bitrate was not equivalent to 0
+modulus 8, that is, it was not in whole bytes.
+.TP
+.B LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE
+The specified capacity was non-positive.
+.TP
+.B LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8
+The specified capacity was not equivalent to 0
+modulus 8, that is, it was not in whole bytes.
+.TP
+.B LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE
+The specified output size was non-positive.
+.TP
+.B LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE
+The state size, that is the sum of the bitrate
+and the capacity, exceeded the supported limit
+(currently at 1600 bits.)
+.TP
+.B LIBKECCAK_SPEC_ERROR_STATE_MOD_25
+The state size, that is the sum of the bitrate
+and the capacity, in bits, was not equivalent
+to 0 modulus 25. Meaning the state size cannot
+cover all lanes equivalently.
+.TP
+.B LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT
+The word size, that is the state size divided
+by 25, is not a power of 2.
+.TP
+.B LIBKECCAK_SPEC_ERROR_WORD_MOD_8
+The word size, that is the state size divided
+by 25, is not quivalent to 0 modulus 8, that
+is, it is not in whole bytes.
+.PP
+Note that there may be more than one error. Only the first
+detected is returned.
+.SH ERRORS
+The
+.BR libkeccak_spec_check ()
+function cannot fail.
+.fi
+.SH SEE ALSO
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_spec_cshake.3 b/man3/libkeccak_spec_cshake.3
new file mode 100644
index 0000000..dfd8ee9
--- /dev/null
+++ b/man3/libkeccak_spec_cshake.3
@@ -0,0 +1,48 @@
+.TH LIBKECCAK_SPEC_CSHAKE 3 LIBKECCAK
+.SH NAME
+libkeccak_spec_cshake - Configure cSHAKE hashing parameters
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_spec_cshake(struct libkeccak_spec *\fIspec\fP, long int \fIx\fP, long int \fId\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_spec_cshake ()
+function sets
+.I *spec
+to specify the Keccak parameters used for cSHAKE hashing
+with the semicapacity specified, in bits, via the
+.I x
+parameter, and the output size specified, in bits, via the
+.I d
+parameter.
+.SH RETURN VALUES
+The
+.BR libkeccak_spec_cshake ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_spec_cshake ()
+function cannot fail.
+.SH EXAMPLE
+This example configure a
+.B struct libkeccak_spec
+to specify the Keccak parameters used for cSHAKE256(, 512):
+.PP
+.nf
+struct libkeccak_spec spec;
+libkeccak_spec_cshake(&spec, 256, 512);
+.fi
+.SH SEE ALSO
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_spec_rawshake.3 b/man3/libkeccak_spec_rawshake.3
new file mode 100644
index 0000000..5d810b2
--- /dev/null
+++ b/man3/libkeccak_spec_rawshake.3
@@ -0,0 +1,48 @@
+.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK
+.SH NAME
+libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_spec_rawshake(struct libkeccak_spec *\fIspec\fP, long int \fIx\fP, long int \fId\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_spec_rawshake ()
+function sets
+.I *spec
+to specify the Keccak parameters used for RawSHAKE hashing
+with the semicapacity specified, in bits, via the
+.I x
+parameter, and the output size specified, in bits, via the
+.I d
+parameter.
+.SH RETURN VALUES
+The
+.BR libkeccak_spec_rawshake ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_spec_rawshake ()
+function cannot fail.
+.SH EXAMPLE
+This example configure a
+.B struct libkeccak_spec
+to specify the Keccak parameters used for RawSHAKE256(, 512):
+.PP
+.nf
+struct libkeccak_spec spec;
+libkeccak_spec_rawshake(&spec, 256, 512);
+.fi
+.SH SEE ALSO
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_spec_sha3.3 b/man3/libkeccak_spec_sha3.3
new file mode 100644
index 0000000..9cafbf6
--- /dev/null
+++ b/man3/libkeccak_spec_sha3.3
@@ -0,0 +1,47 @@
+.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK
+.SH NAME
+libkeccak_spec_sha3 - Configure SHA-3 hashing parameters
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_spec_sha3(struct libkeccak_spec *\fIspec\fP, long int \fIx\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_spec_sha3 ()
+function sets
+.I *spec
+to specify the Keccak parameters
+used for SHA-3 hashing with the output size specified,
+in bits, via the
+.I x
+parameter.
+.SH RETURN VALUES
+The
+.BR libkeccak_spec_sha3 ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_spec_sha3 ()
+function cannot fail.
+.SH EXAMPLE
+This example configure a
+.B struct libkeccak_spec
+to specify the Keccak parameters used for SHA3-256:
+.PP
+.nf
+struct libkeccak_spec spec;
+libkeccak_spec_sha3(&spec, 256);
+.fi
+.SH SEE ALSO
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_spec_shake.3 b/man3/libkeccak_spec_shake.3
new file mode 100644
index 0000000..c98962f
--- /dev/null
+++ b/man3/libkeccak_spec_shake.3
@@ -0,0 +1,48 @@
+.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK
+.SH NAME
+libkeccak_spec_shake - Configure SHAKE hashing parameters
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_spec_shake(struct libkeccak_spec *\fIspec\fP, long int \fIx\fP, long int \fId\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_spec_shake ()
+function sets
+.I *spec
+to specify the Keccak parameters used for SHAKE hashing
+with the semicapacity specified, in bits, via the
+.I x
+parameter, and the output size specified, in bits, via the
+.I d
+parameter.
+.SH RETURN VALUES
+The
+.BR libkeccak_spec_shake ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_spec_shake ()
+function cannot fail.
+.SH EXAMPLE
+This example configure a
+.B struct libkeccak_spec
+to specify the Keccak parameters used for SHAKE256(, 512):
+.PP
+.nf
+struct libkeccak_spec spec;
+libkeccak_spec_shake(&spec, 256, 512);
+.fi
+.SH SEE ALSO
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_squeeze.3 b/man3/libkeccak_squeeze.3
new file mode 100644
index 0000000..1510bb3
--- /dev/null
+++ b/man3/libkeccak_squeeze.3
@@ -0,0 +1,44 @@
+.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK
+.SH NAME
+libkeccak_squeeze - Runs the squeeze phase
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_squeeze(struct libkeccak_state *\fIstate\fP, void *\fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_squeeze ()
+function runs the Keccak squeeze phase, on the the hash
+process described by
+.IR *state ,
+on stores a new digest, in binary form, in
+.IR hashsum .
+.PP
+.I hashsum
+has the same requirement as for the
+.BR libkeccak_digest (3)
+and
+.BR libkeccak_fast_digest (3)
+functions: it must have an allocation size of at least
+.RI (( state->n
++ 7) / 8) bytes. However, it may not be
+.IR NULL .
+.SH RETURN VALUES
+The
+.BR libkeccak_squeeze ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_squeeze ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_digest (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_simple_squeeze (3),
+.BR libkeccak_fast_squeeze (3)
diff --git a/man3/libkeccak_state_copy.3 b/man3/libkeccak_state_copy.3
new file mode 100644
index 0000000..84f6352
--- /dev/null
+++ b/man3/libkeccak_state_copy.3
@@ -0,0 +1,38 @@
+.TH LIBKECCAK_STATE_COPY 3 LIBKECCAK
+.SH NAME
+libkeccak_state_copy - Copies hash state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_state_copy(struct libkeccak_state *\fIdest\fP, const struct libkeccak_state *\fIsrc\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_copy ()
+function initialises
+.I *dest
+to be identical to
+.IR *src .
+This includes all members of the
+.B struct libkeccak_state
+structure, including the state of the sponge and the
+message chunk buffer.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_copy ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_state_copy ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_state_duplicate (3),
+.BR libkeccak_state_initialise (3)
diff --git a/man3/libkeccak_state_create.3 b/man3/libkeccak_state_create.3
new file mode 100644
index 0000000..d037435
--- /dev/null
+++ b/man3/libkeccak_state_create.3
@@ -0,0 +1,41 @@
+.TH LIBKECCAK_STATE_CREATE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_create - Allocate and initialise hash state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+struct libkeccak_state *libkeccak_state_create(const struct libkeccak_spec *\fIspec\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_create ()
+function allocates a new
+.I struct libkeccak_state *
+with one initialised element, and sets the algorithm
+tuning parameters to those specified by
+.IR *spec .
+.SH RETURN VALUES
+The
+.BR libkeccak_state_create ()
+function returns a newly allocated
+.I struct libkeccak_state *
+(of one initialised element) upon successful completion.
+On error,
+.I NULL
+is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_state_create ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_state_free (3),
+.BR libkeccak_state_fast_free (3)
+.BR libkeccak_state_duplicate (3)
diff --git a/man3/libkeccak_state_destroy.3 b/man3/libkeccak_state_destroy.3
new file mode 100644
index 0000000..34365f1
--- /dev/null
+++ b/man3/libkeccak_state_destroy.3
@@ -0,0 +1,38 @@
+.TH LIBKECCAK_STATE_DESTROY 3 LIBKECCAK
+.SH NAME
+libkeccak_state_destroy - Destroys a hash state with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_destroy(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_destroy ()
+function releases the allocations stored in
+.IR *state ,
+without releasing the allocation of
+.I state
+itself.
+.PP
+The
+.BR libkeccak_state_destroy ()
+function securely erases sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_destroy ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_destroy ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_state_free (3),
+.BR libkeccak_state_fast_destroy (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_state_reset (3),
+.BR libkeccak_state_wipe (3)
diff --git a/man3/libkeccak_state_duplicate.3 b/man3/libkeccak_state_duplicate.3
new file mode 100644
index 0000000..ef0bcba
--- /dev/null
+++ b/man3/libkeccak_state_duplicate.3
@@ -0,0 +1,41 @@
+.TH LIBKECCAK_STATE_DUPLICATE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_duplicate - Allocate a duplicate hash state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+struct libkeccak_state *libkeccak_state_duplicate(const struct libkeccak_state *\fIsrc\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak P.
+.SH DESCRIPTION
+The
+.BR libkeccak_state_duplicate ()
+function allocates a new hash state and initialises it
+to be identical to
+.IR *src .
+This includes all members of the
+.B struct libkeccak_state
+structure, including the state of the sponge and the
+message chunk buffer.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_duplicate ()
+function returns a newly allocated
+.I struct libkeccak_state*
+(of one initialised element) upon successful completion.
+On error,
+.I NULL
+is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_state_duplicate ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_state_copy (3),
+.BR libkeccak_state_create (3)
diff --git a/man3/libkeccak_state_fast_destroy.3 b/man3/libkeccak_state_fast_destroy.3
new file mode 100644
index 0000000..bcfdc42
--- /dev/null
+++ b/man3/libkeccak_state_fast_destroy.3
@@ -0,0 +1,38 @@
+.TH LIBKECCAK_STATE_FAST_DESTROY 3 LIBKECCAK
+.SH NAME
+libkeccak_state_fast_destroy - Destroys a hash state without erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_fast_destroy(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_fast_destroy ()
+function releases the allocations stored in
+.IR *state ,
+without releasing the allocation of
+.I state
+itself.
+.PP
+The
+.BR libkeccak_state_fast_destroy ()
+function does not securely erase sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_fast_destroy ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_fast_destroy ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_state_fast_free (3),
+.BR libkeccak_state_destroy (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_state_reset (3),
+.BR libkeccak_state_wipe (3)
diff --git a/man3/libkeccak_state_fast_free.3 b/man3/libkeccak_state_fast_free.3
new file mode 100644
index 0000000..63eac25
--- /dev/null
+++ b/man3/libkeccak_state_fast_free.3
@@ -0,0 +1,46 @@
+.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_fast_free - Destroys and deallocates a hash state without erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_fast_free(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_fast_free ()
+function releases the allocations stored in
+.IR *state ,
+and also released the allocation of
+.IR state .
+.PP
+The
+.BR libkeccak_state_fast_free ()
+function does not securely erase sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_fast_free ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_fast_free ()
+function cannot fail.
+.SH NOTES
+A double call to
+.BR libkeccak_state_fast_free ()
+will either result in a double free,
+which is must likely to crash the process,
+or free an allocation (that was created
+between the calls) that was not intended
+to be freed, resulting in undefined behaviour.
+.SH SEE ALSO
+.BR libkeccak_state_fast_destroy (3),
+.BR libkeccak_state_free (3),
+.BR libkeccak_state_create (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_state_reset (3),
+.BR libkeccak_state_wipe (3)
diff --git a/man3/libkeccak_state_free.3 b/man3/libkeccak_state_free.3
new file mode 100644
index 0000000..529276e
--- /dev/null
+++ b/man3/libkeccak_state_free.3
@@ -0,0 +1,46 @@
+.TH LIBKECCAK_STATE_FREE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_free - Destroys and deallocates a hash state with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_free(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_free ()
+function releases the allocations stored in
+.IR *state ,
+and also release the allocation of
+.IR state .
+.PP
+The
+.BR libkeccak_state_free ()
+function securely erases sensitive data.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_free ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_free ()
+function cannot fail.
+.SH NOTES
+A double call to
+.BR libkeccak_state_free ()
+will either result in a double free,
+which is must likely to crash the process,
+or free an allocation (that was created
+between the calls) that was not intended
+to be freed, resulting in undefined behaviour.
+.SH SEE ALSO
+.BR libkeccak_state_destroy (3),
+.BR libkeccak_state_fast_free (3),
+.BR libkeccak_state_create (3),
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_state_reset (3),
+.BR libkeccak_state_wipe (3)
diff --git a/man3/libkeccak_state_initialise.3 b/man3/libkeccak_state_initialise.3
new file mode 100644
index 0000000..3c63af7
--- /dev/null
+++ b/man3/libkeccak_state_initialise.3
@@ -0,0 +1,57 @@
+.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_initialise - Initialise hash state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_state_initialise(struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\fIspec\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_initialise ()
+function initialises
+.I *state
+and sets the algorithm tuning parameters to those
+specified by
+.IR *spec .
+.SH RETURN VALUES
+The
+.BR libkeccak_state_initialise ()
+function returns 0 upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_state_initialise ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_state_create (3),
+.BR libkeccak_state_reset (3),
+.BR libkeccak_state_destroy (3),
+.BR libkeccak_state_fast_destroy (3),
+.BR libkeccak_state_copy (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_update (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_digest (3),
+.BR libkeccak_generalised_sum_fd (3),
+.BR libkeccak_keccaksum_fd (3),
+.BR libkeccak_sha3sum_fd (3),
+.BR libkeccak_rawshakesum_fd (3),
+.BR libkeccak_shakesum_fd (3),
+.BR libkeccak_spec_cshake (3),
+.BR libkeccak_spec_sha3 (3),
+.BR libkeccak_spec_shake (3),
+.BR libkeccak_spec_rawshake (3),
+.BR libkeccak_spec_check (3),
+.BR libkeccak_generalised_spec_initialise (3),
+.BR libkeccak_state_marshal (3),
+.BR libkeccak_hmac_initialise (3)
diff --git a/man3/libkeccak_state_marshal.3 b/man3/libkeccak_state_marshal.3
new file mode 100644
index 0000000..0599b5a
--- /dev/null
+++ b/man3/libkeccak_state_marshal.3
@@ -0,0 +1,36 @@
+.TH LIBKECCAK_STATE_MARSHAL 3 LIBKECCAK
+.SH NAME
+libkeccak_state_marshal - Marshals a hash state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+size_t libkeccak_state_marshal(const struct libkeccak_state *\fIstate\fP, void *\fIdata\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_marshal ()
+function marshals
+.I *state
+into the beginning of
+.IR data .
+.PP
+Specific
+.I NULL
+as
+.I data
+to get minimum usable allocation size for
+.SH RETURN VALUES
+The
+.BR libkeccak_state_marshal ()
+returns the number of bytes written to
+.IR data .
+.SH ERRORS
+The
+.BR libkeccak_state_marshal ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_state_unmarshal (3)
diff --git a/man3/libkeccak_state_reset.3 b/man3/libkeccak_state_reset.3
new file mode 100644
index 0000000..e847501
--- /dev/null
+++ b/man3/libkeccak_state_reset.3
@@ -0,0 +1,32 @@
+.TH LIBKECCAK_STATE_RESET 3 LIBKECCAK
+.SH NAME
+libkeccak_state_reset - Reinitialise hash state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_reset(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_reset ()
+function reinitialises
+.IR *state ,
+but keeps the
+tuning, so it can be used to hash another message.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_reset ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_reset ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_state_destroy (3),
+.BR libkeccak_state_fast_destroy (3),
+.BR libkeccak_state_wipe (3)
diff --git a/man3/libkeccak_state_unmarshal.3 b/man3/libkeccak_state_unmarshal.3
new file mode 100644
index 0000000..6198e3a
--- /dev/null
+++ b/man3/libkeccak_state_unmarshal.3
@@ -0,0 +1,47 @@
+.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK
+.SH NAME
+libkeccak_state_unmarshal - Unharshals a hash state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+size_t libkeccak_state_unmarshal(struct libkeccak_state *\fIstate\fP, const void *\fIdata\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_unmarshal ()
+function unmarshals a hash state from the beginning
+of
+.IR data .
+and stores it in
+.IR *state .
+.I state
+may be
+.IR NULL .
+.SH RETURN VALUES
+The
+.BR libkeccak_state_unmarshal ()
+returns the number of bytes reads from
+.I data
+upon successful completion.
+On error, -1 is returned and
+.I errno
+is set to describe the error.
+If
+.I state
+is
+.IR NULL ,
+the number the function will always be
+successful and return a positive value,
+this value is the number of bytes that
+make un the marshalled state.
+.SH ERRORS
+The
+.BR libkeccak_state_unmarshal ()
+function may fail for any specified for the function
+.BR malloc (3).
+.SH SEE ALSO
+.BR libkeccak_state_marshal (3)
diff --git a/man3/libkeccak_state_wipe.3 b/man3/libkeccak_state_wipe.3
new file mode 100644
index 0000000..9028dcc
--- /dev/null
+++ b/man3/libkeccak_state_wipe.3
@@ -0,0 +1,32 @@
+.TH LIBKECCAK_STATE_WIPE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_wipe - Securely erase sensitive data
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_wipe(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_wipe ()
+function securely erases data that may be
+sensitive: the state of the Keccak sponge,
+and the message chunk buffer.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_wipe ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_wipe ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_state_wipe_message (3),
+.BR libkeccak_state_wipe_sponge (3),
+.BR libkeccak_state_fast_destroy (3),
+.BR libkeccak_state_destroy (3),
+.BR libkeccak_state_reset (3)
diff --git a/man3/libkeccak_state_wipe_message.3 b/man3/libkeccak_state_wipe_message.3
new file mode 100644
index 0000000..27c838a
--- /dev/null
+++ b/man3/libkeccak_state_wipe_message.3
@@ -0,0 +1,30 @@
+.TH LIBKECCAK_STATE_WIPE_MESSAGE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_wipe_message - Securely erase the message chunk buffer
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_wipe_message(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_wipe_message ()
+function securely erases the message chunk buffer.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_wipe_message ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_wipe_message ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_state_wipe_sponge (3),
+.BR libkeccak_state_wipe (3),
+.BR libkeccak_state_fast_destroy (3),
+.BR libkeccak_state_destroy (3),
+.BR libkeccak_state_reset (3)
diff --git a/man3/libkeccak_state_wipe_sponge.3 b/man3/libkeccak_state_wipe_sponge.3
new file mode 100644
index 0000000..b36e5b4
--- /dev/null
+++ b/man3/libkeccak_state_wipe_sponge.3
@@ -0,0 +1,30 @@
+.TH LIBKECCAK_STATE_WIPE_SPONGE 3 LIBKECCAK
+.SH NAME
+libkeccak_state_wipe_sponge - Securely erase the Keccak sponge state
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_state_wipe_sponge(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_state_wipe_sponge ()
+function securely erases the state of the Keccak sponge.
+.SH RETURN VALUES
+The
+.BR libkeccak_state_wipe_sponge ()
+function does not return any value.
+.SH ERRORS
+The
+.BR libkeccak_state_wipe_sponge ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_state_wipe_message (3),
+.BR libkeccak_state_wipe (3),
+.BR libkeccak_state_fast_destroy (3),
+.BR libkeccak_state_destroy (3),
+.BR libkeccak_state_reset (3)
diff --git a/man3/libkeccak_unhex.3 b/man3/libkeccak_unhex.3
new file mode 100644
index 0000000..c7dc9bc
--- /dev/null
+++ b/man3/libkeccak_unhex.3
@@ -0,0 +1,48 @@
+.TH LIBKECCAK_UNHEX 3 LIBKECCAK
+.SH NAME
+libkeccak_unhex - Converts a hexadecimal hashsum to binary
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_unhex(void *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_unhex ()
+function
+converts a hexadecimal hashsum, stored in
+.IR hashsum ,
+to binary, and stores the binary representation in
+.IR output .
+.PP
+.I hashsum
+must be terminated by a NUL-character. It may be
+in either lowercase or uppercase, or a mixture
+thereof.
+.I output
+will not be terminated.
+.PP
+(\fBstrlen\fP(\fIhashsum\fP) / 2) bytes will be
+written to the beginning of
+.IR Ioutput .
+It should therefore have an allocation of at least
+that number of bytes.
+.SH RETURN VALUES
+The
+.BR libkeccak_unhex ()
+function does return any value.
+.SH ERRORS
+The
+.BR libkeccak_unhex ()
+function cannot fail.
+.SH NOTES
+.I hashsum
+must have an even number of digits
+(characters excluding the terminating NUL-character.)
+.SH SEE ALSO
+.BR libkeccak_behex_lower (3),
+.BR libkeccak_behex_upper (3)
diff --git a/man3/libkeccak_update.3 b/man3/libkeccak_update.3
new file mode 100644
index 0000000..384e492
--- /dev/null
+++ b/man3/libkeccak_update.3
@@ -0,0 +1,100 @@
+.TH LIBKECCAK_UPDATE 3 LIBKECCAK
+.SH NAME
+libkeccak_update - Partially hash a message with erasure
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+int libkeccak_update(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_update ()
+function continues (or starts) hashing a message.
+The current state of the hashing is stored in
+.IR *state ,
+and will be updated. The message specified by the
+.I msg
+parameter with the byte-size specified by the
+.I msglen
+parameter, will be hashed.
+.PP
+The
+.BR libkeccak_update ()
+function may reallocate the state's message chunk buffer.
+When doing so, it attempts to do so as securely as possible,
+rather than as fast as possible.
+.SH RETURN VALUES
+The
+.BR libkeccak_update ()
+function returns 0 upon successful completion. On error,
+-1 is returned and
+.I errno
+is set to describe the error.
+.SH ERRORS
+The
+.BR libkeccak_update ()
+function may fail for any reason specified by the function
+.BR malloc (3).
+.SH NOTES
+Neither parameter by be
+.I NULL
+or 0.
+.SH EXAMPLE
+This example calculates the Keccak[b = 1024, c = 576, n = 256]
+hash of the input from stdin, and prints the hash, in hexadecimal
+form, to stdout.
+.PP
+.nf
+struct libkeccak_state state;
+struct libkeccak_spec spec;
+char binhash[256 / 8];
+char hexhash[256 / 8 * 2 + 1];
+char chunk[4 << 10];
+ssize_t len;
+
+spec.bitrate = 1024;
+spec.capacity = 576;
+spec.output = 256;
+if (libkeccak_state_initialise(&state, &spec) < 0)
+	goto fail;
+
+for (;;) {
+	len = read(STDIN_FILENO, chunk, sizeof(chunk));
+
+	if ((len < 0) && (errno == EINTR))
+		continue;
+	if (len < 0)
+		goto fail;
+	if (len == 0)
+		break;
+
+	if (libkeccak_update(&state, chunk, (size_t)len) < 0)
+		goto fail;
+}
+if (libkeccak_digest(&state, NULL, 0, 0, \(dq\(dq, binhash) < 0)
+	goto fail;
+
+libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
+printf(\(dq%s\en\(dq, hexhash);
+libkeccak_state_destroy(&state);
+.fi
+.SH NOTES
+For cSHAKE, the
+.BR libkeccak_cshake_initialise (3),
+must be called, once, immediately after
+state initialisation; before the first
+call to the
+.BR libkeccak_update ()
+function.
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_digest (3)
diff --git a/man3/libkeccak_zerocopy_chunksize.3 b/man3/libkeccak_zerocopy_chunksize.3
new file mode 100644
index 0000000..b507c7f
--- /dev/null
+++ b/man3/libkeccak_zerocopy_chunksize.3
@@ -0,0 +1,40 @@
+.TH LIBKECCAK_ZEROCOPY_CHUNKSIZE 3 LIBKECCAK
+.SH NAME
+libkeccak_zerocopy_chunksize - Get chunk size for zero-copy processing
+.RB ( ADVANCED )
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+size_t libkeccak_zerocopy_chunksize(struct libkeccak_state *\fIstate\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_zerocopy_chunksize ()
+function returns the number of bytes the sponge
+in the
+.I state
+parameter processes per round. Input to the
+.BR libkeccak_zerocopy_update (3)
+function must be an integer multiple of this
+number, and memory allocated for the
+.BR libkeccak_zerocopy_digest (3)
+function must also be a multiple of this
+number (further restrictions apply, see
+.BR libkeccak_zerocopy_digest (3)
+for more details.)
+.SH RETURN VALUES
+The
+.BR libkeccak_zerocopy_chunksize ()
+function returns the number of bytes that
+the sponge processes per processing round.
+.SH ERRORS
+The
+.BR libkeccak_zerocopy_chunksize ()
+function cannot fail.
+.SH SEE ALSO
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_zerocopy_digest (3)
diff --git a/man3/libkeccak_zerocopy_digest.3 b/man3/libkeccak_zerocopy_digest.3
new file mode 100644
index 0000000..6b752fb
--- /dev/null
+++ b/man3/libkeccak_zerocopy_digest.3
@@ -0,0 +1,136 @@
+.TH LIBKECCAK_ZEROCOPY_DIGEST 3 LIBKECCAK
+.SH NAME
+libkeccak_zerocopy_digest - Complete the hashing of a message without copying
+.RB ( ADVANCED )
+.SH SYNOPSIS
+.LP
+.nf
+#include <libkeccak.h>
+
+void libkeccak_zerocopy_digest(struct libkeccak_state *\fIstate\fP, void *\fImsg\fP, size_t \fImsglen\fP,
+                               size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP);
+.fi
+.P
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_zerocopy_digest ()
+function absorbs the last part of (or all of) a message,
+and returns the hash of the entire message. The last part
+of the message is specified by the
+.I msg
+parameter, and its byte-size is specified by the
+.I msglen
+parameter. If all of the message has already be processed
+by calls to the
+.BR libkeccak_zerocopy_update (3)
+function (with the same pointer on
+.IR state ,)
+.I msg
+and
+.I msglen
+should be set to
+.I NULL
+and 0, respectively.
+.PP
+If the message is not comprised a whole number of bytes,
+the number of bits, modulus 8, in the message should be
+specified in the
+.I bits
+parameter.
+.I msglen
+must only count the number of whole bytes, that is, the
+floor of the number of bits in the message divided by 8.
+.PP
+.I suffix
+should be a NUL-terminated string of ASCII '1':s and '0':s,
+representing the bits that should be appended to the
+message. If this string is empty,
+.I NULL
+may be used instead. This is used to select hash algorithm.
+For pure Keccak,
+.I NULL
+or \(dq\(dq is used. For the other algorithms the constants
+.B LIBKECCAK_SHA3_SUFFIX
+(for SHA-3),
+.B LIBKECCAK_RAWSHAKE_SUFFIX
+(for RawSHAKE), and
+.B LIBKECCAK_SHAKE_SUFFIX
+(for SHAKE), or the return of the
+.BR libkeccak_cshake_suffix (3)
+function (for cSHAKE), are used.
+.PP
+The hash of the message will be stored to
+.IR hashsum ,
+unless
+.IR hashsum
+is
+.IR NULL
+(which increases the performance of the call.) A total of
+.RI (( state->n
++ 7) / 8) bytes will be written to the beginning of
+.IR hashsum .
+Therefore,
+.I hashsum
+needs at least an allocation size of that number of bytes.
+.PP
+.BR libkeccak_zerocopy_digest ()
+will write at and beyond
+.IR &msg[msglen] .
+The caller must make sure that enough memory is allocated
+for the
+.I suffix
+as well as padding of at least 2 bits, for
+.IR msg .
+The sum of
+.IR msglen ,
+the bits specified in
+.IR suffix ,
+and the padded, shall, in bytes, be an integer multiple of
+the bitrate divided by eight, which is returned by the
+.BR libkeccak_zerocopy_chunksize (3)
+function.
+.SH RETURN VALUES
+The
+.BR libkeccak_zerocopy_digest ()
+function does not return a value.
+.SH ERRORS
+The
+.BR libkeccak_zerocopy_digest ()
+function cannot fail.
+.SH NOTES
+Calling the
+.BR libkeccak_zerocopy_digest (3)
+function after the
+.BR libkeccak_update (3)
+or
+.BR libkeccak_fast_update (3)
+functions, with the same
+.I state
+argument, may cause the message to be misread.
+.SH NOTES
+For cSHAKE, the
+.BR libkeccak_cshake_initialise (3),
+must be called, once, immediately after
+state initialisation; before the first
+call to any of the
+.BR libkeccak_fast_update (),
+.BR libkeccak_zerocopy_update (),
+.BR libkeccak_update (),
+and
+.BR libkeccak_zerocopy_digest ()
+functions.
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_zerocopy_chunksize (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_update (3),
+.BR libkeccak_cshake_suffix (3),
+.BR libkeccak_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_simple_squeeze (3),
+.BR libkeccak_fast_squeeze (3),
+.BR libkeccak_squeeze (3)
diff --git a/man3/libkeccak_zerocopy_update.3 b/man3/libkeccak_zerocopy_update.3
new file mode 100644
index 0000000..b4086a0
--- /dev/null
+++ b/man3/libkeccak_zerocopy_update.3
@@ -0,0 +1,89 @@
+.TH LIBKECCAK_ZEROCOPY_UPDATE 3 LIBKECCAK
+.SH NAME
+libkeccak_zerocopy_update - Partially hash a message without copying
+.RB ( ADVANCED )
+.SH SYNOPSIS
+.nf
+#include <libkeccak.h>
+
+void libkeccak_zerocopy_update(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP);
+.fi
+.PP
+Link with
+.IR -lkeccak .
+.SH DESCRIPTION
+The
+.BR libkeccak_zerocopy_update ()
+function continues (or starts) hashing a message.
+The current state of the hashing is stored in
+.IR *state ,
+and will be updated. The message specified by the
+.I msg
+parameter with the byte-size specified by the
+.I msglen
+parameter, will be hashed.
+.PP
+As a restriction specific to the
+.BR libkeccak_zerocopy_update ()
+function, the
+.I msglen
+argument must be an integer multiple of the bitrate
+divided by eight. This is returned by the
+.BR libkeccak_zerocopy_chunksize (3)
+function. The
+.BR libkeccak_update (3)
+or
+.BR libkeccak_fast_update (3)
+functions can be used to avoid this restriction,
+but these, unlike the
+.BR libkeccak_zerocopy_update ()
+function, will copy the message and move around
+copied data.
+.SH RETURN VALUES
+The
+.BR libkeccak_zerocopy_update ()
+function does not return a value.
+.SH ERRORS
+The
+.BR libkeccak_zerocopy_update ()
+function cannot fail.
+.SH NOTES
+Neither parameter by be
+.I NULL
+or 0.
+.PP
+It is safe call the
+.BR libkeccak_zerocopy_update ()
+function before the
+.BR libkeccak_update (3),
+.BR libkeccak_fast_update (3)
+.BR libkeccak_digest (3)
+and
+.BR libkeccak_fast_digest (3)
+functions with the same
+.I state
+argument. However, calling the
+.BR libkeccak_zerocopy_update ()
+function after the
+.BR libkeccak_update (3)
+or
+.BR libkeccak_fast_update (3)
+functions may cause the message
+to be misread.
+.SH NOTES
+For cSHAKE, the
+.BR libkeccak_cshake_initialise (3),
+must be called, once, immediately after
+state initialisation; before the first
+call to the
+.BR libkeccak_zerocopy_update ()
+function.
+.SH SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_cshake_initialise (3),
+.BR libkeccak_zerocopy_chunksize (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_update (3),
+.BR libkeccak_fast_digest (3),
+.BR libkeccak_zerocopy_digest (3),
+.BR libkeccak_digest (3)