General improvements

Signed-off-by: Mattias Andrée <maandree@kth.se>

2 files changed, 0 insertions, 1079 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