From 7085817a3d356f7c3240fe1d616a5b1f1b56e38a Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sat, 9 Feb 2019 21:56:53 +0100 Subject: Fix makefile add add OSCONFIGFILE MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- man3/libkeccak_keccaksum_fd.3 | 119 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 119 insertions(+) create mode 100644 man3/libkeccak_keccaksum_fd.3 (limited to 'man3/libkeccak_keccaksum_fd.3') diff --git a/man3/libkeccak_keccaksum_fd.3 b/man3/libkeccak_keccaksum_fd.3 new file mode 100644 index 0000000..2fc1b21 --- /dev/null +++ b/man3/libkeccak_keccaksum_fd.3 @@ -0,0 +1,119 @@ +.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_keccaksum_fd - Calculate a Keccak hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_keccaksum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + const libkeccak_spec_t *\fIspec\fP, char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_keccaksum_fd () +function calculates a Keccak hashsum of a file, whose file +desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm tuning is specified by +.IR *spec . +.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_keccaksum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_keccaksum_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_keccaksum_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_keccaksum_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_keccaksum_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_keccaksum_fd () +does not stop if interrupted +.RI ( read (2) +returns +.BR EINTR .) +.PP +.BR libkeccak_keccaksum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_keccaksum_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_keccaksum_fd(STDIN_FILENO, &state, &spec, 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_generalised_sum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_shakesum_fd (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 -- cgit v1.2.3-70-g09d2