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
|
.TH LIBKECCAK_GENERALISED_SUM_FD 3 LIBKECCAK
.SH NAME
libkeccak_generalised_sum_fd - Calculate the hash of a file
.SH SYNOPSIS
.LP
.nf
#include <libkeccak.h>
.P
int
libkeccak_generalised_sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP,
const libkeccak_spec_t *\fIspec\fP,
const char *\fIsuffix\fP, char *\fIhashsum\fP);
.fi
.P
Link with
.IR -lkeccak .
.SH DESCRIPTION
The
.BR libkeccak_generalised_sum_fd ()
function calculates the hash of a file, whose file desriptor is
specified by
.I fd
(and should be at the beginning of the file.) The hash algorithm
is specified by
.I *spec
and
.IR suffix ,
where
.I *spec
is the tuning of the algorithm and
.I suffix
is the bits append to the message (or
.I NULL
if none.)
.PP
The hash is stored in binary form to
.IR hashsum .
.I hashsum
should have an allocation size of at least
.RI ((( spec->output
+ 7) / 8) * sizeof(char)).
.PP
.I *state
should not be initialised.
.BR libkeccak_generalised_sum_fd ()
initialises
.I *state
itself. Therefore there would be a memory leak if
.I *state
is already initialised.
.SH RETURN VALUES
The
.BR libkeccak_generalised_sum_fd ()
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_generalised_sum_fd ()
function may fail for any reason, except those resulting
in
.I errno
being set to
.BR EINTR ,
specified for the functions
.BR read (2),
.BR malloc (3),
and
.BR realloc (3).
.SH NOTES
Be aware,
.BR libkeccak_generalised_sum_fd ()
hashes the file until the end has been reached. For pipes
and sockets and this means until the file has been closed.
But for character devices, this usually means never.
Attempting to hash files in /dev is therefore usually a
bad idea.
.BR libkeccak_generalised_sum_fd ()
does not check for the file length or file type before
hashing as this could limit what you can do, and make
the library more complex.
.PP
.BR libkeccak_generalised_sum_fd ()
does not stop if interrupted
.RB ( read (2)
returns
.BR EINTR .)
.PP
.BR libkeccak_generalised_sum_fd ()
assumes all information is non-sensitive, and will
therefore not perform any secure erasure of information.
.PP
.BR libkeccak_generalised_sum_fd ()
does not validate the tuning of the algorithm.
.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.
.LP
.nf
libkeccak_state_t state;
libkeccak_spec_t spec;
char binhash[256 / 8];
char hexhash[256 / 8 * 2 + 1];
spec.bitrate = 1024;
spec.capacity = 576;
spec.output = 256;
if (libkeccak_generalised_sum_fd(STDIN_FILENO, &state, &spec, NULL, binhash) < 0)
goto fail;
libkeccak_behex_lower(hexhash, binhash, sizeof(binhash));
printf("%s\\n", hexhash);
libkeccak_state_destroy(&state);
.fi
.SH SEE ALSO
.BR libkeccak_behex_lower (3),
.BR libkeccak_behex_upper (3),
.BR libkeccak_keccaksum_fd (3),
.BR libkeccak_sha3sum_fd (3),
.BR libkeccak_rawshakesum_fd (3),
.BR libkeccak_shakesum_fd (3),
.BR libkeccak_spec_sha3 (3),
.BR libkeccak_spec_shake (3),
.BR libkeccak_spec_rawshake (3),
.BR libkeccak_spec_check (3),
.BR libkeccak_generalised_spec_initialise (3),
.BR libkeccak_state_initialise (3)
.SH BUGS
Please report bugs to https://github.com/maandree/libkeccak/issues or to
maandree@kth.se
|
