aboutsummaryrefslogtreecommitdiffstats
path: root/doc/info/libkeccak.texinfo
blob: 089f06f98b93069036a7148798ad11b982d80458 (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
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@documentencoding UTF-8
@include macros.texinfo
@copying
@c --------------------------------------------------------------------------------
Copyright @copyright{} 2015  @w{Mattias Andrée @e{maandree@@kth.se}}

@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.
* State of the hashing::                      The structure used to keep track of the hashing process.
* Hashing messages::                          Functions used to hash a message.
* Hexadecimal hashes::                        Converting between binary and hexadecimal.
* Hashing files::                             Functions used to hash entire files.
* Message authentication::                    Functions used for message authentication codes.

* 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



@node Overview
@chapter Overview

@cpindex Orientation
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.

@cpindex Uses
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 number 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

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



@node Linking
@chapter Linking

@cpindex Compiling
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.

@cpindex @command{pkg-config}
@cpindex Linking
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

@cpindex Parameters
@cpindex Tuning
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.

@tpindex libkeccak_spec_t
@tpindex struct libkeccak_spec
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
@fnindex libkeccak_spec_sha3
@cpindex SHA-3
@cpindex Secure Hash Algorithm 3
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
@fnindex libkeccak_spec_rawshake
@cpindex 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
@fnindex libkeccak_spec_shake
@cpindex SHAKE
Identical to @code{libkeccak_spec_rawshake}. Intended for SHAKE
rather than RawSHAKE.
@end table

@fnindex libkeccak_spec_check
@cpindex Keccak
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

@tpindex libkeccak_spec_t
@tpindex struct libkeccak_spec
@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

@tpindex libkeccak_generalised_spec_t
@tpindex struct libkeccak_generalised_spec
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

@fnindex libkeccak_generalised_spec_initialise
By feeding a pointer to a @code{libkeccak_generalised_spec_t},
to the function @code{libkeccak_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 necessary for using the specifications. When doing
so, automatic values will be given a proper value.

@fnindex libkeccak_degeneralise_spec
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 State of the hashing
@chapter State of the hashing

@tpindex libkeccak_state_t
@tpindex struct libkeccak_state
@cpindex Hashing
@cpindex State
Hashing of a message is done by feeding segments of the
message to functions until all of the message has been
processed, and than the users may repeat the last phase
any number of times. Because functions are called multiple
times, the state of the process need to be stored in
a state structure. The structure used in libkeccak to
keep track of the state is called @code{libkeccak_state_t}
(@code{struct libkeccak_state}).

@fnindex libkeccak_state_initialise
@cpindex Initialise
Before you can use the functions for hashing a message,
you must allocate a state and initialise it.
To initialise a state, use the function
@code{libkeccak_state_initialise}. Its first argument
should be a pointer to the state variable, that is,
a @code{libkeccak_state_t*}. The second argument should
be a pointer to the specifications, that is, a
@code{const libkeccak_spec_t*}, see @ref{Selecting hash function}.
@code{libkeccak_state_initialise} till return zero
upon successful completion, and otherwise set
@code{errno} to describe the error and return @code{-1}.

@fnindex libkeccak_state_destroy
@fnindex libkeccak_state_fast_destroy
@fnindex libkeccak_state_wipe
@fnindex libkeccak_state_wipe_sponge
@fnindex libkeccak_state_wipe_message
@cpindex Cleanup
Once done with a state structure, you should release
allocated resources that are stored in the structure.
This can be done either by calling the function
@code{libkeccak_state_destroy} or by calling the function
@code{libkeccak_state_fast_destroy}. These two functions
are almost identical, both takes a pointer to the
state as its only parameter, and neither return a value.
However, @code{libkeccak_state_fast_destroy} will only
release allocations used by the state; @code{libkeccak_state_destroy}
will also securely release all sensitive information
in the state, by calling the function @code{libkeccak_state_wipe}:
the state of the sponge, by calling the function
@code{libkeccak_state_wipe_sponge}, and the message
buffer, by calling the function @code{libkeccak_state_wipe_message}.
@code{libkeccak_state_wipe}, @code{libkeccak_state_wipe_sponge}
and @code{libkeccak_state_wipe_message} takes a
pointer to the state as their only parameter, and
none of them have a return value.

@fnindex libkeccak_state_reset
@cpindex Reuse
An alternative to destroying a state, you can reset
it if you want to reuse it to hash another message
using the same hashing function specifications.
This is done by calling @code{libkeccak_state_reset}
instead of @code{libkeccak_state_fast_destroy}.
It takes a pointer to the state as its only parameter
and does not return a value.

@cpindex Initialise
@cpindex Cleanup
@cpindex Allocation
If you want to use dynamic instead of static allocation
for the state, instead of calling @code{malloc} and
@code{free} yourself, libkeccak offers functions that
does this for you:
@table @code
@item libkeccak_state_create
@fnindex libkeccak_state_create
@fnindex libkeccak_state_initialise
Identical to @code{libkeccak_state_initialise}, except
it does have the first parameter, but it has the second
parameter (the specifications). It returns a pointer
to the allocate state upon successful completion, and
returns @code{NULL} on error, in which case, @code{errno}
is set to describe the error.

@item libkeccak_state_fast_free
@fnindex libkeccak_state_fast_free
@fnindex libkeccak_state_fast_destroy
Identical to @code{libkeccak_state_fast_destroy}, except
it also frees the allocation of the state.

@item libkeccak_state_free
@fnindex libkeccak_state_free
@fnindex libkeccak_state_destroy
Identical to @code{libkeccak_state_destroy}, except
it also frees the allocation of the state.
@end table

@cpindex Duplication
@cpindex Allocation
libkeccak also has two functions for copying a state:
@table @code
@item libkeccak_state_copy
@fnindex libkeccak_state_copy
Takes an output pointer to a state as its first parameter,
and a pointer to the state to copy as its second parameter.
The content of the second parameter will be duplicated into
the first parameter. The state passed in the first parameter
must not be initialised, lest you will suffer a memory leak.
The function returns zero upon successful completion, and
on error, sets @code{errno} to describe the error and returns
@code{-1}.

@item libkeccak_state_duplicate
@fnindex libkeccak_state_duplicate
Identical to @code{libkeccak_state_copy}, except it only
has one parameter, a pointer to the state to copy, and
returns a pointer to a state it has allocated and copied
the state to. On error, @code{errno} is set to describe the
error and @code{NULL} is returned.
@end table

@cpindex Marshal
@cpindex Serialisation
@cpindex Unmarshal
@cpindex Deserialisation
The library also offers functions for marshalling a state,
which can be useful when implementing programs that can
reexecuted into updated version of itself.
@table @code
@item libkeccak_state_marshal_size
@fnindex libkeccak_state_marshal_size
Takes a pointer to a state to marshal as its only parameter,
and returns the number of bytes required to marshal it.

@item libkeccak_state_marshal
@fnindex libkeccak_state_marshal
Takes a pointer to a state to marshal as its first parameter,
and the buffer, to where the state shall be marshalled, as
its second parameter. The function will marshal the state
into the buffer and return the number of bytes written,
which will be the same as @code{libkeccak_state_marshal_size}
returns for the state.

@item libkeccak_state_unmarshal
@fnindex libkeccak_state_unmarshal
Takes an output pointer for the unmarshalled state as its
first parameter, and the buffer where the state is marshalled
as its second parameter. The function will unmarshal the
state from the buffer and store it into the pointer passed
to the first parameter. The function will then return the
number of read bytes, which will be the same as
@code{libkeccak_state_marshal_size} and @code{libkeccak_state_marshal}
returned for the state when it was marshalled, as what they
will return if called again with the unmarshalled function.
On error, @code{errno} is set to describe the error and zero
is returned.

@item libkeccak_state_unmarshal_skip
@fnindex libkeccak_state_unmarshal_skip
Figures out how many bytes the marshalled state uses,
so that the buffers pointer can be incremented with
this value to skip pass the marshalled state.
@end table



@node Hashing messages
@chapter Hashing messages

@fnindex libkeccak_update
@fnindex libkeccak_digest
@fnindex libkeccak_fast_update
@fnindex libkeccak_fast_digest
@cpindex Hashing
Once a state has been initialised, a message can be hashed.
To hash a message the functions @code{libkeccak_update} and
@code{libkeccak_digest} are used, or its variants that do
not securely release sensitive information:
@code{libkeccak_fast_update} and @code{libkeccak_fast_digest},
these are otherwise identical to @code{libkeccak_update}
and @code{libkeccak_fast_update}, respectively.
@table @code
@item libkeccak_update
@fnindex libkeccak_update
@fnindex libkeccak_fast_update
This function shall be called while you do not know that
you have reached the end of the message. It has three
parameters:
@itemize @bullet{}
@item
A pointer to the state. See @ref{State of the hashing}.
@item
The beginning of the chunk of the message to process.
@item
The number of bytes in the message to process.
@end itemize
Note that a part of the message is input, not necessarily
the entire message. The chunks must be input sequentially.
The function returns zero upon success completion. On error,
@code{errno} is set to describe the error and @code{-1} is
returned. The input chunk should not be empty.

@item libkeccak_digest
@fnindex libkeccak_digest
@fnindex libkeccak_fast_digest
This function shall be called either with the last chunk
of the message, or when all chunks as been input to
@code{libkeccak_update} or @code{libkeccak_fast_update}.
The function's first three parameters are the same as
for @code{libkeccak_update}, however, the chunk may be
@code{NULL} and then length zero if all chunks have
been processed by @code{libkeccak_update} or @code{libkeccak_fast_update}.
However, it also has three additional parameters:
@itemize @bullet{}
@item
The number of bits at the end of the message that
are not covered by the third argument. This enables
messages of non-whole byte length.
@item
A NUL-terminated string of ASCII ones and zeroes,
describing the additional bits to suffix the message;
or @code{NULL} if none. This is used to select between
Keccak, SHA-3, RawSHAKE and SHAKE. Use one of the constants:
@table @asis
@item @code{LIBKECCAK_SHA3_SUFFIX} or @code{"01"}
@cpindex SHA-3
@cpindex Secure Hash Algorithm 3
For SHA-3.
@item @code{LIBKECCAK_RAWSHAKE_SUFFIX} or @code{"11"}
@cpindex RawSHAKE
For RawSHAKE.
@item @code{LIBKECCAK_SHAKE_SUFFIX} or @code{"1111"}
@cpindex SHAKE
For SHAKE.
@item @code{NULL} or @code{""}
@cpindex Keccak
For Keccak.
@end table
@item
@cpindex Output size
@cpindex Hash size
@cpindex Size, hash
Output buffer for the hash, in binary. Should be
allocated to fit @code{(state.n + 7) / 8} @w{@code{char}:s},
where @code{state} is the state variable. Alternatively
it may be @code{NULL}, in which case the hash is not
retrieved.
@end itemize
The function returns zero upon success completion. On error,
@code{errno} is set to describe the error and @code{-1} is
returned. The input chunk should not be empty.
@end table

@cpindex Key derivation
@cpindex Pseudorandom number generation
@cpindex Random number generation
@cpindex Output, extended
@cpindex Extended output
libkeccak also has three functions for repeating the squeeze
phase. Neither of these function have a return value, and
their first parameter is a pointer to the state.
@table @code
@item libkeccak_simple_squeeze
@fnindex libkeccak_simple_squeeze
Perform a number of additional rounds of @w{@sc{Keccak}--@i{f}}.
The number of rounds is specified in the second parameter.
@item libkeccak_fast_squeeze
@fnindex libkeccak_fast_squeeze
Perform a number of additional rounds of @w{@sc{Keccak}--@i{f}}.
The number will be exactly enough to get a number of additional
digests. The number of digests is specified in the second parameter.
@item libkeccak_squeeze
@fnindex libkeccak_squeeze
Squeeze out another digest. The hash will be stored in the
second parameter, which should be allocated to fit
@code{(state.n + 7) / 8} @w{@code{char}:s}.
@end table



@node Hexadecimal hashes
@chapter Hexadecimal hashes

@fnindex libkeccak_digest
@fnindex libkeccak_fast_digest
@fnindex libkeccak_squeeze
@cpindex Conversion
@cpindex Binary hash
@cpindex Hexadecimal hash
@cpindex Presentation, hash
@cpindex Hash, presentation
The functions that return hashes: @code{libkeccak_digest},
@code{libkeccak_fast_digest} and @code{libkeccak_squeeze},
store the hashes in binary format. However, it must often
preferred to have hashes in hexadecimal, so that they are
human-readable. This library hash two functions for
converting from binary to hexadecimal, and one function
for converting from hexadecimal to binary. Neither of
these functions have a return value.
@table @code
@item libkeccak_behex_lower
@itemx libkeccak_behex_upper
@fnindex libkeccak_behex_lower
@fnindex libkeccak_behex_upper
Convert from binary to hexadecimal. @code{libkeccak_behex_lower}
converts to lowercase hexadecimal, and @code{libkeccak_behex_upper}
converts to uppercase hexadecimal. Their first parameter
is the output buffer for the hexadecimal representation,
which will be NUL-terminated, it should be allocated to
fit @code{2 * n + 1} @w{@code{char}:s}, where @code{n} is
the length of the input hash. The second parameter is
the input hash, in binary. The third, and final, parameter
is the length of the input bash.

@item libkeccak_unhex
@fnindex libkeccak_unhex
Convert from hexadecimal to binary. Both uppercase and
lowercase, as well as mixed case, is supported as input.
The first parameter is the output buffer for the binary
representation, it should be allocated to fit
@code{strlen(hashsum) / 2} @w{@code{char}:s}, where
@code{hashsum} is the hash in hexadecimal, the input;
this is the number of bytes that will be stored in
the output. The second, and final, parameter is the
hash in hexadecimal, with must be NUL-terminated,
and have an even length.
@end table



@node Hashing files
@chapter Hashing files

@cpindex Files
@cpindex Hash files
libkeccak provides functions for calculating
hashes of files directly, from a file descriptor.

@fnindex libkeccak_generalised_sum_fd
The generalised function is named
@code{libkeccak_generalised_sum_fd}. It has
five parameters:
@itemize @bullet{}
@item
The file descriptor.
@item
A pointer to a state variable. Must not be
initalised, lest you will suffer a memory leak.
@item
The specifications for the hashing functions.
@item
The message suffix.
@item
The output buffer for the binary hash.
It must have an allocation size of at least
@code{(spec->output / 8) * sizeof(char)},
where @code{spec} is the third argument, or
be @code{NULL}.
@end itemize
@code{libkeccak_generalised_sum_fd} returns
zero upon successful completion. On error,
@code{errno} is set to describe the error,
and @code{-1} is returned.

There are also algorithm specific functions.
@table @code
@item libkeccak_keccaksum_fd
@fnindex libkeccak_keccaksum_fd
This function is used for Keccak without message
suffix. It is identical to @code{libkeccak_generalised_sum_fd}
sans the fourth parameter (the message suffix.)

@item libkeccak_sha3sum_fd
@fnindex libkeccak_sha3sum_fd
This function is used for SHA-3. It is similar
to @code{libkeccak_generalised_sum_fd}, however
it does not have the fourth parameter, and the
third parameter is simple the the output size.
The output buffer must have and allocation size
of at least @code{(output / 8) * sizeof(char)},
where @code{output} is the third parameter, or
be @code{NULL}.

@item libkeccak_rawshakesum_fd
@fnindex libkeccak_rawshakesum_fd
This function is used for RawSHAKE, it is
otherwise identical to @code{libkeccak_sha3sum_fd},
except it as a parameter for the semicapacity
before the output size, that is to say, as its
third parameter.

@item libkeccak_shakesum_fd
@fnindex libkeccak_shakesum_fd
This function is used for SHAKE, it is
otherwise identical to @code{libkeccak_rawshakesum_fd}.
@end table



@node Message authentication
@chapter Message authentication

@cpindex Message authentication code
@cpindex MAC
@cpindex HMAC
@cpindex Keyed-hash message authentication code
libkeccak supports HMAC. Note that secure message
authentication codes can be trivially be created
with Keccak by simple prepending the key to the
message; although it will not be HMAC. This makes
Keccak a good hash function alternative for people
who knows next to nothing about cryptography.

@tpindex libkeccak_hmac_state_t
@tpindex struct libkeccak_hmac_state
To keep track of the hashing state, the structure
@code{libkeccak_hmac_state_t} (@code{struct libkeccak_hmac_state})
is used. It has a number of methods analogous to
those for @code{libkeccak_state_t}:
@table @code
@item libkeccak_hmac_initialise
@fnindex libkeccak_hmac_initialise
Has for parameters: pointer to a @code{libkeccak_hmac_state_t}
to initialise, hashing specifications (@code{const libkeccak_spec_t*}),
binary key, and the length of the key.

@item libkeccak_hmac_create
@fnindex libkeccak_hmac_create
Similar to @code{libkeccak_hmac_initialise}. It does
not have a @code{libkeccak_hmac_state_t*} as an output
parameter, rather it returns one.

@item libkeccak_hmac_reset
@fnindex libkeccak_hmac_reset
Resets the sponge and the sets the key, by
calling @code{libkeccak_hmac_set_key}. It
has three parameters: pointer to the
@code{libkeccak_hmac_state_t}, the binary key,
and the length of the key.
The key will not be set if the second
argument is @code{NULL}.

@item libkeccak_hmac_wipe
@fnindex libkeccak_hmac_wipe
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_destroy
@fnindex libkeccak_hmac_fast_destroy
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_destroy
@fnindex libkeccak_hmac_destroy
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_free
@fnindex libkeccak_hmac_fast_free
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_free
@fnindex libkeccak_hmac_free
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_copy
@fnindex libkeccak_hmac_copy
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_duplicate
@fnindex libkeccak_hmac_duplicate
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_marshal_size
@fnindex libkeccak_hmac_marshal_size
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_marshal
@fnindex libkeccak_hmac_marshal
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_unmarshal
@fnindex libkeccak_hmac_unmarshal
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_unmarshal_skip
@fnindex libkeccak_hmac_unmarshal_skip
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_update
@fnindex libkeccak_hmac_fast_update
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_update
@fnindex libkeccak_hmac_update
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_fast_digest
@fnindex libkeccak_hmac_fast_digest
Perfectly analogous to the @code{libkeccak_state_t} counterpart.

@item libkeccak_hmac_digest
@fnindex libkeccak_hmac_digest
Perfectly analogous to the @code{libkeccak_state_t} counterpart.
@end table

@fnindex libkeccak_hmac_set_key
It also has the method @code{libkeccak_hmac_set_key} which
can be used set the key. This function is identical to
@code{libkeccak_hmac_reset}, except it will not reset the
sponge, and the second argument must not be @code{NULL}.



@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

TODO examples