diff options
Diffstat (limited to 'doc')
59 files changed, 0 insertions, 4603 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 diff --git a/doc/info/macros.texinfo b/doc/info/macros.texinfo deleted file mode 100644 index 4ec5d68..0000000 --- a/doc/info/macros.texinfo +++ /dev/null @@ -1,10 +0,0 @@ -@iftex -@macro e{a} -(@email{\a\}) -@end macro -@end iftex -@ifnottex -@macro e{a} -@email{\a\} -@end macro -@end ifnottex diff --git a/doc/man/libkeccak.7 b/doc/man/libkeccak.7 deleted file mode 100644 index 0a6ef04..0000000 --- a/doc/man/libkeccak.7 +++ /dev/null @@ -1,70 +0,0 @@ -.TH LIBKECCAK 7 LIBKECCAK -.SH NAME -libkeccak - Keccak-family hashing library -.SH DESCRIPTION -.BR libkeccak -is a bit-oriented lanewise implementation of the Keccak-family with -support for extend output size, state marshalling, algorithm tuning with -implicit parameters, secure erasure of sensitive data, and HMAC. -.SH FUTURE DIRECTION -Keccak-3200 may be implemented in the future. -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_degeneralise_spec (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_wipe_message (3), -.BR libkeccak_state_wipe_sponge (3), -.BR libkeccak_state_wipe (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_create (3), -.BR libkeccak_state_fast_free (3), -.BR libkeccak_state_free (3), -.BR libkeccak_state_copy (3), -.BR libkeccak_state_duplicate (3), -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_state_unmarshal_skip (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_unhex (3), -.BR libkeccak_hmac_set_key (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_copy (3), -.BR libkeccak_hmac_duplicate (3), -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_unmarshal_skip (3), -.BR libkeccak_hmac_fast_update (3), -.BR libkeccak_hmac_update (3), -.BR libkeccak_hmac_fast_digest (3), -.BR libkeccak_hmac_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_behex_lower.3 b/doc/man/libkeccak_behex_lower.3 deleted file mode 100644 index 85bc843..0000000 --- a/doc/man/libkeccak_behex_lower.3 +++ /dev/null @@ -1,50 +0,0 @@ -.TH LIBKECCAK_BEHEX_LOWER 3 LIBKECCAK -.SH NAME -libkeccak_behex_lower - Converts a binary hashsum to lowercase hexadecimal -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_behex_lower(char *restrict \fIoutput\fP, - const char *restrict \fIhashsum\fP, size_t \fIn\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_behex_lower () -function -converts a binary hashsum, stored in -.IR hashsum , -to lowercase hexadecimal, and stores the -hexadecimal representation in -.IR output . -.PP -.I output -will be terminated by a NUL-character. -.PP -The -.I n -parameter specifies the number of bytes -the binary hashsum is comprised. -.I output -needs an allocation size of (2 * -.I n -+ 1). -.SH RETURN VALUES -The -.BR libkeccak_behex_lower () -function does return any value. -.SH ERRORS -The -.BR libkeccak_behex_lower () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_behex_upper (3), -.BR libkeccak_unhex (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_behex_upper.3 b/doc/man/libkeccak_behex_upper.3 deleted file mode 100644 index 7925efc..0000000 --- a/doc/man/libkeccak_behex_upper.3 +++ /dev/null @@ -1,50 +0,0 @@ -.TH LIBKECCAK_BEHEX_UPPER 3 LIBKECCAK -.SH NAME -libkeccak_behex_upper - Converts a binary hashsum to uppercase hexadecimal -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_behex_upper(char *restrict \fIoutput\fP, - const char *restrict \fIhashsum\fP, size_t \fIn\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_behex_upper () -function -converts a binary hashsum, stored in -.IR hashsum , -to uppercase hexadecimal, and stores the -hexadecimal representation in -.IR output . -.PP -.I output -will be terminated by a NUL-character. -.PP -The -.I n -parameter specifies the number of bytes -the binary hashsum is comprised. -.I output -needs an allocation size of (2 * -.I n -+ 1). -.SH RETURN VALUES -The -.BR libkeccak_behex_upper () -function does return any value. -.SH ERRORS -The -.BR libkeccak_behex_upper () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_unhex (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_degeneralise_spec.3 b/doc/man/libkeccak_degeneralise_spec.3 deleted file mode 100644 index 38a1b73..0000000 --- a/doc/man/libkeccak_degeneralise_spec.3 +++ /dev/null @@ -1,124 +0,0 @@ -.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK -.SH NAME -libkeccak_degeneralise_spec - Set all specification parameters to automatic -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *\fIspec\fP, - libkeccak_spec_t *\fIoutput_spec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_degeneralise_spec () -function will resolve automatic parameters in -.I *spec -and translates the parameters to -.IR *output_spec , -so that it can be used for hashing. -.PP -The function will modify both -.I *spec -and -.IR *output_spec . -.PP -You should call the -.BR libkeccak_spec_check (3) -function after calling -.BR libkeccak_degeneralise_spec (). -.PP -.nf -typedef struct libkeccak_generalised_spec { - long int bitrate; /* bitrate (in bits) */ - long int capacity; /* capacity (in bits) */ - long int output; /* output size (in bits) */ - long int state_size; /* state size (in bits) */ - long int word_size; /* word size (in bits) */ -} libkeccak_generalised_spec_t; -.fi -.SH RETURN VALUES -The -.BR libkeccak_degeneralise_spec () -function returns 0 if the settings are usable. Otherwise -it will return one of the following constants. -.PP -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE -The specified state size is non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE -The specified state size exceeded the supported limit -(currently at 1600 bits.) -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25 -The specified state size, in bits, was not equivalent -to 0 modulus 25. Meaning the state size cannot -cover all lanes equivalently. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE -The specified word size is non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE -The specified word size exceeded the supported limit -(currently at 64 bits.) -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY -The specified state size is not exactly 25 times larger -than the word size. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE -The specified capacity was non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8 -The specified capacity was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE -The specified bitrate was non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8 -The specified bitrate was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE -The specified output size was non-positive. -.PP -Note that there may be more than one error. Only the first -detected is returned. -.SH ERRORS -The -.BR libkeccak_degeneralise_spec () -function cannot fail. -.fi -.SH EXAMPLE -This examples configure a -.B libkeccak_spec_t -to specify settings for Keccak[c = 512]: -.LP -.nf -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; -.fi -.SH SEE ALSO -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_digest.3 b/doc/man/libkeccak_digest.3 deleted file mode 100644 index 33b0479..0000000 --- a/doc/man/libkeccak_digest.3 +++ /dev/null @@ -1,145 +0,0 @@ -.TH LIBKECCAK_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_digest - Complete the hashing of a message with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_digest () -function absorbs the last part of (or all of) a message, -and returns the hash of the entire message. The last part -of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_update (3) -function or the -.BR libkeccak_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s -and '0':s, representing the bits that should be appended to -the message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.I hashsum -is -.I NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_digest () -function may fail for any reason specified by the function -.BR malloc (3). -.SH EXAMPLE -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. -.LP -.nf -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); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_fast_digest.3 b/doc/man/libkeccak_fast_digest.3 deleted file mode 100644 index d5c55a5..0000000 --- a/doc/man/libkeccak_fast_digest.3 +++ /dev/null @@ -1,146 +0,0 @@ -.TH LIBKECCAK_FAST_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_fast_digest - Complete the hashing of a message without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_fast_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_fast_digest () -function absorbs the last part of (or all of) a message, -and returns the hash of the entire message. The last part -of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_update (3) -function or the -.BR libkeccak_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s and '0':s, -representing the bits that should be appended to the -message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.IR hashsum -is -.IR NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_fast_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.SH RETURN VALUES -The -.BR libkeccak_fast_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_fast_digest () -function may fail for any reason specified by the function -.BR realloc (3). -.SH EXAMPLE -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. -.LP -.nf -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_fast_update(&state, chunk, (size_t)len) < 0) - goto fail; -} -if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_fast_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_fast_squeeze.3 b/doc/man/libkeccak_fast_squeeze.3 deleted file mode 100644 index d782a95..0000000 --- a/doc/man/libkeccak_fast_squeeze.3 +++ /dev/null @@ -1,39 +0,0 @@ -.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_fast_squeeze - Runs the squeeze phase a number of times -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_fast_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_fast_squeeze () -function runs the Keccak squeeze phase, on the the hash -process described by -.IR *state , -as many times are required to get -.I times -additional digests. -.SH RETURN VALUES -The -.BR libkeccak_fast_squeeze () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_fast_squeeze () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_digest (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_fast_update.3 b/doc/man/libkeccak_fast_update.3 deleted file mode 100644 index c619e7d..0000000 --- a/doc/man/libkeccak_fast_update.3 +++ /dev/null @@ -1,96 +0,0 @@ -.TH LIBKECCAK_FAST_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_fast_update - Partially hash a message without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_fast_update () -function continues (or starts) hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_fast_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.SH RETURN VALUES -The -.BR libkeccak_fast_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_fast_update () -function may fail for any reason specified by the function -.BR realloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH EXAMPLE -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. -.LP -.nf -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_fast_update(&state, chunk, (size_t)len) < 0) - goto fail; -} -if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_fast_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_generalised_spec_initialise.3 b/doc/man/libkeccak_generalised_spec_initialise.3 deleted file mode 100644 index 42bd62f..0000000 --- a/doc/man/libkeccak_generalised_spec_initialise.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_GENERALISED_SPEC_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_generalised_spec_initialise - Set all specification parameters to automatic -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_generalised_spec_initialise () -function initialises -.IR *spec , -so that all parameters are configured to be -automatically selected. -.PP -Automatic selection means that value will be set -to the default, which depends on the other settings. -.PP -Specifically, all members of -.IR *spec , -will be set to -.BR LIBKECCAK_GENERALISED_SPEC_AUTOMATIC . -.SH RETURN VALUES -The -.BR libkeccak_generalised_spec_initialise () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_generalised_spec_initialise () -function cannot fail. -.fi -.SH SEE ALSO -.BR libkeccak_degeneralise_spec (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_generalised_sum_fd.3 b/doc/man/libkeccak_generalised_sum_fd.3 deleted file mode 100644 index 98e6329..0000000 --- a/doc/man/libkeccak_generalised_sum_fd.3 +++ /dev/null @@ -1,132 +0,0 @@ -.TH LIBKECCAK_GENERALISED_SUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_generalised_sum_fd - Calculate the hash of a file -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_generalised_sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP, - const char *\fIsuffix\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_generalised_sum_fd () -function calculates the hash of a file, whose file desriptor is -specified by -.I fd -(and should be at the beginning of the file.) The hash algorithm -is specified by -.I *spec -and -.IR suffix , -where -.I *spec -is the tuning of the algorithm and -.I suffix -is the bits append to the message (or -.I NULL -if none.) -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( spec->output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_generalised_sum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_generalised_sum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_generalised_sum_fd () -function may fail for any reason, except those resulting -in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_generalised_sum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_generalised_sum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_generalised_sum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_generalised_sum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_generalised_sum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -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. -.LP -.nf -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); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_copy.3 b/doc/man/libkeccak_hmac_copy.3 deleted file mode 100644 index f3939f5..0000000 --- a/doc/man/libkeccak_hmac_copy.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_HMAC_COPY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_copy - Copies an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_copy(libkeccak_hmac_state_t *\fIdest\fP, - const libkeccak_hmac_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_copy () -function initialises -.I *dest -to be identical to -.IR *src . -This includes all members of the -.B libkeccak_hmac_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_hmac_copy () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_copy () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_duplicate (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_create.3 b/doc/man/libkeccak_hmac_create.3 deleted file mode 100644 index fcb99cb..0000000 --- a/doc/man/libkeccak_hmac_create.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH LIBKECCAK_HMAC_CREATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_create - Allocate and initialise HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -libkeccak_hmac_state_t * -libkeccak_hmac_create(const libkeccak_spec_t *\fIspec\fP, const char *\fIkey\fP, - size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_create () -function allocates a new -.I libkeccak_hmac_state_t* -with one initialised element, and sets the -algorithm tuning parameters to those specified by -.IR *spec , -and the key to -.I key -of length -.IR key_length . -.SH RETURN VALUES -The -.BR libkeccak_hmac_create () -function returns a newly allocated -.I libkeccak_hmac_state_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_create () -function may fail for any specified for the functions -.BR malloc (3) -and -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_duplicate (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_destroy.3 b/doc/man/libkeccak_hmac_destroy.3 deleted file mode 100644 index 2f3bbf8..0000000 --- a/doc/man/libkeccak_hmac_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_HMAC_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_destroy - Destroys an HMAC-hashing state with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_hmac_destroy(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_hmac_destroy () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_digest.3 b/doc/man/libkeccak_hmac_digest.3 deleted file mode 100644 index 66d35d4..0000000 --- a/doc/man/libkeccak_hmac_digest.3 +++ /dev/null @@ -1,103 +0,0 @@ -.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_digest(libkeccak_hmac_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_digest () -function absorbes the last part of (or all of) a message, -and returns the HMAC hash of the entire message. The last -part of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_hmac_update (3) -function or the -.BR libkeccak_hmac_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s -and '0':s, representing the bits that should be appended -to the message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.I hashsum -is -.I NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_hmac_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_hmac_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_digest () -function may fail for any reason specified by the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_update (3), -.BR libkeccak_hmac_fast_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_duplicate.3 b/doc/man/libkeccak_hmac_duplicate.3 deleted file mode 100644 index 70c994c..0000000 --- a/doc/man/libkeccak_hmac_duplicate.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_HMAC_DUPLICATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_duplicate - Allocate a duplicate an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -libkeccak_hmac_state_t * -libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_duplicate () -function allocates a new hash state and initialises -it to be identical to -.IR *src . -This includes all members of the -.B libkeccak_hmac_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_hmac_duplicate () -function returns a newly allocated -.I libkeccak_hmac_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_duplicate () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_copy (3), -.BR libkeccak_hmac_create (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_destroy.3 b/doc/man/libkeccak_hmac_fast_destroy.3 deleted file mode 100644 index d2af66e..0000000 --- a/doc/man/libkeccak_hmac_fast_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_destroy - Destroys an HMAC-hashing state without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_hamc_fast_destroy(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_hmac_fast_destroy () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_fast_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_digest.3 b/doc/man/libkeccak_hmac_fast_digest.3 deleted file mode 100644 index 008477c..0000000 --- a/doc/man/libkeccak_hmac_fast_digest.3 +++ /dev/null @@ -1,104 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_digest - Complete the HMAC-hashing of a message without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *\fIstate\fP, - const char *\fImsg\fP, size_t \fImsglen\fP, size_t \fIbits\fP, - const char *\fIsuffix\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_digest () -function absorbes the last part of (or all of) a message, -and returns the HMAC hash of the entire message. The last -part of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_hmac_update (3) -function or the -.BR libkeccak_hmac_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s -and '0':s, representing the bits that should be appended -to the message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.I hashsum -is -.I NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_hmac_fast_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_fast_digest () -function may fail for any reason specified by the function -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_fast_update (3), -.BR libkeccak_hmac_fast_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_free.3 b/doc/man/libkeccak_hmac_fast_free.3 deleted file mode 100644 index b4817ce..0000000 --- a/doc/man/libkeccak_hmac_fast_free.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_free - Destroys and deallocates an HMAC-hashing state without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_hmac_fast_free(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_free () -function releases the allocations stored in -.IR *state , -and also released the allocation of -.IR state . -.PP -The -.BR libkeccak_hmac_fast_free () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_fast_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_hmac_fast_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_update.3 b/doc/man/libkeccak_hmac_fast_update.3 deleted file mode 100644 index 43077d3..0000000 --- a/doc/man/libkeccak_hmac_fast_update.3 +++ /dev/null @@ -1,59 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_update - Partially HMAC-hash a message without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_update () -function continues (or starts) HMAC-hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_hmac_fast_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_fast_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.BR realloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_fast_digest (3), -.BR libkeccak_hmac_update (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_free.3 b/doc/man/libkeccak_hmac_free.3 deleted file mode 100644 index d1f9c84..0000000 --- a/doc/man/libkeccak_hmac_free.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_HMAC_FREE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_free - Destroys and deallocates an HMAC-hashing state with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_hmac_free(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_free () -function releases the allocations stored in -.IR *state , -and also release the allocation of -.IR state . -.PP -The -.BR libkeccak_hmac_free () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_hmac_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_initialise.3 b/doc/man/libkeccak_hmac_initialise.3 deleted file mode 100644 index de514e9..0000000 --- a/doc/man/libkeccak_hmac_initialise.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH LIBKECCAK_HMAC_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_initialise - Initialise HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_initialise(libkeccak_hmac_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP, - const char *\fIkey\fP, size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_initialise () -function initialises -.I *state -and sets the algorithm tuning parameters to -those specified by -.IR *spec , -and the key to -.I key -of length -.IR key_length . -.SH RETURN VALUES -The -.BR libkeccak_hmac_initialise () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_initialise () -function may fail for any specified for the functions -.BR malloc (3) -and -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_copy (3), -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_marshal.3 b/doc/man/libkeccak_hmac_marshal.3 deleted file mode 100644 index b7270f6..0000000 --- a/doc/man/libkeccak_hmac_marshal.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_HMAC_MARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_hmac_marshal - Marshals an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_hmac_marshal(const libkeccak_hmac_state_t *\fIstate\fP, - char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_marshal () -function marshals -.I *state -into the beginning of -.IR data . -.PP -Use the -.BR libkeccak_hmac_marshal_size (3) -function to get minimum usable allocation size -for -.IR data . -.SH RETURN VALUES -The -.BR libkeccak_hmac_marshal () -returns the number of bytes written to -.IR data . -.SH ERRORS -The -.BR libkeccak_hmac_marshal () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_marshal_size.3 b/doc/man/libkeccak_hmac_marshal_size.3 deleted file mode 100644 index 5195b81..0000000 --- a/doc/man/libkeccak_hmac_marshal_size.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH LIBKECCAK_HMAC_MARSHAL_SIZE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_marshal_size - Calculates the marshal-size of an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_marshal_size () -function calculates the number of bytes required -to marshal -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_hmac_marshal_size () -returns a positive value: the number of -bytes required to marshal the specified state. -.SH ERRORS -The -.BR libkeccak_hmac_marshal_size () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_reset.3 b/doc/man/libkeccak_hmac_reset.3 deleted file mode 100644 index d5634d9..0000000 --- a/doc/man/libkeccak_hmac_reset.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_HMAC_RESET 3 LIBKECCAK -.SH NAME -libkeccak_hmac_reset - Reinitialise a HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_reset(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, - size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_reset () -function reinitialises an HMAC-hashing state with a new key. -.I key_length -is the length of the key in bits. If -.I key -is -.IR NULL , -the key remains unchanged. -.SH RETURN VALUES -The -.BR libkeccak_hmac_reset () -function returns 0 successful completion. -On error -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_reset () -function may fail for any specified for the functions -.BR malloc (3) -and -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_set_key (3), -.BR libkeccak_hmac_wipe (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_destroy (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_set_key.3 b/doc/man/libkeccak_hmac_set_key.3 deleted file mode 100644 index 2f4682d..0000000 --- a/doc/man/libkeccak_hmac_set_key.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH LIBKECCAK_HMAC_SET_KEY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_set_key - Changes key for a the HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_set_key(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, - size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_set_key () -function sets the key for a HMAC-hashing state without reseting -the state of the underlaying hashing-algorithm. -.I key_length -is the length of the key in bits. -.SH RETURN VALUES -The -.BR libkeccak_hmac_set_key () -function returns 0 successful completion. -On error -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_set_key () -function may fail for any specified for the function -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_unmarshal.3 b/doc/man/libkeccak_hmac_unmarshal.3 deleted file mode 100644 index 64e8f24..0000000 --- a/doc/man/libkeccak_hmac_unmarshal.3 +++ /dev/null @@ -1,39 +0,0 @@ -.TH LIBKECCAK_HMAC_UNMARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_hmac_unmarshal - Unharshals an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *\fIstate\fP, - const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_unmarshal () -function unmarshals an HMAC-hashing state from the beginning of -.IR data . -and stores it in -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_hmac_unmarshal () -returns the number of bytes reads from -.IR data x. -.SH ERRORS -The -.BR libkeccak_hmac_unmarshal () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_unmarshal_skip.3 b/doc/man/libkeccak_hmac_unmarshal_skip.3 deleted file mode 100644 index 30e7ccf..0000000 --- a/doc/man/libkeccak_hmac_unmarshal_skip.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH LIBKECCAK_HMAC_UNMARSHAL_SKIP 3 LIBKECCAK -.SH NAME -libkeccak_hmac_unmarshal_skip - Calculates the marshal-size of a marshalled HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_hmac_unmarshal_skip(const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_unmarshal_skip () -function gets the number of bytes with which -the HMAC-hashing state in the beginning of -.I data -is store stored. This is useful if you do not -want to unmarshal the state. -.SH RETURN VALUES -The -.BR libkeccak_hmac_unmarshal_skip () -returns a positive value: the number of -bytes to skip forward to skip pass the -hash state stored at the beginning of -the buffer. -.SH ERRORS -The -.BR libkeccak_hmac_unmarshal_skip () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_update.3 b/doc/man/libkeccak_hmac_update.3 deleted file mode 100644 index daaf3fb..0000000 --- a/doc/man/libkeccak_hmac_update.3 +++ /dev/null @@ -1,56 +0,0 @@ -.TH LIBKECCAK_HMAC_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_update - Partially HMAC-hash a message with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_update () -function continues (or starts) HMAC-hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_hmac_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_hmac_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_update () -function may fail for any reason specified by the function -.BR malloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_digest (3), -.BR libkeccak_hmac_fast_update (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_wipe.3 b/doc/man/libkeccak_hmac_wipe.3 deleted file mode 100644 index bad351b..0000000 --- a/doc/man/libkeccak_hmac_wipe.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH LIBKECCAK_HMAC_WIPE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_wipe - Securely erase sensitive data from a HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_hmac_wipe(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_wipe () -function securely erases data that may be -sensitive: the buffer and the state of the -underlaying hash-algorithm. -.SH RETURN VALUES -The -.BR libkeccak_hmac_wipe () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_wipe () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_destroy (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_keccaksum_fd.3 b/doc/man/libkeccak_keccaksum_fd.3 deleted file mode 100644 index 2fc1b21..0000000 --- a/doc/man/libkeccak_keccaksum_fd.3 +++ /dev/null @@ -1,119 +0,0 @@ -.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_keccaksum_fd - Calculate a Keccak hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_keccaksum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_keccaksum_fd () -function calculates a Keccak hashsum of a file, whose file -desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm tuning is specified by -.IR *spec . -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( spec->output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_keccaksum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_keccaksum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_keccaksum_fd () -function may fail for any reason, except those resulting -in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_keccaksum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_keccaksum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_keccaksum_fd () -does not stop if interrupted -.RI ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_keccaksum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_keccaksum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -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. -.LP -.nf -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); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_rawshakesum_fd.3 b/doc/man/libkeccak_rawshakesum_fd.3 deleted file mode 100644 index 27c4f45..0000000 --- a/doc/man/libkeccak_rawshakesum_fd.3 +++ /dev/null @@ -1,115 +0,0 @@ -.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_rawshakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - long int \fIsemicapacity\fP, long int \fIoutput\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_rawshakesum_fd () -function calculates a RawSHAKE hashsum of a file, whose -file desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm is tuned by the -.I semicapacity -and -.I output -parameters; they specify the half of the capacity and -the output size, respectively, in bits. -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_rawshakesum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_rawshakesum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_rawshakesum_fd () -function may fail for any reason, except those resulting in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_rawshakesum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_rawshakesum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_rawshakesum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_rawshakesum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_rawshakesum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the RawSHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -.LP -.nf -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); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_sha3sum_fd.3 b/doc/man/libkeccak_sha3sum_fd.3 deleted file mode 100644 index e8c4fc0..0000000 --- a/doc/man/libkeccak_sha3sum_fd.3 +++ /dev/null @@ -1,111 +0,0 @@ -.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_sha3sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIoutput\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_sha3sum_fd () -function calculates a SHA-3 hashsum of a file, whose file -desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm is tuned by the -.I output -parameter; it specifies the output size, in bits. -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_sha3sum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_sha3sum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_sha3sum_fd () -function may fail for any reason, except those resulting in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_sha3sum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_sha3sum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_sha3sum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_sha3sum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_sha3sum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the SHA3-256 hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -.LP -.nf -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); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_shakesum_fd.3 b/doc/man/libkeccak_shakesum_fd.3 deleted file mode 100644 index 0d89f39..0000000 --- a/doc/man/libkeccak_shakesum_fd.3 +++ /dev/null @@ -1,115 +0,0 @@ -.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - long int \fIsemicapacity\fP, long int \fIoutput\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_shakesum_fd () -function calculates a SHAKE hashsum of a file, whose file -desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm is tuned by the -.I semicapacity -and -.I output -parameters; they specify the half of the capacity and the -output size, respectively, in bits. -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_shakesum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_shakesum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_shakesum_fd () -function may fail for any reason, except those resulting in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_shakesum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_shakesum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_shakesum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_shakesum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_shakesum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the SHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -.LP -.nf -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); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_simple_squeeze.3 b/doc/man/libkeccak_simple_squeeze.3 deleted file mode 100644 index 52605ed..0000000 --- a/doc/man/libkeccak_simple_squeeze.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_SIMPLE_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_simple_squeeze - Runs Keccak-f a number of times -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_simple_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_simple_squeeze () -function runs Keccak-f -.I times -times on the hashing -process described by -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_simple_squeeze () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_simple_squeeze () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_digest (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_check.3 b/doc/man/libkeccak_spec_check.3 deleted file mode 100644 index 9fc70f6..0000000 --- a/doc/man/libkeccak_spec_check.3 +++ /dev/null @@ -1,95 +0,0 @@ -.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK -.SH NAME -libkeccak_spec_check - Validate hashing parameters -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_spec_check(const libkeccak_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_check () -function validates the parameters of -.IR *spec , -so that unusable configurations can be detected. -It is recommended to call this function after calling -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -or, especially, after settings the parameters -manually for Keccak hashing. -.PP -.nf -typedef struct libkeccak_spec { - long int bitrate; /* bitrate (in bits) */ - long int capacity; /* capacity (in bits) */ - long int output; /* output size (in bits) */ -} libkeccak_spec_t; -.fi -.SH RETURN VALUES -The -.BR libkeccak_spec_check () -function returns 0 if the settings are usable. Otherwise -it will return one of the following constants. -.PP -.TP -.B LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE -The specified bitrate was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 -The specified bitrate was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE -The specified capacity was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 -The specified capacity was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE -The specified output size was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE -The state size, that is the sum of the bitrate -and the capacity, exceeded the supported limit -(currently at 1600 bits.) -.TP -.B LIBKECCAK_SPEC_ERROR_STATE_MOD_25 -The state size, that is the sum of the bitrate -and the capacity, in bits, was not equivalent -to 0 modulus 25. Meaning the state size cannot -cover all lanes equivalently. -.TP -.B LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT -The word size, that is the state size divided -by 25, is not a power of 2. -.TP -.B LIBKECCAK_SPEC_ERROR_WORD_MOD_8 -The word size, that is the state size divided -by 25, is not quivalent to 0 modulus 8, that -is, it is not in whole bytes. -.PP -Note that there may be more than one error. Only the first -detected is returned. -.SH ERRORS -The -.BR libkeccak_spec_check () -function cannot fail. -.fi -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_rawshake.3 b/doc/man/libkeccak_spec_rawshake.3 deleted file mode 100644 index 6f60c36..0000000 --- a/doc/man/libkeccak_spec_rawshake.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK -.SH NAME -libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_spec_rawshake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, - long int \fId\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_rawshake () -function sets -.I *spec -to specify the Keccak parameters used for RawSHAKE hashing -with the semicapacity specified, in bits, via the -.I x -parameter, and the output size specified, in bits, via the -.I d -parameter. -.SH RETURN VALUES -The -.BR libkeccak_spec_rawshake () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_spec_rawshake () -function cannot fail. -.SH EXAMPLE -This example configure a -.B libkeccak_spec_t -to specify the Keccak parameters used for RawSHAKE256(, 512): -.LP -.nf -libkeccak_spec_t spec; -libkeccak_spec_rawshake(&spec, 256, 512); -.fi -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_sha3.3 b/doc/man/libkeccak_spec_sha3.3 deleted file mode 100644 index 8e07a7d..0000000 --- a/doc/man/libkeccak_spec_sha3.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK -.SH NAME -libkeccak_spec_sha3 - Configure SHA-3 hashing parameters -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_spec_sha3(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_sha3 () -function sets -.I *spec -to specify the Keccak parameters -used for SHA-3 hashing with the output size specified, -in bits, via the -.I x -parameter. -.SH RETURN VALUES -The -.BR libkeccak_spec_sha3 () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_spec_sha3 () -function cannot fail. -.SH EXAMPLE -This example configure a -.B libkeccak_spec_t -to specify the Keccak parameters used for SHA3-256: -.LP -.nf -libkeccak_spec_t spec; -libkeccak_spec_sha3(&spec, 256); -.fi -.SH SEE ALSO -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_shake.3 b/doc/man/libkeccak_spec_shake.3 deleted file mode 100644 index 9e2d763..0000000 --- a/doc/man/libkeccak_spec_shake.3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK -.SH NAME -libkeccak_spec_shake - Configure SHAKE hashing parameters -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_spec_shake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_shake () -function sets -.I *spec -to specify the Keccak parameters used for SHAKE hashing -with the semicapacity specified, in bits, via the -.I x -parameter, and the output size specified, in bits, via the -.I d -parameter. -.SH RETURN VALUES -The -.BR libkeccak_spec_shake () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_spec_shake () -function cannot fail. -.SH EXAMPLE -This example configure a -.B libkeccak_spec_t -to specify the Keccak parameters used for SHAKE256(, 512): -.LP -.nf -libkeccak_spec_t spec; -libkeccak_spec_shake(&spec, 256, 512); -.fi -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_squeeze.3 b/doc/man/libkeccak_squeeze.3 deleted file mode 100644 index c6c8d01..0000000 --- a/doc/man/libkeccak_squeeze.3 +++ /dev/null @@ -1,48 +0,0 @@ -.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_squeeze - Runs the squeeze phase -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_squeeze(libkeccak_state_t *\fIstate\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_squeeze () -function runs the Keccak squeeze phase, on the the hash -process described by -.IR *state , -on stores a new digest, in binary form, in -.IR hashsum . -.PP -.I hashsum -has the same requirement as for the -.BR libkeccak_digest (3) -and -.BR libkeccak_fast_digest (3) -functions: it must have an allocation size of at least -.RI (( state->n -+ 7) / 8) bytes. However, it may not be -.IR NULL . -.SH RETURN VALUES -The -.BR libkeccak_squeeze () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_squeeze () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_digest (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_copy.3 b/doc/man/libkeccak_state_copy.3 deleted file mode 100644 index c9283ca..0000000 --- a/doc/man/libkeccak_state_copy.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_STATE_COPY 3 LIBKECCAK -.SH NAME -libkeccak_state_copy - Copies hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_state_copy(libkeccak_state_t *\fIdest\fP, - const libkeccak_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_copy () -function initialises -.I *dest -to be identical to -.IR *src . -This includes all members of the -.B libkeccak_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_copy () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_copy () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_duplicate (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_create.3 b/doc/man/libkeccak_state_create.3 deleted file mode 100644 index 77880a3..0000000 --- a/doc/man/libkeccak_state_create.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_STATE_CREATE 3 LIBKECCAK -.SH NAME -libkeccak_state_create - Allocate and initialise hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -libkeccak_state_t * -libkeccak_state_create(const libkeccak_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_create () -function allocates a new -.I libkeccak_state_t* -with one initialised element, and sets the algorithm -tuning parameters to those specified by -.IR *spec . -.SH RETURN VALUES -The -.BR libkeccak_state_create () -function returns a newly allocated -.I libkeccak_state_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_create () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_free (3), -.BR libkeccak_state_fast_free (3) -.BR libkeccak_state_duplicate (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_destroy.3 b/doc/man/libkeccak_state_destroy.3 deleted file mode 100644 index 0a78215..0000000 --- a/doc/man/libkeccak_state_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_STATE_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_state_destroy - Destroys a hash state with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_destroy(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_state_destroy () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_free (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_duplicate.3 b/doc/man/libkeccak_state_duplicate.3 deleted file mode 100644 index 54c9be3..0000000 --- a/doc/man/libkeccak_state_duplicate.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_STATE_DUPLICATE 3 LIBKECCAK -.SH NAME -libkeccak_state_duplicate - Allocate a duplicate hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -libkeccak_state_t * -libkeccak_state_duplicate(const libkeccak_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak P. -.SH DESCRIPTION -The -.BR libkeccak_state_duplicate () -function allocates a new hash state and initialises it -to be identical to -.IR *src . -This includes all members of the -.B libkeccak_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_duplicate () -function returns a newly allocated -.I libkeccak_state_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_duplicate () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_copy (3), -.BR libkeccak_state_create (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_fast_destroy.3 b/doc/man/libkeccak_state_fast_destroy.3 deleted file mode 100644 index e04ca86..0000000 --- a/doc/man/libkeccak_state_fast_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_STATE_FAST_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_state_fast_destroy - Destroys a hash state without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_fast_destroy(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_fast_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_state_fast_destroy () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_fast_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_fast_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_fast_free (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_fast_free.3 b/doc/man/libkeccak_state_fast_free.3 deleted file mode 100644 index e617e21..0000000 --- a/doc/man/libkeccak_state_fast_free.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK -.SH NAME -libkeccak_state_fast_free - Destroys and deallocates a hash state without erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_fast_free(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_fast_free () -function releases the allocations stored in -.IR *state , -and also released the allocation of -.IR state . -.PP -The -.BR libkeccak_state_fast_free () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_fast_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_fast_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_state_fast_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_free (3), -.BR libkeccak_state_create (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_free.3 b/doc/man/libkeccak_state_free.3 deleted file mode 100644 index e6dd3f8..0000000 --- a/doc/man/libkeccak_state_free.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_STATE_FREE 3 LIBKECCAK -.SH NAME -libkeccak_state_free - Destroys and deallocates a hash state with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_free(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_free () -function releases the allocations stored in -.IR *state , -and also release the allocation of -.IR state . -.PP -The -.BR libkeccak_state_free () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_state_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_fast_free (3), -.BR libkeccak_state_create (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_initialise.3 b/doc/man/libkeccak_state_initialise.3 deleted file mode 100644 index 2620686..0000000 --- a/doc/man/libkeccak_state_initialise.3 +++ /dev/null @@ -1,60 +0,0 @@ -.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_state_initialise - Initialise hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_state_initialise(libkeccak_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_initialise () -function initialises -.I *state -and sets the algorithm tuning parameters to those -specified by -.IR *spec . -.SH RETURN VALUES -The -.BR libkeccak_state_initialise () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_initialise () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_create (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_copy (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_marshal.3 b/doc/man/libkeccak_state_marshal.3 deleted file mode 100644 index f5d5e05..0000000 --- a/doc/man/libkeccak_state_marshal.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH LIBKECCAK_STATE_MARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_state_marshal - Marshals a hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_state_marshal(const libkeccak_state_t *\fIstate\fP, char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_marshal () -function marshals \fI*state\fP into the beginning of -.IR data . -.PP -Use the -.BR libkeccak_state_marshal_size (3) -function to get minimum usable allocation size -for -.IR data . -.SH RETURN VALUES -The -.BR libkeccak_state_marshal () -returns the number of bytes written to -.IR data . -.SH ERRORS -The -.BR libkeccak_state_marshal () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_state_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_marshal_size.3 b/doc/man/libkeccak_state_marshal_size.3 deleted file mode 100644 index 8ebb16a..0000000 --- a/doc/man/libkeccak_state_marshal_size.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH LIBKECCAK_STATE_MARSHAL_SIZE 3 LIBKECCAK -.SH NAME -libkeccak_state_marshal_size - Calculates the marshal-size of a hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_state_marshal_size(const libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_marshal_size () -function calculates the number of bytes required -to marshal -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_state_marshal_size () -returns a positive value: the number of -bytes required to marshal the specified state. -.SH ERRORS -The -.BR libkeccak_state_marshal_size () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_state_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_reset.3 b/doc/man/libkeccak_state_reset.3 deleted file mode 100644 index 60bb778..0000000 --- a/doc/man/libkeccak_state_reset.3 +++ /dev/null @@ -1,37 +0,0 @@ -.TH LIBKECCAK_STATE_RESET 3 LIBKECCAK -.SH NAME -libkeccak_state_reset - Reinitialise hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_reset(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_reset () -function reinitialises -.IR *state , -but keeps the -tuning, so it can be used to hash another message. -.SH RETURN VALUES -The -.BR libkeccak_state_reset () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_reset () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_unmarshal.3 b/doc/man/libkeccak_state_unmarshal.3 deleted file mode 100644 index 5a9e59b..0000000 --- a/doc/man/libkeccak_state_unmarshal.3 +++ /dev/null @@ -1,39 +0,0 @@ -.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_state_unmarshal - Unharshals a hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_state_unmarshal(libkeccak_state_t *\fIstate\fP, const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_unmarshal () -function unmarshals a hash state from the beginning -of -.IR data . -and stores it in -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_state_unmarshal () -returns the number of bytes reads from -.IR data . -.SH ERRORS -The -.BR libkeccak_state_unmarshal () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_unmarshal_skip.3 b/doc/man/libkeccak_state_unmarshal_skip.3 deleted file mode 100644 index b87386c..0000000 --- a/doc/man/libkeccak_state_unmarshal_skip.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH LIBKECCAK_STATE_UNMARSHAL_SKIP 3 LIBKECCAK -.SH NAME -libkeccak_state_unmarshal_skip - Calculates the marshal-size of a marshalled hash state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -size_t -libkeccak_state_unmarshal_skip(const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_unmarshal_skip () -function gets the number of bytes with which -the hash state in the beginning of -.I data -is store stored. This is useful if you do not -want to unmarshal the state. -.SH RETURN VALUES -The -.BR libkeccak_state_unmarshal_skip () -returns a positive value: the number of -bytes to skip forward to skip pass the -hash state stored at the beginning of -the buffer. -.SH ERRORS -The -.BR libkeccak_state_unmarshal_skip () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_wipe.3 b/doc/man/libkeccak_state_wipe.3 deleted file mode 100644 index 664cd51..0000000 --- a/doc/man/libkeccak_state_wipe.3 +++ /dev/null @@ -1,37 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe - Securely erase sensitive data -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_wipe(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_wipe () -function securely erases data that may be -sensitive: the state of the Keccak sponge, -and the message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_wipe () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_wipe () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_wipe_message (3), -.BR libkeccak_state_wipe_sponge (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_wipe_message.3 b/doc/man/libkeccak_state_wipe_message.3 deleted file mode 100644 index c734560..0000000 --- a/doc/man/libkeccak_state_wipe_message.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE_MESSAGE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe_message - Securely erase the message chunk buffer -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_wipe_message(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_wipe_message () -function securely erases the message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_wipe_message () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_wipe_message () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_wipe_sponge (3), -.BR libkeccak_state_wipe (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_wipe_sponge.3 b/doc/man/libkeccak_state_wipe_sponge.3 deleted file mode 100644 index 4651fc0..0000000 --- a/doc/man/libkeccak_state_wipe_sponge.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE_SPONGE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe_sponge - Securely erase the Keccak sponge state -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_state_wipe_sponge(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_wipe_sponge () -function securely erases the state of the Keccak sponge. -.SH RETURN VALUES -The -.BR libkeccak_state_wipe_sponge () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_wipe_sponge () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_wipe_message (3), -.BR libkeccak_state_wipe (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_unhex.3 b/doc/man/libkeccak_unhex.3 deleted file mode 100644 index 93cde63..0000000 --- a/doc/man/libkeccak_unhex.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH LIBKECCAK_UNHEX 3 LIBKECCAK -.SH NAME -libkeccak_unhex - Converts a hexadecimal hashsum to binary -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -void -libkeccak_unhex(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_unhex () -function -converts a hexadecimal hashsum, stored in -.IR hashsum , -to binary, and stores the binary representation in -.IR output . -.PP -.I hashsum -must be terminated by a NUL-character. It may be -in either lowercase or uppercase, or a mixture -thereof. -.I output -will not be terminated. -.PP -(\fBstrlen\fP(\fIhashsum\fP) / 2) bytes will be -written to the beginning of -.IR Ioutput . -It should therefore have an allocation of at least -that number of bytes. -.SH RETURN VALUES -The -.BR libkeccak_unhex () -function does return any value. -.SH ERRORS -The -.BR libkeccak_unhex () -function cannot fail. -.SH NOTES -.I hashsum -must have an even number of digits -(characters excluding the terminating NUL-character.) -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_update.3 b/doc/man/libkeccak_update.3 deleted file mode 100644 index d83f74b..0000000 --- a/doc/man/libkeccak_update.3 +++ /dev/null @@ -1,95 +0,0 @@ -.TH LIBKECCAK_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_update - Partially hash a message with erasure -.SH SYNOPSIS -.LP -.nf -#include <libkeccak.h> -.P -int -libkeccak_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_update () -function continues (or starts) hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_update () -function may fail for any reason specified by the function -.BR malloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH EXAMPLE -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. -.LP -.nf -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); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se |