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;