path: root/doc/info/libkeccak.texinfo

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

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version@tie{}1.3
or any later version published by the Free Software Foundation; with the
Invariant Sections being the ``GNU Affero General Public License'', the
``GNU Free Documentation License'', with no Front-Cover Texts, and with
no Back-Cover Texts. A copy of the license is included in the section
entitled ``GNU Free Documentation License''.
@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.

* GNU Affero General Public License::         Copying and sharing libkeccak.
* GNU Free Documentation License::            Copying and sharing this manual.

* Concept index::                             Index of concepts.
* Data type index::                           Index of data types.
* Function index::                            Index of functions.
@end menu
@c TODO @detailmenu (`C-c C-u m`)



@node Overview
@chapter Overview

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.

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 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.
libkeccak must compelling feature however is that it is
licensed under the strongest free software license:
GNU Affero General Public License version@tie{}3
(see @ref{GNU Affero General Public License},) which
gives the user the four essential freedoms:
@itemize @bullet{}
@item
The freedom to run the program as you wish, for any purpose (freedom 0).
@item
The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1).
@item
The freedom to redistribute copies so you can help your neighbor (freedom 2).
@item
The freedom to distribute copies of your modified versions to others (freedom 3).
@end itemize

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



@node Linking
@chapter Linking

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.

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

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.

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
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
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
Identical to @code{libkeccak_spec_rawshake}. Intended for SHAKE
rather than RawSHAKE.
@end table

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

@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

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

By feeding a pointer to a @code{libkeccak_generalised_spec_t},
to the function @code{ibkeccak_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 neccessary for using the specifications. When doing
so, automatic values will be given a proper value.

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

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}).

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}.

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.

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.

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
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
Identical to @code{libkeccak_state_fast_destroy}, except
it also frees the allocation of the state.

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

libkeccak also has two functions for copying a state:
@table @code
@item 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
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

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
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
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
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
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

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 @w{@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 @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
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

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl-1.3.texinfo

@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