     [file macros.texinfo not included]

libkeccak -- Library for the Keccak-family hash functions
*********************************************************

Copyright © 2015  Mattias Andrée maandree@member.fsf.org

     Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with the Invariant Sections being the ``GNU Affero General Public License'', the ``GNU Free Documentation License'', with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the section entitled ``GNU Free Documentation License''.

Overview
********

libkeccak is a free software bit-oriented implementation of the cryptographic hash function Keccak and its subsets SHA-3 (Secure Hash Algorithm 3), RawSHAKE and SHAKE.

Being bit-oriented means that it supports messages of length consisting of a non-whole number of bytes.

Keccak is a generic and tunable cryptographic hash function that can be used for all customary tasks that required a cryptographic hash function:

  * Password verification (Using additional squeezes, but not using iterated hashing.)

  * Proof-of-work

  * File and data identification

  * Data integrity

  * Pseudorandom generation (Although not too random, since entropi is not utilised.)

  * Key derivation

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 (Although doing so is unnecessary because the key can securely be prepended to the message when using Keccak to produce a message authentication code.). This library implements the Keccak algorithm using a lanewise implementation. libkeccak must compelling feature however is that it is licensed under the strongest free software license: GNU Affero General Public License version 3 (see GNU Affero General Public License,) which gives the user the four essential freedoms:

  * The freedom to run the program as you wish, for any purpose (freedom 0).

  * The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1).

  * The freedom to redistribute copies so you can help your neighbor (freedom 2).

  * The freedom to distribute copies of your modified versions to others (freedom 3).

This implementation is limited to state sizes up to, and including, 1600 bits.

Linking
*******

libkeccak's API is C standard library independent. This means that libkeccak does not need to be compiled with the same C standard library as software using it. However, the header files contain __attributes__:s for GCC, if these are incompatible with your compiler, your should temporarily define a macro named __attributes__ to remove all attributes.

Because of libkeccak's simplicity it does not have a pkg-config file. Instead, you only need to specify the flag -lkeccak when linking your binaries. No flags are required during compilation (of object files.)

To make libkeccak's API available, include the header file <libkeccak.h> in your source files.

Selecting hash function
***********************

Keccak-based hash functions have three parameters:

  * the bitrate,

  * the capacity, and

  * the output size.

Selecting these is the first step when using the library.

The structure libkeccak_spec_t (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

libkeccak_spec_sha3
     Sets the parameters for SHA-3. It has two parameters:

       * Pointer to the libkeccak_spec_t where the settings shall be stored.

       * The output size, that is the value appended to the name.

libkeccak_spec_rawshake
     Sets the parameters for RawSHAKE (or SHAKE). It has three parameters:

       * Pointer to the libkeccak_spec_t where the settings shall be stored.

       * The semicapacity, that is the value appended to the name.

       * The output size.

libkeccak_spec_shake
     Identical to libkeccak_spec_rawshake. Intended for SHAKE rather than RawSHAKE.

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 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, (Their meaning is documented in the header file <libkeccak/spec.h>.) will be returned:

  * LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE

  * LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8

  * LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE

  * LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8

  * LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE

  * LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE

  * LIBKECCAK_SPEC_ERROR_STATE_MOD_25

  * LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT

  * LIBKECCAK_SPEC_ERROR_WORD_MOD_8

libkeccak_spec_t's members are:

bitrate
     The bitrate, in bits.

capacity
     The capacity, in bits.

output
     The output size, in bits.

It is also possible to select some but not all of the parameters. For this, the structure libkeccak_generalised_spec_t (struct libkeccak_generalised_spec) is used. It extends libkeccak_spec_t with two additional parameters

state_size
     The state size, in bits.

word_size
     The word size, in bits.

By feeding a pointer to a libkeccak_generalised_spec_t, to the function ibkeccak_generalised_spec_initialise, all its members are set to 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 libkeccak_generalised_spec_t has been set, it can be converted to a libkeccak_spec_t, which is neccessary for using the specifications. When doing so, automatic values will be given a proper value.

To do this, the function libkeccak_degeneralise_spec is used. It takes two parameters:

  * Input pointer to the libkeccak_generalised_spec_t.

  * Output pointer to a libkeccak_spec_t.

On success, zero is returned, otherwise one of the values, with somewhat self-explanatory names, (Their meaning is documented in the header file <libkeccak/generalised-spec.h>.) will be returned:

  * LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE

  * LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE

  * LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25

  * LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE

  * LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE

  * LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY

  * LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE

  * LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8

  * LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE

  * LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8

  * LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE

State of the hashing
********************

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 libkeccak_state_t (struct libkeccak_state).

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 libkeccak_state_initialise. Its first argument should be a pointer to the state variable, that is, a libkeccak_state_t*. The second argument should be a pointer to the specifications, that is, a const libkeccak_spec_t*, see Selecting hash function. libkeccak_state_initialise till return zero upon successful completion, and otherwise set errno to describe the error and return -1.

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 libkeccak_state_destroy or by calling the function 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, libkeccak_state_fast_destroy will only release allocations used by the state; libkeccak_state_destroy will also securely release all sensitive information in the state, by calling the function libkeccak_state_wipe: the state of the sponge, by calling the function libkeccak_state_wipe_sponge, and the message buffer, by calling the function libkeccak_state_wipe_message. libkeccak_state_wipe, libkeccak_state_wipe_sponge and libkeccak_state_wipe_message takes a pointer to the state as their only parameter, and none of them have a return value.

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 libkeccak_state_reset instead of libkeccak_state_fast_destroy. It takes a pointer to the state as its only parameter and does not return a value.

If you want to use dynamic instead of static allocation for the state, instead of calling malloc and free yourself, libkeccak offers functions that does this for you:

libkeccak_state_create
     Identical to 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 NULL on error, in which case, errno is set to describe the error.

libkeccak_state_fast_free
     Identical to libkeccak_state_fast_destroy, except it also frees the allocation of the state.

libkeccak_state_free
     Identical to libkeccak_state_destroy, except it also frees the allocation of the state.

libkeccak also has two functions for copying a state:

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 errno to describe the error and returns -1.

libkeccak_state_duplicate
     Identical to 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, errno is set to describe the error and NULL is returned.

The library also offers functions for marshalling a state, which can be useful when implementing programs that can reexecuted into updated version of itself.

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.

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 libkeccak_state_marshal_size returns for the state.

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 libkeccak_state_marshal_size and 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, errno is set to describe the error and zero is returned.

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.

Hashing messages
****************

Once a state has been initialised, a message can be hashed. To hash a message the functions libkeccak_update and libkeccak_digest are used, or its variants that do not securely release sensitive information: libkeccak_fast_update and libkeccak_fast_digest, these are otherwise identical to libkeccak_update and libkeccak_fast_update, respectively.

libkeccak_update
     This function shall be called while you do not know that you have reached the end of the message. It has three parameters:

       * A pointer to the state. See State of the hashing.

       * The beginning of the chunk of the message to process.

       * The number of bytes in the message to process.

     Note that a part of the message is input, not necessarily the entire message. The chunks must be input sequentially. The funtion returns zero upon success completion. On error, errno is set to describe the error and -1 is returned. The input chunk should not be empty.

libkeccak_digest
     This function shall be called either with the last chunk of the message, or when all chunks as been input to libkeccak_update or libkeccak_fast_update. The function's first three parameters are the same as for libkeccak_update, however, the chunk may be NULL and then length zero if all chunks have been processed by libkeccak_update or libkeccak_fast_update. However, it also has three additional parameters:

       * 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.

       * A NUL-terminated string of ASCII ones and zeroes, describing the additional bits to suffix the message; or NULL if none. This is used to select between Keccak, SHA-3, RawSHAKE and SHAKE. Use one of the constants:

          LIBKECCAK_SHA3_SUFFIX or "01"
               For SHA-3.

          LIBKECCAK_RAWSHAKE_SUFFIX or "11"
               For RawSHAKE.

          LIBKECCAK_SHAKE_SUFFIX or "1111"
               For SHAKE.

          NULL or ""
               For Keccak.

       * Output buffer for the hash, in binary. Should be allocated to fit (state.n + 7) / 8 char:s, where state is the state variable. Alternatively it may be NULL, in which case the hash is not retrieved.

     The funtion returns zero upon success completion. On error, errno is set to describe the error and -1 is returned. The input chunk should not be empty.

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.

libkeccak_simple_squeeze
     Perform a number of additional rounds of KECCAK--f. The number of rounds is specified in the second parameter.

libkeccak_fast_squeeze
     Perform a number of additional rounds of KECCAK--f. The number will be exactly enough to get a number of additional digests. The number of digests is specified in the second parameter.

libkeccak_squeeze
     Squeeze out another digest. The hash will be stored in the second parameter, which should be allocated to fit (state.n + 7) / 8 char:s.

Hexadecimal hashes
******************

The functions that return hashes: libkeccak_digest, libkeccak_fast_digest and 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.

libkeccak_behex_lower
libkeccak_behex_upper
     Convert from binary to hexadecimal. libkeccak_behex_lower converts to lowercase hexadecimal, and 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 2 * n + 1 char:s, where 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.

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 strlen(hashsum) / 2 char:s, where 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.

Hashing files
*************

libkeccak provides functions for calculating hashes of files directly, from a file descriptor.

The generalised function is named libkeccak_generalised_sum_fd. It has five parameters:

  * The file descriptor.

  * A pointer to a state variable. Must not be initalised, lest you will suffer a memory leak.

  * The specifications for the hashing functions.

  * The message suffix.

  * The output buffer for the binary hash. It must have an allocation size of at least (spec->output / 8) * sizeof(char), where spec is the third argument, or be NULL.

libkeccak_generalised_sum_fd returns zero upon successful completion. On error, errno is set to describe the error, and -1 is returned.

There are also algorithm specific functions.

libkeccak_keccaksum_fd
     This function is used for Keccak without message suffix. It is identical to libkeccak_generalised_sum_fd sans the fourth parameter (the message suffix.)

libkeccak_sha3sum_fd
     This function is used for SHA-3. It is similar to 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 (output / 8) * sizeof(char), where output is the third parameter, or be NULL.

libkeccak_rawshakesum_fd
     This function is used for RawSHAKE, it is otherwise identical to libkeccak_sha3sum_fd, except it as a parameter for the semicapacity before the output size, that is to say, as its third parameter.

libkeccak_shakesum_fd
     This function is used for SHAKE, it is otherwise identical to libkeccak_rawshakesum_fd.

GNU Affero General Public License
*********************************

     [file agpl-3.0.texinfo not included]

GNU Free Documentation License
******************************

     [file fdl-1.3.texinfo not included]