1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
|
.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK
.SH NAME
libkeccak_degeneralise_spec - Set all specification parameters to automatic
.SH SYNOPSIS
.nf
#include <libkeccak.h>
int libkeccak_degeneralise_spec(struct libkeccak_generalised_spec *\fIspec\fP, struct libkeccak_spec *\fIoutput_spec\fP);
.fi
.PP
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
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) */
};
.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.
.TP
.B 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).
.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 struct libkeccak_spec
to specify settings for Keccak[c = 512]:
.PP
.nf
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;
.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)
|
