diff options
Diffstat (limited to 'libkeccak.texinfo')
| -rw-r--r-- | libkeccak.texinfo | 403 |
1 files changed, 0 insertions, 403 deletions
diff --git a/libkeccak.texinfo b/libkeccak.texinfo deleted file mode 100644 index 7640da9..0000000 --- a/libkeccak.texinfo +++ /dev/null @@ -1,403 +0,0 @@ -\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 |