LIBKECCAK_DEGENERALISE_SPEC(3)

NAME
libkeccak_degeneralise_spec - Set all specification parameters to automatic

SYNOPSIS
#include <libkeccak.h>
int libkeccak_degeneralise_spec(struct libkeccak_generalised_spec *spec, struct libkeccak_spec *output_spec);

Link with -lkeccak.

DESCRIPTION
The libkeccak_degeneralise_spec() function will resolve automatic parameters in *spec and translates the parameters to *output_spec, so that it can be used for hashing.

The function will modify both *spec and *output_spec.

You should call the libkeccak_spec_check(3) function after calling libkeccak_degeneralise_spec().

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) */
};

RETURN VALUES
The libkeccak_degeneralise_spec() function returns 0 if the settings are usable. Otherwise it will return one of the following constants.

LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE
    The specified state size is non-positive.

LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE
    The specified state size exceeded the supported limit (currently at 1600 bits.)

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.

LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE
    The specified word size is non-positive.

LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE
    The specified word size exceeded the supported limit (currently at 64 bits.)

LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY
    The specified state size is not exactly 25 times larger than the word size.

LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE
    The specified capacity was non-positive.

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.

LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE
    The specified bitrate was non-positive.

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.

LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE
    The specified output size was non-positive.

LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_BITRATE_CAPACITY_INCONSISTENCY
    The sum of the bitrate and the capacity does not equal the state size (25 times the word size).

Note that there may be more than one error. Only the first detected is returned.

ERRORS
The libkeccak_degeneralise_spec() function cannot fail.

EXAMPLE
This examples configure a struct libkeccak_spec to specify settings for Keccak[c = 512]:

int r;
struct libkeccak_spec spec;
struct libkeccak_generalised_spec 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;

SEE ALSO
libkeccak_generalised_spec_initialise(3), libkeccak_spec_check(3), libkeccak_spec_cshake(3), libkeccak_spec_sha3(3), libkeccak_spec_rawshake(3), libkeccak_spec_shake(3), libkeccak_state_initialise(3), libkeccak_hmac_initialise(3)