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
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
|
.TH LIBKECCAK_DIGEST 3 LIBKECCAK
.SH NAME
libkeccak_digest - Complete the hashing of a message with erasure
.SH SYNOPSIS
.nf
#include <libkeccak.h>
int libkeccak_digest(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP,
size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP);
.fi
.PP
Link with
.IR -lkeccak .
.SH DESCRIPTION
The
.BR libkeccak_digest ()
function absorbs the last part of (or all of) a message,
and returns the hash of the entire message. The last part
of the message is specified by the
.I msg
parameter, and its byte-size is specified by the
.I msglen
parameter. If all of the message has already be processed
by calls to the
.BR libkeccak_update (3),
.BR libkeccak_fast_update (3),
or
.BR libkeccak_zerocopy_update (3)
function (with the same pointer on
.IR state ,)
.I msg
and
.I msglen
should be set to
.I NULL
and 0, respectively.
.PP
If the message is not comprised a whole number of bytes,
the number of bits, modulus 8, in the message should be
specified in the
.I bits
parameter.
.I msglen
must only count the number of whole bytes, that is, the
floor of the number of bits in the message divided by 8.
.PP
.I suffix
should be a NUL-terminated string of ASCII '1':s
and '0':s, representing the bits that should be appended to
the message. If this string is empty,
.I NULL
may be used instead. This is used to select hash algorithm.
For pure Keccak,
.I NULL
or \(dq\(dq is used. For the other algorithms the constants
.B LIBKECCAK_SHA3_SUFFIX
(for SHA-3),
.B LIBKECCAK_RAWSHAKE_SUFFIX
(for RawSHAKE), and
.B LIBKECCAK_SHAKE_SUFFIX
(for SHAKE), or the return of the
.BR libkeccak_cshake_suffix (3)
function (for cSHAKE), are used.
.PP
The hash of the message will be stored to
.IR hashsum ,
unless
.I hashsum
is
.I NULL
(which increases the performance of the call.) A total of
.RI (( state->n
+ 7) / 8) bytes will be written to the beginning of
.IR hashsum .
Therefore,
.I hashsum
needs at least an allocation size of that number of bytes.
.PP
The
.BR libkeccak_digest ()
function may reallocate the state's message chunk buffer.
When doing so, it attempts to do so as securely as possible,
rather than as fast as possible.
.SH RETURN VALUES
The
.BR libkeccak_digest ()
function returns 0 upon successful completion. On error,
-1 is returned and
.I errno
is set to describe the error.
.SH ERRORS
The
.BR libkeccak_digest ()
function may fail for any reason specified by the function
.BR malloc (3).
.SH EXAMPLE
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.
.PP
.nf
struct libkeccak_state state;
struct libkeccak_spec 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, \(dq\(dq, binhash) < 0)
goto fail;
libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf(\(dq%s\en\(dq, hexhash);
libkeccak_state_destroy(&state);
.fi
.SH NOTES
For cSHAKE, the
.BR libkeccak_cshake_initialise (3),
must be called, once, immediately after
state initialisation; before the first
call to any of the
.BR libkeccak_fast_update (),
.BR libkeccak_zerocopy_update (),
.BR libkeccak_update (),
and
.BR libkeccak_digest ()
functions.
.SH SEE ALSO
.BR libkeccak_state_initialise (3),
.BR libkeccak_cshake_initialise (3),
.BR libkeccak_fast_update (3),
.BR libkeccak_update (3),
.BR libkeccak_cshake_suffix (3),
.BR libkeccak_fast_digest (3),
.BR libkeccak_zerocopy_digest (3),
.BR libkeccak_simple_squeeze (3),
.BR libkeccak_fast_squeeze (3),
.BR libkeccak_squeeze (3)
|
