aboutsummaryrefslogtreecommitdiffstats
path: root/libhashsum_init_shake_hasher.3
blob: 5ab1320d3684168cdd1392705f2d3b0b0ba0a550 (plain) (blame)
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
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
.TH LIBHASHSUM_INIT_SHAKE_HASHER 3 libhashsum
.SH NAME
libhashsum_init_shake_hasher - initialise state for SHAKE hashing

.SH SYNOPSIS
.nf
#include <libhashsum.h>

\fBstruct libhashsum_hasher\fP {
	enum libhashsum_algorithm \fIalgorithm\fP;
	const char *\fIalgorithm_string\fP;
	size_t \fIinput_block_size\fP;
	size_t \fIhash_size\fP;
	unsigned char *\fIhash_output\fP;
	unsigned char \fIsupports_non_whole_bytes\fP;
	unsigned char \fIstandard_partial_byte_input_encoding\fP;
	unsigned char \fIstandard_partial_byte_output_encoding\fP;
	size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP);
	int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP);
	int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP);
	void (*\fIstretch\fP)(struct libhashsum_hasher *\fPthis\fP, int \fPskip\fP, void *\fPbuffer\fP);
	void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP);
	union libhashsum_state { /* definition omitted */ } \fIstate\fP;
};

int \fBlibhashsum_init_shake_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhcapbits\fP, size_t \fIhashbits\fP);
.fi
.PP
Link with
.I -lhashsum
.IR "-lkeccak" .

.SH DESCRIPTION
The
.B libhashsum_init_shake_hasher
function initialises
.I *hasher
for hashing using the cryptographic hash function
SHAKE, and stores hash function information and
hashing functions for SHAKE in
.IR *hasher .
.PP
.I hcapbits
shall be the hash functions's (the Keccak sponge's)
capacity, in bits, divided by 2, which shall be
either 128, 256, or 512.
.PP
.I hashbits
shall the hash size in bits or 0, for the default
hash size (which is
.IR hcapbits ).
.PP
.I hasher->algorithm
will be set to
.I LIBHASHSUM_SHAKE128
(if
.I hcapbits
is 128),
.I LIBHASHSUM_SHAKE256
(if
.I hcapbits
is 256), or
.I LIBHASHSUM_SHAKE512
(if
.I hcapbits
is 512).
.PP
.I hasher->algorithm_string
will be set to
.RB \(dq SHAKE \fIhcapbits\fP\(dq,
or (if
.I hashbits
is neither 0 nor
.IR hcapbits )
.RB \(dq SHAKE \fIhcapbits\fP [n= \fIhashbits\fP ] \(dq,
in which case
.I hasher->algorithm_string
will point to a buffer in
.IR hasher->state .
.PP
.I hasher->input_block_size
will be set to the block size, in bytes.
.PP
.I hasher->hash_size
will be set to the hash size, in bytes
.RI ( (hashbits?hashbits:hcapbits)/8 ).
.PP
.I hasher->hash_output
will be set to
.IR NULL .
.PP
.I hasher->supports_non_whole_bytes
will be set to 1
to indicate that the
.I *hasher->finalise
and
.I *hasher->finalise_const
functions support non-zero values in their
.I extra_bits
parameter.
.PP
.I hasher->process
will be set to a pointer to the function to call
to feed, and process, data into the hash function.
Its parameter
.I this
shall be set to
.IR hasher .
Its parameter
.I data
parameter shall be set to the buffer of data to
process, and its parameter
.I bytes
shall set to the number of bytes to process from
.IR data .
.I *hasher->process
will return the number of bytes processed, which
will be a multiple of
.IR hasher->input_block_size
no greater than
.IR bytes .
.PP
.I hasher->finalise_const
will be set to a pointer to the function to call
once the entire text being hashed has been loaded,
and to get the hash of the text. Its parameter
.I this
shall be set to
.IR hasher .
Its parameter
.I data
shall be set to the beginning of any yet unprocessed
data, and its parameter
.I bytes
shall be set to the number of bytes to process from
.IR data .
Its parameter
.I extra_bits
shall be set to the number of bits to process from
the lower bits of the incomplete byte
.IR data[bytes] .
The
.I *hasher->finalise_const
function will return 0 upon successful completion,
and set
.I hasher->hash_output
to a pointer to a buffer in
.I hasher->state
containing the binary hash of the processed data.
Otherwise, the function will return -1, and set
.I errno
to indicate the error. However, if the user has
already set
.I hasher->hash_output
to a
.RI non- NULL
pointer, the function will output the binary hash
to that pointer instead without redirecting
.I hasher->hash_output
(the application must make sure this buffer is
sufficiently large). The function will failure if:
.RS
.TP
.B EINVAL
.I extra_bits
is 8 or greater.
.RE
.PP
.I hasher->finalise
will be set to the pointer to a function that
is an alternative to
.I *hasher->finalise_const
that can support zero-copy provided that the
buffer input as the argument
.I data
is sufficiently large. The
.I *hasher->finalise
function may rewrite
.I data
and shall is does not safe to use for multiple
hashers (if the same text is hashed using multiple
hashers,
.I *hasher->finalise_const
must be used). The
function's parameter
.I size
shall be set to the size of the buffer
.IR data .
.I *hasher->finalise
is otherwise identical to
.IR *hasher->finalise_const .
.PP
.I hasher->stretch
will be set to
.IR NULL ,
however upon successful completion of
.I *hasher->finalise
or
.IR *hasher->finalise_const ,
.I hasher->stretch
will be set to point to a function that can be
used to extend the hash by
.I hasher->hash_size
bytes, and can be called repeated without limitation.
The hash extent will be written to a buffer in
.I hasher->state
(which
.I *hasher->finalize
and
.I *hasher->finalize_const
also write the hash to), and
.I hasher->hash_output
will be set to point to this buffer.
.IR *hasher->stretch 's
parameter
.I this
shall be
.IR hasher .
Its parameter
.I skip
can be set to non-zero if the hash extent should
be discarded
.RI ( hasher->hash_output
will not be set in this case).
Its parameter
.I buffer
shall be
.I NULL
for the above described behaviour, or an sufficiently
large buffer the function shall output the hash extent
to. If
.I buffer
is
.RI non- NULL ,
.I hasher->hash_output
will be set to
.IR NULL ).
.PP
.I hasher->destroy
will be set to a pointer to a function to to
call, with
.I hasher
as the argument, deallocate dynamically
allocated data, which may invalidate any
pointer in
.IR *hasher .
.PP
.I hasher->state
will be initialised, it shall be treated as
internal to the library's implementation, and
may change between versions.
.PP
.I hasher
must not be
.IR NULL .

.SH RETURN VALUE
Upon successful completion, the
.B libhashsum_init_shake_hasher
function returns 0. Otherwise,
the function returns -1 and sets
.I errno
to indicate the error. If -1
is returned, the state of
.I *hasher
is undefined.

.SH ERRORS
The
.B libhashsum_init_shake_hasher
function fails if:
.TP
.B ENOSYS
Support was excluded at compile time.
.TP
.B ENOMEM
Insufficient memory available.
.TP
.B EINVAL
.I hcapbits
is neither 128, 256, nor 512.
.TP
.B EINVAL
.I hashbits
is too large.

.SH EXTENDED DESCRIPTION
libhashsum has normalises the all implemented hash
functions to always use the least significant bits
in non-whole octets, however each hash function has
its unstandarded. To make it easier to create an
application the use the same encoding of partial
octets as other application using any particular
hash function,
.B struct libhashsum_hasher
contains two fields:
.I standard_partial_byte_input_encoding
and
.IR standard_partial_byte_output_encoding ;
which are merely informtional. They are not set to
specify how libhashsum expects and encodes non-whole
octets, but rather specify how partial bytes are
encoded in the reference implementation or
specification of a hash function.
.PP
SHAKE supports non-whole octet both in its
input and its output, and in its standard uses
the least significant bits of non-whole octets
both in the input and in the output, thus
.I this->standard_partial_byte_input_encoding
and
.I this->standard_partial_byte_output_encoding
will both be set to
.IR LIBHASHSUM_LEAST_SIGNIFICANT ,
which the same behaviour as libhashsum implements.

.SH HISTORY
libhashsum 1.0.

.SH NOTES
.IR "libhashsum_init_shake_hasher(hasher, 128, hashbits)" ,
.IR "libhashsum_init_shake_hasher(hasher, 256, hashbits)" ,
and
.I libhashsum_init_shake_hasher(hasher, 512, hashbits)
are equivalent to
.IR "libhashsum_init_shake128_hasher(hasher, hashbits)" ,
.IR "libhashsum_init_shake256_hasher(hasher, hashbits)" ,
and
.I libhashsum_init_shake512_hasher(hasher, hashbits)
respectively.

.SH SEE ALSO
.BR libhashsum (7),
.BR libhashsum_init_shake128_hasher (3),
.BR libhashsum_init_shake256_hasher (3),
.BR libhashsum_init_shake512_hasher (3)