From 4f5ee0a1c1816ebee53973594fd278d4997c8489 Mon Sep 17 00:00:00 2001
From: Mattias Andrée <maandree@operamail.com>
Date: Sun, 20 Sep 2015 12:10:15 +0200
Subject: info: hashing
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Signed-off-by: Mattias Andrée <maandree@operamail.com>
---
 doc/info/libkeccak.texinfo | 90 ++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 90 insertions(+)

(limited to 'doc/info/libkeccak.texinfo')

diff --git a/doc/info/libkeccak.texinfo b/doc/info/libkeccak.texinfo
index c64c4b6..e3a6ad5 100644
--- a/doc/info/libkeccak.texinfo
+++ b/doc/info/libkeccak.texinfo
@@ -71,6 +71,7 @@ with support for bit-oriented data.
 * Linking::                                   How to use libkeccak in your software.
 * Selecting hash function::                   Selecting and tuning the function.
 * State of the hashing::                      The structure used to keep track of the hashing process.
+* Hashing messages::                          Functions used to hash a message.
 
 * GNU Affero General Public License::         Copying and sharing libkeccak.
 * GNU Free Documentation License::            Copying and sharing this manual.
@@ -436,6 +437,95 @@ this value to skip pass the marshalled state.
 
 
 
+@node Hashing messages
+@chapter Hashing messages
+
+Once a state has been initialised, a message can be hashed.
+To hash a message the functions @code{libkeccak_update} and
+@code{libkeccak_digest} are used, or its variants that do
+not securely release sensitive information:
+@code{libkeccak_fast_update} and @code{libkeccak_fast_digest},
+these are otherwise identical to @code{libkeccak_update}
+and @code{libkeccak_fast_update}, respectively.
+@table @code
+@item libkeccak_update
+This function shall be called while you do not know that
+you have reached the end of the message. It has three
+parameters:
+@itemize @bullet{}
+@item
+A pointer to the state. See @ref{State of the hashing}.
+@item
+The beginning of the chunk of the message to process.
+@item
+The number of bytes in the message to process.
+@end itemize
+Note that a part of the message is input, not necessarily
+the entire message. The chunks must be input sequentially.
+The funtion returns zero upon success completion. On error,
+@code{errno} is set to describe the error and @code{-1} is
+returned. The input chunk should not be empty.
+
+@item libkeccak_digest
+This function shall be called either with the last chunk
+of the message, or when all chunks as been input to
+@code{libkeccak_update} or @code{libkeccak_fast_update}.
+The function's first three parameters are the same as
+for @code{libkeccak_update}, however, the chunk may be
+@code{NULL} and then length zero if all chunks have
+been processed by @code{libkeccak_update} or @code{libkeccak_fast_update}.
+However, it also has three additional parameters:
+@itemize @bullet{}
+@item
+The number of bits at the end of the message that
+are not covered by the third argument. This enables
+messages of non-whole byte length.
+@item
+A @code{NUL}-terminated string of ASCII ones and zeroes,
+describing the additional bits to suffix the message;
+or @code{NULL} if none. This is used to select between
+Keccak, SHA-3, RawSHAKE and SHAKE. Use one of the constants:
+@table @asis
+@item @code{LIBKECCAK_SHA3_SUFFIX} or @code{"01"}
+For SHA-3.
+@item @code{LIBKECCAK_RAWSHAKE_SUFFIX} or @code{"11"}
+For RawSHAKE.
+@item @code{LIBKECCAK_SHAKE_SUFFIX} or @code{"1111"}
+For SHAKE.
+@item @code{NULL} or @code{""}
+For Keccak.
+@end table
+@item
+Output buffer for the hash, in binary. Should be
+allocated to fit @code{(state.n + 7) / 8} @code{char}:s,
+where @code{state} is the state variable. Alternatively
+it may be @code{NULL}, in which case the hash is not
+retrieved.
+@end itemize
+The funtion returns zero upon success completion. On error,
+@code{errno} is set to describe the error and @code{-1} is
+returned. The input chunk should not be empty.
+@end table
+
+libkeccak also has three functions for repeating the squeeze
+phase. Neither of these function have a return value, and
+their first parameter is a pointer to the state.
+@table @code
+@item libkeccak_simple_squeeze
+Perform a number of additional rounds of @sc{Keccak}--@i{f}.
+The number of rounds is specified in the second parameter.
+@item libkeccak_fast_squeeze
+Perform a number of additional rounds of @sc{Keccak}--@i{f}.
+The number will be exactly enough to get a number of additional
+digests. The number of digests is specified in the second parameter.
+@item libkeccak_squeeze
+Squeeze out another digest. The hash will be stored in the
+second parameter, which should be allocated to fit
+@code{(state.n + 7) / 8} @code{char}:s.
+@end table
+
+
+
 @node GNU Affero General Public License
 @appendix GNU Affero General Public License
 @include agpl-3.0.texinfo
-- 
cgit v1.2.3-70-g09d2