Add man pages for zero-copy functions

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

13 files changed, 266 insertions, 7 deletions

diff --git a/Makefile b/Makefile
index f7a4503..a6aa425 100644
--- a/Makefile
+++ b/Makefile
@@ -122,7 +122,10 @@ MAN3 =\
 	libkeccak_state_wipe_message.3\
 	libkeccak_state_wipe_sponge.3\
 	libkeccak_unhex.3\
-	libkeccak_update.3
+	libkeccak_update.3\
+	libkeccak_zerocopy_chunksize.3\
+	libkeccak_zerocopy_digest.3\
+	libkeccak_zerocopy_update.3
 
 MAN7 =\
 	libkeccak.7
diff --git a/libkeccak.7 b/libkeccak.7
index 8aba9e7..9ece381 100644
--- a/libkeccak.7
+++ b/libkeccak.7
@@ -30,8 +30,10 @@ Keccak-3200 may be implemented in the future.
 .BR libkeccak_state_marshal (3),
 .BR libkeccak_state_unmarshal (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_simple_squeeze (3),
 .BR libkeccak_fast_squeeze (3),
diff --git a/libkeccak_digest.3 b/libkeccak_digest.3
index 1df8e2e..726c02e 100644
--- a/libkeccak_digest.3
+++ b/libkeccak_digest.3
@@ -22,9 +22,10 @@ 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)
-function or the
-.BR libkeccak_fast_update (3)
+.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
@@ -134,6 +135,7 @@ libkeccak_state_destroy(&state);
 .BR libkeccak_fast_update (3),
 .BR libkeccak_update (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/libkeccak_fast_digest.3 b/libkeccak_fast_digest.3
index 149b023..3c1d28c 100644
--- a/libkeccak_fast_digest.3
+++ b/libkeccak_fast_digest.3
@@ -23,9 +23,10 @@ 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)
-function or the
-.BR libkeccak_fast_update (3)
+.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
@@ -134,8 +135,10 @@ libkeccak_state_fast_destroy(&state);
 .SH SEE ALSO
 .BR libkeccak_state_initialise (3),
 .BR libkeccak_fast_update (3),
+.BR libkeccak_zerocopy_update (3),
 .BR libkeccak_update (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/libkeccak_fast_squeeze.3 b/libkeccak_fast_squeeze.3
index c575eef..5be6cd6 100644
--- a/libkeccak_fast_squeeze.3
+++ b/libkeccak_fast_squeeze.3
@@ -30,5 +30,6 @@ 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/libkeccak_fast_update.3 b/libkeccak_fast_update.3
index f2497be..6231da9 100644
--- a/libkeccak_fast_update.3
+++ b/libkeccak_fast_update.3
@@ -85,6 +85,8 @@ libkeccak_state_fast_destroy(&state);
 .fi
 .SH SEE ALSO
 .BR libkeccak_state_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/libkeccak_simple_squeeze.3 b/libkeccak_simple_squeeze.3
index defa936..0ddfaea 100644
--- a/libkeccak_simple_squeeze.3
+++ b/libkeccak_simple_squeeze.3
@@ -29,5 +29,6 @@ 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/libkeccak_squeeze.3 b/libkeccak_squeeze.3
index 1a595bb..1510bb3 100644
--- a/libkeccak_squeeze.3
+++ b/libkeccak_squeeze.3
@@ -39,5 +39,6 @@ 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/libkeccak_state_initialise.3 b/libkeccak_state_initialise.3
index 84d6ae9..a2ccffd 100644
--- a/libkeccak_state_initialise.3
+++ b/libkeccak_state_initialise.3
@@ -37,8 +37,10 @@ function may fail for any specified for the function
 .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),
diff --git a/libkeccak_update.3 b/libkeccak_update.3
index ea94849..3d295c8 100644
--- a/libkeccak_update.3
+++ b/libkeccak_update.3
@@ -85,5 +85,7 @@ libkeccak_state_destroy(&state);
 .SH SEE ALSO
 .BR libkeccak_state_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/libkeccak_zerocopy_chunksize.3 b/libkeccak_zerocopy_chunksize.3
new file mode 100644
index 0000000..b507c7f
--- /dev/null
+++ b/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/libkeccak_zerocopy_digest.3 b/libkeccak_zerocopy_digest.3
new file mode 100644
index 0000000..2d63df3
--- /dev/null
+++ b/libkeccak_zerocopy_digest.3
@@ -0,0 +1,120 @@
+.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) 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 SEE ALSO
+.BR libkeccak_state_initialise (3),
+.BR libkeccak_zerocopy_chunksize (3),
+.BR libkeccak_fast_update (3),
+.BR libkeccak_zerocopy_update (3),
+.BR libkeccak_update (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/libkeccak_zerocopy_update.3 b/libkeccak_zerocopy_update.3
new file mode 100644
index 0000000..4c3f006
--- /dev/null
+++ b/libkeccak_zerocopy_update.3
@@ -0,0 +1,80 @@
+.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 SEE ALSO
+.BR libkeccak_state_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)