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.
* Hexadecimal hashes::                        Converting between binary and hexadecimal.
* Hashing files::                             Functions used to hash entire files.
* Message authentication::                    Functions used for message authentication codes.

* 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



@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 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} @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 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} @w{@code{char}:s}.
@end table



@node Hexadecimal hashes
@chapter Hexadecimal hashes

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

libkeccak provides functions for calculating
hashes of files directly, from a file descriptor.

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
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
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
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
This function is used for SHAKE, it is
otherwise identical to @code{libkeccak_rawshakesum_fd}.
@end table



@node Message authentication
@chapter Message authentication

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.

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
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
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
Resets the sponge and the sets the key, by
calling @code{libkeccak_hmac_set_key}. IT
has three paramters: 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
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

TODO add indices
TODO examples