From be0ef12ca3bd2c5d81b4cb8d978e20d8f2d20687 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Tue, 6 Oct 2015 16:09:31 +0200 Subject: add libkeccak_keccaksum_fd.3, libkeccak_rawshakesum_fd.3, libkeccak_sha3sum_fd.3, and libkeccak_shakesum_fd.3 + m libkeccak_generalised_sum_fd.3 MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- doc/man/libkeccak_generalised_sum_fd.3 | 5 +- doc/man/libkeccak_keccaksum_fd.3 | 102 +++++++++++++++++++++++++++++++++ doc/man/libkeccak_rawshakesum_fd.3 | 97 +++++++++++++++++++++++++++++++ doc/man/libkeccak_sha3sum_fd.3 | 95 ++++++++++++++++++++++++++++++ doc/man/libkeccak_shakesum_fd.3 | 97 +++++++++++++++++++++++++++++++ 5 files changed, 395 insertions(+), 1 deletion(-) create mode 100644 doc/man/libkeccak_keccaksum_fd.3 create mode 100644 doc/man/libkeccak_rawshakesum_fd.3 create mode 100644 doc/man/libkeccak_sha3sum_fd.3 create mode 100644 doc/man/libkeccak_shakesum_fd.3 diff --git a/doc/man/libkeccak_generalised_sum_fd.3 b/doc/man/libkeccak_generalised_sum_fd.3 index 2518cc0..ac50e10 100644 --- a/doc/man/libkeccak_generalised_sum_fd.3 +++ b/doc/man/libkeccak_generalised_sum_fd.3 @@ -25,7 +25,7 @@ The hash is stored in binary form to \fIhashsum\fP. \fIhashsum\fP should have an allocation size of at least (((\fIspec->output\fP + 7) / 8) * sizeof(char)). .PP -\fI*state\fP should not be allocated. +\fI*state\fP should not be initialised. .BR libkeccak_generalised_sum_fd () initialises \fI*state\fP itself. Therefore there would be a memory leak if \fI*state\fP is already initialised. @@ -65,6 +65,9 @@ does not stop if interrupted (\fBread\fP(2) returns .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 EXAMPLES This example calculates the Keccak[b = 1024, c = 576, n = 256] hash of the input from stdin, and prints the hash, in hexadecimal diff --git a/doc/man/libkeccak_keccaksum_fd.3 b/doc/man/libkeccak_keccaksum_fd.3 new file mode 100644 index 0000000..4328fce --- /dev/null +++ b/doc/man/libkeccak_keccaksum_fd.3 @@ -0,0 +1,102 @@ +.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK-%VERSION% +.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 \fI-lkeccak\fP. +.SH DESCRIPTION +The +.BR libkeccak_keccaksum_fd () +calculates a Keccak hashsum of a file, whose file desriptor is specified +by \fIfd\fP (and should be at the beginning of the file.) The +hash algorithm tuning is specified by \fI*spec\fP. +.PP +The hash is stored in binary form to \fIhashsum\fP. \fIhashsum\fP +should have an allocation size of at least +(((\fIspec->output\fP + 7) / 8) * sizeof(char)). +.PP +\fI*state\fP should not be initialised. +.BR libkeccak_keccaksum_fd () +initialises \fI*state\fP itself. Therefore there would be a +memory leak if \fI*state\fP is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_keccaksum_fd () +function return 0 upon successful completion. +On error, -1 is returned and \fIerrno\fP is set to describe +the error. +.SH ERRORS +The +.BR libkeccak_keccaksum_fd () +function may fail for any reason, except those resulting +in \fIerrno\fP being set to \fBEINTR\fP, 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 (\fBread\fP(2) returns +\fBEINTR\fP.) +.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 EXAMPLES +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_FILNO, &state, &spec, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +.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) +.SH AUTHORS +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. +.SH BUGS +Please report bugs to https://github.com/maandree/bus/issues or to +maandree@member.fsf.org diff --git a/doc/man/libkeccak_rawshakesum_fd.3 b/doc/man/libkeccak_rawshakesum_fd.3 new file mode 100644 index 0000000..329b5db --- /dev/null +++ b/doc/man/libkeccak_rawshakesum_fd.3 @@ -0,0 +1,97 @@ +.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK-%VERSION% +.SH NAME +libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int libkeccak_rawshakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + long \fIsemicapacity\fP, long \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with \fI-lkeccak\fP. +.SH DESCRIPTION +The +.BR libkeccak_rawshakesum_fd () +calculates a RawSHAKE hashsum of a file, whose file desriptor is +specified by \fIfd\fP (and should be at the beginning of the file.) +The hash algorithm is tuned by the \fIsemicapacity\fP and \fIoutput\fP +parameters; they specify the half of the capacity and the output size, +respectively, in bits. +.PP +The hash is stored in binary form to \fIhashsum\fP. \fIhashsum\fP +should have an allocation size of at least +(((\fIoutput\fP + 7) / 8) * sizeof(char)). +.PP +\fI*state\fP should not be initialised. +.BR libkeccak_rawshakesum_fd () +initialises \fI*state\fP itself. Therefore there would be a +memory leak if \fI*state\fP is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_rawshakesum_fd () +function return 0 upon successful completion. +On error, -1 is returned and \fIerrno\fP is set to describe +the error. +.SH ERRORS +The +.BR libkeccak_rawshakesum_fd () +function may fail for any reason, except those resulting +in \fIerrno\fP being set to \fBEINTR\fP, specified for the +functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_rawshakesum_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_rawshakesum_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_rawshakesum_fd () +does not stop if interrupted (\fBread\fP(2) returns +\fBEINTR\fP.) +.PP +.BR libkeccak_rawshakesum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_rawshakesum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLES +This example calculates the RawSHAKE256(, 512) hash of the input +from stdin, and prints the hash, in hexadecimal form, to stdout. +.LP +.nf +libkeccak_state_t state; +if (libkeccak_rawshakesum_fd(STDIN_FILNO, &state, 256, 512, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3) +.SH AUTHORS +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. +.SH BUGS +Please report bugs to https://github.com/maandree/bus/issues or to +maandree@member.fsf.org diff --git a/doc/man/libkeccak_sha3sum_fd.3 b/doc/man/libkeccak_sha3sum_fd.3 new file mode 100644 index 0000000..b2d5f80 --- /dev/null +++ b/doc/man/libkeccak_sha3sum_fd.3 @@ -0,0 +1,95 @@ +.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK-%VERSION% +.SH NAME +libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int libkeccak_sha3sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + long \fIoutput\fP, char *\fIhashsum\fP); +.fi +.P +Link with \fI-lkeccak\fP. +.SH DESCRIPTION +The +.BR libkeccak_sha3sum_fd () +calculates a SHA-3 hashsum of a file, whose file desriptor is specified +by \fIfd\fP (and should be at the beginning of the file.) The +hash algorithm is tuned by the \fIoutput\fP parameter; it specifies +the output size, in bits. +.PP +The hash is stored in binary form to \fIhashsum\fP. \fIhashsum\fP +should have an allocation size of at least +(((\fIoutput\fP + 7) / 8) * sizeof(char)). +.PP +\fI*state\fP should not be initialised. +.BR libkeccak_sha3sum_fd () +initialises \fI*state\fP itself. Therefore there would be a +memory leak if \fI*state\fP is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_sha3sum_fd () +function return 0 upon successful completion. +On error, -1 is returned and \fIerrno\fP is set to describe +the error. +.SH ERRORS +The +.BR libkeccak_sha3sum_fd () +function may fail for any reason, except those resulting +in \fIerrno\fP being set to \fBEINTR\fP, specified for the +functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_sha3sum_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_sha3sum_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_sha3sum_fd () +does not stop if interrupted (\fBread\fP(2) returns +\fBEINTR\fP.) +.PP +.BR libkeccak_sha3sum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_sha3sum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLES +This example calculates the SHA3-256 hash of the input +from stdin, and prints the hash, in hexadecimal form, to stdout. +.LP +.nf +libkeccak_state_t state; +if (libkeccak_sha3sum_fd(STDIN_FILNO, &state, 256, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3) +.SH AUTHORS +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. +.SH BUGS +Please report bugs to https://github.com/maandree/bus/issues or to +maandree@member.fsf.org diff --git a/doc/man/libkeccak_shakesum_fd.3 b/doc/man/libkeccak_shakesum_fd.3 new file mode 100644 index 0000000..591f827 --- /dev/null +++ b/doc/man/libkeccak_shakesum_fd.3 @@ -0,0 +1,97 @@ +.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK-%VERSION% +.SH NAME +libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + long \fIsemicapacity\fP, long \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with \fI-lkeccak\fP. +.SH DESCRIPTION +The +.BR libkeccak_shakesum_fd () +calculates a SHAKE hashsum of a file, whose file desriptor is +specified by \fIfd\fP (and should be at the beginning of the file.) +The hash algorithm is tuned by the \fIsemicapacity\fP and \fIoutput\fP +parameters; they specify the half of the capacity and the output size, +respectively, in bits. +.PP +The hash is stored in binary form to \fIhashsum\fP. \fIhashsum\fP +should have an allocation size of at least +(((\fIoutput\fP + 7) / 8) * sizeof(char)). +.PP +\fI*state\fP should not be initialised. +.BR libkeccak_shakesum_fd () +initialises \fI*state\fP itself. Therefore there would be a +memory leak if \fI*state\fP is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_shakesum_fd () +function return 0 upon successful completion. +On error, -1 is returned and \fIerrno\fP is set to describe +the error. +.SH ERRORS +The +.BR libkeccak_shakesum_fd () +function may fail for any reason, except those resulting +in \fIerrno\fP being set to \fBEINTR\fP, specified for the +functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_shakesum_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_shakesum_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_shakesum_fd () +does not stop if interrupted (\fBread\fP(2) returns +\fBEINTR\fP.) +.PP +.BR libkeccak_shakesum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_shakesum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLES +This example calculates the SHAKE256(, 512) hash of the input +from stdin, and prints the hash, in hexadecimal form, to stdout. +.LP +.nf +libkeccak_state_t state; +if (libkeccak_shakesum_fd(STDIN_FILNO, &state, 256, 512, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3) +.SH AUTHORS +Principal author, Mattias Andrée. See the LICENSE file for the full +list of authors. +.SH BUGS +Please report bugs to https://github.com/maandree/bus/issues or to +maandree@member.fsf.org -- cgit v1.2.3-70-g09d2