\input texinfo   @c -*-texinfo-*-
@c %**start of header
@documentencoding UTF-8
@include macros.texinfo
@copying
@c --------------------------------------------------------------------------------
Copyright @copyright{} 2015, 2017  @w{Mattias Andrée @e{maandree@@kth.se}}

@quotation
Permission to use, copy, modify, and/or distribute this document for any purpose
with or without fee is hereby granted, provided that the above copyright notice
and this permission notice appear in all copies.
@end quotation
@c --------------------------------------------------------------------------------
@end copying


@setfilename libkeccak.info
@settitle libkeccak -- Library for the Keccak-family hash functions
@documentlanguage en_GB
@finalout
@frenchspacing on
@afourpaper

@c @paragraphindent asis
@c @firstparagraphindent none
@c @exampleindent asis

@dircategory Libraries
@direntry
* libkeccak: (libkeccak).       Library for the Keccak-family hash functions.
@end direntry

@documentdescription
Developer reference manual for libkeccak, a library
for hashing with Keccak, SHA-3 RawSHAKE and SHAKE,
with support for bit-oriented data.
@end documentdescription
@c %**end of header



@ifnottex
@node Top
@top libkeccak -- Library for the Keccak-family hash functions
@insertcopying
@end ifnottex

@titlepage
@title libkeccak
@subtitle Library for the Keccak-family hash functions

@author by Mattias Andrée (maandree)

@page
@center `Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! …'
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Overview::                                  Brief overview of libkeccak.
* 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.
* Hexadecimal hashes::                        Converting between binary and hexadecimal.
* Hashing files::                             Functions used to hash entire files.
* Message authentication::                    Functions used for message authentication codes.
* Examples::                                  Examples of how to use libkeccak.

* Concept index::                             Index of concepts.
* Data type index::                           Index of data types.
* Function index::                            Index of functions.
@end menu



@node Overview
@chapter Overview

@cpindex Orientation
libkeccak is a free software bit-oriented implementation
of the cryptographic hash function Keccak and its subsets
SHA-3 (Secure Hash Algorithm@tie{}3), RawSHAKE and SHAKE.

Being bit-oriented means that it supports messages of length
consisting of a non-whole number of bytes.

@cpindex Uses
Keccak is a generic and tunable cryptographic hash function
that can be used for all customary tasks that required a
cryptographic hash function:
@itemize @bullet{}
@item
Password verification@footnote{Using additional squeezes, but not using iterated hashing.}
@item
Proof-of-work
@item
File and data identification
@item
Data integrity
@item
Pseudorandom number generation@footnote{Although not too random, since entropi is not utilised.}
@item
Key derivation
@end itemize

libkeccak support secure erasure of sensitive data,
marshalling of hashing state, and indefinite output length.
It also has builting functions for hashing files and
wrapping the hash functions with HMAC@footnote{Although
doing so is unnecessary because the key can securely be
prepended to the message when using Keccak to produce
a message authentication code.}. This library implements
the Keccak algorithm using a lanewise implementation.

@cpindex Limitations
This implementation is limited to state sizes up to,
and including, 1600 bits.



@node Linking
@chapter Linking

@cpindex Compiling
libkeccak's API is C standard library independent. This means
that libkeccak does not need to be compiled with the same
C standard library as software using it. However, the header
files contain @code{__attributes__}:s for GCC, if these are
incompatible with your compiler, your should temporarily define
a macro named @code{__attributes__} to remove all attributes.

@cpindex @command{pkg-config}
@cpindex Linking
Because of libkeccak's simplicity it does not have a pkg-config
file. Instead, you only need to specify the flag @code{-lkeccak}
when linking your binaries. No flags are required during compilation
(of object files.)

To make libkeccak's API available, include the header file
@file{<libkeccak.h>} in your source files.



@node Selecting hash function
@chapter Selecting hash function

@cpindex Parameters
@cpindex Tuning
Keccak-based hash functions have three parameters:
@itemize @bullet{}
@item
the bitrate,
@item
the capacity, and
@item
the output size.
@end itemize
@noindent
Selecting these is the first step when using the library.

@tpindex libkeccak_spec_t
@tpindex struct libkeccak_spec
The structure @code{libkeccak_spec_t} (@code{struct libkeccak_spec}),
is to specify these parameters. For the less tunable functions
SHA-3, RawSHAKE and SHAKE, these values can be set with the functions
@table @code
@item libkeccak_spec_sha3
@fnindex libkeccak_spec_sha3
@cpindex SHA-3
@cpindex Secure Hash Algorithm 3
Sets the parameters for SHA-3. It has two parameters:
@itemize @bullet{}
@item
Pointer to the @code{libkeccak_spec_t} where the settings shall be stored.
@item
The output size, that is the value appended to the name.
@end itemize

@item libkeccak_spec_rawshake
@fnindex libkeccak_spec_rawshake
@cpindex RawSHAKE
Sets the parameters for RawSHAKE (or SHAKE). It has three parameters:
@itemize @bullet{}
@item
Pointer to the @code{libkeccak_spec_t} where the settings shall be stored.
@item
The semicapacity, that is the value appended to the name.
@item
The output size.
@end itemize

@item libkeccak_spec_shake
@fnindex libkeccak_spec_shake
@cpindex SHAKE
Identical to @code{libkeccak_spec_rawshake}. Intended for SHAKE
rather than RawSHAKE.
@end table

@fnindex libkeccak_spec_check
@cpindex Keccak
For Keccak, these values shall be selected individually by hand.
Once the values have been selected, they can be checked for errors
with the function @code{libkeccak_spec_check}. It takes a pointer
to the specifications as its only parameters and returns zero if
there are no errors. If however there are errors, one of the values,
with somewhat self-explanatory names,@footnote{Their meaning is
documented in the header file @file{<libkeccak/spec.h>}.} will
be returned:
@itemize @bullet{}
@item
@code{LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE}
@item
@code{LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8}
@item
@code{LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE}
@item
@code{LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8}
@item
@code{LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE}
@item
@code{LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE}
@item
@code{LIBKECCAK_SPEC_ERROR_STATE_MOD_25}
@item
@code{LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT}
@item
@code{LIBKECCAK_SPEC_ERROR_WORD_MOD_8}
@end itemize

@tpindex libkeccak_spec_t
@tpindex struct libkeccak_spec
@code{libkeccak_spec_t}'s members are:
@table @code
@item bitrate
The bitrate, in bits.
@item capacity
The capacity, in bits.
@item output
The output size, in bits.
@end table

@tpindex libkeccak_generalised_spec_t
@tpindex struct libkeccak_generalised_spec
It is also possible to select some but not all of the parameters.
For this, the structure @code{libkeccak_generalised_spec_t}
(@code{struct libkeccak_generalised_spec}) is used. It extends
@code{libkeccak_spec_t} with two additional parameters
@table @code
@item state_size
The state size, in bits.
@item word_size
The word size, in bits.
@end table

@fnindex libkeccak_generalised_spec_initialise
By feeding a pointer to a @code{libkeccak_generalised_spec_t},
to the function @code{libkeccak_generalised_spec_initialise},
all its members are set to @code{LIBKECCAK_GENERALISED_SPEC_AUTOMATIC},
a sentinel value that specifies that the parameter shall be
set automatically, to its default that depends on the other
parameters.

Once the members of a @code{libkeccak_generalised_spec_t} has
been set, it can be converted to a @code{libkeccak_spec_t},
which is necessary for using the specifications. When doing
so, automatic values will be given a proper value.

@fnindex libkeccak_degeneralise_spec
To do this, the function @code{libkeccak_degeneralise_spec}
is used. It takes two parameters:
@itemize @bullet{}
@item
Input pointer to the @code{libkeccak_generalised_spec_t}.
@item
Output pointer to a @code{libkeccak_spec_t}.
@end itemize
@noindent
On success, zero is returned, otherwise one of the values, with
somewhat self-explanatory names,@footnote{Their meaning is documented
in the header file @file{<libkeccak/generalised-spec.h>}.} will be
returned:
@itemize @bullet{}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE}
@end itemize



@node State of the hashing
@chapter State of the hashing

@tpindex libkeccak_state_t
@tpindex struct libkeccak_state
@cpindex Hashing
@cpindex State
Hashing of a message is done by feeding segments of the
message to functions until all of the message has been
processed, and than the users may repeat the last phase
any number of times. Because functions are called multiple
times, the state of the process need to be stored in
a state structure. The structure used in libkeccak to
keep track of the state is called @code{libkeccak_state_t}
(@code{struct libkeccak_state}).

@fnindex libkeccak_state_initialise
@cpindex Initialise
Before you can use the functions for hashing a message,
you must allocate a state and initialise it.
To initialise a state, use the function
@code{libkeccak_state_initialise}. Its first argument
should be a pointer to the state variable, that is,
a @code{libkeccak_state_t*}. The second argument should
be a pointer to the specifications, that is, a
@code{const libkeccak_spec_t*}, see @ref{Selecting hash function}.
@code{libkeccak_state_initialise} till return zero
upon successful completion, and otherwise set
@code{errno} to describe the error and return @code{-1}.

@fnindex libkeccak_state_destroy
@fnindex libkeccak_state_fast_destroy
@fnindex libkeccak_state_wipe
@fnindex libkeccak_state_wipe_sponge
@fnindex libkeccak_state_wipe_message
@cpindex Cleanup
Once done with a state structure, you should release
allocated resources that are stored in the structure.
This can be done either by calling the function
@code{libkeccak_state_destroy} or by calling the function
@code{libkeccak_state_fast_destroy}. These two functions
are almost identical, both takes a pointer to the
state as its only parameter, and neither return a value.
However, @code{libkeccak_state_fast_destroy} will only
release allocations used by the state; @code{libkeccak_state_destroy}
will also securely release all sensitive information
in the state, by calling the function @code{libkeccak_state_wipe}:
the state of the sponge, by calling the function
@code{libkeccak_state_wipe_sponge}, and the message
buffer, by calling the function @code{libkeccak_state_wipe_message}.
@code{libkeccak_state_wipe}, @code{libkeccak_state_wipe_sponge}
and @code{libkeccak_state_wipe_message} takes a
pointer to the state as their only parameter, and
none of them have a return value.

@fnindex libkeccak_state_reset
@cpindex Reuse
An alternative to destroying a state, you can reset
it if you want to reuse it to hash another message
using the same hashing function specifications.
This is done by calling @code{libkeccak_state_reset}
instead of @code{libkeccak_state_fast_destroy}.
It takes a pointer to the state as its only parameter
and does not return a value.

@cpindex Initialise
@cpindex Cleanup
@cpindex Allocation
If you want to use dynamic instead of static allocation
for the state, instead of calling @code{malloc} and
@code{free} yourself, libkeccak offers functions that
does this for you:
@table @code
@item libkeccak_state_create
@fnindex libkeccak_state_create
@fnindex libkeccak_state_initialise
Identical to @code{libkeccak_state_initialise}, except
it does have the first parameter, but it has the second
parameter (the specifications). It returns a pointer
to the allocate state upon successful completion, and
returns @code{NULL} on error, in which case, @code{errno}
is set to describe the error.

@item libkeccak_state_fast_free
@fnindex libkeccak_state_fast_free
@fnindex libkeccak_state_fast_destroy
Identical to @code{libkeccak_state_fast_destroy}, except
it also frees the allocation of the state.

@item libkeccak_state_free
@fnindex libkeccak_state_free
@fnindex libkeccak_state_destroy
Identical to @code{libkeccak_state_destroy}, except
it also frees the allocation of the state.
@end table

@cpindex Duplication
@cpindex Allocation
libkeccak also has two functions for copying a state:
@table @code
@item libkeccak_state_copy
@fnindex libkeccak_state_copy
Takes an output pointer to a state as its first parameter,
and a pointer to the state to copy as its second parameter.
The content of the second parameter will be duplicated into
the first parameter. The state passed in the first parameter
must not be initialised, lest you will suffer a memory leak.
The function returns zero upon successful completion, and
on error, sets @code{errno} to describe the error and returns
@code{-1}.

@item libkeccak_state_duplicate
@fnindex libkeccak_state_duplicate
Identical to @code{libkeccak_state_copy}, except it only
has one parameter, a pointer to the state to copy, and
returns a pointer to a state it has allocated and copied
the state to. On error, @code{errno} is set to describe the
error and @code{NULL} is returned.
@end table

@cpindex Marshal
@cpindex Serialisation
@cpindex Unmarshal
@cpindex Deserialisation
The library also offers functions for marshalling a state,
which can be useful when implementing programs that can
reexecuted into updated version of itself.
@table @code
@item libkeccak_state_marshal_size
@fnindex libkeccak_state_marshal_size
Takes a pointer to a state to marshal as its only parameter,
and returns the number of bytes required to marshal it.

@item libkeccak_state_marshal
@fnindex libkeccak_state_marshal
Takes a pointer to a state to marshal as its first parameter,
and the buffer, to where the state shall be marshalled, as
its second parameter. The function will marshal the state
into the buffer and return the number of bytes written,
which will be the same as @code{libkeccak_state_marshal_size}
returns for the state.

@item libkeccak_state_unmarshal
@fnindex libkeccak_state_unmarshal
Takes an output pointer for the unmarshalled state as its
first parameter, and the buffer where the state is marshalled
as its second parameter. The function will unmarshal the
state from the buffer and store it into the pointer passed
to the first parameter. The function will then return the
number of read bytes, which will be the same as
@code{libkeccak_state_marshal_size} and @code{libkeccak_state_marshal}
returned for the state when it was marshalled, as what they
will return if called again with the unmarshalled function.
On error, @code{errno} is set to describe the error and zero
is returned.

@item libkeccak_state_unmarshal_skip
@fnindex libkeccak_state_unmarshal_skip
Figures out how many bytes the marshalled state uses,
so that the buffers pointer can be incremented with
this value to skip pass the marshalled state.
@end table



@node Hashing messages
@chapter Hashing messages

@fnindex libkeccak_update
@fnindex libkeccak_digest
@fnindex libkeccak_fast_update
@fnindex libkeccak_fast_digest
@cpindex Hashing
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
@fnindex libkeccak_update
@fnindex libkeccak_fast_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 function 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
@fnindex libkeccak_digest
@fnindex libkeccak_fast_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 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"}
@cpindex SHA-3
@cpindex Secure Hash Algorithm 3
For SHA-3.
@item @code{LIBKECCAK_RAWSHAKE_SUFFIX} or @code{"11"}
@cpindex RawSHAKE
For RawSHAKE.
@item @code{LIBKECCAK_SHAKE_SUFFIX} or @code{"1111"}
@cpindex SHAKE
For SHAKE.
@item @code{NULL} or @code{""}
@cpindex Keccak
For Keccak.
@end table
@item
@cpindex Output size
@cpindex Hash size
@cpindex Size, hash
Output buffer for the hash, in binary. Should be
allocated to fit @code{(state.n + 7) / 8} @w{@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 function 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

@cpindex Key derivation
@cpindex Pseudorandom number generation
@cpindex Random number generation
@cpindex Output, extended
@cpindex Extended output
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
@fnindex libkeccak_simple_squeeze
Perform a number of additional rounds of @w{@sc{Keccak}--@i{f}}.
The number of rounds is specified in the second parameter.
@item libkeccak_fast_squeeze
@fnindex libkeccak_fast_squeeze
Perform a number of additional rounds of @w{@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
@fnindex 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} @w{@code{char}:s}.
@end table



@node Hexadecimal hashes
@chapter Hexadecimal hashes

@fnindex libkeccak_digest
@fnindex libkeccak_fast_digest
@fnindex libkeccak_squeeze
@cpindex Conversion
@cpindex Binary hash
@cpindex Hexadecimal hash
@cpindex Presentation, hash
@cpindex Hash, presentation
The functions that return hashes: @code{libkeccak_digest},
@code{libkeccak_fast_digest} and @code{libkeccak_squeeze},
store the hashes in binary format. However, it must often
preferred to have hashes in hexadecimal, so that they are
human-readable. This library hash two functions for
converting from binary to hexadecimal, and one function
for converting from hexadecimal to binary. Neither of
these functions have a return value.
@table @code
@item libkeccak_behex_lower
@itemx libkeccak_behex_upper
@fnindex libkeccak_behex_lower
@fnindex libkeccak_behex_upper
Convert from binary to hexadecimal. @code{libkeccak_behex_lower}
converts to lowercase hexadecimal, and @code{libkeccak_behex_upper}
converts to uppercase hexadecimal. Their first parameter
is the output buffer for the hexadecimal representation,
which will be NUL-terminated, it should be allocated to
fit @code{2 * n + 1} @w{@code{char}:s}, where @code{n} is
the length of the input hash. The second parameter is
the input hash, in binary. The third, and final, parameter
is the length of the input bash.

@item libkeccak_unhex
@fnindex libkeccak_unhex
Convert from hexadecimal to binary. Both uppercase and
lowercase, as well as mixed case, is supported as input.
The first parameter is the output buffer for the binary
representation, it should be allocated to fit
@code{strlen(hashsum) / 2} @w{@code{char}:s}, where
@code{hashsum} is the hash in hexadecimal, the input;
this is the number of bytes that will be stored in
the output. The second, and final, parameter is the
hash in hexadecimal, with must be NUL-terminated,
and have an even length.
@end table



@node Hashing files
@chapter Hashing files

@cpindex Files
@cpindex Hash files
libkeccak provides functions for calculating
hashes of files directly, from a file descriptor.

@fnindex libkeccak_generalised_sum_fd
The generalised function is named
@code{libkeccak_generalised_sum_fd}. It has
five parameters:
@itemize @bullet{}
@item
The file descriptor.
@item
A pointer to a state variable. Must not be
initalised, lest you will suffer a memory leak.
@item
The specifications for the hashing functions.
@item
The message suffix.
@item
The output buffer for the binary hash.
It must have an allocation size of at least
@code{(spec->output / 8) * sizeof(char)},
where @code{spec} is the third argument, or
be @code{NULL}.
@end itemize
@code{libkeccak_generalised_sum_fd} returns
zero upon successful completion. On error,
@code{errno} is set to describe the error,
and @code{-1} is returned.

There are also algorithm specific functions.
@table @code
@item libkeccak_keccaksum_fd
@fnindex libkeccak_keccaksum_fd
This function is used for Keccak without message
suffix. It is identical to @code{libkeccak_generalised_sum_fd}
sans the fourth parameter (the message suffix.)

@item libkeccak_sha3sum_fd
@fnindex libkeccak_sha3sum_fd
This function is used for SHA-3. It is similar
to @code{libkeccak_generalised_sum_fd}, however
it does not have the fourth parameter, and the
third parameter is simple the the output size.
The output buffer must have and allocation size
of at least @code{(output / 8) * sizeof(char)},
where @code{output} is the third parameter, or
be @code{NULL}.

@item libkeccak_rawshakesum_fd
@fnindex libkeccak_rawshakesum_fd
This function is used for RawSHAKE, it is
otherwise identical to @code{libkeccak_sha3sum_fd},
except it as a parameter for the semicapacity
before the output size, that is to say, as its
third parameter.

@item libkeccak_shakesum_fd
@fnindex libkeccak_shakesum_fd
This function is used for SHAKE, it is
otherwise identical to @code{libkeccak_rawshakesum_fd}.
@end table



@node Message authentication
@chapter Message authentication

@cpindex Message authentication code
@cpindex MAC
@cpindex HMAC
@cpindex Keyed-hash message authentication code
libkeccak supports HMAC. Note that secure message
authentication codes can be trivially be created
with Keccak by simple prepending the key to the
message; although it will not be HMAC. This makes
Keccak a good hash function alternative for people
who knows next to nothing about cryptography.

@tpindex libkeccak_hmac_state_t
@tpindex struct libkeccak_hmac_state
To keep track of the hashing state, the structure
@code{libkeccak_hmac_state_t} (@code{struct libkeccak_hmac_state})
is used. It has a number of methods analogous to
those for @code{libkeccak_state_t}:
@table @code
@item libkeccak_hmac_initialise
@fnindex libkeccak_hmac_initialise
Has for parameters: pointer to a @code{libkeccak_hmac_state_t}
to initialise, hashing specifications (@code{const libkeccak_spec_t*}),
binary key, and the length of the key.

@item libkeccak_hmac_create
@fnindex libkeccak_hmac_create
Similar to @code{libkeccak_hmac_initialise}. It does
not have a @code{libkeccak_hmac_state_t*} as an output
parameter, rather it returns one.

@item libkeccak_hmac_reset
@fnindex libkeccak_hmac_reset
Resets the sponge and the sets the key, by
calling @code{libkeccak_hmac_set_key}. It
has three parameters: pointer to the
@code{libkeccak_hmac_state_t}, the binary key,
and the length of the key.
The key will not be set if the second
argument is @code{NULL}.

@item libkeccak_hmac_wipe
@fnindex libkeccak_hmac_wipe
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_destroy
@fnindex libkeccak_hmac_fast_destroy
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_destroy
@fnindex libkeccak_hmac_destroy
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_free
@fnindex libkeccak_hmac_fast_free
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_free
@fnindex libkeccak_hmac_free
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_copy
@fnindex libkeccak_hmac_copy
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_duplicate
@fnindex libkeccak_hmac_duplicate
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_marshal_size
@fnindex libkeccak_hmac_marshal_size
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_marshal
@fnindex libkeccak_hmac_marshal
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_unmarshal
@fnindex libkeccak_hmac_unmarshal
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_unmarshal_skip
@fnindex libkeccak_hmac_unmarshal_skip
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_update
@fnindex libkeccak_hmac_fast_update
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_update
@fnindex libkeccak_hmac_update
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_digest
@fnindex libkeccak_hmac_fast_digest
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_digest
@fnindex libkeccak_hmac_digest
Perfectly analogous to the @code{libkeccak_state_t} counterpart.
@end table

@fnindex libkeccak_hmac_set_key
It also has the method @code{libkeccak_hmac_set_key} which
can be used set the key. This function is identical to
@code{libkeccak_hmac_reset}, except it will not reset the
sponge, and the second argument must not be @code{NULL}.



@node Examples
@chapter Examples
@cpindex Example

@cartouche
@cpindex Configure state
@tpindex libkeccak_spec_t
@tpindex libkeccak_generalised_spec_t
@fnindex libkeccak_generalised_spec_initialise
@fnindex libkeccak_degeneralise_spec
@fnindex libkeccak_spec_check
This examples configure a @code{libkeccak_spec_t} to specify settings for Keccak[c = 512].
@example
int r;
libkeccak_spec_t spec;
libkeccak_generalised_spec_t 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;
@end example
@end cartouche

@cartouche
@cpindex Calculate hash
@cpindex Hash, calculate
@cpindex Configure state
@cpindex Hexadecimal hash
@tpindex libkeccak_state_t
@tpindex libkeccak_spec_t
@fnindex libkeccak_state_initialise
@fnindex libkeccak_update
@fnindex libkeccak_digest
@fnindex libkeccak_behex_lower
@fnindex libkeccak_state_destroy
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.
@example
libkeccak_state_t state;
libkeccak_spec_t 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, "", binhash) < 0)
    goto fail;

libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\n", hexhash);
libkeccak_state_destroy(&state);
@end example
@end cartouche

@cartouche
@cpindex Configure state, RawSHAKE
@cpindex RawSHAKE, configure state
@tpindex libkeccak_spec_t
@fnindex libkeccak_spec_rawshake
This example configure a @code{libkeccak_spec_t} to specify
the Keccak parameters used for RawSHAKE256(, 512).
@example
libkeccak_spec_t spec;
libkeccak_spec_rawshake(&spec, 256, 512);
@end example
@end cartouche

@cartouche
@cpindex Configure state, SHA-3
@cpindex SHA-3, configure state
@tpindex libkeccak_spec_t
@fnindex libkeccak_spec_sha3
This example configure a @code{libkeccak_spec_t} to specify
the Keccak parameters used for SHA3-256.
@example
libkeccak_spec_t spec;
libkeccak_spec_sha3(&spec, 256);
@end example
@end cartouche

@cartouche
@cpindex Configure state, SHAKE
@cpindex SHAKE, configure state
@tpindex libkeccak_spec_t
@fnindex libkeccak_spec_shake
This example configure a @code{libkeccak_spec_t} to specify
the Keccak parameters used for SHAKE256(, 512).
@example
libkeccak_spec_t spec;
libkeccak_spec_shake(&spec, 256, 512);
@end example
@end cartouche

@cartouche
@cpindex Calculate hash, SHA-3, from file
@cpindex Hash, calculate, SHA-3, from file
@cpindex SHA-3, calculate hash, from file
@cpindex File, calculate hash, SHA-3
@fnindex libkeccak_sha3sum_fd
This example calculates the SHA3-256 hash of the input from
stdin, and prints the hash, in hexadecimal form, to stdout.
@example
libkeccak_state_t state;
if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0)
    goto fail;
libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\n", hexhash);
libkeccak_state_destroy(&state);
@end example
@end cartouche

@cartouche
@cpindex Calculate hash, RawSHAKE, from file
@cpindex Hash, calculate, RawSHAKE, from file
@cpindex RawSHAKE, calculate hash, from file
@cpindex File, calculate hash, RawSHAKE
@fnindex libkeccak_rawshakesum_fd
This example calculates the RawSHAKE256(, 512) hash of the input
from stdin, and prints the hash, in hexadecimal form, to stdout.
@example
libkeccak_state_t state;
if (libkeccak_rawshakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0)
    goto fail;
libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\n", hexhash);
libkeccak_state_destroy(&state);
@end example
@end cartouche

@cartouche
@cpindex Calculate hash, SHAKE, from file
@cpindex Hash, calculate, SHAKE, from file
@cpindex SHAKE, calculate hash, from file
@cpindex File, calculate hash, SHAKE
@fnindex libkeccak_shakesum_fd
This example calculates the SHAKE256(, 512) hash of the input
from stdin, and prints the hash, in hexadecimal form, to stdout.
@example
libkeccak_state_t state;
if (libkeccak_shakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0)
    goto fail;
libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\n", hexhash);
libkeccak_state_destroy(&state);
@end example
@end cartouche

@cartouche
@cpindex Calculate hash, Keccak, from file
@cpindex Hash, calculate, Keccak, from file
@cpindex Keccak, calculate hash, from file
@cpindex File, calculate hash, Keccak
@tpindex libkeccak_spec_t
@fnindex libkeccak_keccaksum_fd
@fnindex libkeccak_behex_lower
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.
@example
libkeccak_state_t state;
libkeccak_spec_t 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("%s\n", hexhash);
libkeccak_state_destroy(&state);
@end example
@end cartouche

@cartouche
@cpindex Calculate hash, from file
@cpindex Hash, calculate, from file
@cpindex Calculate hash, from file
@cpindex File, calculate hash
@tpindex libkeccak_spec_t
@fnindex libkeccak_generalised_sum_fd
@fnindex libkeccak_behex_lower
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.
@example
libkeccak_state_t state;
libkeccak_spec_t 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("%s\n", hexhash);
libkeccak_state_destroy(&state);
@end example
@end cartouche



@node Concept index
@unnumbered Concept index
@printindex cp

@node Data type index
@unnumbered Data type index
@printindex tp

@node Function index
@unnumbered Function index
@printindex fn


@bye