General improvements

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 403 insertions, 0 deletions

diff --git a/libkeccak.texinfo b/libkeccak.texinfo
new file mode 100644
index 0000000..7640da9
--- /dev/null
+++ b/libkeccak.texinfo
@@ -0,0 +1,403 @@
+\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