aboutsummaryrefslogtreecommitdiffstats
path: root/doc/info/libkeccak.texinfo
blob: b3516b3a6c3ac0a30e3bcc72b24070aea341b3aa (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
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@documentencoding UTF-8
@include macros.texinfo
@copying
@c --------------------------------------------------------------------------------
Copyright @copyright{} 2015  Mattias Andrée @e{maandree@@member.fsf.org}

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version@tie{}1.3
or any later version published by the Free Software Foundation; with the
Invariant Sections being the ``GNU Affero General Public License'', the
``GNU Free Documentation License'', with no Front-Cover Texts, and with
no Back-Cover Texts. A copy of the license is included in the section
entitled ``GNU Free Documentation License''.
@end quotation
@c --------------------------------------------------------------------------------
@end copying


@setfilename libkeccak.info
@settitle libkeccak -- Library for the Keccak-family hash functions
@documentlanguage en_GB
@finalout
@frenchspacing on
@afourpaper

@c @paragraphindent asis
@c @firstparagraphindent none
@c @exampleindent asis

@dircategory Libraries
@direntry
* libkeccak: (libkeccak).       Library for the Keccak-family hash functions.
@end direntry

@documentdescription
Developer reference manual for libkeccak, a library
for hashing with Keccak, SHA-3 RawSHAKE and SHAKE,
with support for bit-oriented data.
@end documentdescription
@c %**end of header



@ifnottex
@node Top
@top libkeccak -- Library for the Keccak-family hash functions
@insertcopying
@end ifnottex

@titlepage
@title libkeccak
@subtitle Library for the Keccak-family hash functions

@author by Mattias Andrée (maandree)

@page
@center `Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! …'
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents



@menu
* Overview::                                  Brief overview of libkeccak.
* Linking::                                   How to use libkeccak in your software.
* Selecting hash function::                   Selecting and tuning the function.

* GNU Affero General Public License::         Copying and sharing libkeccak.
* GNU Free Documentation License::            Copying and sharing this manual.

* Concept index::                             Index of concepts.
* Data type index::                           Index of data types.
* Function index::                            Index of functions.
@end menu
@c TODO @detailmenu (`C-c C-u m`)



@node Overview
@chapter Overview

libkeccak is a free software bit-oriented implementation
of the cryptographic hash function Keccak and its subsets
SHA-3 (Secure Hash Algorithm@tie{}3), RawSHAKE and SHAKE.

Being bit-oriented means that it supports messages of length
consisting of a non-whole number of bytes.

Keccak is a generic and tunable cryptographic hash function
that can be used for all customary tasks that required a
cryptographic hash function:
@itemize @bullet{}
@item
Password verification@footnote{Using additional squeezes, but not using iterated hashing.}
@item
Proof-of-work
@item
File and data identification
@item
Data integrity
@item
Pseudorandom generation@footnote{Although not too random, since entropi is not utilised.}
@item
Key derivation
@end itemize

libkeccak support secure erasure of sensitive data,
marshalling of hashing state, and indefinite output length.
It also has builting functions for hashing files and
wrapping the hash functions with HMAC@footnote{Although
doing so is unnecessary because the key can securely be
prepended to the message when using Keccak to produce
a message authentication code.}. This library implements
the Keccak algorithm using a lanewise implementation.
libkeccak must compelling feature however is that it is
licensed under the strongest free software license:
GNU Affero General Public License version@tie{}3
(see @ref{GNU Affero General Public License},) which
gives the user the four essential freedoms:
@itemize @bullet{}
@item
The freedom to run the program as you wish, for any purpose (freedom 0).
@item
The freedom to study how the program works, and change it so it does your computing as you wish (freedom 1).
@item
The freedom to redistribute copies so you can help your neighbor (freedom 2).
@item
The freedom to distribute copies of your modified versions to others (freedom 3).
@end itemize

This implementation is limited to state sizes up to,
and including, 1600 bits.



@node Linking
@chapter Linking

libkeccak's API is C standard library independent. This means
that libkeccak does not need to be compiled with the same
C standard library as software using it. However, the header
files contain @code{__attributes__}:s for GCC, if these are
incompatible with your compiler, your should temporarily define
a macro named @code{__attributes__} to remove all attributes.

Because of libkeccak's simplicity it does not have a pkg-config
file. Instead, you only need to specify the flag @code{-lkeccak}
when linking your binaries. No flags are required during compilation
(of object files.)

To make libkeccak's API available, include the header file
@file{<libkeccak.h>} in your source files.



@node Selecting hash function
@chapter Selecting hash function

Keccak-based hash functions have three parameters:
@itemize @bullet{}
@item
the bitrate,
@item
the capacity, and
@item
the output size.
@end itemize
@noindent
Selecting these is the first step when using the library.

The structure @code{libkeccak_spec_t} (@code{struct libkeccak_spec}),
is to specify these parameters. For the less tunable functions
SHA-3, RawSHAKE and SHAKE, these values can be set with the functions
@table @code
@item libkeccak_spec_sha3
Sets the parameters for SHA-3. It has two parameters:
@itemize @bullet{}
@item
Pointer to the @code{libkeccak_spec_t} where the settings shall be stored.
@item
The output size, that is the value appended to the name.
@end itemize

@item libkeccak_spec_rawshake
Sets the parameters for RawSHAKE (or SHAKE). It has three parameters:
@itemize @bullet{}
@item
Pointer to the @code{libkeccak_spec_t} where the settings shall be stored.
@item
The semicapacity, that is the value appended to the name.
@item
The output size.
@end itemize

@item libkeccak_spec_shake
Identical to @code{libkeccak_spec_rawshake}. Intended for SHAKE
rather than RawSHAKE.
@end table

For Keccak, these values shall be selected individually by hand.
Once the values have been selected, they can be checked for errors
with the function @code{libkeccak_spec_check}. It takes a pointer
to the specifications as its only parameters and returns zero if
there are no errors. If however there are errors, one of the values,
with somewhat self-explanatory names,@footnote{Their meaning is
documented in the header file @file{<libkeccak/spec.h>}.} will
be returned:
@itemize @bullet{}
@item
@code{LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE}
@item
@code{LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8}
@item
@code{LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE}
@item
@code{LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8}
@item
@code{LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE}
@item
@code{LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE}
@item
@code{LIBKECCAK_SPEC_ERROR_STATE_MOD_25}
@item
@code{LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT}
@item
@code{LIBKECCAK_SPEC_ERROR_WORD_MOD_8}
@end itemize

@code{libkeccak_spec_t}'s members are:
@table @code
@item bitrate
The bitrate, in bits.
@item capacity
The capacity, in bits.
@item output
The output size, in bits.
@end table

It is also possible to select some but not all of the parameters.
For this, the structure @code{libkeccak_generalised_spec_t}
(@code{struct libkeccak_generalised_spec}) is used. It extends
@code{libkeccak_spec_t} with two additional parameters
@table @code
@item state_size
The state size, in bits.
@item word_size
The word size, in bits.
@end table

By feeding a pointer to a @code{libkeccak_generalised_spec_t},
to the function @code{ibkeccak_generalised_spec_initialise},
all its members are set to @code{LIBKECCAK_GENERALISED_SPEC_AUTOMATIC},
a sentinel value that specifies that the parameter shall be
set automatically, to its default that depends on the other
parameters.

Once the members of a @code{libkeccak_generalised_spec_t} has
been set, it can be converted to a @code{libkeccak_spec_t},
which is neccessary for using the specifications. When doing
so, automatic values will be given a proper value.

To do this, the function @code{libkeccak_degeneralise_spec}
is used. It takes two parameters:
@itemize @bullet{}
@item
Input pointer to the @code{libkeccak_generalised_spec_t}.
@item
Output pointer to a @code{libkeccak_spec_t}.
@end itemize
@noindent
On success, zero is returned, otherwise one of the values, with
somewhat self-explanatory names,@footnote{Their meaning is documented
in the header file @file{<libkeccak/generalised-spec.h>}.} will be
returned:
@itemize @bullet{}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8}
@item
@code{LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE}
@end itemize



@node GNU Affero General Public License
@appendix GNU Affero General Public License
@include agpl-3.0.texinfo

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include fdl-1.3.texinfo

@node Concept index
@unnumbered Concept index
@printindex cp

@node Data type index
@unnumbered Data type index
@printindex tp

@node Function index
@unnumbered Function index
@printindex fn


@bye