From f14ba70de62cbd47e074756b1f1aec1f3b77a02d Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 15 Sep 2024 00:47:51 +0200 Subject: Move man pages into man3/ and man7/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- man3/libkeccak_spec_check.3 | 92 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) create mode 100644 man3/libkeccak_spec_check.3 (limited to 'man3/libkeccak_spec_check.3') diff --git a/man3/libkeccak_spec_check.3 b/man3/libkeccak_spec_check.3 new file mode 100644 index 0000000..3b5c9df --- /dev/null +++ b/man3/libkeccak_spec_check.3 @@ -0,0 +1,92 @@ +.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK +.SH NAME +libkeccak_spec_check - Validate hashing parameters +.SH SYNOPSIS +.nf +#include + +int libkeccak_spec_check(const struct libkeccak_spec *\fIspec\fP); +.fi +.PP +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_cshake (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +or, especially, after settings the parameters +manually for Keccak hashing. +.PP +.nf +struct libkeccak_spec { + long int bitrate; /* bitrate (in bits) */ + long int capacity; /* capacity (in bits) */ + long int output; /* output size (in bits) */ +}; +.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_cshake (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) -- cgit v1.2.3-70-g09d2