diff options
| -rw-r--r-- | doc/info/libkeccak.texinfo | 150 |
1 files changed, 150 insertions, 0 deletions
diff --git a/doc/info/libkeccak.texinfo b/doc/info/libkeccak.texinfo index 632032f..b3516b3 100644 --- a/doc/info/libkeccak.texinfo +++ b/doc/info/libkeccak.texinfo @@ -69,6 +69,7 @@ with support for bit-oriented data. @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. @@ -133,6 +134,9 @@ The freedom to redistribute copies so you can help your neighbor (freedom 2). 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 @@ -155,6 +159,152 @@ To make libkeccak's API available, include the header file +@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{<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 + +@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{<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 GNU Affero General Public License @appendix GNU Affero General Public License @include agpl-3.0.texinfo |