diff options
Diffstat (limited to '')
| -rw-r--r-- | doc/info/libkeccak.texinfo | 1069 |
1 files changed, 0 insertions, 1069 deletions
diff --git a/doc/info/libkeccak.texinfo b/doc/info/libkeccak.texinfo deleted file mode 100644 index 68bf147..0000000 --- a/doc/info/libkeccak.texinfo +++ /dev/null @@ -1,1069 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@documentencoding UTF-8 -@include macros.texinfo -@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, if these are -incompatible with your compiler, your should temporarily define -a macro named @code{__attributes__} to remove all attributes. - -@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 -returns @code{NULL} on error, in which case, @code{errno} -is set to describe the error. - -@item libkeccak_state_fast_free -@fnindex libkeccak_state_fast_free -@fnindex libkeccak_state_fast_destroy -Identical to @code{libkeccak_state_fast_destroy}, except -it also frees the allocation of the state. - -@item libkeccak_state_free -@fnindex libkeccak_state_free -@fnindex libkeccak_state_destroy -Identical to @code{libkeccak_state_destroy}, except -it also frees the allocation of the state. -@end table - -@cpindex Duplication -@cpindex Allocation -libkeccak also has two functions for copying a state: -@table @code -@item libkeccak_state_copy -@fnindex libkeccak_state_copy -Takes an output pointer to a state as its first parameter, -and a pointer to the state to copy as its second parameter. -The content of the second parameter will be duplicated into -the first parameter. The state passed in the first parameter -must not be initialised, lest you will suffer a memory leak. -The function returns zero upon successful completion, and -on error, sets @code{errno} to describe the error and returns -@code{-1}. - -@item libkeccak_state_duplicate -@fnindex libkeccak_state_duplicate -Identical to @code{libkeccak_state_copy}, except it only -has one parameter, a pointer to the state to copy, and -returns a pointer to a state it has allocated and copied -the state to. On error, @code{errno} is set to describe the -error and @code{NULL} is returned. -@end table - -@cpindex Marshal -@cpindex Serialisation -@cpindex Unmarshal -@cpindex Deserialisation -The library also offers functions for marshalling a state, -which can be useful when implementing programs that can -reexecuted into updated version of itself. -@table @code -@item libkeccak_state_marshal_size -@fnindex libkeccak_state_marshal_size -Takes a pointer to a state to marshal as its only parameter, -and returns the number of bytes required to marshal it. - -@item libkeccak_state_marshal -@fnindex libkeccak_state_marshal -Takes a pointer to a state to marshal as its first parameter, -and the buffer, to where the state shall be marshalled, as -its second parameter. The function will marshal the state -into the buffer and return the number of bytes written, -which will be the same as @code{libkeccak_state_marshal_size} -returns for the state. - -@item libkeccak_state_unmarshal -@fnindex libkeccak_state_unmarshal -Takes an output pointer for the unmarshalled state as its -first parameter, and the buffer where the state is marshalled -as its second parameter. The function will unmarshal the -state from the buffer and store it into the pointer passed -to the first parameter. The function will then return the -number of read bytes, which will be the same as -@code{libkeccak_state_marshal_size} and @code{libkeccak_state_marshal} -returned for the state when it was marshalled, as what they -will return if called again with the unmarshalled function. -On error, @code{errno} is set to describe the error and zero -is returned. - -@item libkeccak_state_unmarshal_skip -@fnindex libkeccak_state_unmarshal_skip -Figures out how many bytes the marshalled state uses, -so that the buffers pointer can be incremented with -this value to skip pass the marshalled state. -@end table - - - -@node Hashing messages -@chapter Hashing messages - -@fnindex libkeccak_update -@fnindex libkeccak_digest -@fnindex libkeccak_fast_update -@fnindex libkeccak_fast_digest -@cpindex Hashing -Once a state has been initialised, a message can be hashed. -To hash a message the functions @code{libkeccak_update} and -@code{libkeccak_digest} are used, or its variants that do -not securely release sensitive information: -@code{libkeccak_fast_update} and @code{libkeccak_fast_digest}, -these are otherwise identical to @code{libkeccak_update} -and @code{libkeccak_fast_update}, respectively. -@table @code -@item libkeccak_update -@fnindex libkeccak_update -@fnindex libkeccak_fast_update -This function shall be called while you do not know that -you have reached the end of the message. It has three -parameters: -@itemize @bullet{} -@item -A pointer to the state. See @ref{State of the hashing}. -@item -The beginning of the chunk of the message to process. -@item -The number of bytes in the message to process. -@end itemize -Note that a part of the message is input, not necessarily -the entire message. The chunks must be input sequentially. -The function returns zero upon success completion. On error, -@code{errno} is set to describe the error and @code{-1} is -returned. The input chunk should not be empty. - -@item libkeccak_digest -@fnindex libkeccak_digest -@fnindex libkeccak_fast_digest -This function shall be called either with the last chunk -of the message, or when all chunks as been input to -@code{libkeccak_update} or @code{libkeccak_fast_update}. -The function's first three parameters are the same as -for @code{libkeccak_update}, however, the chunk may be -@code{NULL} and then length zero if all chunks have -been processed by @code{libkeccak_update} or @code{libkeccak_fast_update}. -However, it also has three additional parameters: -@itemize @bullet{} -@item -The number of bits at the end of the message that -are not covered by the third argument. This enables -messages of non-whole byte length. -@item -A NUL-terminated string of ASCII ones and zeroes, -describing the additional bits to suffix the message; -or @code{NULL} if none. This is used to select between -Keccak, SHA-3, RawSHAKE and SHAKE. Use one of the constants: -@table @asis -@item @code{LIBKECCAK_SHA3_SUFFIX} or @code{"01"} -@cpindex SHA-3 -@cpindex Secure Hash Algorithm 3 -For SHA-3. -@item @code{LIBKECCAK_RAWSHAKE_SUFFIX} or @code{"11"} -@cpindex RawSHAKE -For RawSHAKE. -@item @code{LIBKECCAK_SHAKE_SUFFIX} or @code{"1111"} -@cpindex SHAKE -For SHAKE. -@item @code{NULL} or @code{""} -@cpindex Keccak -For Keccak. -@end table -@item -@cpindex Output size -@cpindex Hash size -@cpindex Size, hash -Output buffer for the hash, in binary. Should be -allocated to fit @code{(state.n + 7) / 8} @w{@code{char}:s}, -where @code{state} is the state variable. Alternatively -it may be @code{NULL}, in which case the hash is not -retrieved. -@end itemize -The function returns zero upon success completion. On error, -@code{errno} is set to describe the error and @code{-1} is -returned. The input chunk should not be empty. -@end table - -@cpindex Key derivation -@cpindex Pseudorandom number generation -@cpindex Random number generation -@cpindex Output, extended -@cpindex Extended output -libkeccak also has three functions for repeating the squeeze -phase. Neither of these function have a return value, and -their first parameter is a pointer to the state. -@table @code -@item libkeccak_simple_squeeze -@fnindex libkeccak_simple_squeeze -Perform a number of additional rounds of @w{@sc{Keccak}--@i{f}}. -The number of rounds is specified in the second parameter. -@item libkeccak_fast_squeeze -@fnindex libkeccak_fast_squeeze -Perform a number of additional rounds of @w{@sc{Keccak}--@i{f}}. -The number will be exactly enough to get a number of additional -digests. The number of digests is specified in the second parameter. -@item libkeccak_squeeze -@fnindex libkeccak_squeeze -Squeeze out another digest. The hash will be stored in the -second parameter, which should be allocated to fit -@code{(state.n + 7) / 8} @w{@code{char}:s}. -@end table - - - -@node Hexadecimal hashes -@chapter Hexadecimal hashes - -@fnindex libkeccak_digest -@fnindex libkeccak_fast_digest -@fnindex libkeccak_squeeze -@cpindex Conversion -@cpindex Binary hash -@cpindex Hexadecimal hash -@cpindex Presentation, hash -@cpindex Hash, presentation -The functions that return hashes: @code{libkeccak_digest}, -@code{libkeccak_fast_digest} and @code{libkeccak_squeeze}, -store the hashes in binary format. However, it must often -preferred to have hashes in hexadecimal, so that they are -human-readable. This library hash two functions for -converting from binary to hexadecimal, and one function -for converting from hexadecimal to binary. Neither of -these functions have a return value. -@table @code -@item libkeccak_behex_lower -@itemx libkeccak_behex_upper -@fnindex libkeccak_behex_lower -@fnindex libkeccak_behex_upper -Convert from binary to hexadecimal. @code{libkeccak_behex_lower} -converts to lowercase hexadecimal, and @code{libkeccak_behex_upper} -converts to uppercase hexadecimal. Their first parameter -is the output buffer for the hexadecimal representation, -which will be NUL-terminated, it should be allocated to -fit @code{2 * n + 1} @w{@code{char}:s}, where @code{n} is -the length of the input hash. The second parameter is -the input hash, in binary. The third, and final, parameter -is the length of the input bash. - -@item libkeccak_unhex -@fnindex libkeccak_unhex -Convert from hexadecimal to binary. Both uppercase and -lowercase, as well as mixed case, is supported as input. -The first parameter is the output buffer for the binary -representation, it should be allocated to fit -@code{strlen(hashsum) / 2} @w{@code{char}:s}, where -@code{hashsum} is the hash in hexadecimal, the input; -this is the number of bytes that will be stored in -the output. The second, and final, parameter is the -hash in hexadecimal, with must be NUL-terminated, -and have an even length. -@end table - - - -@node Hashing files -@chapter Hashing files - -@cpindex Files -@cpindex Hash files -libkeccak provides functions for calculating -hashes of files directly, from a file descriptor. - -@fnindex libkeccak_generalised_sum_fd -The generalised function is named -@code{libkeccak_generalised_sum_fd}. It has -five parameters: -@itemize @bullet{} -@item -The file descriptor. -@item -A pointer to a state variable. Must not be -initalised, lest you will suffer a memory leak. -@item -The specifications for the hashing functions. -@item -The message suffix. -@item -The output buffer for the binary hash. -It must have an allocation size of at least -@code{(spec->output / 8) * sizeof(char)}, -where @code{spec} is the third argument, or -be @code{NULL}. -@end itemize -@code{libkeccak_generalised_sum_fd} returns -zero upon successful completion. On error, -@code{errno} is set to describe the error, -and @code{-1} is returned. - -There are also algorithm specific functions. -@table @code -@item libkeccak_keccaksum_fd -@fnindex libkeccak_keccaksum_fd -This function is used for Keccak without message -suffix. It is identical to @code{libkeccak_generalised_sum_fd} -sans the fourth parameter (the message suffix.) - -@item libkeccak_sha3sum_fd -@fnindex libkeccak_sha3sum_fd -This function is used for SHA-3. It is similar -to @code{libkeccak_generalised_sum_fd}, however -it does not have the fourth parameter, and the -third parameter is simple the the output size. -The output buffer must have and allocation size -of at least @code{(output / 8) * sizeof(char)}, -where @code{output} is the third parameter, or -be @code{NULL}. - -@item libkeccak_rawshakesum_fd -@fnindex libkeccak_rawshakesum_fd -This function is used for RawSHAKE, it is -otherwise identical to @code{libkeccak_sha3sum_fd}, -except it as a parameter for the semicapacity -before the output size, that is to say, as its -third parameter. - -@item libkeccak_shakesum_fd -@fnindex libkeccak_shakesum_fd -This function is used for SHAKE, it is -otherwise identical to @code{libkeccak_rawshakesum_fd}. -@end table - - - -@node Message authentication -@chapter Message authentication - -@cpindex Message authentication code -@cpindex MAC -@cpindex HMAC -@cpindex Keyed-hash message authentication code -libkeccak supports HMAC. Note that secure message -authentication codes can be trivially be created -with Keccak by simple prepending the key to the -message; although it will not be HMAC. This makes -Keccak a good hash function alternative for people -who knows next to nothing about cryptography. - -@tpindex libkeccak_hmac_state_t -@tpindex struct libkeccak_hmac_state -To keep track of the hashing state, the structure -@code{libkeccak_hmac_state_t} (@code{struct libkeccak_hmac_state}) -is used. It has a number of methods analogous to -those for @code{libkeccak_state_t}: -@table @code -@item libkeccak_hmac_initialise -@fnindex libkeccak_hmac_initialise -Has for parameters: pointer to a @code{libkeccak_hmac_state_t} -to initialise, hashing specifications (@code{const libkeccak_spec_t*}), -binary key, and the length of the key. - -@item libkeccak_hmac_create -@fnindex libkeccak_hmac_create -Similar to @code{libkeccak_hmac_initialise}. It does -not have a @code{libkeccak_hmac_state_t*} as an output -parameter, rather it returns one. - -@item libkeccak_hmac_reset -@fnindex libkeccak_hmac_reset -Resets the sponge and the sets the key, by -calling @code{libkeccak_hmac_set_key}. It -has three parameters: pointer to the -@code{libkeccak_hmac_state_t}, the binary key, -and the length of the key. -The key will not be set if the second -argument is @code{NULL}. - -@item libkeccak_hmac_wipe -@fnindex libkeccak_hmac_wipe -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_destroy -@fnindex libkeccak_hmac_fast_destroy -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_destroy -@fnindex libkeccak_hmac_destroy -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_free -@fnindex libkeccak_hmac_fast_free -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_free -@fnindex libkeccak_hmac_free -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_copy -@fnindex libkeccak_hmac_copy -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_duplicate -@fnindex libkeccak_hmac_duplicate -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_marshal_size -@fnindex libkeccak_hmac_marshal_size -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_marshal -@fnindex libkeccak_hmac_marshal -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_unmarshal -@fnindex libkeccak_hmac_unmarshal -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_unmarshal_skip -@fnindex libkeccak_hmac_unmarshal_skip -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_update -@fnindex libkeccak_hmac_fast_update -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_update -@fnindex libkeccak_hmac_update -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_digest -@fnindex libkeccak_hmac_fast_digest -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_digest -@fnindex libkeccak_hmac_digest -Perfectly analogous to the @code{libkeccak_state_t} counterpart. -@end table - -@fnindex libkeccak_hmac_set_key -It also has the method @code{libkeccak_hmac_set_key} which -can be used set the key. This function is identical to -@code{libkeccak_hmac_reset}, except it will not reset the -sponge, and the second argument must not be @code{NULL}. - - - -@node Examples -@chapter Examples -@cpindex Example - -@cartouche -@cpindex Configure state -@tpindex libkeccak_spec_t -@tpindex libkeccak_generalised_spec_t -@fnindex libkeccak_generalised_spec_initialise -@fnindex libkeccak_degeneralise_spec -@fnindex libkeccak_spec_check -This examples configure a @code{libkeccak_spec_t} to specify settings for Keccak[c = 512]. -@example -int r; -libkeccak_spec_t spec; -libkeccak_generalised_spec_t gspec; -libkeccak_generalised_spec_initialise(&gspec); -gspec.capacity = 512; -if ((r = libkeccak_degeneralise_spec(&gspec, &spec))) - goto fail_degeneralise_spec; -if ((r = libkeccak_spec_check(&spec))); - goto fail_spec_check; -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash -@cpindex Hash, calculate -@cpindex Configure state -@cpindex Hexadecimal hash -@tpindex libkeccak_state_t -@tpindex libkeccak_spec_t -@fnindex libkeccak_state_initialise -@fnindex libkeccak_update -@fnindex libkeccak_digest -@fnindex libkeccak_behex_lower -@fnindex libkeccak_state_destroy -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in -hexadecimal form, to stdout. -@example -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; -char chunk[4 << 10]; -ssize_t len; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; -if (libkeccak_state_initialise(&state, &spec) < 0) - goto fail; - -for (;;) @{ - len = read(STDIN_FILENO, chunk, sizeof(chunk)); - - if ((len < 0) && (errno == EINTR)) - continue; - if (len < 0) - goto fail; - if (len == 0) - break; - - if (libkeccak_update(&state, chunk, (size_t)len) < 0) - goto fail; -@} -if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Configure state, RawSHAKE -@cpindex RawSHAKE, configure state -@tpindex libkeccak_spec_t -@fnindex libkeccak_spec_rawshake -This example configure a @code{libkeccak_spec_t} to specify -the Keccak parameters used for RawSHAKE256(, 512). -@example -libkeccak_spec_t spec; -libkeccak_spec_rawshake(&spec, 256, 512); -@end example -@end cartouche - -@cartouche -@cpindex Configure state, SHA-3 -@cpindex SHA-3, configure state -@tpindex libkeccak_spec_t -@fnindex libkeccak_spec_sha3 -This example configure a @code{libkeccak_spec_t} to specify -the Keccak parameters used for SHA3-256. -@example -libkeccak_spec_t spec; -libkeccak_spec_sha3(&spec, 256); -@end example -@end cartouche - -@cartouche -@cpindex Configure state, SHAKE -@cpindex SHAKE, configure state -@tpindex libkeccak_spec_t -@fnindex libkeccak_spec_shake -This example configure a @code{libkeccak_spec_t} to specify -the Keccak parameters used for SHAKE256(, 512). -@example -libkeccak_spec_t spec; -libkeccak_spec_shake(&spec, 256, 512); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, SHA-3, from file -@cpindex Hash, calculate, SHA-3, from file -@cpindex SHA-3, calculate hash, from file -@cpindex File, calculate hash, SHA-3 -@fnindex libkeccak_sha3sum_fd -This example calculates the SHA3-256 hash of the input from -stdin, and prints the hash, in hexadecimal form, to stdout. -@example -libkeccak_state_t state; -if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, RawSHAKE, from file -@cpindex Hash, calculate, RawSHAKE, from file -@cpindex RawSHAKE, calculate hash, from file -@cpindex File, calculate hash, RawSHAKE -@fnindex libkeccak_rawshakesum_fd -This example calculates the RawSHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -@example -libkeccak_state_t state; -if (libkeccak_rawshakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, SHAKE, from file -@cpindex Hash, calculate, SHAKE, from file -@cpindex SHAKE, calculate hash, from file -@cpindex File, calculate hash, SHAKE -@fnindex libkeccak_shakesum_fd -This example calculates the SHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -@example -libkeccak_state_t state; -if (libkeccak_shakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, Keccak, from file -@cpindex Hash, calculate, Keccak, from file -@cpindex Keccak, calculate hash, from file -@cpindex File, calculate hash, Keccak -@tpindex libkeccak_spec_t -@fnindex libkeccak_keccaksum_fd -@fnindex libkeccak_behex_lower -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -@example -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; - -if (libkeccak_keccaksum_fd(STDIN_FILENO, &state, &spec, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, from file -@cpindex Hash, calculate, from file -@cpindex Calculate hash, from file -@cpindex File, calculate hash -@tpindex libkeccak_spec_t -@fnindex libkeccak_generalised_sum_fd -@fnindex libkeccak_behex_lower -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -@example -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; - -if (libkeccak_generalised_sum_fd(STDIN_FILENO, &state, - &spec, NULL, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - - - -@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 |