diff options
Diffstat (limited to 'man3')
56 files changed, 3454 insertions, 0 deletions
diff --git a/man3/libkeccak_behex_lower.3 b/man3/libkeccak_behex_lower.3 new file mode 100644 index 0000000..85bc843 --- /dev/null +++ b/man3/libkeccak_behex_lower.3 @@ -0,0 +1,50 @@ +.TH LIBKECCAK_BEHEX_LOWER 3 LIBKECCAK +.SH NAME +libkeccak_behex_lower - Converts a binary hashsum to lowercase hexadecimal +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_behex_lower(char *restrict \fIoutput\fP, + const char *restrict \fIhashsum\fP, size_t \fIn\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_behex_lower () +function +converts a binary hashsum, stored in +.IR hashsum , +to lowercase hexadecimal, and stores the +hexadecimal representation in +.IR output . +.PP +.I output +will be terminated by a NUL-character. +.PP +The +.I n +parameter specifies the number of bytes +the binary hashsum is comprised. +.I output +needs an allocation size of (2 * +.I n ++ 1). +.SH RETURN VALUES +The +.BR libkeccak_behex_lower () +function does return any value. +.SH ERRORS +The +.BR libkeccak_behex_lower () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_behex_upper (3), +.BR libkeccak_unhex (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_behex_upper.3 b/man3/libkeccak_behex_upper.3 new file mode 100644 index 0000000..7925efc --- /dev/null +++ b/man3/libkeccak_behex_upper.3 @@ -0,0 +1,50 @@ +.TH LIBKECCAK_BEHEX_UPPER 3 LIBKECCAK +.SH NAME +libkeccak_behex_upper - Converts a binary hashsum to uppercase hexadecimal +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_behex_upper(char *restrict \fIoutput\fP, + const char *restrict \fIhashsum\fP, size_t \fIn\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_behex_upper () +function +converts a binary hashsum, stored in +.IR hashsum , +to uppercase hexadecimal, and stores the +hexadecimal representation in +.IR output . +.PP +.I output +will be terminated by a NUL-character. +.PP +The +.I n +parameter specifies the number of bytes +the binary hashsum is comprised. +.I output +needs an allocation size of (2 * +.I n ++ 1). +.SH RETURN VALUES +The +.BR libkeccak_behex_upper () +function does return any value. +.SH ERRORS +The +.BR libkeccak_behex_upper () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_unhex (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_degeneralise_spec.3 b/man3/libkeccak_degeneralise_spec.3 new file mode 100644 index 0000000..38a1b73 --- /dev/null +++ b/man3/libkeccak_degeneralise_spec.3 @@ -0,0 +1,124 @@ +.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK +.SH NAME +libkeccak_degeneralise_spec - Set all specification parameters to automatic +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *\fIspec\fP, + libkeccak_spec_t *\fIoutput_spec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_degeneralise_spec () +function will resolve automatic parameters in +.I *spec +and translates the parameters to +.IR *output_spec , +so that it can be used for hashing. +.PP +The function will modify both +.I *spec +and +.IR *output_spec . +.PP +You should call the +.BR libkeccak_spec_check (3) +function after calling +.BR libkeccak_degeneralise_spec (). +.PP +.nf +typedef struct libkeccak_generalised_spec { + long int bitrate; /* bitrate (in bits) */ + long int capacity; /* capacity (in bits) */ + long int output; /* output size (in bits) */ + long int state_size; /* state size (in bits) */ + long int word_size; /* word size (in bits) */ +} libkeccak_generalised_spec_t; +.fi +.SH RETURN VALUES +The +.BR libkeccak_degeneralise_spec () +function returns 0 if the settings are usable. Otherwise +it will return one of the following constants. +.PP +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE +The specified state size is non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE +The specified state size exceeded the supported limit +(currently at 1600 bits.) +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25 +The specified state size, in bits, was not equivalent +to 0 modulus 25. Meaning the state size cannot +cover all lanes equivalently. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE +The specified word size is non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE +The specified word size exceeded the supported limit +(currently at 64 bits.) +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY +The specified state size is not exactly 25 times larger +than the word size. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE +The specified capacity was non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8 +The specified capacity was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE +The specified bitrate was non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8 +The specified bitrate was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE +The specified output size was non-positive. +.PP +Note that there may be more than one error. Only the first +detected is returned. +.SH ERRORS +The +.BR libkeccak_degeneralise_spec () +function cannot fail. +.fi +.SH EXAMPLE +This examples configure a +.B libkeccak_spec_t +to specify settings for Keccak[c = 512]: +.LP +.nf +int r; +libkeccak_spec_t spec; +libkeccak_generalised_spec_t gspec; +libkeccak_generalised_spec_initialise(&gspec); +gspec.capacity = 512; +if ((r = libkeccak_degeneralise_spec(&gspec, &spec))) + goto fail_degeneralise_spec; +if ((r = libkeccak_spec_check(&spec))); + goto fail_spec_check; +.fi +.SH SEE ALSO +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_digest.3 b/man3/libkeccak_digest.3 new file mode 100644 index 0000000..33b0479 --- /dev/null +++ b/man3/libkeccak_digest.3 @@ -0,0 +1,145 @@ +.TH LIBKECCAK_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_digest - Complete the hashing of a message with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_digest () +function absorbs the last part of (or all of) a message, +and returns the hash of the entire message. The last part +of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_update (3) +function or the +.BR libkeccak_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s +and '0':s, representing the bits that should be appended to +the message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_digest () +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_digest () +function may fail for any reason specified by the function +.BR malloc (3). +.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]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_digest(&state, NULL, 0, 0, "", 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_state_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_fast_digest.3 b/man3/libkeccak_fast_digest.3 new file mode 100644 index 0000000..d5c55a5 --- /dev/null +++ b/man3/libkeccak_fast_digest.3 @@ -0,0 +1,146 @@ +.TH LIBKECCAK_FAST_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_fast_digest - Complete the hashing of a message without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_fast_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_fast_digest () +function absorbs the last part of (or all of) a message, +and returns the hash of the entire message. The last part +of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_update (3) +function or the +.BR libkeccak_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s and '0':s, +representing the bits that should be appended to the +message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.IR hashsum +is +.IR NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_fast_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.SH RETURN VALUES +The +.BR libkeccak_fast_digest () +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_fast_digest () +function may fail for any reason specified by the function +.BR realloc (3). +.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]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_fast_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_fast_squeeze.3 b/man3/libkeccak_fast_squeeze.3 new file mode 100644 index 0000000..d782a95 --- /dev/null +++ b/man3/libkeccak_fast_squeeze.3 @@ -0,0 +1,39 @@ +.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_fast_squeeze - Runs the squeeze phase a number of times +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_fast_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_fast_squeeze () +function runs the Keccak squeeze phase, on the the hash +process described by +.IR *state , +as many times are required to get +.I times +additional digests. +.SH RETURN VALUES +The +.BR libkeccak_fast_squeeze () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_fast_squeeze () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_digest (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_fast_update.3 b/man3/libkeccak_fast_update.3 new file mode 100644 index 0000000..c619e7d --- /dev/null +++ b/man3/libkeccak_fast_update.3 @@ -0,0 +1,96 @@ +.TH LIBKECCAK_FAST_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_fast_update - Partially hash a message without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_fast_update () +function continues (or starts) hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_fast_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.SH RETURN VALUES +The +.BR libkeccak_fast_update () +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_fast_update () +function may fail for any reason specified by the function +.BR realloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.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]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_fast_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_generalised_spec_initialise.3 b/man3/libkeccak_generalised_spec_initialise.3 new file mode 100644 index 0000000..42bd62f --- /dev/null +++ b/man3/libkeccak_generalised_spec_initialise.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_GENERALISED_SPEC_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_generalised_spec_initialise - Set all specification parameters to automatic +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_generalised_spec_initialise () +function initialises +.IR *spec , +so that all parameters are configured to be +automatically selected. +.PP +Automatic selection means that value will be set +to the default, which depends on the other settings. +.PP +Specifically, all members of +.IR *spec , +will be set to +.BR LIBKECCAK_GENERALISED_SPEC_AUTOMATIC . +.SH RETURN VALUES +The +.BR libkeccak_generalised_spec_initialise () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_generalised_spec_initialise () +function cannot fail. +.fi +.SH SEE ALSO +.BR libkeccak_degeneralise_spec (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_generalised_sum_fd.3 b/man3/libkeccak_generalised_sum_fd.3 new file mode 100644 index 0000000..98e6329 --- /dev/null +++ b/man3/libkeccak_generalised_sum_fd.3 @@ -0,0 +1,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 diff --git a/man3/libkeccak_hmac_copy.3 b/man3/libkeccak_hmac_copy.3 new file mode 100644 index 0000000..f3939f5 --- /dev/null +++ b/man3/libkeccak_hmac_copy.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_HMAC_COPY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_copy - Copies an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_copy(libkeccak_hmac_state_t *\fIdest\fP, + const libkeccak_hmac_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_copy () +function initialises +.I *dest +to be identical to +.IR *src . +This includes all members of the +.B libkeccak_hmac_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_hmac_copy () +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_hmac_copy () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_duplicate (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_create.3 b/man3/libkeccak_hmac_create.3 new file mode 100644 index 0000000..fcb99cb --- /dev/null +++ b/man3/libkeccak_hmac_create.3 @@ -0,0 +1,53 @@ +.TH LIBKECCAK_HMAC_CREATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_create - Allocate and initialise HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +libkeccak_hmac_state_t * +libkeccak_hmac_create(const libkeccak_spec_t *\fIspec\fP, const char *\fIkey\fP, + size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_create () +function allocates a new +.I libkeccak_hmac_state_t* +with one initialised element, and sets the +algorithm tuning parameters to those specified by +.IR *spec , +and the key to +.I key +of length +.IR key_length . +.SH RETURN VALUES +The +.BR libkeccak_hmac_create () +function returns a newly allocated +.I libkeccak_hmac_state_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_create () +function may fail for any specified for the functions +.BR malloc (3) +and +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_duplicate (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_destroy.3 b/man3/libkeccak_hmac_destroy.3 new file mode 100644 index 0000000..2f3bbf8 --- /dev/null +++ b/man3/libkeccak_hmac_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_HMAC_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_destroy - Destroys an HMAC-hashing state with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_hmac_destroy(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_hmac_destroy () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_digest.3 b/man3/libkeccak_hmac_digest.3 new file mode 100644 index 0000000..66d35d4 --- /dev/null +++ b/man3/libkeccak_hmac_digest.3 @@ -0,0 +1,103 @@ +.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_digest(libkeccak_hmac_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_digest () +function absorbes the last part of (or all of) a message, +and returns the HMAC hash of the entire message. The last +part of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_hmac_update (3) +function or the +.BR libkeccak_hmac_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s +and '0':s, representing the bits that should be appended +to the message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_hmac_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_hmac_digest () +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_hmac_digest () +function may fail for any reason specified by the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_update (3), +.BR libkeccak_hmac_fast_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_duplicate.3 b/man3/libkeccak_hmac_duplicate.3 new file mode 100644 index 0000000..70c994c --- /dev/null +++ b/man3/libkeccak_hmac_duplicate.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_HMAC_DUPLICATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_duplicate - Allocate a duplicate an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +libkeccak_hmac_state_t * +libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_duplicate () +function allocates a new hash state and initialises +it to be identical to +.IR *src . +This includes all members of the +.B libkeccak_hmac_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_hmac_duplicate () +function returns a newly allocated +.I libkeccak_hmac_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_duplicate () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_copy (3), +.BR libkeccak_hmac_create (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_fast_destroy.3 b/man3/libkeccak_hmac_fast_destroy.3 new file mode 100644 index 0000000..d2af66e --- /dev/null +++ b/man3/libkeccak_hmac_fast_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_HMAC_FAST_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_destroy - Destroys an HMAC-hashing state without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_hamc_fast_destroy(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_hmac_fast_destroy () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_fast_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_fast_digest.3 b/man3/libkeccak_hmac_fast_digest.3 new file mode 100644 index 0000000..008477c --- /dev/null +++ b/man3/libkeccak_hmac_fast_digest.3 @@ -0,0 +1,104 @@ +.TH LIBKECCAK_HMAC_FAST_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_digest - Complete the HMAC-hashing of a message without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *\fIstate\fP, + const char *\fImsg\fP, size_t \fImsglen\fP, size_t \fIbits\fP, + const char *\fIsuffix\fP, char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_digest () +function absorbes the last part of (or all of) a message, +and returns the HMAC hash of the entire message. The last +part of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_hmac_update (3) +function or the +.BR libkeccak_hmac_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s +and '0':s, representing the bits that should be appended +to the message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_hmac_fast_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_digest () +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_hmac_fast_digest () +function may fail for any reason specified by the function +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_fast_update (3), +.BR libkeccak_hmac_fast_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_fast_free.3 b/man3/libkeccak_hmac_fast_free.3 new file mode 100644 index 0000000..b4817ce --- /dev/null +++ b/man3/libkeccak_hmac_fast_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_free - Destroys and deallocates an HMAC-hashing state without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_hmac_fast_free(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_free () +function releases the allocations stored in +.IR *state , +and also released the allocation of +.IR state . +.PP +The +.BR libkeccak_hmac_fast_free () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_fast_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_hmac_fast_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_fast_update.3 b/man3/libkeccak_hmac_fast_update.3 new file mode 100644 index 0000000..43077d3 --- /dev/null +++ b/man3/libkeccak_hmac_fast_update.3 @@ -0,0 +1,59 @@ +.TH LIBKECCAK_HMAC_FAST_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_update - Partially HMAC-hash a message without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_update () +function continues (or starts) HMAC-hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_hmac_fast_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_update () +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_hmac_fast_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.BR realloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_fast_digest (3), +.BR libkeccak_hmac_update (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_free.3 b/man3/libkeccak_hmac_free.3 new file mode 100644 index 0000000..d1f9c84 --- /dev/null +++ b/man3/libkeccak_hmac_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_HMAC_FREE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_free - Destroys and deallocates an HMAC-hashing state with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_hmac_free(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_free () +function releases the allocations stored in +.IR *state , +and also release the allocation of +.IR state . +.PP +The +.BR libkeccak_hmac_free () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_hmac_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_initialise.3 b/man3/libkeccak_hmac_initialise.3 new file mode 100644 index 0000000..de514e9 --- /dev/null +++ b/man3/libkeccak_hmac_initialise.3 @@ -0,0 +1,57 @@ +.TH LIBKECCAK_HMAC_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_initialise - Initialise HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_initialise(libkeccak_hmac_state_t *\fIstate\fP, + const libkeccak_spec_t *\fIspec\fP, + const char *\fIkey\fP, size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_initialise () +function initialises +.I *state +and sets the algorithm tuning parameters to +those specified by +.IR *spec , +and the key to +.I key +of length +.IR key_length . +.SH RETURN VALUES +The +.BR libkeccak_hmac_initialise () +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_hmac_initialise () +function may fail for any specified for the functions +.BR malloc (3) +and +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_copy (3), +.BR libkeccak_hmac_marshal_size (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 diff --git a/man3/libkeccak_hmac_marshal.3 b/man3/libkeccak_hmac_marshal.3 new file mode 100644 index 0000000..b7270f6 --- /dev/null +++ b/man3/libkeccak_hmac_marshal.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_HMAC_MARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_hmac_marshal - Marshals an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_hmac_marshal(const libkeccak_hmac_state_t *\fIstate\fP, + char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_marshal () +function marshals +.I *state +into the beginning of +.IR data . +.PP +Use the +.BR libkeccak_hmac_marshal_size (3) +function to get minimum usable allocation size +for +.IR data . +.SH RETURN VALUES +The +.BR libkeccak_hmac_marshal () +returns the number of bytes written to +.IR data . +.SH ERRORS +The +.BR libkeccak_hmac_marshal () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_unmarshal (3), +.BR libkeccak_hmac_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_marshal_size.3 b/man3/libkeccak_hmac_marshal_size.3 new file mode 100644 index 0000000..5195b81 --- /dev/null +++ b/man3/libkeccak_hmac_marshal_size.3 @@ -0,0 +1,36 @@ +.TH LIBKECCAK_HMAC_MARSHAL_SIZE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_marshal_size - Calculates the marshal-size of an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_marshal_size () +function calculates the number of bytes required +to marshal +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_hmac_marshal_size () +returns a positive value: the number of +bytes required to marshal the specified state. +.SH ERRORS +The +.BR libkeccak_hmac_marshal_size () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal (3), +.BR libkeccak_hmac_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_reset.3 b/man3/libkeccak_hmac_reset.3 new file mode 100644 index 0000000..d5634d9 --- /dev/null +++ b/man3/libkeccak_hmac_reset.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_HMAC_RESET 3 LIBKECCAK +.SH NAME +libkeccak_hmac_reset - Reinitialise a HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_reset(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, + size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_reset () +function reinitialises an HMAC-hashing state with a new key. +.I key_length +is the length of the key in bits. If +.I key +is +.IR NULL , +the key remains unchanged. +.SH RETURN VALUES +The +.BR libkeccak_hmac_reset () +function returns 0 successful completion. +On error -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_reset () +function may fail for any specified for the functions +.BR malloc (3) +and +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_set_key (3), +.BR libkeccak_hmac_wipe (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_destroy (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_set_key.3 b/man3/libkeccak_hmac_set_key.3 new file mode 100644 index 0000000..2f4682d --- /dev/null +++ b/man3/libkeccak_hmac_set_key.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_HMAC_SET_KEY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_set_key - Changes key for a the HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_set_key(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, + size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_set_key () +function sets the key for a HMAC-hashing state without reseting +the state of the underlaying hashing-algorithm. +.I key_length +is the length of the key in bits. +.SH RETURN VALUES +The +.BR libkeccak_hmac_set_key () +function returns 0 successful completion. +On error -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_set_key () +function may fail for any specified for the function +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_unmarshal.3 b/man3/libkeccak_hmac_unmarshal.3 new file mode 100644 index 0000000..64e8f24 --- /dev/null +++ b/man3/libkeccak_hmac_unmarshal.3 @@ -0,0 +1,39 @@ +.TH LIBKECCAK_HMAC_UNMARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_hmac_unmarshal - Unharshals an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *\fIstate\fP, + const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_unmarshal () +function unmarshals an HMAC-hashing state from the beginning of +.IR data . +and stores it in +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_hmac_unmarshal () +returns the number of bytes reads from +.IR data x. +.SH ERRORS +The +.BR libkeccak_hmac_unmarshal () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_unmarshal_skip.3 b/man3/libkeccak_hmac_unmarshal_skip.3 new file mode 100644 index 0000000..30e7ccf --- /dev/null +++ b/man3/libkeccak_hmac_unmarshal_skip.3 @@ -0,0 +1,40 @@ +.TH LIBKECCAK_HMAC_UNMARSHAL_SKIP 3 LIBKECCAK +.SH NAME +libkeccak_hmac_unmarshal_skip - Calculates the marshal-size of a marshalled HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_hmac_unmarshal_skip(const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_unmarshal_skip () +function gets the number of bytes with which +the HMAC-hashing state in the beginning of +.I data +is store stored. This is useful if you do not +want to unmarshal the state. +.SH RETURN VALUES +The +.BR libkeccak_hmac_unmarshal_skip () +returns a positive value: the number of +bytes to skip forward to skip pass the +hash state stored at the beginning of +the buffer. +.SH ERRORS +The +.BR libkeccak_hmac_unmarshal_skip () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_update.3 b/man3/libkeccak_hmac_update.3 new file mode 100644 index 0000000..daaf3fb --- /dev/null +++ b/man3/libkeccak_hmac_update.3 @@ -0,0 +1,56 @@ +.TH LIBKECCAK_HMAC_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_update - Partially HMAC-hash a message with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_update () +function continues (or starts) HMAC-hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_hmac_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_hmac_update () +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_hmac_update () +function may fail for any reason specified by the function +.BR malloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_digest (3), +.BR libkeccak_hmac_fast_update (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_hmac_wipe.3 b/man3/libkeccak_hmac_wipe.3 new file mode 100644 index 0000000..bad351b --- /dev/null +++ b/man3/libkeccak_hmac_wipe.3 @@ -0,0 +1,36 @@ +.TH LIBKECCAK_HMAC_WIPE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_wipe - Securely erase sensitive data from a HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_hmac_wipe(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_wipe () +function securely erases data that may be +sensitive: the buffer and the state of the +underlaying hash-algorithm. +.SH RETURN VALUES +The +.BR libkeccak_hmac_wipe () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_wipe () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_destroy (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se 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 <libkeccak.h> +.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 diff --git a/man3/libkeccak_rawshakesum_fd.3 b/man3/libkeccak_rawshakesum_fd.3 new file mode 100644 index 0000000..27c4f45 --- /dev/null +++ b/man3/libkeccak_rawshakesum_fd.3 @@ -0,0 +1,115 @@ +.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_rawshakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + long int \fIsemicapacity\fP, long int \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_rawshakesum_fd () +function calculates a RawSHAKE hashsum of a file, whose +file desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm is tuned by the +.I semicapacity +and +.I output +parameters; they specify the half of the capacity and +the output size, respectively, in bits. +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_rawshakesum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_rawshakesum_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_rawshakesum_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_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 +.RB ( read (2) +returns +.BR EINTR .) +.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 EXAMPLE +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_FILENO, &state, 256, 512, 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_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), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_sha3sum_fd.3 b/man3/libkeccak_sha3sum_fd.3 new file mode 100644 index 0000000..e8c4fc0 --- /dev/null +++ b/man3/libkeccak_sha3sum_fd.3 @@ -0,0 +1,111 @@ +.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_sha3sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_sha3sum_fd () +function calculates a SHA-3 hashsum of a file, whose file +desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm is tuned by the +.I output +parameter; it specifies the output size, in bits. +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_sha3sum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_sha3sum_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_sha3sum_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_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 +.RB ( read (2) +returns +.BR EINTR .) +.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 EXAMPLE +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_FILENO, &state, 256, 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_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), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_shakesum_fd.3 b/man3/libkeccak_shakesum_fd.3 new file mode 100644 index 0000000..0d89f39 --- /dev/null +++ b/man3/libkeccak_shakesum_fd.3 @@ -0,0 +1,115 @@ +.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + long int \fIsemicapacity\fP, long int \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_shakesum_fd () +function calculates a SHAKE hashsum of a file, whose file +desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm is tuned by the +.I semicapacity +and +.I output +parameters; they specify the half of the capacity and the +output size, respectively, in bits. +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_shakesum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_shakesum_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_shakesum_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_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 +.RB ( read (2) +returns +.BR EINTR .) +.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 EXAMPLE +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_FILENO, &state, 256, 512, 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_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), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_simple_squeeze.3 b/man3/libkeccak_simple_squeeze.3 new file mode 100644 index 0000000..52605ed --- /dev/null +++ b/man3/libkeccak_simple_squeeze.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_SIMPLE_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_simple_squeeze - Runs Keccak-f a number of times +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_simple_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_simple_squeeze () +function runs Keccak-f +.I times +times on the hashing +process described by +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_simple_squeeze () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_simple_squeeze () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_digest (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_spec_check.3 b/man3/libkeccak_spec_check.3 new file mode 100644 index 0000000..9fc70f6 --- /dev/null +++ b/man3/libkeccak_spec_check.3 @@ -0,0 +1,95 @@ +.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK +.SH NAME +libkeccak_spec_check - Validate hashing parameters +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_spec_check(const libkeccak_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_check () +function validates the parameters of +.IR *spec , +so that unusable configurations can be detected. +It is recommended to call this function after calling +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +or, especially, after settings the parameters +manually for Keccak hashing. +.PP +.nf +typedef struct libkeccak_spec { + long int bitrate; /* bitrate (in bits) */ + long int capacity; /* capacity (in bits) */ + long int output; /* output size (in bits) */ +} libkeccak_spec_t; +.fi +.SH RETURN VALUES +The +.BR libkeccak_spec_check () +function returns 0 if the settings are usable. Otherwise +it will return one of the following constants. +.PP +.TP +.B LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE +The specified bitrate was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 +The specified bitrate was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE +The specified capacity was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 +The specified capacity was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE +The specified output size was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE +The state size, that is the sum of the bitrate +and the capacity, exceeded the supported limit +(currently at 1600 bits.) +.TP +.B LIBKECCAK_SPEC_ERROR_STATE_MOD_25 +The state size, that is the sum of the bitrate +and the capacity, in bits, was not equivalent +to 0 modulus 25. Meaning the state size cannot +cover all lanes equivalently. +.TP +.B LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT +The word size, that is the state size divided +by 25, is not a power of 2. +.TP +.B LIBKECCAK_SPEC_ERROR_WORD_MOD_8 +The word size, that is the state size divided +by 25, is not quivalent to 0 modulus 8, that +is, it is not in whole bytes. +.PP +Note that there may be more than one error. Only the first +detected is returned. +.SH ERRORS +The +.BR libkeccak_spec_check () +function cannot fail. +.fi +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_spec_rawshake.3 b/man3/libkeccak_spec_rawshake.3 new file mode 100644 index 0000000..6f60c36 --- /dev/null +++ b/man3/libkeccak_spec_rawshake.3 @@ -0,0 +1,53 @@ +.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_spec_rawshake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, + long int \fId\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_rawshake () +function sets +.I *spec +to specify the Keccak parameters used for RawSHAKE hashing +with the semicapacity specified, in bits, via the +.I x +parameter, and the output size specified, in bits, via the +.I d +parameter. +.SH RETURN VALUES +The +.BR libkeccak_spec_rawshake () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_spec_rawshake () +function cannot fail. +.SH EXAMPLE +This example configure a +.B libkeccak_spec_t +to specify the Keccak parameters used for RawSHAKE256(, 512): +.LP +.nf +libkeccak_spec_t spec; +libkeccak_spec_rawshake(&spec, 256, 512); +.fi +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_spec_sha3.3 b/man3/libkeccak_spec_sha3.3 new file mode 100644 index 0000000..8e07a7d --- /dev/null +++ b/man3/libkeccak_spec_sha3.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK +.SH NAME +libkeccak_spec_sha3 - Configure SHA-3 hashing parameters +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_spec_sha3(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_sha3 () +function sets +.I *spec +to specify the Keccak parameters +used for SHA-3 hashing with the output size specified, +in bits, via the +.I x +parameter. +.SH RETURN VALUES +The +.BR libkeccak_spec_sha3 () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_spec_sha3 () +function cannot fail. +.SH EXAMPLE +This example configure a +.B libkeccak_spec_t +to specify the Keccak parameters used for SHA3-256: +.LP +.nf +libkeccak_spec_t spec; +libkeccak_spec_sha3(&spec, 256); +.fi +.SH SEE ALSO +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_spec_shake.3 b/man3/libkeccak_spec_shake.3 new file mode 100644 index 0000000..9e2d763 --- /dev/null +++ b/man3/libkeccak_spec_shake.3 @@ -0,0 +1,52 @@ +.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_shake - Configure SHAKE hashing parameters +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_spec_shake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_shake () +function sets +.I *spec +to specify the Keccak parameters used for SHAKE hashing +with the semicapacity specified, in bits, via the +.I x +parameter, and the output size specified, in bits, via the +.I d +parameter. +.SH RETURN VALUES +The +.BR libkeccak_spec_shake () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_spec_shake () +function cannot fail. +.SH EXAMPLE +This example configure a +.B libkeccak_spec_t +to specify the Keccak parameters used for SHAKE256(, 512): +.LP +.nf +libkeccak_spec_t spec; +libkeccak_spec_shake(&spec, 256, 512); +.fi +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_squeeze.3 b/man3/libkeccak_squeeze.3 new file mode 100644 index 0000000..c6c8d01 --- /dev/null +++ b/man3/libkeccak_squeeze.3 @@ -0,0 +1,48 @@ +.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_squeeze - Runs the squeeze phase +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_squeeze(libkeccak_state_t *\fIstate\fP, char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_squeeze () +function runs the Keccak squeeze phase, on the the hash +process described by +.IR *state , +on stores a new digest, in binary form, in +.IR hashsum . +.PP +.I hashsum +has the same requirement as for the +.BR libkeccak_digest (3) +and +.BR libkeccak_fast_digest (3) +functions: it must have an allocation size of at least +.RI (( state->n ++ 7) / 8) bytes. However, it may not be +.IR NULL . +.SH RETURN VALUES +The +.BR libkeccak_squeeze () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_squeeze () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_digest (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_copy.3 b/man3/libkeccak_state_copy.3 new file mode 100644 index 0000000..c9283ca --- /dev/null +++ b/man3/libkeccak_state_copy.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_STATE_COPY 3 LIBKECCAK +.SH NAME +libkeccak_state_copy - Copies hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_state_copy(libkeccak_state_t *\fIdest\fP, + const libkeccak_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_copy () +function initialises +.I *dest +to be identical to +.IR *src . +This includes all members of the +.B libkeccak_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_copy () +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_state_copy () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_duplicate (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_create.3 b/man3/libkeccak_state_create.3 new file mode 100644 index 0000000..77880a3 --- /dev/null +++ b/man3/libkeccak_state_create.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_STATE_CREATE 3 LIBKECCAK +.SH NAME +libkeccak_state_create - Allocate and initialise hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +libkeccak_state_t * +libkeccak_state_create(const libkeccak_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_create () +function allocates a new +.I libkeccak_state_t* +with one initialised element, and sets the algorithm +tuning parameters to those specified by +.IR *spec . +.SH RETURN VALUES +The +.BR libkeccak_state_create () +function returns a newly allocated +.I libkeccak_state_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_state_create () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_free (3), +.BR libkeccak_state_fast_free (3) +.BR libkeccak_state_duplicate (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_destroy.3 b/man3/libkeccak_state_destroy.3 new file mode 100644 index 0000000..0a78215 --- /dev/null +++ b/man3/libkeccak_state_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_STATE_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_state_destroy - Destroys a hash state with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_destroy(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_state_destroy () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_free (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_duplicate.3 b/man3/libkeccak_state_duplicate.3 new file mode 100644 index 0000000..54c9be3 --- /dev/null +++ b/man3/libkeccak_state_duplicate.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_STATE_DUPLICATE 3 LIBKECCAK +.SH NAME +libkeccak_state_duplicate - Allocate a duplicate hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +libkeccak_state_t * +libkeccak_state_duplicate(const libkeccak_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak P. +.SH DESCRIPTION +The +.BR libkeccak_state_duplicate () +function allocates a new hash state and initialises it +to be identical to +.IR *src . +This includes all members of the +.B libkeccak_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_duplicate () +function returns a newly allocated +.I libkeccak_state_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_state_duplicate () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_copy (3), +.BR libkeccak_state_create (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_fast_destroy.3 b/man3/libkeccak_state_fast_destroy.3 new file mode 100644 index 0000000..e04ca86 --- /dev/null +++ b/man3/libkeccak_state_fast_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_STATE_FAST_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_state_fast_destroy - Destroys a hash state without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_fast_destroy(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_fast_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_state_fast_destroy () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_fast_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_fast_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_fast_free (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_fast_free.3 b/man3/libkeccak_state_fast_free.3 new file mode 100644 index 0000000..e617e21 --- /dev/null +++ b/man3/libkeccak_state_fast_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK +.SH NAME +libkeccak_state_fast_free - Destroys and deallocates a hash state without erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_fast_free(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_fast_free () +function releases the allocations stored in +.IR *state , +and also released the allocation of +.IR state . +.PP +The +.BR libkeccak_state_fast_free () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_fast_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_fast_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_state_fast_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_free (3), +.BR libkeccak_state_create (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_free.3 b/man3/libkeccak_state_free.3 new file mode 100644 index 0000000..e6dd3f8 --- /dev/null +++ b/man3/libkeccak_state_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_STATE_FREE 3 LIBKECCAK +.SH NAME +libkeccak_state_free - Destroys and deallocates a hash state with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_free(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_free () +function releases the allocations stored in +.IR *state , +and also release the allocation of +.IR state . +.PP +The +.BR libkeccak_state_free () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_state_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_fast_free (3), +.BR libkeccak_state_create (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_initialise.3 b/man3/libkeccak_state_initialise.3 new file mode 100644 index 0000000..2620686 --- /dev/null +++ b/man3/libkeccak_state_initialise.3 @@ -0,0 +1,60 @@ +.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_state_initialise - Initialise hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_state_initialise(libkeccak_state_t *\fIstate\fP, + const libkeccak_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_initialise () +function initialises +.I *state +and sets the algorithm tuning parameters to those +specified by +.IR *spec . +.SH RETURN VALUES +The +.BR libkeccak_state_initialise () +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_state_initialise () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_create (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_copy (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3), +.BR libkeccak_generalised_sum_fd (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_marshal_size (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_marshal.3 b/man3/libkeccak_state_marshal.3 new file mode 100644 index 0000000..f5d5e05 --- /dev/null +++ b/man3/libkeccak_state_marshal.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_STATE_MARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_state_marshal - Marshals a hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_state_marshal(const libkeccak_state_t *\fIstate\fP, char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_marshal () +function marshals \fI*state\fP into the beginning of +.IR data . +.PP +Use the +.BR libkeccak_state_marshal_size (3) +function to get minimum usable allocation size +for +.IR data . +.SH RETURN VALUES +The +.BR libkeccak_state_marshal () +returns the number of bytes written to +.IR data . +.SH ERRORS +The +.BR libkeccak_state_marshal () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_unmarshal (3), +.BR libkeccak_state_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_marshal_size.3 b/man3/libkeccak_state_marshal_size.3 new file mode 100644 index 0000000..8ebb16a --- /dev/null +++ b/man3/libkeccak_state_marshal_size.3 @@ -0,0 +1,36 @@ +.TH LIBKECCAK_STATE_MARSHAL_SIZE 3 LIBKECCAK +.SH NAME +libkeccak_state_marshal_size - Calculates the marshal-size of a hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_state_marshal_size(const libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_marshal_size () +function calculates the number of bytes required +to marshal +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_state_marshal_size () +returns a positive value: the number of +bytes required to marshal the specified state. +.SH ERRORS +The +.BR libkeccak_state_marshal_size () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal (3), +.BR libkeccak_state_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_reset.3 b/man3/libkeccak_state_reset.3 new file mode 100644 index 0000000..60bb778 --- /dev/null +++ b/man3/libkeccak_state_reset.3 @@ -0,0 +1,37 @@ +.TH LIBKECCAK_STATE_RESET 3 LIBKECCAK +.SH NAME +libkeccak_state_reset - Reinitialise hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_reset(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_reset () +function reinitialises +.IR *state , +but keeps the +tuning, so it can be used to hash another message. +.SH RETURN VALUES +The +.BR libkeccak_state_reset () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_reset () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_unmarshal.3 b/man3/libkeccak_state_unmarshal.3 new file mode 100644 index 0000000..5a9e59b --- /dev/null +++ b/man3/libkeccak_state_unmarshal.3 @@ -0,0 +1,39 @@ +.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_state_unmarshal - Unharshals a hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_state_unmarshal(libkeccak_state_t *\fIstate\fP, const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_unmarshal () +function unmarshals a hash state from the beginning +of +.IR data . +and stores it in +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_state_unmarshal () +returns the number of bytes reads from +.IR data . +.SH ERRORS +The +.BR libkeccak_state_unmarshal () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_unmarshal_skip.3 b/man3/libkeccak_state_unmarshal_skip.3 new file mode 100644 index 0000000..b87386c --- /dev/null +++ b/man3/libkeccak_state_unmarshal_skip.3 @@ -0,0 +1,40 @@ +.TH LIBKECCAK_STATE_UNMARSHAL_SKIP 3 LIBKECCAK +.SH NAME +libkeccak_state_unmarshal_skip - Calculates the marshal-size of a marshalled hash state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +size_t +libkeccak_state_unmarshal_skip(const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_unmarshal_skip () +function gets the number of bytes with which +the hash state in the beginning of +.I data +is store stored. This is useful if you do not +want to unmarshal the state. +.SH RETURN VALUES +The +.BR libkeccak_state_unmarshal_skip () +returns a positive value: the number of +bytes to skip forward to skip pass the +hash state stored at the beginning of +the buffer. +.SH ERRORS +The +.BR libkeccak_state_unmarshal_skip () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_wipe.3 b/man3/libkeccak_state_wipe.3 new file mode 100644 index 0000000..664cd51 --- /dev/null +++ b/man3/libkeccak_state_wipe.3 @@ -0,0 +1,37 @@ +.TH LIBKECCAK_STATE_WIPE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe - Securely erase sensitive data +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_wipe(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_wipe () +function securely erases data that may be +sensitive: the state of the Keccak sponge, +and the message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_wipe () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_wipe () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_wipe_message (3), +.BR libkeccak_state_wipe_sponge (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_wipe_message.3 b/man3/libkeccak_state_wipe_message.3 new file mode 100644 index 0000000..c734560 --- /dev/null +++ b/man3/libkeccak_state_wipe_message.3 @@ -0,0 +1,35 @@ +.TH LIBKECCAK_STATE_WIPE_MESSAGE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe_message - Securely erase the message chunk buffer +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_wipe_message(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_wipe_message () +function securely erases the message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_wipe_message () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_wipe_message () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_wipe_sponge (3), +.BR libkeccak_state_wipe (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_state_wipe_sponge.3 b/man3/libkeccak_state_wipe_sponge.3 new file mode 100644 index 0000000..4651fc0 --- /dev/null +++ b/man3/libkeccak_state_wipe_sponge.3 @@ -0,0 +1,35 @@ +.TH LIBKECCAK_STATE_WIPE_SPONGE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe_sponge - Securely erase the Keccak sponge state +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_state_wipe_sponge(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_wipe_sponge () +function securely erases the state of the Keccak sponge. +.SH RETURN VALUES +The +.BR libkeccak_state_wipe_sponge () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_wipe_sponge () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_wipe_message (3), +.BR libkeccak_state_wipe (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_unhex.3 b/man3/libkeccak_unhex.3 new file mode 100644 index 0000000..93cde63 --- /dev/null +++ b/man3/libkeccak_unhex.3 @@ -0,0 +1,53 @@ +.TH LIBKECCAK_UNHEX 3 LIBKECCAK +.SH NAME +libkeccak_unhex - Converts a hexadecimal hashsum to binary +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +void +libkeccak_unhex(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_unhex () +function +converts a hexadecimal hashsum, stored in +.IR hashsum , +to binary, and stores the binary representation in +.IR output . +.PP +.I hashsum +must be terminated by a NUL-character. It may be +in either lowercase or uppercase, or a mixture +thereof. +.I output +will not be terminated. +.PP +(\fBstrlen\fP(\fIhashsum\fP) / 2) bytes will be +written to the beginning of +.IR Ioutput . +It should therefore have an allocation of at least +that number of bytes. +.SH RETURN VALUES +The +.BR libkeccak_unhex () +function does return any value. +.SH ERRORS +The +.BR libkeccak_unhex () +function cannot fail. +.SH NOTES +.I hashsum +must have an even number of digits +(characters excluding the terminating NUL-character.) +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man3/libkeccak_update.3 b/man3/libkeccak_update.3 new file mode 100644 index 0000000..d83f74b --- /dev/null +++ b/man3/libkeccak_update.3 @@ -0,0 +1,95 @@ +.TH LIBKECCAK_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_update - Partially hash a message with erasure +.SH SYNOPSIS +.LP +.nf +#include <libkeccak.h> +.P +int +libkeccak_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_update () +function continues (or starts) hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_update () +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_update () +function may fail for any reason specified by the function +.BR malloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.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]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_digest(&state, NULL, 0, 0, "", 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_state_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se |