From e974f623f88c3f38209117408c6db9cdb9d7c080 Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@kth.se>
Date: Fri, 24 Dec 2021 21:24:00 +0100
Subject: Add man pages for zero-copy functions
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <maandree@kth.se>
---
 libkeccak_zerocopy_digest.3 | 120 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 120 insertions(+)
 create mode 100644 libkeccak_zerocopy_digest.3

(limited to '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)
-- 
cgit v1.2.3-70-g09d2