diff options
Diffstat (limited to 'libkeccak.texinfo')
| -rw-r--r-- | libkeccak.texinfo | 403 |
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 |