path: root/libkeccak.texinfo

\input texinfo   @c -*-texinfo-*-
@c %**start of header
@documentencoding UTF-8
@iftex
@macro e{a}
(@email{\a\})
@end macro
@end iftex
@ifnottex
@macro e{a}
@email{\a\}
@end macro
@end ifnottex
@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, therefore it
can be beneficial to use GCC, however any C99 compiler will work.

@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