\input texinfo @c -*-texinfo-*- @c %**start of header @documentencoding UTF-8 @include macros.texinfo @copying @c -------------------------------------------------------------------------------- Copyright @copyright{} 2015 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. * 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 @c TODO @detailmenu (`C-c C-u m`) @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{} 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{}.} 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{}.} 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 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