From 5ff4c5af715d098852d124de116d354ee10f4ea4 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Mon, 11 Feb 2019 16:22:00 +0100 Subject: Split most .c files into one per function and flatten file hierarchy MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- Makefile | 31 +- common.h | 19 + digest.c | 594 +++++++++++++++++++++++++++ libkeccak.7 | 70 ++++ libkeccak/digest.c | 594 --------------------------- libkeccak/files.c | 49 --- libkeccak/generalised-spec.c | 112 ----- libkeccak/hex.c | 65 --- libkeccak/hmac.c | 423 ------------------- libkeccak/state.c | 174 -------- libkeccak_behex_lower.3 | 45 ++ libkeccak_behex_lower.c | 21 + libkeccak_behex_upper.3 | 44 ++ libkeccak_behex_upper.c | 21 + libkeccak_degeneralise_spec.3 | 118 ++++++ libkeccak_degeneralise_spec.c | 111 +++++ libkeccak_digest.3 | 139 +++++++ libkeccak_fast_digest.3 | 141 +++++++ libkeccak_fast_squeeze.3 | 34 ++ libkeccak_fast_update.3 | 90 ++++ libkeccak_generalised_spec_initialise.3 | 41 ++ libkeccak_generalised_sum_fd.3 | 126 ++++++ libkeccak_generalised_sum_fd.c | 49 +++ libkeccak_hmac_copy.3 | 38 ++ libkeccak_hmac_copy.c | 38 ++ libkeccak_hmac_create.3 | 47 +++ libkeccak_hmac_destroy.3 | 38 ++ libkeccak_hmac_digest.3 | 97 +++++ libkeccak_hmac_digest.c | 80 ++++ libkeccak_hmac_duplicate.3 | 41 ++ libkeccak_hmac_fast_destroy.3 | 38 ++ libkeccak_hmac_fast_digest.3 | 98 +++++ libkeccak_hmac_fast_digest.c | 78 ++++ libkeccak_hmac_fast_free.3 | 46 +++ libkeccak_hmac_fast_update.3 | 53 +++ libkeccak_hmac_fast_update.c | 51 +++ libkeccak_hmac_free.3 | 46 +++ libkeccak_hmac_initialise.3 | 51 +++ libkeccak_hmac_marshal.3 | 38 ++ libkeccak_hmac_marshal_size.3 | 31 ++ libkeccak_hmac_reset.3 | 45 ++ libkeccak_hmac_set_key.3 | 35 ++ libkeccak_hmac_set_key.c | 46 +++ libkeccak_hmac_unmarshal.3 | 33 ++ libkeccak_hmac_unmarshal.c | 50 +++ libkeccak_hmac_unmarshal_skip.3 | 35 ++ libkeccak_hmac_update.3 | 50 +++ libkeccak_hmac_update.c | 52 +++ libkeccak_hmac_wipe.3 | 31 ++ libkeccak_hmac_wipe.c | 22 + libkeccak_keccaksum_fd.3 | 113 +++++ libkeccak_rawshakesum_fd.3 | 108 +++++ libkeccak_sha3sum_fd.3 | 105 +++++ libkeccak_shakesum_fd.3 | 108 +++++ libkeccak_simple_squeeze.3 | 33 ++ libkeccak_spec_check.3 | 90 ++++ libkeccak_spec_rawshake.3 | 47 +++ libkeccak_spec_sha3.3 | 46 +++ libkeccak_spec_shake.3 | 47 +++ libkeccak_squeeze.3 | 43 ++ libkeccak_state_copy.3 | 38 ++ libkeccak_state_copy.c | 21 + libkeccak_state_create.3 | 41 ++ libkeccak_state_destroy.3 | 38 ++ libkeccak_state_duplicate.3 | 41 ++ libkeccak_state_fast_destroy.3 | 38 ++ libkeccak_state_fast_free.3 | 46 +++ libkeccak_state_free.3 | 46 +++ libkeccak_state_initialise.3 | 54 +++ libkeccak_state_initialise.c | 33 ++ libkeccak_state_marshal.3 | 38 ++ libkeccak_state_marshal.c | 33 ++ libkeccak_state_marshal_size.3 | 31 ++ libkeccak_state_reset.3 | 32 ++ libkeccak_state_unmarshal.3 | 34 ++ libkeccak_state_unmarshal.c | 36 ++ libkeccak_state_unmarshal_skip.3 | 35 ++ libkeccak_state_unmarshal_skip.c | 18 + libkeccak_state_wipe.3 | 32 ++ libkeccak_state_wipe.c | 15 + libkeccak_state_wipe_message.3 | 30 ++ libkeccak_state_wipe_message.c | 17 + libkeccak_state_wipe_sponge.3 | 30 ++ libkeccak_state_wipe_sponge.c | 17 + libkeccak_unhex.3 | 48 +++ libkeccak_unhex.c | 29 ++ libkeccak_update.3 | 89 ++++ man3/libkeccak_behex_lower.3 | 45 -- man3/libkeccak_behex_upper.3 | 44 -- man3/libkeccak_degeneralise_spec.3 | 118 ------ man3/libkeccak_digest.3 | 139 ------- man3/libkeccak_fast_digest.3 | 141 ------- man3/libkeccak_fast_squeeze.3 | 34 -- man3/libkeccak_fast_update.3 | 90 ---- man3/libkeccak_generalised_spec_initialise.3 | 41 -- man3/libkeccak_generalised_sum_fd.3 | 126 ------ man3/libkeccak_hmac_copy.3 | 38 -- man3/libkeccak_hmac_create.3 | 47 --- man3/libkeccak_hmac_destroy.3 | 38 -- man3/libkeccak_hmac_digest.3 | 97 ----- man3/libkeccak_hmac_duplicate.3 | 41 -- man3/libkeccak_hmac_fast_destroy.3 | 38 -- man3/libkeccak_hmac_fast_digest.3 | 98 ----- man3/libkeccak_hmac_fast_free.3 | 46 --- man3/libkeccak_hmac_fast_update.3 | 53 --- man3/libkeccak_hmac_free.3 | 46 --- man3/libkeccak_hmac_initialise.3 | 51 --- man3/libkeccak_hmac_marshal.3 | 38 -- man3/libkeccak_hmac_marshal_size.3 | 31 -- man3/libkeccak_hmac_reset.3 | 45 -- man3/libkeccak_hmac_set_key.3 | 35 -- man3/libkeccak_hmac_unmarshal.3 | 33 -- man3/libkeccak_hmac_unmarshal_skip.3 | 35 -- man3/libkeccak_hmac_update.3 | 50 --- man3/libkeccak_hmac_wipe.3 | 31 -- man3/libkeccak_keccaksum_fd.3 | 113 ----- man3/libkeccak_rawshakesum_fd.3 | 108 ----- man3/libkeccak_sha3sum_fd.3 | 105 ----- man3/libkeccak_shakesum_fd.3 | 108 ----- man3/libkeccak_simple_squeeze.3 | 33 -- man3/libkeccak_spec_check.3 | 90 ---- man3/libkeccak_spec_rawshake.3 | 47 --- man3/libkeccak_spec_sha3.3 | 46 --- man3/libkeccak_spec_shake.3 | 47 --- man3/libkeccak_squeeze.3 | 43 -- man3/libkeccak_state_copy.3 | 38 -- man3/libkeccak_state_create.3 | 41 -- man3/libkeccak_state_destroy.3 | 38 -- man3/libkeccak_state_duplicate.3 | 41 -- man3/libkeccak_state_fast_destroy.3 | 38 -- man3/libkeccak_state_fast_free.3 | 46 --- man3/libkeccak_state_free.3 | 46 --- man3/libkeccak_state_initialise.3 | 54 --- man3/libkeccak_state_marshal.3 | 38 -- man3/libkeccak_state_marshal_size.3 | 31 -- man3/libkeccak_state_reset.3 | 32 -- man3/libkeccak_state_unmarshal.3 | 34 -- man3/libkeccak_state_unmarshal_skip.3 | 35 -- man3/libkeccak_state_wipe.3 | 32 -- man3/libkeccak_state_wipe_message.3 | 30 -- man3/libkeccak_state_wipe_sponge.3 | 30 -- man3/libkeccak_unhex.3 | 48 --- man3/libkeccak_update.3 | 89 ---- man7/libkeccak.7 | 70 ---- 144 files changed, 4695 insertions(+), 4644 deletions(-) create mode 100644 digest.c create mode 100644 libkeccak.7 delete mode 100644 libkeccak/digest.c delete mode 100644 libkeccak/files.c delete mode 100644 libkeccak/generalised-spec.c delete mode 100644 libkeccak/hex.c delete mode 100644 libkeccak/hmac.c delete mode 100644 libkeccak/state.c create mode 100644 libkeccak_behex_lower.3 create mode 100644 libkeccak_behex_lower.c create mode 100644 libkeccak_behex_upper.3 create mode 100644 libkeccak_behex_upper.c create mode 100644 libkeccak_degeneralise_spec.3 create mode 100644 libkeccak_degeneralise_spec.c create mode 100644 libkeccak_digest.3 create mode 100644 libkeccak_fast_digest.3 create mode 100644 libkeccak_fast_squeeze.3 create mode 100644 libkeccak_fast_update.3 create mode 100644 libkeccak_generalised_spec_initialise.3 create mode 100644 libkeccak_generalised_sum_fd.3 create mode 100644 libkeccak_generalised_sum_fd.c create mode 100644 libkeccak_hmac_copy.3 create mode 100644 libkeccak_hmac_copy.c create mode 100644 libkeccak_hmac_create.3 create mode 100644 libkeccak_hmac_destroy.3 create mode 100644 libkeccak_hmac_digest.3 create mode 100644 libkeccak_hmac_digest.c create mode 100644 libkeccak_hmac_duplicate.3 create mode 100644 libkeccak_hmac_fast_destroy.3 create mode 100644 libkeccak_hmac_fast_digest.3 create mode 100644 libkeccak_hmac_fast_digest.c create mode 100644 libkeccak_hmac_fast_free.3 create mode 100644 libkeccak_hmac_fast_update.3 create mode 100644 libkeccak_hmac_fast_update.c create mode 100644 libkeccak_hmac_free.3 create mode 100644 libkeccak_hmac_initialise.3 create mode 100644 libkeccak_hmac_marshal.3 create mode 100644 libkeccak_hmac_marshal_size.3 create mode 100644 libkeccak_hmac_reset.3 create mode 100644 libkeccak_hmac_set_key.3 create mode 100644 libkeccak_hmac_set_key.c create mode 100644 libkeccak_hmac_unmarshal.3 create mode 100644 libkeccak_hmac_unmarshal.c create mode 100644 libkeccak_hmac_unmarshal_skip.3 create mode 100644 libkeccak_hmac_update.3 create mode 100644 libkeccak_hmac_update.c create mode 100644 libkeccak_hmac_wipe.3 create mode 100644 libkeccak_hmac_wipe.c create mode 100644 libkeccak_keccaksum_fd.3 create mode 100644 libkeccak_rawshakesum_fd.3 create mode 100644 libkeccak_sha3sum_fd.3 create mode 100644 libkeccak_shakesum_fd.3 create mode 100644 libkeccak_simple_squeeze.3 create mode 100644 libkeccak_spec_check.3 create mode 100644 libkeccak_spec_rawshake.3 create mode 100644 libkeccak_spec_sha3.3 create mode 100644 libkeccak_spec_shake.3 create mode 100644 libkeccak_squeeze.3 create mode 100644 libkeccak_state_copy.3 create mode 100644 libkeccak_state_copy.c create mode 100644 libkeccak_state_create.3 create mode 100644 libkeccak_state_destroy.3 create mode 100644 libkeccak_state_duplicate.3 create mode 100644 libkeccak_state_fast_destroy.3 create mode 100644 libkeccak_state_fast_free.3 create mode 100644 libkeccak_state_free.3 create mode 100644 libkeccak_state_initialise.3 create mode 100644 libkeccak_state_initialise.c create mode 100644 libkeccak_state_marshal.3 create mode 100644 libkeccak_state_marshal.c create mode 100644 libkeccak_state_marshal_size.3 create mode 100644 libkeccak_state_reset.3 create mode 100644 libkeccak_state_unmarshal.3 create mode 100644 libkeccak_state_unmarshal.c create mode 100644 libkeccak_state_unmarshal_skip.3 create mode 100644 libkeccak_state_unmarshal_skip.c create mode 100644 libkeccak_state_wipe.3 create mode 100644 libkeccak_state_wipe.c create mode 100644 libkeccak_state_wipe_message.3 create mode 100644 libkeccak_state_wipe_message.c create mode 100644 libkeccak_state_wipe_sponge.3 create mode 100644 libkeccak_state_wipe_sponge.c create mode 100644 libkeccak_unhex.3 create mode 100644 libkeccak_unhex.c create mode 100644 libkeccak_update.3 delete mode 100644 man3/libkeccak_behex_lower.3 delete mode 100644 man3/libkeccak_behex_upper.3 delete mode 100644 man3/libkeccak_degeneralise_spec.3 delete mode 100644 man3/libkeccak_digest.3 delete mode 100644 man3/libkeccak_fast_digest.3 delete mode 100644 man3/libkeccak_fast_squeeze.3 delete mode 100644 man3/libkeccak_fast_update.3 delete mode 100644 man3/libkeccak_generalised_spec_initialise.3 delete mode 100644 man3/libkeccak_generalised_sum_fd.3 delete mode 100644 man3/libkeccak_hmac_copy.3 delete mode 100644 man3/libkeccak_hmac_create.3 delete mode 100644 man3/libkeccak_hmac_destroy.3 delete mode 100644 man3/libkeccak_hmac_digest.3 delete mode 100644 man3/libkeccak_hmac_duplicate.3 delete mode 100644 man3/libkeccak_hmac_fast_destroy.3 delete mode 100644 man3/libkeccak_hmac_fast_digest.3 delete mode 100644 man3/libkeccak_hmac_fast_free.3 delete mode 100644 man3/libkeccak_hmac_fast_update.3 delete mode 100644 man3/libkeccak_hmac_free.3 delete mode 100644 man3/libkeccak_hmac_initialise.3 delete mode 100644 man3/libkeccak_hmac_marshal.3 delete mode 100644 man3/libkeccak_hmac_marshal_size.3 delete mode 100644 man3/libkeccak_hmac_reset.3 delete mode 100644 man3/libkeccak_hmac_set_key.3 delete mode 100644 man3/libkeccak_hmac_unmarshal.3 delete mode 100644 man3/libkeccak_hmac_unmarshal_skip.3 delete mode 100644 man3/libkeccak_hmac_update.3 delete mode 100644 man3/libkeccak_hmac_wipe.3 delete mode 100644 man3/libkeccak_keccaksum_fd.3 delete mode 100644 man3/libkeccak_rawshakesum_fd.3 delete mode 100644 man3/libkeccak_sha3sum_fd.3 delete mode 100644 man3/libkeccak_shakesum_fd.3 delete mode 100644 man3/libkeccak_simple_squeeze.3 delete mode 100644 man3/libkeccak_spec_check.3 delete mode 100644 man3/libkeccak_spec_rawshake.3 delete mode 100644 man3/libkeccak_spec_sha3.3 delete mode 100644 man3/libkeccak_spec_shake.3 delete mode 100644 man3/libkeccak_squeeze.3 delete mode 100644 man3/libkeccak_state_copy.3 delete mode 100644 man3/libkeccak_state_create.3 delete mode 100644 man3/libkeccak_state_destroy.3 delete mode 100644 man3/libkeccak_state_duplicate.3 delete mode 100644 man3/libkeccak_state_fast_destroy.3 delete mode 100644 man3/libkeccak_state_fast_free.3 delete mode 100644 man3/libkeccak_state_free.3 delete mode 100644 man3/libkeccak_state_initialise.3 delete mode 100644 man3/libkeccak_state_marshal.3 delete mode 100644 man3/libkeccak_state_marshal_size.3 delete mode 100644 man3/libkeccak_state_reset.3 delete mode 100644 man3/libkeccak_state_unmarshal.3 delete mode 100644 man3/libkeccak_state_unmarshal_skip.3 delete mode 100644 man3/libkeccak_state_wipe.3 delete mode 100644 man3/libkeccak_state_wipe_message.3 delete mode 100644 man3/libkeccak_state_wipe_sponge.3 delete mode 100644 man3/libkeccak_unhex.3 delete mode 100644 man3/libkeccak_update.3 delete mode 100644 man7/libkeccak.7 diff --git a/Makefile b/Makefile index e8c9b80..9a51de9 100644 --- a/Makefile +++ b/Makefile @@ -18,12 +18,28 @@ LIB_VERSION = $(LIB_MAJOR).$(LIB_MINOR) OBJ =\ - libkeccak/digest.o\ - libkeccak/files.o\ - libkeccak/generalised-spec.o\ - libkeccak/hex.o\ - libkeccak/state.o\ - libkeccak/hmac.o + digest.o\ + libkeccak_behex_lower.o\ + libkeccak_behex_upper.o\ + libkeccak_degeneralise_spec.o\ + libkeccak_generalised_sum_fd.o\ + libkeccak_hmac_copy.o\ + libkeccak_hmac_digest.o\ + libkeccak_hmac_fast_digest.o\ + libkeccak_hmac_fast_update.o\ + libkeccak_hmac_set_key.o\ + libkeccak_hmac_unmarshal.o\ + libkeccak_hmac_update.o\ + libkeccak_hmac_wipe.o\ + libkeccak_state_copy.o\ + libkeccak_state_initialise.o\ + libkeccak_state_marshal.o\ + libkeccak_state_unmarshal.o\ + libkeccak_state_unmarshal_skip.o\ + libkeccak_state_wipe.o\ + libkeccak_state_wipe_message.o\ + libkeccak_state_wipe_sponge.o\ + libkeccak_unhex.o HDR =\ libkeccak.h\ @@ -154,7 +170,8 @@ uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.a" -rm -rf -- "$(DESTDIR)$(PREFIX)/include/libkeccak" -rm -f -- "$(DESTDIR)$(PREFIX)/include/libkeccak.h" - -cd -- "$(DESTDIR)$(MANPREFIX)" && rm -f -- $(MAN3) $(MAN7) + -cd -- "$(DESTDIR)$(MANPREFIX)/man3" && rm -f -- $(MAN3) + -cd -- "$(DESTDIR)$(MANPREFIX)/man7" && rm -f -- $(MAN7) -rm -rf -- "$(DESTDIR)$(PREFIX)/share/licenses/libkeccak" clean: diff --git a/common.h b/common.h index 1245bf6..df8b53c 100644 --- a/common.h +++ b/common.h @@ -15,3 +15,22 @@ # define __builtin_memcpy(dest, src, n) memcpy(dest, src, n) # define __builtin_memmove(dest, src, n) memmove(dest, src, n) #endif + + +/** + * The outer pad pattern for HMAC + */ +#define HMAC_OUTER_PAD 0x5C + +/** + * The inner pad pattern for HMAC + */ +#define HMAC_INNER_PAD 0x36 + + +static void *(*volatile my_explicit_memset)(void *, int, size_t) = memset; +static __attribute__((__optimize__("-O0"))) void +my_explicit_bzero(void *ptr, size_t size) +{ + (*my_explicit_memset)(ptr, 0, size); +} diff --git a/digest.c b/digest.c new file mode 100644 index 0000000..891b471 --- /dev/null +++ b/digest.c @@ -0,0 +1,594 @@ +/* See LICENSE file for copyright and license details. */ +#include "../common.h" + + +/** + * X-macro-enabled listing of all intergers in [0, 4] + */ +#define LIST_5 X(0) X(1) X(2) X(3) X(4) + +/** + * X-macro-enabled listing of all intergers in [0, 7] + */ +#define LIST_8 LIST_5 X(5) X(6) X(7) + +/** + * X-macro-enabled listing of all intergers in [0, 23] + */ +#define LIST_24 LIST_8 X(8) X(9) X(10) X(11) X(12) X(13) X(14) X(15)\ + X(16) X(17) X(18) X(19) X(20) X(21) X(22) X(23) + +/** + * X-macro-enabled listing of all intergers in [0, 24] + */ +#define LIST_25 LIST_24 X(24) + + + +#define X(N) (N % 5) * 5 + N / 5, +/** + * The order the lanes should be read when absorbing or squeezing, + * it transposes the lanes in the sponge + */ +static const long int LANE_TRANSPOSE_MAP[] = { LIST_25 }; +#undef X + + + +/** + * Keccak-f round constants + */ +static const uint_fast64_t RC[] = { + 0x0000000000000001ULL, 0x0000000000008082ULL, 0x800000000000808AULL, 0x8000000080008000ULL, + 0x000000000000808BULL, 0x0000000080000001ULL, 0x8000000080008081ULL, 0x8000000000008009ULL, + 0x000000000000008AULL, 0x0000000000000088ULL, 0x0000000080008009ULL, 0x000000008000000AULL, + 0x000000008000808BULL, 0x800000000000008BULL, 0x8000000000008089ULL, 0x8000000000008003ULL, + 0x8000000000008002ULL, 0x8000000000000080ULL, 0x000000000000800AULL, 0x800000008000000AULL, + 0x8000000080008081ULL, 0x8000000000008080ULL, 0x0000000080000001ULL, 0x8000000080008008ULL +}; + + +/** + * Rotate a word + * + * @param x:int_fast64_t The value to rotate + * @param n:long Rotation steps, may be zero mod `w` + * @param w:long `state->w` + * @param wmod:int_fast64_t `state->wmod` + * @return :int_fast64_t The value rotated + */ +#define rotate(x, n, w, wmod) ((((x) >> ((w) - ((n) % (w)))) | ((x) << ((n) % (w)))) & (wmod)) + + +/** + * Rotate a 64-bit word + * + * @param x:int_fast64_t The value to rotate + * @param n:long Rotation steps, may not be zero + * @return :int_fast64_t The value rotated + */ +#define rotate64(x, n) ((int_fast64_t)(((uint64_t)(x) >> (64L - (n))) | ((uint64_t)(x) << (n)))) + + +/** + * Perform one round of computation + * + * @param state The hashing state + * @param rc The round contant for this round + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __hot__))) +static void +libkeccak_f_round(register libkeccak_state_t *restrict state, register int_fast64_t rc) +{ + int_fast64_t *restrict A = state->S; + int_fast64_t B[25]; + int_fast64_t C[5]; + int_fast64_t da, db, dc, dd, de; + int_fast64_t wmod = state->wmod; + long int w = state->w; + + /* θ step (step 1 of 3). */ +#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; + LIST_5; +#undef X + + /* θ step (step 2 of 3). */ + da = C[4] ^ rotate(C[1], 1, w, wmod); + dd = C[2] ^ rotate(C[4], 1, w, wmod); + db = C[0] ^ rotate(C[2], 1, w, wmod); + de = C[3] ^ rotate(C[0], 1, w, wmod); + dc = C[1] ^ rotate(C[3], 1, w, wmod); + + /* ρ and π steps, with last two part of θ. */ +#define X(bi, ai, dv, r) B[bi] = rotate(A[ai] ^ dv, r, w, wmod) + B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); + X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); + X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); + X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); + X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); +#undef X + + /* ξ step. */ +#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); + LIST_25; +#undef X + + /* ι step. */ + A[0] ^= rc; +} + + +/** + * 64-bit word version of `libkeccak_f_round` + * + * @param state The hashing state + * @param rc The round contant for this round + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __hot__))) +static void +libkeccak_f_round64(register libkeccak_state_t *restrict state, register int_fast64_t rc) +{ + int_fast64_t *restrict A = state->S; + int_fast64_t B[25]; + int_fast64_t C[5]; + int_fast64_t da, db, dc, dd, de; + + /* θ step (step 1 of 3). */ +#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; + LIST_5; +#undef X + + /* θ step (step 2 of 3). */ + da = C[4] ^ rotate64(C[1], 1); + dd = C[2] ^ rotate64(C[4], 1); + db = C[0] ^ rotate64(C[2], 1); + de = C[3] ^ rotate64(C[0], 1); + dc = C[1] ^ rotate64(C[3], 1); + + /* ρ and π steps, with last two part of θ. */ +#define X(bi, ai, dv, r) B[bi] = rotate64(A[ai] ^ dv, r) + B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); + X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); + X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); + X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); + X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); +#undef X + + /* ξ step. */ +#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); + LIST_25; +#undef X + + /* ι step. */ + A[0] ^= rc; +} + + +/** + * Convert a chunk of bytes to a lane + * + * @param state The hashing state + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __gnu_inline__))) +static inline void +libkeccak_f(register libkeccak_state_t *restrict state) +{ + register long int i = 0; + register long int nr = state->nr; + register long int wmod = state->wmod; + if (nr == 24) { + for (; i < nr; i++) + libkeccak_f_round64(state, (int_fast64_t)(RC[i])); + } else { + for (; i < nr; i++) + libkeccak_f_round(state, (int_fast64_t)(RC[i] & (uint_fast64_t)wmod)); + } +} + + +/** + * Convert a chunk of bytes to a lane + * + * @param message The message + * @param msglen The length of the message + * @param rr Bitrate in bytes + * @param ww Word size in bytes + * @param off The offset in the message + * @return The lane + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __pure__, __warn_unused_result__, __gnu_inline__))) +static inline int_fast64_t +libkeccak_to_lane(register const char *restrict message, register size_t msglen, + register long int rr, register long int ww, size_t off) +{ + register long int n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); + int_fast64_t rc = 0; + message += off; + while (ww--) { + rc <<= 8; + rc |= __builtin_expect(ww < n, 1) ? (int_fast64_t)(unsigned char)(message[ww]) : 0L; + } + return rc; +} + + +/** + * 64-bit lane version of `libkeccak_to_lane` + * + * @param message The message + * @param msglen The length of the message + * @param rr Bitrate in bytes + * @param off The offset in the message + * @return The lane + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __pure__, __hot__, __warn_unused_result__, __gnu_inline__))) +static inline int_fast64_t +libkeccak_to_lane64(register const char *restrict message, register size_t msglen, register long int rr, size_t off) +{ + register long int n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); + int_fast64_t rc = 0; + message += off; +#define X(N) if (__builtin_expect(N < n, 1)) rc |= (int_fast64_t)(unsigned char)(message[N]) << (N * 8);\ + else return rc; + LIST_8; +#undef X + return rc; +} + + +/** + * pad 10*1 + * + * @param state The hashing state, `state->M` and `state->mptr` will be updated, + * `state->M` should have `state->r / 8` bytes left over at the end + * @param bits The number of bits in the end of the message that does not make a whole byte + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __gnu_inline__))) +static inline void +libkeccak_pad10star1(register libkeccak_state_t *restrict state, register size_t bits) +{ + register size_t r = (size_t)(state->r); + register size_t nrf = state->mptr - !!bits; + register size_t len = (nrf << 3) | bits; + register size_t ll = len % r; + register char b = (char)(bits ? (state->M[nrf] | (1 << bits)) : 1); + + if (r - 8 <= ll && ll <= r - 2) { + state->M[nrf] = (char)(b ^ 0x80); + state->mptr = nrf + 1; + } else { + len = ++nrf << 3; + len = (len - (len % r) + (r - 8)) >> 3; + state->mptr = len + 1; + + state->M[nrf - 1] = b; + __builtin_memset(state->M + nrf, 0, (len - nrf) * sizeof(char)); + state->M[len] = (char)0x80; + } +} + + +/** + * Perform the absorption phase + * + * @param state The hashing state + * @param len The number of bytes from `state->M` to absorb + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__))) +static void +libkeccak_absorption_phase(register libkeccak_state_t *restrict state, register size_t len) +{ + register long int rr = state->r >> 3; + register long int ww = state->w >> 3; + register long int n = (long)len / rr; + register const char* restrict message = state->M; + if (__builtin_expect(ww >= 8, 1)) { /* ww > 8 is impossible, it is just for optimisation possibilities. */ + while (n--) { +#define X(N) state->S[N] ^= libkeccak_to_lane64(message, len, rr, (size_t)(LANE_TRANSPOSE_MAP[N] * 8)); + LIST_25; +#undef X + libkeccak_f(state); + message += (size_t)rr; + len -= (size_t)rr; + } + } else { + while (n--) { +#define X(N) state->S[N] ^= libkeccak_to_lane(message, len, rr, ww, (size_t)(LANE_TRANSPOSE_MAP[N] * ww)); + LIST_25; +#undef X + libkeccak_f(state); + message += (size_t)rr; + len -= (size_t)rr; + } + } +} + + +/** + * Perform the squeezing phase + * + * @param state The hashing state + * @param rr The bitrate in bytes + * @param nn The output size in bytes, rounded up to whole bytes + * @param ww The word size in bytes + * @param hashsum Output parameter for the hashsum + */ +LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __hot__))) +static void +libkeccak_squeezing_phase(register libkeccak_state_t *restrict state, long int rr, + long int nn, long int ww, register unsigned char *restrict hashsum) +{ + register int_fast64_t v; + register long int ni = rr / ww; + auto long int olen = state->n; + auto long int i, j = 0; + register long int k; + while (olen > 0) { + for (i = 0; i < ni && j < nn; i++) { + v = state->S[LANE_TRANSPOSE_MAP[i]]; + for (k = 0; k++ < ww && j++ < nn; v >>= 8) + *hashsum++ = (unsigned char)v; + } + if (olen -= state->r, olen > 0) + libkeccak_f(state); + } + if (state->n & 7) + hashsum[-1] &= (unsigned char)((1 << (state->n & 7)) - 1); +} + + +/** + * Absorb more of the message to the Keccak sponge + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message + * @return Zero on success, -1 on error + */ +int +libkeccak_fast_update(libkeccak_state_t *restrict state, const void *restrict msg, size_t msglen) +{ + size_t len; + auto char *restrict new; + + if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { + state->mlen += msglen; + new = realloc(state->M, state->mlen * sizeof(char)); + if (!new) + return state->mlen -= msglen, -1; + state->M = new; + } + + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + len = state->mptr; + len -= state->mptr % (size_t)((state->r * state->b) >> 3); + state->mptr -= len; + + libkeccak_absorption_phase(state, len); + __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); + + return 0; +} + + +/** + * Absorb more of the message to the Keccak sponge + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message + * @return Zero on success, -1 on error + */ +int +libkeccak_update(libkeccak_state_t *restrict state, const void *restrict msg, size_t msglen) +{ + size_t len; + auto char *restrict new; + + if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { + state->mlen += msglen; + new = malloc(state->mlen * sizeof(char)); + if (new == NULL) + return state->mlen -= msglen, -1; + libkeccak_state_wipe_message(state); + free(state->M); + state->M = new; + } + + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + len = state->mptr; + len -= state->mptr % (size_t)((state->r * state->b) >> 3); + state->mptr -= len; + + libkeccak_absorption_phase(state, len); + __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); + + return 0; +} + + +/** + * Absorb the last part of the message and squeeze the Keccak sponge + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL` + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_fast_digest(libkeccak_state_t *restrict state, const void *restrict msg_, size_t msglen, + size_t bits, const char *restrict suffix, void *restrict hashsum) +{ + const char *restrict msg = msg_; + auto char *restrict new; + register long int rr = state->r >> 3; + auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; + register size_t ext; + register long int i; + + if (!msg) + msglen = bits = 0; + else + msglen += bits >> 3, bits &= 7; + + ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; + if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { + state->mlen += ext; + new = realloc(state->M, state->mlen * sizeof(char)); + if (!new) + return state->mlen -= ext, -1; + state->M = new; + } + + if (msglen) + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + + if (bits) + state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); + if (__builtin_expect(!!suffix_len, 1)) { + if (bits == 0) + state->M[state->mptr] = 0; + while (suffix_len--) { + state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); + if (bits == 8) + bits = 0, state->M[++(state->mptr)] = 0; + } + } + if (bits) + state->mptr++; + + libkeccak_pad10star1(state, bits); + libkeccak_absorption_phase(state, state->mptr); + + if (hashsum) { + libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); + } else { + for (i = (state->n - 1) / state->r; i--;) + libkeccak_f(state); + } + + return 0; +} + + +/** + * Absorb the last part of the message and squeeze the Keccak sponge + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL` + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_digest(libkeccak_state_t *restrict state, const void *restrict msg_, size_t msglen, + size_t bits, const char *restrict suffix, void *restrict hashsum) +{ + const char *restrict msg = msg_; + auto char *restrict new; + register long int rr = state->r >> 3; + auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; + register size_t ext; + register long int i; + + if (!msg) + msglen = bits = 0; + else + msglen += bits >> 3, bits &= 7; + + ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; + if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { + state->mlen += ext; + new = malloc(state->mlen * sizeof(char)); + if (!new) + return state->mlen -= ext, -1; + libkeccak_state_wipe_message(state); + free(state->M); + state->M = new; + } + + if (msglen) + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + + if (bits) + state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); + if (__builtin_expect(!!suffix_len, 1)) { + if (bits == 0) + state->M[state->mptr] = 0; + while (suffix_len--) { + state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); + if (bits == 8) + bits = 0, state->M[++(state->mptr)] = 0; + } + } + if (bits) + state->mptr++; + + libkeccak_pad10star1(state, bits); + libkeccak_absorption_phase(state, state->mptr); + + if (hashsum) { + libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); + } else { + for (i = (state->n - 1) / state->r; i--;) + libkeccak_f(state); + } + + return 0; +} + + +/** + * Force some rounds of Keccak-f + * + * @param state The hashing state + * @param times The number of rounds + */ +void +libkeccak_simple_squeeze(register libkeccak_state_t *restrict state, register long int times) +{ + while (times--) + libkeccak_f(state); +} + + +/** + * Squeeze as much as is needed to get a digest a number of times + * + * @param state The hashing state + * @param times The number of digests + */ +void +libkeccak_fast_squeeze(register libkeccak_state_t *restrict state, register long int times) +{ + times *= (state->n - 1) / state->r + 1; + while (times--) + libkeccak_f(state); +} + + +/** + * Squeeze out another digest + * + * @param state The hashing state + * @param hashsum Output parameter for the hashsum + */ +void +libkeccak_squeeze(register libkeccak_state_t *restrict state, register void *restrict hashsum) +{ + libkeccak_f(state); + libkeccak_squeezing_phase(state, state->r >> 3, (state->n + 7) >> 3, state->w >> 3, hashsum); +} diff --git a/libkeccak.7 b/libkeccak.7 new file mode 100644 index 0000000..0a6ef04 --- /dev/null +++ b/libkeccak.7 @@ -0,0 +1,70 @@ +.TH LIBKECCAK 7 LIBKECCAK +.SH NAME +libkeccak - Keccak-family hashing library +.SH DESCRIPTION +.BR libkeccak +is a bit-oriented lanewise implementation of the Keccak-family with +support for extend output size, state marshalling, algorithm tuning with +implicit parameters, secure erasure of sensitive data, and HMAC. +.SH FUTURE DIRECTION +Keccak-3200 may be implemented in the future. +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_degeneralise_spec (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_wipe_message (3), +.BR libkeccak_state_wipe_sponge (3), +.BR libkeccak_state_wipe (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_create (3), +.BR libkeccak_state_fast_free (3), +.BR libkeccak_state_free (3), +.BR libkeccak_state_copy (3), +.BR libkeccak_state_duplicate (3), +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal (3), +.BR libkeccak_state_unmarshal_skip (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (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_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_unhex (3), +.BR libkeccak_hmac_set_key (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_copy (3), +.BR libkeccak_hmac_duplicate (3), +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal (3), +.BR libkeccak_hmac_unmarshal_skip (3), +.BR libkeccak_hmac_fast_update (3), +.BR libkeccak_hmac_update (3), +.BR libkeccak_hmac_fast_digest (3), +.BR libkeccak_hmac_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/libkeccak/digest.c b/libkeccak/digest.c deleted file mode 100644 index 891b471..0000000 --- a/libkeccak/digest.c +++ /dev/null @@ -1,594 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "../common.h" - - -/** - * X-macro-enabled listing of all intergers in [0, 4] - */ -#define LIST_5 X(0) X(1) X(2) X(3) X(4) - -/** - * X-macro-enabled listing of all intergers in [0, 7] - */ -#define LIST_8 LIST_5 X(5) X(6) X(7) - -/** - * X-macro-enabled listing of all intergers in [0, 23] - */ -#define LIST_24 LIST_8 X(8) X(9) X(10) X(11) X(12) X(13) X(14) X(15)\ - X(16) X(17) X(18) X(19) X(20) X(21) X(22) X(23) - -/** - * X-macro-enabled listing of all intergers in [0, 24] - */ -#define LIST_25 LIST_24 X(24) - - - -#define X(N) (N % 5) * 5 + N / 5, -/** - * The order the lanes should be read when absorbing or squeezing, - * it transposes the lanes in the sponge - */ -static const long int LANE_TRANSPOSE_MAP[] = { LIST_25 }; -#undef X - - - -/** - * Keccak-f round constants - */ -static const uint_fast64_t RC[] = { - 0x0000000000000001ULL, 0x0000000000008082ULL, 0x800000000000808AULL, 0x8000000080008000ULL, - 0x000000000000808BULL, 0x0000000080000001ULL, 0x8000000080008081ULL, 0x8000000000008009ULL, - 0x000000000000008AULL, 0x0000000000000088ULL, 0x0000000080008009ULL, 0x000000008000000AULL, - 0x000000008000808BULL, 0x800000000000008BULL, 0x8000000000008089ULL, 0x8000000000008003ULL, - 0x8000000000008002ULL, 0x8000000000000080ULL, 0x000000000000800AULL, 0x800000008000000AULL, - 0x8000000080008081ULL, 0x8000000000008080ULL, 0x0000000080000001ULL, 0x8000000080008008ULL -}; - - -/** - * Rotate a word - * - * @param x:int_fast64_t The value to rotate - * @param n:long Rotation steps, may be zero mod `w` - * @param w:long `state->w` - * @param wmod:int_fast64_t `state->wmod` - * @return :int_fast64_t The value rotated - */ -#define rotate(x, n, w, wmod) ((((x) >> ((w) - ((n) % (w)))) | ((x) << ((n) % (w)))) & (wmod)) - - -/** - * Rotate a 64-bit word - * - * @param x:int_fast64_t The value to rotate - * @param n:long Rotation steps, may not be zero - * @return :int_fast64_t The value rotated - */ -#define rotate64(x, n) ((int_fast64_t)(((uint64_t)(x) >> (64L - (n))) | ((uint64_t)(x) << (n)))) - - -/** - * Perform one round of computation - * - * @param state The hashing state - * @param rc The round contant for this round - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __hot__))) -static void -libkeccak_f_round(register libkeccak_state_t *restrict state, register int_fast64_t rc) -{ - int_fast64_t *restrict A = state->S; - int_fast64_t B[25]; - int_fast64_t C[5]; - int_fast64_t da, db, dc, dd, de; - int_fast64_t wmod = state->wmod; - long int w = state->w; - - /* θ step (step 1 of 3). */ -#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; - LIST_5; -#undef X - - /* θ step (step 2 of 3). */ - da = C[4] ^ rotate(C[1], 1, w, wmod); - dd = C[2] ^ rotate(C[4], 1, w, wmod); - db = C[0] ^ rotate(C[2], 1, w, wmod); - de = C[3] ^ rotate(C[0], 1, w, wmod); - dc = C[1] ^ rotate(C[3], 1, w, wmod); - - /* ρ and π steps, with last two part of θ. */ -#define X(bi, ai, dv, r) B[bi] = rotate(A[ai] ^ dv, r, w, wmod) - B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); - X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); - X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); - X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); - X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); -#undef X - - /* ξ step. */ -#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); - LIST_25; -#undef X - - /* ι step. */ - A[0] ^= rc; -} - - -/** - * 64-bit word version of `libkeccak_f_round` - * - * @param state The hashing state - * @param rc The round contant for this round - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __hot__))) -static void -libkeccak_f_round64(register libkeccak_state_t *restrict state, register int_fast64_t rc) -{ - int_fast64_t *restrict A = state->S; - int_fast64_t B[25]; - int_fast64_t C[5]; - int_fast64_t da, db, dc, dd, de; - - /* θ step (step 1 of 3). */ -#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; - LIST_5; -#undef X - - /* θ step (step 2 of 3). */ - da = C[4] ^ rotate64(C[1], 1); - dd = C[2] ^ rotate64(C[4], 1); - db = C[0] ^ rotate64(C[2], 1); - de = C[3] ^ rotate64(C[0], 1); - dc = C[1] ^ rotate64(C[3], 1); - - /* ρ and π steps, with last two part of θ. */ -#define X(bi, ai, dv, r) B[bi] = rotate64(A[ai] ^ dv, r) - B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); - X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); - X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); - X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); - X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); -#undef X - - /* ξ step. */ -#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); - LIST_25; -#undef X - - /* ι step. */ - A[0] ^= rc; -} - - -/** - * Convert a chunk of bytes to a lane - * - * @param state The hashing state - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __gnu_inline__))) -static inline void -libkeccak_f(register libkeccak_state_t *restrict state) -{ - register long int i = 0; - register long int nr = state->nr; - register long int wmod = state->wmod; - if (nr == 24) { - for (; i < nr; i++) - libkeccak_f_round64(state, (int_fast64_t)(RC[i])); - } else { - for (; i < nr; i++) - libkeccak_f_round(state, (int_fast64_t)(RC[i] & (uint_fast64_t)wmod)); - } -} - - -/** - * Convert a chunk of bytes to a lane - * - * @param message The message - * @param msglen The length of the message - * @param rr Bitrate in bytes - * @param ww Word size in bytes - * @param off The offset in the message - * @return The lane - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __pure__, __warn_unused_result__, __gnu_inline__))) -static inline int_fast64_t -libkeccak_to_lane(register const char *restrict message, register size_t msglen, - register long int rr, register long int ww, size_t off) -{ - register long int n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); - int_fast64_t rc = 0; - message += off; - while (ww--) { - rc <<= 8; - rc |= __builtin_expect(ww < n, 1) ? (int_fast64_t)(unsigned char)(message[ww]) : 0L; - } - return rc; -} - - -/** - * 64-bit lane version of `libkeccak_to_lane` - * - * @param message The message - * @param msglen The length of the message - * @param rr Bitrate in bytes - * @param off The offset in the message - * @return The lane - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __pure__, __hot__, __warn_unused_result__, __gnu_inline__))) -static inline int_fast64_t -libkeccak_to_lane64(register const char *restrict message, register size_t msglen, register long int rr, size_t off) -{ - register long int n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); - int_fast64_t rc = 0; - message += off; -#define X(N) if (__builtin_expect(N < n, 1)) rc |= (int_fast64_t)(unsigned char)(message[N]) << (N * 8);\ - else return rc; - LIST_8; -#undef X - return rc; -} - - -/** - * pad 10*1 - * - * @param state The hashing state, `state->M` and `state->mptr` will be updated, - * `state->M` should have `state->r / 8` bytes left over at the end - * @param bits The number of bits in the end of the message that does not make a whole byte - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __gnu_inline__))) -static inline void -libkeccak_pad10star1(register libkeccak_state_t *restrict state, register size_t bits) -{ - register size_t r = (size_t)(state->r); - register size_t nrf = state->mptr - !!bits; - register size_t len = (nrf << 3) | bits; - register size_t ll = len % r; - register char b = (char)(bits ? (state->M[nrf] | (1 << bits)) : 1); - - if (r - 8 <= ll && ll <= r - 2) { - state->M[nrf] = (char)(b ^ 0x80); - state->mptr = nrf + 1; - } else { - len = ++nrf << 3; - len = (len - (len % r) + (r - 8)) >> 3; - state->mptr = len + 1; - - state->M[nrf - 1] = b; - __builtin_memset(state->M + nrf, 0, (len - nrf) * sizeof(char)); - state->M[len] = (char)0x80; - } -} - - -/** - * Perform the absorption phase - * - * @param state The hashing state - * @param len The number of bytes from `state->M` to absorb - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__))) -static void -libkeccak_absorption_phase(register libkeccak_state_t *restrict state, register size_t len) -{ - register long int rr = state->r >> 3; - register long int ww = state->w >> 3; - register long int n = (long)len / rr; - register const char* restrict message = state->M; - if (__builtin_expect(ww >= 8, 1)) { /* ww > 8 is impossible, it is just for optimisation possibilities. */ - while (n--) { -#define X(N) state->S[N] ^= libkeccak_to_lane64(message, len, rr, (size_t)(LANE_TRANSPOSE_MAP[N] * 8)); - LIST_25; -#undef X - libkeccak_f(state); - message += (size_t)rr; - len -= (size_t)rr; - } - } else { - while (n--) { -#define X(N) state->S[N] ^= libkeccak_to_lane(message, len, rr, ww, (size_t)(LANE_TRANSPOSE_MAP[N] * ww)); - LIST_25; -#undef X - libkeccak_f(state); - message += (size_t)rr; - len -= (size_t)rr; - } - } -} - - -/** - * Perform the squeezing phase - * - * @param state The hashing state - * @param rr The bitrate in bytes - * @param nn The output size in bytes, rounded up to whole bytes - * @param ww The word size in bytes - * @param hashsum Output parameter for the hashsum - */ -LIBKECCAK_GCC_ONLY(__attribute__((__nonnull__, __nothrow__, __hot__))) -static void -libkeccak_squeezing_phase(register libkeccak_state_t *restrict state, long int rr, - long int nn, long int ww, register unsigned char *restrict hashsum) -{ - register int_fast64_t v; - register long int ni = rr / ww; - auto long int olen = state->n; - auto long int i, j = 0; - register long int k; - while (olen > 0) { - for (i = 0; i < ni && j < nn; i++) { - v = state->S[LANE_TRANSPOSE_MAP[i]]; - for (k = 0; k++ < ww && j++ < nn; v >>= 8) - *hashsum++ = (unsigned char)v; - } - if (olen -= state->r, olen > 0) - libkeccak_f(state); - } - if (state->n & 7) - hashsum[-1] &= (unsigned char)((1 << (state->n & 7)) - 1); -} - - -/** - * Absorb more of the message to the Keccak sponge - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message - * @return Zero on success, -1 on error - */ -int -libkeccak_fast_update(libkeccak_state_t *restrict state, const void *restrict msg, size_t msglen) -{ - size_t len; - auto char *restrict new; - - if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { - state->mlen += msglen; - new = realloc(state->M, state->mlen * sizeof(char)); - if (!new) - return state->mlen -= msglen, -1; - state->M = new; - } - - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - len = state->mptr; - len -= state->mptr % (size_t)((state->r * state->b) >> 3); - state->mptr -= len; - - libkeccak_absorption_phase(state, len); - __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); - - return 0; -} - - -/** - * Absorb more of the message to the Keccak sponge - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message - * @return Zero on success, -1 on error - */ -int -libkeccak_update(libkeccak_state_t *restrict state, const void *restrict msg, size_t msglen) -{ - size_t len; - auto char *restrict new; - - if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { - state->mlen += msglen; - new = malloc(state->mlen * sizeof(char)); - if (new == NULL) - return state->mlen -= msglen, -1; - libkeccak_state_wipe_message(state); - free(state->M); - state->M = new; - } - - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - len = state->mptr; - len -= state->mptr % (size_t)((state->r * state->b) >> 3); - state->mptr -= len; - - libkeccak_absorption_phase(state, len); - __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); - - return 0; -} - - -/** - * Absorb the last part of the message and squeeze the Keccak sponge - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL` - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_fast_digest(libkeccak_state_t *restrict state, const void *restrict msg_, size_t msglen, - size_t bits, const char *restrict suffix, void *restrict hashsum) -{ - const char *restrict msg = msg_; - auto char *restrict new; - register long int rr = state->r >> 3; - auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; - register size_t ext; - register long int i; - - if (!msg) - msglen = bits = 0; - else - msglen += bits >> 3, bits &= 7; - - ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; - if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { - state->mlen += ext; - new = realloc(state->M, state->mlen * sizeof(char)); - if (!new) - return state->mlen -= ext, -1; - state->M = new; - } - - if (msglen) - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - - if (bits) - state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); - if (__builtin_expect(!!suffix_len, 1)) { - if (bits == 0) - state->M[state->mptr] = 0; - while (suffix_len--) { - state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); - if (bits == 8) - bits = 0, state->M[++(state->mptr)] = 0; - } - } - if (bits) - state->mptr++; - - libkeccak_pad10star1(state, bits); - libkeccak_absorption_phase(state, state->mptr); - - if (hashsum) { - libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); - } else { - for (i = (state->n - 1) / state->r; i--;) - libkeccak_f(state); - } - - return 0; -} - - -/** - * Absorb the last part of the message and squeeze the Keccak sponge - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL` - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_digest(libkeccak_state_t *restrict state, const void *restrict msg_, size_t msglen, - size_t bits, const char *restrict suffix, void *restrict hashsum) -{ - const char *restrict msg = msg_; - auto char *restrict new; - register long int rr = state->r >> 3; - auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; - register size_t ext; - register long int i; - - if (!msg) - msglen = bits = 0; - else - msglen += bits >> 3, bits &= 7; - - ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; - if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { - state->mlen += ext; - new = malloc(state->mlen * sizeof(char)); - if (!new) - return state->mlen -= ext, -1; - libkeccak_state_wipe_message(state); - free(state->M); - state->M = new; - } - - if (msglen) - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - - if (bits) - state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); - if (__builtin_expect(!!suffix_len, 1)) { - if (bits == 0) - state->M[state->mptr] = 0; - while (suffix_len--) { - state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); - if (bits == 8) - bits = 0, state->M[++(state->mptr)] = 0; - } - } - if (bits) - state->mptr++; - - libkeccak_pad10star1(state, bits); - libkeccak_absorption_phase(state, state->mptr); - - if (hashsum) { - libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); - } else { - for (i = (state->n - 1) / state->r; i--;) - libkeccak_f(state); - } - - return 0; -} - - -/** - * Force some rounds of Keccak-f - * - * @param state The hashing state - * @param times The number of rounds - */ -void -libkeccak_simple_squeeze(register libkeccak_state_t *restrict state, register long int times) -{ - while (times--) - libkeccak_f(state); -} - - -/** - * Squeeze as much as is needed to get a digest a number of times - * - * @param state The hashing state - * @param times The number of digests - */ -void -libkeccak_fast_squeeze(register libkeccak_state_t *restrict state, register long int times) -{ - times *= (state->n - 1) / state->r + 1; - while (times--) - libkeccak_f(state); -} - - -/** - * Squeeze out another digest - * - * @param state The hashing state - * @param hashsum Output parameter for the hashsum - */ -void -libkeccak_squeeze(register libkeccak_state_t *restrict state, register void *restrict hashsum) -{ - libkeccak_f(state); - libkeccak_squeezing_phase(state, state->r >> 3, (state->n + 7) >> 3, state->w >> 3, hashsum); -} diff --git a/libkeccak/files.c b/libkeccak/files.c deleted file mode 100644 index 14a4290..0000000 --- a/libkeccak/files.c +++ /dev/null @@ -1,49 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "../common.h" - - -/** - * Calculate a Keccak-family hashsum of a file, - * the content of the file is assumed non-sensitive - * - * @param fd The file descriptor of the file to hash - * @param state The hashing state, should not be initialised (memory leak otherwise) - * @param spec Specifications for the hashing algorithm - * @param suffix The data suffix, see `libkeccak_digest` - * @param hashsum Output array for the hashsum, have an allocation size of - * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_generalised_sum_fd(int fd, libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec, - const char *restrict suffix, void *restrict hashsum) -{ - ssize_t got; - struct stat attr; - size_t blksize = 4096; - char *restrict chunk; - - if (libkeccak_state_initialise(state, spec) < 0) - return -1; - - if (fstat(fd, &attr) == 0) - if (attr.st_blksize > 0) - blksize = (size_t)(attr.st_blksize); - - chunk = alloca(blksize); - - for (;;) { - got = read(fd, chunk, blksize); - if (got < 0) { - if (errno == EINTR) - continue; - return -1; - } - if (got == 0) - break; - if (libkeccak_fast_update(state, chunk, (size_t)got) < 0) - return -1; - } - - return libkeccak_fast_digest(state, NULL, 0, 0, suffix, hashsum); -} diff --git a/libkeccak/generalised-spec.c b/libkeccak/generalised-spec.c deleted file mode 100644 index 0f78583..0000000 --- a/libkeccak/generalised-spec.c +++ /dev/null @@ -1,112 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "../common.h" - - -#ifdef __GNUC__ -# pragma GCC diagnostic push -# pragma GCC diagnostic ignored "-Wmaybe-uninitialized" -#endif - -#define have(v) (spec->v != LIBKECCAK_GENERALISED_SPEC_AUTOMATIC) -#define copy(v) (v = spec->v) -#define deft(v, dv) (have_##v ? v : (dv)) - - - -/** - * Convert a `libkeccak_generalised_spec_t` to a `libkeccak_spec_t` - * - * If you are interrested in finding errors, you should call - * `libkeccak_spec_check(output)` if this function returns zero - * - * @param spec The generalised input specifications, will be update with resolved automatic values - * @param output_spec The specification datastructure to fill in - * @return Zero if `spec` is valid, a `LIBKECCAK_GENERALISED_SPEC_ERROR_*` if an error was found - */ -int -libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *restrict spec, - libkeccak_spec_t *restrict output_spec) -{ - long int state_size, word_size, capacity, bitrate, output; - const int have_state_size = have(state_size); - const int have_word_size = have(word_size); - const int have_capacity = have(capacity); - const int have_bitrate = have(bitrate); - const int have_output = have(output); - - - if (have_state_size) { - copy(state_size); - if (state_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE; - if (state_size > 1600) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE; - if (state_size % 25) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25; - } - - if (have_word_size) { - copy(word_size); - if (word_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE; - if (word_size > 64) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE; - if (have_state_size && state_size != word_size * 25) - return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY; - else if (!have_state_size) - spec->state_size = 1, state_size = word_size * 25; - } - - if (have_capacity) { - copy(capacity); - if (capacity <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE; - if (capacity & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8; - } - - if (have_bitrate) { - copy(bitrate); - if (bitrate <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE; - if (bitrate & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8; - } - - if (have_output) { - copy(output); - if (output <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE; - } - - - if (!have_bitrate && !have_capacity && !have_output) { - state_size = deft(state_size, 1600L); - output = ((state_size << 5) / 100L + 7L) & ~0x07L; - bitrate = output << 1; - capacity = state_size - bitrate; - output = output >= 8 ? output : 8; - } else if (!have_bitrate && !have_capacity) { - bitrate = 1024; - capacity = 1600 - 1024; - state_size = deft(state_size, bitrate + capacity); - } else if (!have_bitrate) { - state_size = deft(state_size, 1600L); - bitrate = state_size - capacity; - output = deft(output, capacity == 8 ? 8 : (capacity << 1)); - } else if (!have_capacity) { - state_size = deft(state_size, 1600L); - capacity = state_size - bitrate; - output = deft(output, capacity == 8 ? 8 : (capacity << 1)); - } else { - state_size = deft(state_size, bitrate + capacity); - output = deft(output, capacity == 8 ? 8 : (capacity << 1)); - } - - spec->capacity = output_spec->capacity = capacity; - spec->bitrate = output_spec->bitrate = bitrate; - spec->output = output_spec->output = output; - spec->state_size = state_size; - spec->word_size = state_size / 25; - - return 0; -} - - -#undef deft -#undef copy -#undef have - -#ifdef __GNUC__ -# pragma GCC diagnostic pop -#endif diff --git a/libkeccak/hex.c b/libkeccak/hex.c deleted file mode 100644 index 7db49a6..0000000 --- a/libkeccak/hex.c +++ /dev/null @@ -1,65 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "../libkeccak.h" - - -/** - * Convert a binary hashsum to lower case hexadecimal representation - * - * @param output Output array, should have an allocation size of at least `2 * n + 1` - * @param hashsum The hashsum to convert - * @param n The size of `hashsum` - */ -void -libkeccak_behex_lower(char *restrict output, const void *restrict hashsum_, size_t n) -{ - const char *restrict hashsum = hashsum_; - output[2 * n] = '\0'; - while (n--) { - output[2 * n + 0] = "0123456789abcdef"[(hashsum[n] >> 4) & 15]; - output[2 * n + 1] = "0123456789abcdef"[(hashsum[n] >> 0) & 15]; - } -} - - -/** - * Convert a binary hashsum to upper case hexadecimal representation - * - * @param output Output array, should have an allocation size of at least `2 * n + 1` - * @param hashsum The hashsum to convert - * @param n The size of `hashsum` - */ -void -libkeccak_behex_upper(char *restrict output, const void *restrict hashsum_, size_t n) -{ - const char *restrict hashsum = hashsum_; - output[2 * n] = '\0'; - while (n--) { - output[2 * n + 0] = "0123456789ABCDEF"[(hashsum[n] >> 4) & 15]; - output[2 * n + 1] = "0123456789ABCDEF"[(hashsum[n] >> 0) & 15]; - } -} - - -/** - * Convert a hexadecimal hashsum (both lower case, upper - * case and mixed is supported) to binary representation - * - * @param output Output array, should have an allocation size of at least `strlen(hashsum) / 2` - * @param hashsum The hashsum to convert - */ -void -libkeccak_unhex(void *restrict output_, const char *restrict hashsum) -{ - char *restrict output = output_; - size_t n = strlen(hashsum) / 2; - char a, b; - while (n--) { - a = hashsum[2 * n + 0]; - b = hashsum[2 * n + 1]; - - a = (char)((a & 15) + (a > '9' ? 9 : 0)); - b = (char)((b & 15) + (b > '9' ? 9 : 0)); - - output[n] = (char)((a << 4) | b); - } -} diff --git a/libkeccak/hmac.c b/libkeccak/hmac.c deleted file mode 100644 index 8b14eba..0000000 --- a/libkeccak/hmac.c +++ /dev/null @@ -1,423 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "../common.h" - - - -/** - * The outer pad pattern - */ -#define OUTER_PAD 0x5C - -/** - * The inner pad pattern - */ -#define INNER_PAD 0x36 - - - -static void *(*volatile my_explicit_memset)(void *, int, size_t) = memset; -static __attribute__((__optimize__("-O0"))) void -my_explicit_bzero(void *ptr, size_t size) -{ - (*my_explicit_memset)(ptr, 0, size); -} - - -/** - * Change the HMAC-hashing key on the state - * - * @param state The state that should be reset - * @param key The new key - * @param key_length The length of key, in bits - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_set_key(libkeccak_hmac_state_t *restrict state, const void *restrict key, size_t key_length) -{ - size_t i, size, new_key_length, key_bytes; - char *old; - - size = (size_t)(state->sponge.r) > key_length ? (size_t)(state->sponge.r) : key_length; - new_key_length = size; - size = (size + 7) >> 3; - key_bytes = (key_length + 7) >> 3; - - if (size != key_bytes) { - state->key_opad = realloc(old = state->key_opad, 2 * size); - if (!state->key_opad) - return state->key_opad = old, -1; - state->key_ipad = state->key_opad + size / sizeof(char); - } - - memcpy(state->key_opad, key, key_bytes); - if (key_length & 7) - state->key_opad[(key_bytes >> 3) - 1] &= (char)((1 << (key_length & 7)) - 1); - - if ((size_t)(state->sponge.r) > key_length) - __builtin_memset(state->key_opad + key_bytes / sizeof(char), 0, size - key_bytes); - - for (i = 0; i < size; i++) { - state->key_ipad[i] = state->key_opad[i] ^ INNER_PAD; - state->key_opad[i] ^= OUTER_PAD; - } - - state->key_length = new_key_length; - - return 0; -} - - -/** - * Wipe sensitive data wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_hmac_wipe(volatile libkeccak_hmac_state_t *restrict state) -{ - volatile char *restrict key_pads; - size_t i, size; - key_pads = state->key_opad; - size = 2 * ((state->key_length + 7) >> 3); - libkeccak_state_wipe(&state->sponge); - for (i = 0; i < size; i++) - key_pads[i] = 0; - state->leftover = 0; - __builtin_memset(state->buffer, 0, state->buffer_size); -} - - -/** - * Make a copy of an HMAC hashing-state - * - * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) - * @param src The state to duplicate - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_copy(libkeccak_hmac_state_t *restrict dest, const libkeccak_hmac_state_t *restrict src) -{ - size_t size; - - dest->key_opad = NULL; - dest->key_ipad = NULL; - - if (libkeccak_state_copy(&dest->sponge, &src->sponge) < 0) - return -1; - - dest->key_length = src->key_length; - dest->leftover = src->leftover; - - size = (src->key_length + 7) >> 3; - dest->key_opad = malloc(2 * size); - if (dest->key_opad == NULL) - return libkeccak_state_destroy(&dest->sponge), -1; - dest->key_ipad = dest->key_opad + size / sizeof(char); - - memcpy(dest->key_opad, src->key_opad, size); - memcpy(dest->key_ipad, src->key_ipad, size); - - return 0; -} - - -/** - * Unmarshal a `libkeccak_hmac_state_t` from a buffer - * - * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) - * @param data The input buffer - * @return The number of bytes read from `data`, 0 on error - */ -size_t -libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *restrict state, const void *restrict data_) -{ - const char *restrict data = data_; - size_t parsed, size, i; - - state->key_opad = NULL; - state->key_ipad = NULL; - - parsed = libkeccak_state_unmarshal(&state->sponge, data); - if (parsed == 0) - return 0; - - data += parsed / sizeof(char); - state->key_length = *(const size_t *)data; - data += sizeof(size_t) / sizeof(char); - size = (state->key_length + 7) >> 3; - - state->key_opad = malloc(2 * size); - if (!state->key_opad) { - libkeccak_state_destroy(&state->sponge); - return 0; - } - memcpy(state->key_opad, data, size); - data += size / sizeof(char); - - if (data[0]) { - state->key_ipad = state->key_opad + size / sizeof(char); - memcpy(state->key_ipad, state->key_opad, size); - for (i = 0; i < size / sizeof(char); i++) - state->key_ipad[i] ^= (char)(OUTER_PAD ^ INNER_PAD); - } - - state->leftover = data[1]; - state->buffer = NULL; - state->buffer_size = 0; - - return parsed + sizeof(size_t) + size + 2 * sizeof(char); -} - - -/** - * Absorb more, or the first part, of the message - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message, in bytes - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_fast_update(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen) -{ - const char *restrict msg = msg_; - char *old; - size_t i; - int n, cn; - - if (state->key_ipad) { - if (libkeccak_fast_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) - return -1; - if (state->key_length & 7) - state->leftover = state->key_ipad[state->key_length >> 3]; - state->key_ipad = NULL; - } - - if (!msg || !msglen) - return 0; - - if (!(state->key_length & 7)) - return libkeccak_fast_update(&state->sponge, msg, msglen); - - if (msglen != state->buffer_size) { - state->buffer = realloc(old = state->buffer, msglen); - if (!state->buffer) - return state->buffer = old, -1; - state->buffer_size = msglen; - } - - n = (int)(state->key_length & 7); - cn = 8 - n; - for (i = 1; i < msglen; i++) - state->buffer[i] = (char)((msg[i - 1] >> cn) | (msg[i] << n)); - state->buffer[0] = (char)((state->leftover & ((1 << n) - 1)) | (msg[0] << n)); - state->leftover = (char)((unsigned char)msg[msglen - 1] >> cn); - - return libkeccak_fast_update(&state->sponge, state->buffer, msglen); -} - - -/** - * Absorb more, or the first part, of the message - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message, in bytes - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_update(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen) -{ - const char *restrict msg = msg_; - size_t i; - int n, cn, r; - - if (state->key_ipad) { - if (libkeccak_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) - return -1; - if (state->key_length & 7) - state->leftover = state->key_ipad[state->key_length >> 3]; - state->key_ipad = NULL; - } - - if (!msg || !msglen) - return 0; - - if (!(state->key_length & 7)) - return libkeccak_update(&state->sponge, msg, msglen); - - if (msglen != state->buffer_size) { - free(state->buffer); - state->buffer = malloc(state->buffer_size = msglen); - if (!state->buffer) - return -1; - } - - n = (int)(state->key_length & 7); - cn = 8 - n; - for (i = 1; i < msglen; i++) - state->buffer[i] = (char)(((unsigned char)msg[i - 1] >> cn) | (msg[i] << n)); - state->buffer[0] = (char)((state->leftover & ((1 << n) - 1)) | (msg[0] << n)); - state->leftover = (char)((unsigned char)msg[msglen - 1] >> cn); - - r = libkeccak_update(&state->sponge, state->buffer, msglen); - my_explicit_bzero(state->buffer, msglen); - return r; -} - - -/** - * Absorb the last part of the message and fetch the hash - * without wiping sensitive data when possible - * - * You may use `&state->sponge` for continued squeezing - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL`, may be modified - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen, - size_t bits, const char *restrict suffix, void *restrict hashsum) -{ - const char *restrict msg = msg_; - size_t hashsize = (size_t)state->sponge.n >> 3; - char *tmp = malloc((size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); - char leftover[2]; - size_t newlen; - - if (!tmp) - return -1; - - if (!(state->key_length & 7)) { - if (libkeccak_fast_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) - goto fail; - goto stage_2; - } - - if (libkeccak_hmac_fast_update(state, msg, msglen) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= (char)(msg[msglen] >> (state->key_length & 7)); - leftover[1] = (char)((unsigned char)msg[msglen] << (8 - (state->key_length & 7))); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_2: - bits = state->sponge.n & 7; - state->key_ipad = state->key_opad; - if (libkeccak_hmac_fast_update(state, NULL, 0) < 0) - goto fail; - - if (!(state->key_length & 7)) { - if (libkeccak_fast_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) - goto fail; - goto stage_3; - } - - if (libkeccak_hmac_fast_update(state, tmp, hashsize) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= (char)(tmp[hashsize] >> (state->key_length & 7)); - leftover[1] = (char)((unsigned char)tmp[hashsize] << (8 - (state->key_length & 7))); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_3: - free(tmp); - return 0; -fail: - free(tmp); - return -1; -} - - -/** - * Absorb the last part of the message and fetch the hash - * and wipe sensitive data when possible - * - * You may use `&state->sponge` for continued squeezing - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL`, may be modified - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_digest(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen, - size_t bits, const char *restrict suffix, void *restrict hashsum) -{ - const char *restrict msg = msg_; - size_t hashsize = (size_t)(state->sponge.n >> 3); - char *tmp = malloc((size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); - char leftover[2]; - size_t newlen; - - if (!tmp) - return -1; - - if (!(state->key_length & 7)) { - if (libkeccak_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) - goto fail; - goto stage_2; - } - - if (libkeccak_hmac_update(state, msg, msglen) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= (char)(msg[msglen] >> (state->key_length & 7)); - leftover[1] = (char)((unsigned char)msg[msglen] << (8 - (state->key_length & 7))); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_2: - bits = state->sponge.n & 7; - state->key_ipad = state->key_opad; - if (libkeccak_hmac_update(state, NULL, 0) < 0) - goto fail; - - if (!(state->key_length & 7)) { - if (libkeccak_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) - goto fail; - goto stage_3; - } - - if (libkeccak_hmac_update(state, tmp, hashsize) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= (char)(tmp[hashsize] >> (state->key_length & 7)); - leftover[1] = (char)((unsigned char)tmp[hashsize] << (8 - (state->key_length & 7))); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_3: - my_explicit_bzero(tmp, (size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); - free(tmp); - return 0; -fail: - my_explicit_bzero(tmp, (size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); - free(tmp); - return -1; -} - diff --git a/libkeccak/state.c b/libkeccak/state.c deleted file mode 100644 index 9e0ffb1..0000000 --- a/libkeccak/state.c +++ /dev/null @@ -1,174 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "../common.h" - - -/** - * Initialise a state according to hashing specifications - * - * @param state The state that should be initialised - * @param spec The specifications for the state - * @return Zero on success, -1 on error - */ -int -libkeccak_state_initialise(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec) -{ - long int x; - state->r = spec->bitrate; - state->n = spec->output; - state->c = spec->capacity; - state->b = state->r + state->c; - state->w = x = state->b / 25; - state->l = 0; - if (x & 0xF0L) state->l |= 4, x >>= 4; - if (x & 0x0CL) state->l |= 2, x >>= 2; - if (x & 0x02L) state->l |= 1; - state->nr = 12 + (state->l << 1); - state->wmod = (state->w == 64) ? ~0LL : (int64_t)((1ULL << state->w) - 1); - for (x = 0; x < 25; x++) - state->S[x] = 0; - state->mptr = 0; - state->mlen = (size_t)(state->r * state->b) >> 2; - state->M = malloc(state->mlen * sizeof(char)); - return state->M == NULL ? -1 : 0; -} - - -/** - * Wipe data in the state's message wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_state_wipe_message(volatile libkeccak_state_t *restrict state) -{ - volatile char *restrict M = state->M; - size_t i; - for (i = 0; i < state->mptr; i++) - M[i] = 0; -} - -/** - * Wipe data in the state's sponge wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_state_wipe_sponge(volatile libkeccak_state_t *restrict state) -{ - volatile int64_t *restrict S = state->S; - size_t i; - for (i = 0; i < 25; i++) - S[i] = 0; -} - -/** - * Wipe sensitive data wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_state_wipe(volatile libkeccak_state_t *restrict state) -{ - libkeccak_state_wipe_message(state); - libkeccak_state_wipe_sponge(state); -} - - -/** - * Make a copy of a state - * - * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) - * @param src The state to duplicate - * @return Zero on success, -1 on error - */ -int -libkeccak_state_copy(libkeccak_state_t *restrict dest, const libkeccak_state_t *restrict src) -{ - memcpy(dest, src, sizeof(libkeccak_state_t)); - dest->M = malloc(src->mlen * sizeof(char)); - if (!dest->M) - return -1; - memcpy(dest->M, src->M, src->mptr * sizeof(char)); - return 0; -} - - -/** - * Marshal a `libkeccak_state_t` into a buffer - * - * @param state The state to marshal - * @param data The output buffer - * @return The number of bytes stored to `data` - */ -size_t -libkeccak_state_marshal(const libkeccak_state_t *restrict state, void *restrict data_) -{ -#define set(type, var) *((type *)data) = state->var, data += sizeof(type) / sizeof(char) - char *restrict data = data_; - set(long int, r); - set(long int, c); - set(long int, n); - set(long int, b); - set(long int, w); - set(int64_t, wmod); - set(long int, l); - set(long int, nr); - memcpy(data, state->S, sizeof(state->S)); - data += sizeof(state->S) / sizeof(char); - set(size_t, mptr); - set(size_t, mlen); - memcpy(data, state->M, state->mptr * sizeof(char)); - data += state->mptr; - return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); -#undef set -} - - -/** - * Unmarshal a `libkeccak_state_t` from a buffer - * - * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) - * @param data The input buffer - * @return The number of bytes read from `data`, 0 on error - */ -size_t -libkeccak_state_unmarshal(libkeccak_state_t *restrict state, const void *restrict data_) -{ -#define get(type, var) state->var = *((const type *)data), data += sizeof(type) / sizeof(char) - const char *restrict data = data_; - get(long int, r); - get(long int, c); - get(long int, n); - get(long int, b); - get(long int, w); - get(int64_t, wmod); - get(long int, l); - get(long int, nr); - memcpy(state->S, data, sizeof(state->S)); - data += sizeof(state->S) / sizeof(char); - get(size_t, mptr); - get(size_t, mlen); - state->M = malloc(state->mptr * sizeof(char)); - if (!state->M) - return 0; - memcpy(state->M, data, state->mptr * sizeof(char)); - data += state->mptr; - return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); -#undef get -} - - -/** - * Gets the number of bytes the `libkeccak_state_t` stored - * at the beginning of `data` occupies - * - * @param data The data buffer - * @return The byte size of the stored state - */ -size_t -libkeccak_state_unmarshal_skip(const void *restrict data_) -{ - const char *restrict data = data_; - data += (7 * sizeof(long int) + 26 * sizeof(int64_t)) / sizeof(char); - return sizeof(libkeccak_state_t) - sizeof(char *) + *(const size_t *)data * sizeof(char); -} diff --git a/libkeccak_behex_lower.3 b/libkeccak_behex_lower.3 new file mode 100644 index 0000000..2078790 --- /dev/null +++ b/libkeccak_behex_lower.3 @@ -0,0 +1,45 @@ +.TH LIBKECCAK_BEHEX_LOWER 3 LIBKECCAK +.SH NAME +libkeccak_behex_lower - Converts a binary hashsum to lower case hexadecimal +.SH SYNOPSIS +.LP +.nf +#include + +void libkeccak_behex_lower(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP); +.fi +.PP +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) diff --git a/libkeccak_behex_lower.c b/libkeccak_behex_lower.c new file mode 100644 index 0000000..77e48c1 --- /dev/null +++ b/libkeccak_behex_lower.c @@ -0,0 +1,21 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Convert a binary hashsum to lower case hexadecimal representation + * + * @param output Output array, should have an allocation size of at least `2 * n + 1` + * @param hashsum The hashsum to convert + * @param n The size of `hashsum` + */ +void +libkeccak_behex_lower(char *restrict output, const void *restrict hashsum_, size_t n) +{ + const unsigned char *restrict hashsum = hashsum_; + output[2 * n] = '\0'; + while (n--) { + output[2 * n + 0] = "0123456789abcdef"[(hashsum[n] >> 4) & 15]; + output[2 * n + 1] = "0123456789abcdef"[(hashsum[n] >> 0) & 15]; + } +} diff --git a/libkeccak_behex_upper.3 b/libkeccak_behex_upper.3 new file mode 100644 index 0000000..b5c67bb --- /dev/null +++ b/libkeccak_behex_upper.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_BEHEX_UPPER 3 LIBKECCAK +.SH NAME +libkeccak_behex_upper - Converts a binary hashsum to upper case hexadecimal +.SH SYNOPSIS +.nf +#include + +void libkeccak_behex_upper(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP); +.fi +.PP +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) diff --git a/libkeccak_behex_upper.c b/libkeccak_behex_upper.c new file mode 100644 index 0000000..73a67a1 --- /dev/null +++ b/libkeccak_behex_upper.c @@ -0,0 +1,21 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Convert a binary hashsum to upper case hexadecimal representation + * + * @param output Output array, should have an allocation size of at least `2 * n + 1` + * @param hashsum The hashsum to convert + * @param n The size of `hashsum` + */ +void +libkeccak_behex_upper(char *restrict output, const void *restrict hashsum_, size_t n) +{ + const unsigned char *restrict hashsum = hashsum_; + output[2 * n] = '\0'; + while (n--) { + output[2 * n + 0] = "0123456789ABCDEF"[(hashsum[n] >> 4) & 15]; + output[2 * n + 1] = "0123456789ABCDEF"[(hashsum[n] >> 0) & 15]; + } +} diff --git a/libkeccak_degeneralise_spec.3 b/libkeccak_degeneralise_spec.3 new file mode 100644 index 0000000..7ec2b72 --- /dev/null +++ b/libkeccak_degeneralise_spec.3 @@ -0,0 +1,118 @@ +.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK +.SH NAME +libkeccak_degeneralise_spec - Set all specification parameters to automatic +.SH SYNOPSIS +.nf +#include + +int libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *\fIspec\fP, libkeccak_spec_t *\fIoutput_spec\fP); +.fi +.PP +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]: +.PP +.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) diff --git a/libkeccak_degeneralise_spec.c b/libkeccak_degeneralise_spec.c new file mode 100644 index 0000000..13963f8 --- /dev/null +++ b/libkeccak_degeneralise_spec.c @@ -0,0 +1,111 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +#ifdef __GNUC__ +# pragma GCC diagnostic push +# pragma GCC diagnostic ignored "-Wmaybe-uninitialized" +#endif + +#define have(v) (spec->v != LIBKECCAK_GENERALISED_SPEC_AUTOMATIC) +#define copy(v) (v = spec->v) +#define deft(v, dv) (have_##v ? v : (dv)) + + +/** + * Convert a `libkeccak_generalised_spec_t` to a `libkeccak_spec_t` + * + * If you are interrested in finding errors, you should call + * `libkeccak_spec_check(output)` if this function returns zero + * + * @param spec The generalised input specifications, will be update with resolved automatic values + * @param output_spec The specification datastructure to fill in + * @return Zero if `spec` is valid, a `LIBKECCAK_GENERALISED_SPEC_ERROR_*` if an error was found + */ +int +libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *restrict spec, + libkeccak_spec_t *restrict output_spec) +{ + long int state_size, word_size, capacity, bitrate, output; + const int have_state_size = have(state_size); + const int have_word_size = have(word_size); + const int have_capacity = have(capacity); + const int have_bitrate = have(bitrate); + const int have_output = have(output); + + + if (have_state_size) { + copy(state_size); + if (state_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE; + if (state_size > 1600) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE; + if (state_size % 25) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25; + } + + if (have_word_size) { + copy(word_size); + if (word_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE; + if (word_size > 64) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE; + if (have_state_size && state_size != word_size * 25) + return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY; + else if (!have_state_size) + spec->state_size = 1, state_size = word_size * 25; + } + + if (have_capacity) { + copy(capacity); + if (capacity <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE; + if (capacity & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8; + } + + if (have_bitrate) { + copy(bitrate); + if (bitrate <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE; + if (bitrate & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8; + } + + if (have_output) { + copy(output); + if (output <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE; + } + + + if (!have_bitrate && !have_capacity && !have_output) { + state_size = deft(state_size, 1600L); + output = ((state_size << 5) / 100L + 7L) & ~0x07L; + bitrate = output << 1; + capacity = state_size - bitrate; + output = output >= 8 ? output : 8; + } else if (!have_bitrate && !have_capacity) { + bitrate = 1024; + capacity = 1600 - 1024; + state_size = deft(state_size, bitrate + capacity); + } else if (!have_bitrate) { + state_size = deft(state_size, 1600L); + bitrate = state_size - capacity; + output = deft(output, capacity == 8 ? 8 : (capacity << 1)); + } else if (!have_capacity) { + state_size = deft(state_size, 1600L); + capacity = state_size - bitrate; + output = deft(output, capacity == 8 ? 8 : (capacity << 1)); + } else { + state_size = deft(state_size, bitrate + capacity); + output = deft(output, capacity == 8 ? 8 : (capacity << 1)); + } + + spec->capacity = output_spec->capacity = capacity; + spec->bitrate = output_spec->bitrate = bitrate; + spec->output = output_spec->output = output; + spec->state_size = state_size; + spec->word_size = state_size / 25; + + return 0; +} + + +#undef deft +#undef copy +#undef have + +#ifdef __GNUC__ +# pragma GCC diagnostic pop +#endif diff --git a/libkeccak_digest.3 b/libkeccak_digest.3 new file mode 100644 index 0000000..5f42796 --- /dev/null +++ b/libkeccak_digest.3 @@ -0,0 +1,139 @@ +.TH LIBKECCAK_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_digest - Complete the hashing of a message with erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_digest(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, + size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP); +.fi +.PP +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 \(dq\(dq 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. +.PP +.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, \(dq\(dq, binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf(\(dq%s\en\(dq, 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) diff --git a/libkeccak_fast_digest.3 b/libkeccak_fast_digest.3 new file mode 100644 index 0000000..9e9c1f3 --- /dev/null +++ b/libkeccak_fast_digest.3 @@ -0,0 +1,141 @@ +.TH LIBKECCAK_FAST_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_fast_digest - Complete the hashing of a message without erasure +.SH SYNOPSIS +.LP +.nf +#include + +int libkeccak_fast_digest(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, + size_t \fIbits\fP, const char *\fIsuffix\fP, void *\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 \(dq\(dq 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. +.PP +.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, \(dq\(dq, binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf(\(dq%s\en\(dq, 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) diff --git a/libkeccak_fast_squeeze.3 b/libkeccak_fast_squeeze.3 new file mode 100644 index 0000000..393e264 --- /dev/null +++ b/libkeccak_fast_squeeze.3 @@ -0,0 +1,34 @@ +.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_fast_squeeze - Runs the squeeze phase a number of times +.SH SYNOPSIS +.nf +#include + +void libkeccak_fast_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); +.fi +.PP +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) diff --git a/libkeccak_fast_update.3 b/libkeccak_fast_update.3 new file mode 100644 index 0000000..3398984 --- /dev/null +++ b/libkeccak_fast_update.3 @@ -0,0 +1,90 @@ +.TH LIBKECCAK_FAST_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_fast_update - Partially hash a message without erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_fast_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); +.fi +.PP +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. +.PP +.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, \(dq\(dq, binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf(\(dq%s\en\(dq, 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) diff --git a/libkeccak_generalised_spec_initialise.3 b/libkeccak_generalised_spec_initialise.3 new file mode 100644 index 0000000..1a3bccb --- /dev/null +++ b/libkeccak_generalised_spec_initialise.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_GENERALISED_SPEC_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_generalised_spec_initialise - Set all specification parameters to automatic +.SH SYNOPSIS +.nf +#include + +void libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *\fIspec\fP); +.fi +.PP +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) diff --git a/libkeccak_generalised_sum_fd.3 b/libkeccak_generalised_sum_fd.3 new file mode 100644 index 0000000..bae5bae --- /dev/null +++ b/libkeccak_generalised_sum_fd.3 @@ -0,0 +1,126 @@ +.TH LIBKECCAK_GENERALISED_SUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_generalised_sum_fd - Calculate the hash of a file +.SH SYNOPSIS +.nf +#include + +int libkeccak_generalised_sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP, + const char *\fIsuffix\fP, void *\fIhashsum\fP); +.fi +.PP +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. +.PP +.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(\(dq%s\en\(dq, 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) diff --git a/libkeccak_generalised_sum_fd.c b/libkeccak_generalised_sum_fd.c new file mode 100644 index 0000000..133ffa9 --- /dev/null +++ b/libkeccak_generalised_sum_fd.c @@ -0,0 +1,49 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Calculate a Keccak-family hashsum of a file, + * the content of the file is assumed non-sensitive + * + * @param fd The file descriptor of the file to hash + * @param state The hashing state, should not be initialised (memory leak otherwise) + * @param spec Specifications for the hashing algorithm + * @param suffix The data suffix, see `libkeccak_digest` + * @param hashsum Output array for the hashsum, have an allocation size of + * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_generalised_sum_fd(int fd, libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec, + const char *restrict suffix, void *restrict hashsum) +{ + ssize_t got; + struct stat attr; + size_t blksize = 4096; + char *restrict chunk; + + if (libkeccak_state_initialise(state, spec) < 0) + return -1; + + if (fstat(fd, &attr) == 0) + if (attr.st_blksize > 0) + blksize = (size_t)(attr.st_blksize); + + chunk = alloca(blksize); + + for (;;) { + got = read(fd, chunk, blksize); + if (got < 0) { + if (errno == EINTR) + continue; + return -1; + } + if (got == 0) + break; + if (libkeccak_fast_update(state, chunk, (size_t)got) < 0) + return -1; + } + + return libkeccak_fast_digest(state, NULL, 0, 0, suffix, hashsum); +} diff --git a/libkeccak_hmac_copy.3 b/libkeccak_hmac_copy.3 new file mode 100644 index 0000000..0f29ae8 --- /dev/null +++ b/libkeccak_hmac_copy.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_HMAC_COPY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_copy - Copies an HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_copy(libkeccak_hmac_state_t *\fIdest\fP, const libkeccak_hmac_state_t *\fIsrc\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_copy.c b/libkeccak_hmac_copy.c new file mode 100644 index 0000000..49fc1e7 --- /dev/null +++ b/libkeccak_hmac_copy.c @@ -0,0 +1,38 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Make a copy of an HMAC hashing-state + * + * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) + * @param src The state to duplicate + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_copy(libkeccak_hmac_state_t *restrict dest, const libkeccak_hmac_state_t *restrict src) +{ + size_t size; + + dest->key_opad = NULL; + dest->key_ipad = NULL; + + if (libkeccak_state_copy(&dest->sponge, &src->sponge) < 0) + return -1; + + dest->key_length = src->key_length; + dest->leftover = src->leftover; + + size = (src->key_length + 7) >> 3; + dest->key_opad = malloc(2 * size); + if (dest->key_opad == NULL) { + libkeccak_state_destroy(&dest->sponge); + return -1; + } + dest->key_ipad = dest->key_opad + size / sizeof(char); + + memcpy(dest->key_opad, src->key_opad, size); + memcpy(dest->key_ipad, src->key_ipad, size); + + return 0; +} diff --git a/libkeccak_hmac_create.3 b/libkeccak_hmac_create.3 new file mode 100644 index 0000000..91bb8a1 --- /dev/null +++ b/libkeccak_hmac_create.3 @@ -0,0 +1,47 @@ +.TH LIBKECCAK_HMAC_CREATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_create - Allocate and initialise HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +libkeccak_hmac_state_t *libkeccak_hmac_create(const libkeccak_spec_t *\fIspec\fP, const void *\fIkey\fP, size_t \fIkey_length\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_destroy.3 b/libkeccak_hmac_destroy.3 new file mode 100644 index 0000000..0038eca --- /dev/null +++ b/libkeccak_hmac_destroy.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_HMAC_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_destroy - Destroys an HMAC-hashing state with erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_hmac_destroy(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_digest.3 b/libkeccak_hmac_digest.3 new file mode 100644 index 0000000..99e460a --- /dev/null +++ b/libkeccak_hmac_digest.3 @@ -0,0 +1,97 @@ +.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_digest(libkeccak_hmac_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, + size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP); +.fi +.PP +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 \(dq\(dq 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) diff --git a/libkeccak_hmac_digest.c b/libkeccak_hmac_digest.c new file mode 100644 index 0000000..1cba224 --- /dev/null +++ b/libkeccak_hmac_digest.c @@ -0,0 +1,80 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Absorb the last part of the message and fetch the hash + * and wipe sensitive data when possible + * + * You may use `&state->sponge` for continued squeezing + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL`, may be modified + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_digest(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen, + size_t bits, const char *restrict suffix, void *restrict hashsum) +{ + const char *restrict msg = msg_; + size_t hashsize = (size_t)(state->sponge.n >> 3); + char *tmp = malloc((size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); + char leftover[2]; + size_t newlen; + + if (!tmp) + return -1; + + if (!(state->key_length & 7)) { + if (libkeccak_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) + goto fail; + goto stage_2; + } + + if (libkeccak_hmac_update(state, msg, msglen) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= (char)(msg[msglen] >> (state->key_length & 7)); + leftover[1] = (char)((unsigned char)msg[msglen] << (8 - (state->key_length & 7))); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_2: + bits = state->sponge.n & 7; + state->key_ipad = state->key_opad; + if (libkeccak_hmac_update(state, NULL, 0) < 0) + goto fail; + + if (!(state->key_length & 7)) { + if (libkeccak_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) + goto fail; + goto stage_3; + } + + if (libkeccak_hmac_update(state, tmp, hashsize) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= (char)(tmp[hashsize] >> (state->key_length & 7)); + leftover[1] = (char)((unsigned char)tmp[hashsize] << (8 - (state->key_length & 7))); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_3: + my_explicit_bzero(tmp, (size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); + free(tmp); + return 0; +fail: + my_explicit_bzero(tmp, (size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); + free(tmp); + return -1; +} diff --git a/libkeccak_hmac_duplicate.3 b/libkeccak_hmac_duplicate.3 new file mode 100644 index 0000000..bb16139 --- /dev/null +++ b/libkeccak_hmac_duplicate.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_HMAC_DUPLICATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_duplicate - Allocate a duplicate an HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +libkeccak_hmac_state_t *libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *\fIsrc\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_fast_destroy.3 b/libkeccak_hmac_fast_destroy.3 new file mode 100644 index 0000000..31bf894 --- /dev/null +++ b/libkeccak_hmac_fast_destroy.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_HMAC_FAST_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_destroy - Destroys an HMAC-hashing state without erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_hamc_fast_destroy(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_fast_digest.3 b/libkeccak_hmac_fast_digest.3 new file mode 100644 index 0000000..68fcc69 --- /dev/null +++ b/libkeccak_hmac_fast_digest.3 @@ -0,0 +1,98 @@ +.TH LIBKECCAK_HMAC_FAST_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_digest - Complete the HMAC-hashing of a message without erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, + size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP); +.fi +.PP +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 \(dq\(dq 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) diff --git a/libkeccak_hmac_fast_digest.c b/libkeccak_hmac_fast_digest.c new file mode 100644 index 0000000..d4bacb8 --- /dev/null +++ b/libkeccak_hmac_fast_digest.c @@ -0,0 +1,78 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Absorb the last part of the message and fetch the hash + * without wiping sensitive data when possible + * + * You may use `&state->sponge` for continued squeezing + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL`, may be modified + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen, + size_t bits, const char *restrict suffix, void *restrict hashsum) +{ + const char *restrict msg = msg_; + size_t hashsize = (size_t)state->sponge.n >> 3; + char *tmp = malloc((size_t)((state->sponge.n + 7) >> 3) * sizeof(char)); + char leftover[2]; + size_t newlen; + + if (!tmp) + return -1; + + if (!(state->key_length & 7)) { + if (libkeccak_fast_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) + goto fail; + goto stage_2; + } + + if (libkeccak_hmac_fast_update(state, msg, msglen) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= (char)(msg[msglen] >> (state->key_length & 7)); + leftover[1] = (char)((unsigned char)msg[msglen] << (8 - (state->key_length & 7))); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_2: + bits = state->sponge.n & 7; + state->key_ipad = state->key_opad; + if (libkeccak_hmac_fast_update(state, NULL, 0) < 0) + goto fail; + + if (!(state->key_length & 7)) { + if (libkeccak_fast_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) + goto fail; + goto stage_3; + } + + if (libkeccak_hmac_fast_update(state, tmp, hashsize) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= (char)(tmp[hashsize] >> (state->key_length & 7)); + leftover[1] = (char)((unsigned char)tmp[hashsize] << (8 - (state->key_length & 7))); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_3: + free(tmp); + return 0; +fail: + free(tmp); + return -1; +} diff --git a/libkeccak_hmac_fast_free.3 b/libkeccak_hmac_fast_free.3 new file mode 100644 index 0000000..f888872 --- /dev/null +++ b/libkeccak_hmac_fast_free.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_free - Destroys and deallocates an HMAC-hashing state without erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_hmac_fast_free(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_fast_update.3 b/libkeccak_hmac_fast_update.3 new file mode 100644 index 0000000..a41b72f --- /dev/null +++ b/libkeccak_hmac_fast_update.3 @@ -0,0 +1,53 @@ +.TH LIBKECCAK_HMAC_FAST_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_update - Partially HMAC-hash a message without erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_fast_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_fast_update.c b/libkeccak_hmac_fast_update.c new file mode 100644 index 0000000..d4a3fbe --- /dev/null +++ b/libkeccak_hmac_fast_update.c @@ -0,0 +1,51 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Absorb more, or the first part, of the message + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message, in bytes + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_fast_update(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen) +{ + const char *restrict msg = msg_; + char *old; + size_t i; + int n, cn; + + if (state->key_ipad) { + if (libkeccak_fast_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) + return -1; + if (state->key_length & 7) + state->leftover = state->key_ipad[state->key_length >> 3]; + state->key_ipad = NULL; + } + + if (!msg || !msglen) + return 0; + + if (!(state->key_length & 7)) + return libkeccak_fast_update(&state->sponge, msg, msglen); + + if (msglen != state->buffer_size) { + state->buffer = realloc(old = state->buffer, msglen); + if (!state->buffer) + return state->buffer = old, -1; + state->buffer_size = msglen; + } + + n = (int)(state->key_length & 7); + cn = 8 - n; + for (i = 1; i < msglen; i++) + state->buffer[i] = (char)((msg[i - 1] >> cn) | (msg[i] << n)); + state->buffer[0] = (char)((state->leftover & ((1 << n) - 1)) | (msg[0] << n)); + state->leftover = (char)((unsigned char)msg[msglen - 1] >> cn); + + return libkeccak_fast_update(&state->sponge, state->buffer, msglen); +} diff --git a/libkeccak_hmac_free.3 b/libkeccak_hmac_free.3 new file mode 100644 index 0000000..c70f369 --- /dev/null +++ b/libkeccak_hmac_free.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_HMAC_FREE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_free - Destroys and deallocates an HMAC-hashing state with erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_hmac_free(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_initialise.3 b/libkeccak_hmac_initialise.3 new file mode 100644 index 0000000..17b2b9f --- /dev/null +++ b/libkeccak_hmac_initialise.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_HMAC_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_initialise - Initialise HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_initialise(libkeccak_hmac_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP, + const void *\fIkey\fP, size_t \fIkey_length\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_marshal.3 b/libkeccak_hmac_marshal.3 new file mode 100644 index 0000000..2e31dd7 --- /dev/null +++ b/libkeccak_hmac_marshal.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_HMAC_MARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_hmac_marshal - Marshals an HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_hmac_marshal(const libkeccak_hmac_state_t *\fIstate\fP, void *\fIdata\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_marshal_size.3 b/libkeccak_hmac_marshal_size.3 new file mode 100644 index 0000000..fe8ec2f --- /dev/null +++ b/libkeccak_hmac_marshal_size.3 @@ -0,0 +1,31 @@ +.TH LIBKECCAK_HMAC_MARSHAL_SIZE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_marshal_size - Calculates the marshal-size of an HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_reset.3 b/libkeccak_hmac_reset.3 new file mode 100644 index 0000000..4a9aadf --- /dev/null +++ b/libkeccak_hmac_reset.3 @@ -0,0 +1,45 @@ +.TH LIBKECCAK_HMAC_RESET 3 LIBKECCAK +.SH NAME +libkeccak_hmac_reset - Reinitialise a HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_reset(libkeccak_hmac_state_t *\fIstate\fP, const void *\fIkey\fP, size_t \fIkey_length\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_set_key.3 b/libkeccak_hmac_set_key.3 new file mode 100644 index 0000000..ea8084e --- /dev/null +++ b/libkeccak_hmac_set_key.3 @@ -0,0 +1,35 @@ +.TH LIBKECCAK_HMAC_SET_KEY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_set_key - Changes key for a the HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_set_key(libkeccak_hmac_state_t *\fIstate\fP, const void *\fIkey\fP, size_t \fIkey_length\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_set_key.c b/libkeccak_hmac_set_key.c new file mode 100644 index 0000000..4f450f8 --- /dev/null +++ b/libkeccak_hmac_set_key.c @@ -0,0 +1,46 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Change the HMAC-hashing key on the state + * + * @param state The state that should be reset + * @param key The new key + * @param key_length The length of key, in bits + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_set_key(libkeccak_hmac_state_t *restrict state, const void *restrict key, size_t key_length) +{ + size_t i, size, new_key_length, key_bytes; + char *old; + + size = (size_t)(state->sponge.r) > key_length ? (size_t)(state->sponge.r) : key_length; + new_key_length = size; + size = (size + 7) >> 3; + key_bytes = (key_length + 7) >> 3; + + if (size != key_bytes) { + state->key_opad = realloc(old = state->key_opad, 2 * size); + if (!state->key_opad) + return state->key_opad = old, -1; + state->key_ipad = state->key_opad + size / sizeof(char); + } + + memcpy(state->key_opad, key, key_bytes); + if (key_length & 7) + state->key_opad[(key_bytes >> 3) - 1] &= (char)((1 << (key_length & 7)) - 1); + + if ((size_t)(state->sponge.r) > key_length) + __builtin_memset(state->key_opad + key_bytes / sizeof(char), 0, size - key_bytes); + + for (i = 0; i < size; i++) { + state->key_ipad[i] = state->key_opad[i] ^ HMAC_INNER_PAD; + state->key_opad[i] ^= HMAC_OUTER_PAD; + } + + state->key_length = new_key_length; + + return 0; +} diff --git a/libkeccak_hmac_unmarshal.3 b/libkeccak_hmac_unmarshal.3 new file mode 100644 index 0000000..c3ed187 --- /dev/null +++ b/libkeccak_hmac_unmarshal.3 @@ -0,0 +1,33 @@ +.TH LIBKECCAK_HMAC_UNMARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_hmac_unmarshal - Unharshals an HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *\fIstate\fP, const void *\fIdata\fP); +.fi +.PP +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 . +.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) diff --git a/libkeccak_hmac_unmarshal.c b/libkeccak_hmac_unmarshal.c new file mode 100644 index 0000000..e64cd08 --- /dev/null +++ b/libkeccak_hmac_unmarshal.c @@ -0,0 +1,50 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Unmarshal a `libkeccak_hmac_state_t` from a buffer + * + * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) + * @param data The input buffer + * @return The number of bytes read from `data`, 0 on error + */ +size_t +libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *restrict state, const void *restrict data_) +{ + const char *restrict data = data_; + size_t parsed, size, i; + + state->key_opad = NULL; + state->key_ipad = NULL; + + parsed = libkeccak_state_unmarshal(&state->sponge, data); + if (parsed == 0) + return 0; + + data += parsed / sizeof(char); + state->key_length = *(const size_t *)data; + data += sizeof(size_t) / sizeof(char); + size = (state->key_length + 7) >> 3; + + state->key_opad = malloc(2 * size); + if (!state->key_opad) { + libkeccak_state_destroy(&state->sponge); + return 0; + } + memcpy(state->key_opad, data, size); + data += size / sizeof(char); + + if (data[0]) { + state->key_ipad = state->key_opad + size / sizeof(char); + memcpy(state->key_ipad, state->key_opad, size); + for (i = 0; i < size / sizeof(char); i++) + state->key_ipad[i] ^= (char)(HMAC_OUTER_PAD ^ HMAC_INNER_PAD); + } + + state->leftover = data[1]; + state->buffer = NULL; + state->buffer_size = 0; + + return parsed + sizeof(size_t) + size + 2 * sizeof(char); +} diff --git a/libkeccak_hmac_unmarshal_skip.3 b/libkeccak_hmac_unmarshal_skip.3 new file mode 100644 index 0000000..25db1ba --- /dev/null +++ b/libkeccak_hmac_unmarshal_skip.3 @@ -0,0 +1,35 @@ +.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 +.nf +#include + +size_t libkeccak_hmac_unmarshal_skip(const void *\fIdata\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_update.3 b/libkeccak_hmac_update.3 new file mode 100644 index 0000000..13891cb --- /dev/null +++ b/libkeccak_hmac_update.3 @@ -0,0 +1,50 @@ +.TH LIBKECCAK_HMAC_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_update - Partially HMAC-hash a message with erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_update.c b/libkeccak_hmac_update.c new file mode 100644 index 0000000..b2321f2 --- /dev/null +++ b/libkeccak_hmac_update.c @@ -0,0 +1,52 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Absorb more, or the first part, of the message + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message, in bytes + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_update(libkeccak_hmac_state_t *restrict state, const void *restrict msg_, size_t msglen) +{ + const char *restrict msg = msg_; + size_t i; + int n, cn, r; + + if (state->key_ipad) { + if (libkeccak_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) + return -1; + if (state->key_length & 7) + state->leftover = state->key_ipad[state->key_length >> 3]; + state->key_ipad = NULL; + } + + if (!msg || !msglen) + return 0; + + if (!(state->key_length & 7)) + return libkeccak_update(&state->sponge, msg, msglen); + + if (msglen != state->buffer_size) { + free(state->buffer); + state->buffer = malloc(state->buffer_size = msglen); + if (!state->buffer) + return -1; + } + + n = (int)(state->key_length & 7); + cn = 8 - n; + for (i = 1; i < msglen; i++) + state->buffer[i] = (char)(((unsigned char)msg[i - 1] >> cn) | (msg[i] << n)); + state->buffer[0] = (char)((state->leftover & ((1 << n) - 1)) | (msg[0] << n)); + state->leftover = (char)((unsigned char)msg[msglen - 1] >> cn); + + r = libkeccak_update(&state->sponge, state->buffer, msglen); + my_explicit_bzero(state->buffer, msglen); + return r; +} diff --git a/libkeccak_hmac_wipe.3 b/libkeccak_hmac_wipe.3 new file mode 100644 index 0000000..471a9a8 --- /dev/null +++ b/libkeccak_hmac_wipe.3 @@ -0,0 +1,31 @@ +.TH LIBKECCAK_HMAC_WIPE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_wipe - Securely erase sensitive data from a HMAC-hashing state +.SH SYNOPSIS +.nf +#include + +int libkeccak_hmac_wipe(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_hmac_wipe.c b/libkeccak_hmac_wipe.c new file mode 100644 index 0000000..fd99c48 --- /dev/null +++ b/libkeccak_hmac_wipe.c @@ -0,0 +1,22 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Wipe sensitive data wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_hmac_wipe(volatile libkeccak_hmac_state_t *restrict state) +{ + volatile char *restrict key_pads; + size_t i, size; + key_pads = state->key_opad; + size = 2 * ((state->key_length + 7) >> 3); + libkeccak_state_wipe(&state->sponge); + for (i = 0; i < size; i++) + key_pads[i] = 0; + state->leftover = 0; + __builtin_memset(state->buffer, 0, state->buffer_size); +} diff --git a/libkeccak_keccaksum_fd.3 b/libkeccak_keccaksum_fd.3 new file mode 100644 index 0000000..ccd1f8a --- /dev/null +++ b/libkeccak_keccaksum_fd.3 @@ -0,0 +1,113 @@ +.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_keccaksum_fd - Calculate a Keccak hashsum of a file +.SH SYNOPSIS +.nf +#include + +int libkeccak_keccaksum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP, void *\fIhashsum\fP); +.fi +.PP +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(\(dq%s\en\(dq, 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) diff --git a/libkeccak_rawshakesum_fd.3 b/libkeccak_rawshakesum_fd.3 new file mode 100644 index 0000000..8fad150 --- /dev/null +++ b/libkeccak_rawshakesum_fd.3 @@ -0,0 +1,108 @@ +.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file +.SH SYNOPSIS +.nf +#include + +int libkeccak_rawshakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIsemicapacity\fP, long int \fIoutput\fP, void *\fIhashsum\fP); +.fi +.PP +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(\(dq%s\en\(dq, 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) diff --git a/libkeccak_sha3sum_fd.3 b/libkeccak_sha3sum_fd.3 new file mode 100644 index 0000000..0d697e6 --- /dev/null +++ b/libkeccak_sha3sum_fd.3 @@ -0,0 +1,105 @@ +.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file +.SH SYNOPSIS +.nf +#include + +int libkeccak_sha3sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIoutput\fP, void *\fIhashsum\fP); +.fi +.PP +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(\(dq%s\en\(dq, 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) diff --git a/libkeccak_shakesum_fd.3 b/libkeccak_shakesum_fd.3 new file mode 100644 index 0000000..441c549 --- /dev/null +++ b/libkeccak_shakesum_fd.3 @@ -0,0 +1,108 @@ +.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file +.SH SYNOPSIS +.nf +#include + +int libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIsemicapacity\fP, long int \fIoutput\fP, void *\fIhashsum\fP); +.fi +.PP +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(\(dq%s\en\(dq, 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) diff --git a/libkeccak_simple_squeeze.3 b/libkeccak_simple_squeeze.3 new file mode 100644 index 0000000..8626f5a --- /dev/null +++ b/libkeccak_simple_squeeze.3 @@ -0,0 +1,33 @@ +.TH LIBKECCAK_SIMPLE_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_simple_squeeze - Runs Keccak-f a number of times +.SH SYNOPSIS +.nf +#include + +void libkeccak_simple_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); +.fi +.PP +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) diff --git a/libkeccak_spec_check.3 b/libkeccak_spec_check.3 new file mode 100644 index 0000000..7dd19d8 --- /dev/null +++ b/libkeccak_spec_check.3 @@ -0,0 +1,90 @@ +.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK +.SH NAME +libkeccak_spec_check - Validate hashing parameters +.SH SYNOPSIS +.nf +#include + +int libkeccak_spec_check(const libkeccak_spec_t *\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_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) diff --git a/libkeccak_spec_rawshake.3 b/libkeccak_spec_rawshake.3 new file mode 100644 index 0000000..f5f16b8 --- /dev/null +++ b/libkeccak_spec_rawshake.3 @@ -0,0 +1,47 @@ +.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters +.SH SYNOPSIS +.nf +#include + +void libkeccak_spec_rawshake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); +.fi +.PP +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): +.PP +.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) diff --git a/libkeccak_spec_sha3.3 b/libkeccak_spec_sha3.3 new file mode 100644 index 0000000..1320631 --- /dev/null +++ b/libkeccak_spec_sha3.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK +.SH NAME +libkeccak_spec_sha3 - Configure SHA-3 hashing parameters +.SH SYNOPSIS +.nf +#include + +void libkeccak_spec_sha3(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP); +.fi +.PP +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: +.PP +.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) diff --git a/libkeccak_spec_shake.3 b/libkeccak_spec_shake.3 new file mode 100644 index 0000000..4beea49 --- /dev/null +++ b/libkeccak_spec_shake.3 @@ -0,0 +1,47 @@ +.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_shake - Configure SHAKE hashing parameters +.SH SYNOPSIS +.nf +#include + +void libkeccak_spec_shake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); +.fi +.PP +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): +.PP +.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) diff --git a/libkeccak_squeeze.3 b/libkeccak_squeeze.3 new file mode 100644 index 0000000..67430a4 --- /dev/null +++ b/libkeccak_squeeze.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_squeeze - Runs the squeeze phase +.SH SYNOPSIS +.nf +#include + +void libkeccak_squeeze(libkeccak_state_t *\fIstate\fP, void *\fIhashsum\fP); +.fi +.PP +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) diff --git a/libkeccak_state_copy.3 b/libkeccak_state_copy.3 new file mode 100644 index 0000000..4bd892c --- /dev/null +++ b/libkeccak_state_copy.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_STATE_COPY 3 LIBKECCAK +.SH NAME +libkeccak_state_copy - Copies hash state +.SH SYNOPSIS +.nf +#include + +int libkeccak_state_copy(libkeccak_state_t *\fIdest\fP, const libkeccak_state_t *\fIsrc\fP); +.fi +.PP +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) diff --git a/libkeccak_state_copy.c b/libkeccak_state_copy.c new file mode 100644 index 0000000..76672d2 --- /dev/null +++ b/libkeccak_state_copy.c @@ -0,0 +1,21 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Make a copy of a state + * + * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) + * @param src The state to duplicate + * @return Zero on success, -1 on error + */ +int +libkeccak_state_copy(libkeccak_state_t *restrict dest, const libkeccak_state_t *restrict src) +{ + memcpy(dest, src, sizeof(libkeccak_state_t)); + dest->M = malloc(src->mlen * sizeof(char)); + if (!dest->M) + return -1; + memcpy(dest->M, src->M, src->mptr * sizeof(char)); + return 0; +} diff --git a/libkeccak_state_create.3 b/libkeccak_state_create.3 new file mode 100644 index 0000000..f27e124 --- /dev/null +++ b/libkeccak_state_create.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_STATE_CREATE 3 LIBKECCAK +.SH NAME +libkeccak_state_create - Allocate and initialise hash state +.SH SYNOPSIS +.nf +#include + +libkeccak_state_t *libkeccak_state_create(const libkeccak_spec_t *\fIspec\fP); +.fi +.PP +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) diff --git a/libkeccak_state_destroy.3 b/libkeccak_state_destroy.3 new file mode 100644 index 0000000..2df1f49 --- /dev/null +++ b/libkeccak_state_destroy.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_STATE_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_state_destroy - Destroys a hash state with erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_destroy(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_duplicate.3 b/libkeccak_state_duplicate.3 new file mode 100644 index 0000000..dfd0612 --- /dev/null +++ b/libkeccak_state_duplicate.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_STATE_DUPLICATE 3 LIBKECCAK +.SH NAME +libkeccak_state_duplicate - Allocate a duplicate hash state +.SH SYNOPSIS +.nf +#include + +libkeccak_state_t *libkeccak_state_duplicate(const libkeccak_state_t *\fIsrc\fP); +.fi +.PP +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) diff --git a/libkeccak_state_fast_destroy.3 b/libkeccak_state_fast_destroy.3 new file mode 100644 index 0000000..f346611 --- /dev/null +++ b/libkeccak_state_fast_destroy.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_STATE_FAST_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_state_fast_destroy - Destroys a hash state without erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_fast_destroy(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_fast_free.3 b/libkeccak_state_fast_free.3 new file mode 100644 index 0000000..01d0ed8 --- /dev/null +++ b/libkeccak_state_fast_free.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK +.SH NAME +libkeccak_state_fast_free - Destroys and deallocates a hash state without erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_fast_free(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_free.3 b/libkeccak_state_free.3 new file mode 100644 index 0000000..8761d54 --- /dev/null +++ b/libkeccak_state_free.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_STATE_FREE 3 LIBKECCAK +.SH NAME +libkeccak_state_free - Destroys and deallocates a hash state with erasure +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_free(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_initialise.3 b/libkeccak_state_initialise.3 new file mode 100644 index 0000000..cef4d3d --- /dev/null +++ b/libkeccak_state_initialise.3 @@ -0,0 +1,54 @@ +.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_state_initialise - Initialise hash state +.SH SYNOPSIS +.nf +#include + +int libkeccak_state_initialise(libkeccak_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP); +.fi +.PP +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) diff --git a/libkeccak_state_initialise.c b/libkeccak_state_initialise.c new file mode 100644 index 0000000..2559f47 --- /dev/null +++ b/libkeccak_state_initialise.c @@ -0,0 +1,33 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Initialise a state according to hashing specifications + * + * @param state The state that should be initialised + * @param spec The specifications for the state + * @return Zero on success, -1 on error + */ +int +libkeccak_state_initialise(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec) +{ + long int x; + state->r = spec->bitrate; + state->n = spec->output; + state->c = spec->capacity; + state->b = state->r + state->c; + state->w = x = state->b / 25; + state->l = 0; + if (x & 0xF0L) state->l |= 4, x >>= 4; + if (x & 0x0CL) state->l |= 2, x >>= 2; + if (x & 0x02L) state->l |= 1; + state->nr = 12 + (state->l << 1); + state->wmod = (state->w == 64) ? ~0LL : (int64_t)((1ULL << state->w) - 1); + for (x = 0; x < 25; x++) + state->S[x] = 0; + state->mptr = 0; + state->mlen = (size_t)(state->r * state->b) >> 2; + state->M = malloc(state->mlen * sizeof(char)); + return state->M == NULL ? -1 : 0; +} diff --git a/libkeccak_state_marshal.3 b/libkeccak_state_marshal.3 new file mode 100644 index 0000000..ae21d17 --- /dev/null +++ b/libkeccak_state_marshal.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_STATE_MARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_state_marshal - Marshals a hash state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_state_marshal(const libkeccak_state_t *\fIstate\fP, void *\fIdata\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_marshal () +function marshals +.I *state +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) diff --git a/libkeccak_state_marshal.c b/libkeccak_state_marshal.c new file mode 100644 index 0000000..2714a52 --- /dev/null +++ b/libkeccak_state_marshal.c @@ -0,0 +1,33 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Marshal a `libkeccak_state_t` into a buffer + * + * @param state The state to marshal + * @param data The output buffer + * @return The number of bytes stored to `data` + */ +size_t +libkeccak_state_marshal(const libkeccak_state_t *restrict state, void *restrict data_) +{ +#define set(type, var) *((type *)data) = state->var, data += sizeof(type) / sizeof(char) + char *restrict data = data_; + set(long int, r); + set(long int, c); + set(long int, n); + set(long int, b); + set(long int, w); + set(int64_t, wmod); + set(long int, l); + set(long int, nr); + memcpy(data, state->S, sizeof(state->S)); + data += sizeof(state->S) / sizeof(char); + set(size_t, mptr); + set(size_t, mlen); + memcpy(data, state->M, state->mptr * sizeof(char)); + data += state->mptr; + return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); +#undef set +} diff --git a/libkeccak_state_marshal_size.3 b/libkeccak_state_marshal_size.3 new file mode 100644 index 0000000..9eca42b --- /dev/null +++ b/libkeccak_state_marshal_size.3 @@ -0,0 +1,31 @@ +.TH LIBKECCAK_STATE_MARSHAL_SIZE 3 LIBKECCAK +.SH NAME +libkeccak_state_marshal_size - Calculates the marshal-size of a hash state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_state_marshal_size(const libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_reset.3 b/libkeccak_state_reset.3 new file mode 100644 index 0000000..566bd6b --- /dev/null +++ b/libkeccak_state_reset.3 @@ -0,0 +1,32 @@ +.TH LIBKECCAK_STATE_RESET 3 LIBKECCAK +.SH NAME +libkeccak_state_reset - Reinitialise hash state +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_reset(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_unmarshal.3 b/libkeccak_state_unmarshal.3 new file mode 100644 index 0000000..8643164 --- /dev/null +++ b/libkeccak_state_unmarshal.3 @@ -0,0 +1,34 @@ +.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_state_unmarshal - Unharshals a hash state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_state_unmarshal(libkeccak_state_t *\fIstate\fP, const void *\fIdata\fP); +.fi +.PP +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) diff --git a/libkeccak_state_unmarshal.c b/libkeccak_state_unmarshal.c new file mode 100644 index 0000000..7177bd5 --- /dev/null +++ b/libkeccak_state_unmarshal.c @@ -0,0 +1,36 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Unmarshal a `libkeccak_state_t` from a buffer + * + * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) + * @param data The input buffer + * @return The number of bytes read from `data`, 0 on error + */ +size_t +libkeccak_state_unmarshal(libkeccak_state_t *restrict state, const void *restrict data_) +{ +#define get(type, var) state->var = *((const type *)data), data += sizeof(type) / sizeof(char) + const char *restrict data = data_; + get(long int, r); + get(long int, c); + get(long int, n); + get(long int, b); + get(long int, w); + get(int64_t, wmod); + get(long int, l); + get(long int, nr); + memcpy(state->S, data, sizeof(state->S)); + data += sizeof(state->S) / sizeof(char); + get(size_t, mptr); + get(size_t, mlen); + state->M = malloc(state->mptr * sizeof(char)); + if (!state->M) + return 0; + memcpy(state->M, data, state->mptr * sizeof(char)); + data += state->mptr; + return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); +#undef get +} diff --git a/libkeccak_state_unmarshal_skip.3 b/libkeccak_state_unmarshal_skip.3 new file mode 100644 index 0000000..9fb9336 --- /dev/null +++ b/libkeccak_state_unmarshal_skip.3 @@ -0,0 +1,35 @@ +.TH LIBKECCAK_STATE_UNMARSHAL_SKIP 3 LIBKECCAK +.SH NAME +libkeccak_state_unmarshal_skip - Calculates the marshal-size of a marshalled hash state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_state_unmarshal_skip(const void *\fIdata\fP); +.fi +.PP +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) diff --git a/libkeccak_state_unmarshal_skip.c b/libkeccak_state_unmarshal_skip.c new file mode 100644 index 0000000..df488bf --- /dev/null +++ b/libkeccak_state_unmarshal_skip.c @@ -0,0 +1,18 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Gets the number of bytes the `libkeccak_state_t` stored + * at the beginning of `data` occupies + * + * @param data The data buffer + * @return The byte size of the stored state + */ +size_t +libkeccak_state_unmarshal_skip(const void *restrict data_) +{ + const char *restrict data = data_; + data += (7 * sizeof(long int) + 26 * sizeof(int64_t)) / sizeof(char); + return sizeof(libkeccak_state_t) - sizeof(char *) + *(const size_t *)data * sizeof(char); +} diff --git a/libkeccak_state_wipe.3 b/libkeccak_state_wipe.3 new file mode 100644 index 0000000..1ae2759 --- /dev/null +++ b/libkeccak_state_wipe.3 @@ -0,0 +1,32 @@ +.TH LIBKECCAK_STATE_WIPE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe - Securely erase sensitive data +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_wipe(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_wipe.c b/libkeccak_state_wipe.c new file mode 100644 index 0000000..e5c721c --- /dev/null +++ b/libkeccak_state_wipe.c @@ -0,0 +1,15 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Wipe sensitive data wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_state_wipe(volatile libkeccak_state_t *restrict state) +{ + libkeccak_state_wipe_message(state); + libkeccak_state_wipe_sponge(state); +} diff --git a/libkeccak_state_wipe_message.3 b/libkeccak_state_wipe_message.3 new file mode 100644 index 0000000..7d53afb --- /dev/null +++ b/libkeccak_state_wipe_message.3 @@ -0,0 +1,30 @@ +.TH LIBKECCAK_STATE_WIPE_MESSAGE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe_message - Securely erase the message chunk buffer +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_wipe_message(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_wipe_message.c b/libkeccak_state_wipe_message.c new file mode 100644 index 0000000..d6bc8a0 --- /dev/null +++ b/libkeccak_state_wipe_message.c @@ -0,0 +1,17 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Wipe data in the state's message wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_state_wipe_message(volatile libkeccak_state_t *restrict state) +{ + volatile char *restrict M = state->M; + size_t i; + for (i = 0; i < state->mptr; i++) + M[i] = 0; +} diff --git a/libkeccak_state_wipe_sponge.3 b/libkeccak_state_wipe_sponge.3 new file mode 100644 index 0000000..31d6c66 --- /dev/null +++ b/libkeccak_state_wipe_sponge.3 @@ -0,0 +1,30 @@ +.TH LIBKECCAK_STATE_WIPE_SPONGE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe_sponge - Securely erase the Keccak sponge state +.SH SYNOPSIS +.nf +#include + +void libkeccak_state_wipe_sponge(libkeccak_state_t *\fIstate\fP); +.fi +.PP +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) diff --git a/libkeccak_state_wipe_sponge.c b/libkeccak_state_wipe_sponge.c new file mode 100644 index 0000000..ad8c29f --- /dev/null +++ b/libkeccak_state_wipe_sponge.c @@ -0,0 +1,17 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Wipe data in the state's sponge wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_state_wipe_sponge(volatile libkeccak_state_t *restrict state) +{ + volatile int64_t *restrict S = state->S; + size_t i; + for (i = 0; i < 25; i++) + S[i] = 0; +} diff --git a/libkeccak_unhex.3 b/libkeccak_unhex.3 new file mode 100644 index 0000000..c7dc9bc --- /dev/null +++ b/libkeccak_unhex.3 @@ -0,0 +1,48 @@ +.TH LIBKECCAK_UNHEX 3 LIBKECCAK +.SH NAME +libkeccak_unhex - Converts a hexadecimal hashsum to binary +.SH SYNOPSIS +.nf +#include + +void libkeccak_unhex(void *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP); +.fi +.PP +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) diff --git a/libkeccak_unhex.c b/libkeccak_unhex.c new file mode 100644 index 0000000..a12beb1 --- /dev/null +++ b/libkeccak_unhex.c @@ -0,0 +1,29 @@ +/* See LICENSE file for copyright and license details. */ +#include "common.h" + + +/** + * Convert a hexadecimal hashsum (both lower case, upper + * case and mixed is supported) to binary representation + * + * @param output Output array, should have an allocation size of at least `strlen(hashsum) / 2` + * @param hashsum The hashsum to convert + */ +void +libkeccak_unhex(void *restrict output_, const char *restrict hashsum) +{ + unsigned char *restrict output = output_; + size_t n = strlen(hashsum) / 2; + unsigned char a, b; + while (n--) { + a = (unsigned char)hashsum[2 * n + 0]; + b = (unsigned char)hashsum[2 * n + 1]; + + a = (unsigned char)((a & 15) + (a > '9' ? 9 : 0)); + b = (unsigned char)((b & 15) + (b > '9' ? 9 : 0)); + + a <<= 4; + a |= b; + output[n] = a; + } +} diff --git a/libkeccak_update.3 b/libkeccak_update.3 new file mode 100644 index 0000000..4e9f584 --- /dev/null +++ b/libkeccak_update.3 @@ -0,0 +1,89 @@ +.TH LIBKECCAK_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_update - Partially hash a message with erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); +.fi +.PP +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. +.PP +.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, \(dq\(dq, binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_behex_lower.3 b/man3/libkeccak_behex_lower.3 deleted file mode 100644 index 2078790..0000000 --- a/man3/libkeccak_behex_lower.3 +++ /dev/null @@ -1,45 +0,0 @@ -.TH LIBKECCAK_BEHEX_LOWER 3 LIBKECCAK -.SH NAME -libkeccak_behex_lower - Converts a binary hashsum to lower case hexadecimal -.SH SYNOPSIS -.LP -.nf -#include - -void libkeccak_behex_lower(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_behex_upper.3 b/man3/libkeccak_behex_upper.3 deleted file mode 100644 index b5c67bb..0000000 --- a/man3/libkeccak_behex_upper.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_BEHEX_UPPER 3 LIBKECCAK -.SH NAME -libkeccak_behex_upper - Converts a binary hashsum to upper case hexadecimal -.SH SYNOPSIS -.nf -#include - -void libkeccak_behex_upper(char *restrict \fIoutput\fP, const void *restrict \fIhashsum\fP, size_t \fIn\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_degeneralise_spec.3 b/man3/libkeccak_degeneralise_spec.3 deleted file mode 100644 index 7ec2b72..0000000 --- a/man3/libkeccak_degeneralise_spec.3 +++ /dev/null @@ -1,118 +0,0 @@ -.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK -.SH NAME -libkeccak_degeneralise_spec - Set all specification parameters to automatic -.SH SYNOPSIS -.nf -#include - -int libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *\fIspec\fP, libkeccak_spec_t *\fIoutput_spec\fP); -.fi -.PP -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]: -.PP -.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) diff --git a/man3/libkeccak_digest.3 b/man3/libkeccak_digest.3 deleted file mode 100644 index 5f42796..0000000 --- a/man3/libkeccak_digest.3 +++ /dev/null @@ -1,139 +0,0 @@ -.TH LIBKECCAK_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_digest - Complete the hashing of a message with erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_digest(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, - size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP); -.fi -.PP -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 \(dq\(dq 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. -.PP -.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, \(dq\(dq, binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_fast_digest.3 b/man3/libkeccak_fast_digest.3 deleted file mode 100644 index 9e9c1f3..0000000 --- a/man3/libkeccak_fast_digest.3 +++ /dev/null @@ -1,141 +0,0 @@ -.TH LIBKECCAK_FAST_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_fast_digest - Complete the hashing of a message without erasure -.SH SYNOPSIS -.LP -.nf -#include - -int libkeccak_fast_digest(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, - size_t \fIbits\fP, const char *\fIsuffix\fP, void *\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 \(dq\(dq 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. -.PP -.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, \(dq\(dq, binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_fast_squeeze.3 b/man3/libkeccak_fast_squeeze.3 deleted file mode 100644 index 393e264..0000000 --- a/man3/libkeccak_fast_squeeze.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_fast_squeeze - Runs the squeeze phase a number of times -.SH SYNOPSIS -.nf -#include - -void libkeccak_fast_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_fast_update.3 b/man3/libkeccak_fast_update.3 deleted file mode 100644 index 3398984..0000000 --- a/man3/libkeccak_fast_update.3 +++ /dev/null @@ -1,90 +0,0 @@ -.TH LIBKECCAK_FAST_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_fast_update - Partially hash a message without erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_fast_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); -.fi -.PP -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. -.PP -.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, \(dq\(dq, binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_generalised_spec_initialise.3 b/man3/libkeccak_generalised_spec_initialise.3 deleted file mode 100644 index 1a3bccb..0000000 --- a/man3/libkeccak_generalised_spec_initialise.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH LIBKECCAK_GENERALISED_SPEC_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_generalised_spec_initialise - Set all specification parameters to automatic -.SH SYNOPSIS -.nf -#include - -void libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *\fIspec\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_generalised_sum_fd.3 b/man3/libkeccak_generalised_sum_fd.3 deleted file mode 100644 index bae5bae..0000000 --- a/man3/libkeccak_generalised_sum_fd.3 +++ /dev/null @@ -1,126 +0,0 @@ -.TH LIBKECCAK_GENERALISED_SUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_generalised_sum_fd - Calculate the hash of a file -.SH SYNOPSIS -.nf -#include - -int libkeccak_generalised_sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP, - const char *\fIsuffix\fP, void *\fIhashsum\fP); -.fi -.PP -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. -.PP -.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(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_hmac_copy.3 b/man3/libkeccak_hmac_copy.3 deleted file mode 100644 index 0f29ae8..0000000 --- a/man3/libkeccak_hmac_copy.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_HMAC_COPY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_copy - Copies an HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_copy(libkeccak_hmac_state_t *\fIdest\fP, const libkeccak_hmac_state_t *\fIsrc\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_create.3 b/man3/libkeccak_hmac_create.3 deleted file mode 100644 index 91bb8a1..0000000 --- a/man3/libkeccak_hmac_create.3 +++ /dev/null @@ -1,47 +0,0 @@ -.TH LIBKECCAK_HMAC_CREATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_create - Allocate and initialise HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -libkeccak_hmac_state_t *libkeccak_hmac_create(const libkeccak_spec_t *\fIspec\fP, const void *\fIkey\fP, size_t \fIkey_length\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_destroy.3 b/man3/libkeccak_hmac_destroy.3 deleted file mode 100644 index 0038eca..0000000 --- a/man3/libkeccak_hmac_destroy.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_HMAC_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_destroy - Destroys an HMAC-hashing state with erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_hmac_destroy(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_digest.3 b/man3/libkeccak_hmac_digest.3 deleted file mode 100644 index 99e460a..0000000 --- a/man3/libkeccak_hmac_digest.3 +++ /dev/null @@ -1,97 +0,0 @@ -.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_digest(libkeccak_hmac_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, - size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP); -.fi -.PP -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 \(dq\(dq 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) diff --git a/man3/libkeccak_hmac_duplicate.3 b/man3/libkeccak_hmac_duplicate.3 deleted file mode 100644 index bb16139..0000000 --- a/man3/libkeccak_hmac_duplicate.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH LIBKECCAK_HMAC_DUPLICATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_duplicate - Allocate a duplicate an HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -libkeccak_hmac_state_t *libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *\fIsrc\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_fast_destroy.3 b/man3/libkeccak_hmac_fast_destroy.3 deleted file mode 100644 index 31bf894..0000000 --- a/man3/libkeccak_hmac_fast_destroy.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_destroy - Destroys an HMAC-hashing state without erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_hamc_fast_destroy(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_fast_digest.3 b/man3/libkeccak_hmac_fast_digest.3 deleted file mode 100644 index 68fcc69..0000000 --- a/man3/libkeccak_hmac_fast_digest.3 +++ /dev/null @@ -1,98 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_digest - Complete the HMAC-hashing of a message without erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP, - size_t \fIbits\fP, const char *\fIsuffix\fP, void *\fIhashsum\fP); -.fi -.PP -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 \(dq\(dq 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) diff --git a/man3/libkeccak_hmac_fast_free.3 b/man3/libkeccak_hmac_fast_free.3 deleted file mode 100644 index f888872..0000000 --- a/man3/libkeccak_hmac_fast_free.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_free - Destroys and deallocates an HMAC-hashing state without erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_hmac_fast_free(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_fast_update.3 b/man3/libkeccak_hmac_fast_update.3 deleted file mode 100644 index a41b72f..0000000 --- a/man3/libkeccak_hmac_fast_update.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_update - Partially HMAC-hash a message without erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_fast_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_free.3 b/man3/libkeccak_hmac_free.3 deleted file mode 100644 index c70f369..0000000 --- a/man3/libkeccak_hmac_free.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_HMAC_FREE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_free - Destroys and deallocates an HMAC-hashing state with erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_hmac_free(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_initialise.3 b/man3/libkeccak_hmac_initialise.3 deleted file mode 100644 index 17b2b9f..0000000 --- a/man3/libkeccak_hmac_initialise.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_HMAC_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_initialise - Initialise HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_initialise(libkeccak_hmac_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP, - const void *\fIkey\fP, size_t \fIkey_length\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_marshal.3 b/man3/libkeccak_hmac_marshal.3 deleted file mode 100644 index 2e31dd7..0000000 --- a/man3/libkeccak_hmac_marshal.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_HMAC_MARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_hmac_marshal - Marshals an HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_hmac_marshal(const libkeccak_hmac_state_t *\fIstate\fP, void *\fIdata\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_marshal_size.3 b/man3/libkeccak_hmac_marshal_size.3 deleted file mode 100644 index fe8ec2f..0000000 --- a/man3/libkeccak_hmac_marshal_size.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH LIBKECCAK_HMAC_MARSHAL_SIZE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_marshal_size - Calculates the marshal-size of an HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_reset.3 b/man3/libkeccak_hmac_reset.3 deleted file mode 100644 index 4a9aadf..0000000 --- a/man3/libkeccak_hmac_reset.3 +++ /dev/null @@ -1,45 +0,0 @@ -.TH LIBKECCAK_HMAC_RESET 3 LIBKECCAK -.SH NAME -libkeccak_hmac_reset - Reinitialise a HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_reset(libkeccak_hmac_state_t *\fIstate\fP, const void *\fIkey\fP, size_t \fIkey_length\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_set_key.3 b/man3/libkeccak_hmac_set_key.3 deleted file mode 100644 index ea8084e..0000000 --- a/man3/libkeccak_hmac_set_key.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH LIBKECCAK_HMAC_SET_KEY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_set_key - Changes key for a the HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_set_key(libkeccak_hmac_state_t *\fIstate\fP, const void *\fIkey\fP, size_t \fIkey_length\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_unmarshal.3 b/man3/libkeccak_hmac_unmarshal.3 deleted file mode 100644 index c3ed187..0000000 --- a/man3/libkeccak_hmac_unmarshal.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH LIBKECCAK_HMAC_UNMARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_hmac_unmarshal - Unharshals an HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *\fIstate\fP, const void *\fIdata\fP); -.fi -.PP -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 . -.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) diff --git a/man3/libkeccak_hmac_unmarshal_skip.3 b/man3/libkeccak_hmac_unmarshal_skip.3 deleted file mode 100644 index 25db1ba..0000000 --- a/man3/libkeccak_hmac_unmarshal_skip.3 +++ /dev/null @@ -1,35 +0,0 @@ -.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 -.nf -#include - -size_t libkeccak_hmac_unmarshal_skip(const void *\fIdata\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_update.3 b/man3/libkeccak_hmac_update.3 deleted file mode 100644 index 13891cb..0000000 --- a/man3/libkeccak_hmac_update.3 +++ /dev/null @@ -1,50 +0,0 @@ -.TH LIBKECCAK_HMAC_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_update - Partially HMAC-hash a message with erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_hmac_wipe.3 b/man3/libkeccak_hmac_wipe.3 deleted file mode 100644 index 471a9a8..0000000 --- a/man3/libkeccak_hmac_wipe.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH LIBKECCAK_HMAC_WIPE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_wipe - Securely erase sensitive data from a HMAC-hashing state -.SH SYNOPSIS -.nf -#include - -int libkeccak_hmac_wipe(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_keccaksum_fd.3 b/man3/libkeccak_keccaksum_fd.3 deleted file mode 100644 index ccd1f8a..0000000 --- a/man3/libkeccak_keccaksum_fd.3 +++ /dev/null @@ -1,113 +0,0 @@ -.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_keccaksum_fd - Calculate a Keccak hashsum of a file -.SH SYNOPSIS -.nf -#include - -int libkeccak_keccaksum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP, void *\fIhashsum\fP); -.fi -.PP -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(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_rawshakesum_fd.3 b/man3/libkeccak_rawshakesum_fd.3 deleted file mode 100644 index 8fad150..0000000 --- a/man3/libkeccak_rawshakesum_fd.3 +++ /dev/null @@ -1,108 +0,0 @@ -.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file -.SH SYNOPSIS -.nf -#include - -int libkeccak_rawshakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIsemicapacity\fP, long int \fIoutput\fP, void *\fIhashsum\fP); -.fi -.PP -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(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_sha3sum_fd.3 b/man3/libkeccak_sha3sum_fd.3 deleted file mode 100644 index 0d697e6..0000000 --- a/man3/libkeccak_sha3sum_fd.3 +++ /dev/null @@ -1,105 +0,0 @@ -.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file -.SH SYNOPSIS -.nf -#include - -int libkeccak_sha3sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIoutput\fP, void *\fIhashsum\fP); -.fi -.PP -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(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_shakesum_fd.3 b/man3/libkeccak_shakesum_fd.3 deleted file mode 100644 index 441c549..0000000 --- a/man3/libkeccak_shakesum_fd.3 +++ /dev/null @@ -1,108 +0,0 @@ -.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file -.SH SYNOPSIS -.nf -#include - -int libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIsemicapacity\fP, long int \fIoutput\fP, void *\fIhashsum\fP); -.fi -.PP -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(\(dq%s\en\(dq, 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) diff --git a/man3/libkeccak_simple_squeeze.3 b/man3/libkeccak_simple_squeeze.3 deleted file mode 100644 index 8626f5a..0000000 --- a/man3/libkeccak_simple_squeeze.3 +++ /dev/null @@ -1,33 +0,0 @@ -.TH LIBKECCAK_SIMPLE_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_simple_squeeze - Runs Keccak-f a number of times -.SH SYNOPSIS -.nf -#include - -void libkeccak_simple_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_spec_check.3 b/man3/libkeccak_spec_check.3 deleted file mode 100644 index 7dd19d8..0000000 --- a/man3/libkeccak_spec_check.3 +++ /dev/null @@ -1,90 +0,0 @@ -.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK -.SH NAME -libkeccak_spec_check - Validate hashing parameters -.SH SYNOPSIS -.nf -#include - -int libkeccak_spec_check(const libkeccak_spec_t *\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_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) diff --git a/man3/libkeccak_spec_rawshake.3 b/man3/libkeccak_spec_rawshake.3 deleted file mode 100644 index f5f16b8..0000000 --- a/man3/libkeccak_spec_rawshake.3 +++ /dev/null @@ -1,47 +0,0 @@ -.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK -.SH NAME -libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters -.SH SYNOPSIS -.nf -#include - -void libkeccak_spec_rawshake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); -.fi -.PP -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): -.PP -.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) diff --git a/man3/libkeccak_spec_sha3.3 b/man3/libkeccak_spec_sha3.3 deleted file mode 100644 index 1320631..0000000 --- a/man3/libkeccak_spec_sha3.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK -.SH NAME -libkeccak_spec_sha3 - Configure SHA-3 hashing parameters -.SH SYNOPSIS -.nf -#include - -void libkeccak_spec_sha3(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP); -.fi -.PP -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: -.PP -.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) diff --git a/man3/libkeccak_spec_shake.3 b/man3/libkeccak_spec_shake.3 deleted file mode 100644 index 4beea49..0000000 --- a/man3/libkeccak_spec_shake.3 +++ /dev/null @@ -1,47 +0,0 @@ -.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK -.SH NAME -libkeccak_spec_shake - Configure SHAKE hashing parameters -.SH SYNOPSIS -.nf -#include - -void libkeccak_spec_shake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); -.fi -.PP -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): -.PP -.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) diff --git a/man3/libkeccak_squeeze.3 b/man3/libkeccak_squeeze.3 deleted file mode 100644 index 67430a4..0000000 --- a/man3/libkeccak_squeeze.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_squeeze - Runs the squeeze phase -.SH SYNOPSIS -.nf -#include - -void libkeccak_squeeze(libkeccak_state_t *\fIstate\fP, void *\fIhashsum\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_copy.3 b/man3/libkeccak_state_copy.3 deleted file mode 100644 index 4bd892c..0000000 --- a/man3/libkeccak_state_copy.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_STATE_COPY 3 LIBKECCAK -.SH NAME -libkeccak_state_copy - Copies hash state -.SH SYNOPSIS -.nf -#include - -int libkeccak_state_copy(libkeccak_state_t *\fIdest\fP, const libkeccak_state_t *\fIsrc\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_create.3 b/man3/libkeccak_state_create.3 deleted file mode 100644 index f27e124..0000000 --- a/man3/libkeccak_state_create.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH LIBKECCAK_STATE_CREATE 3 LIBKECCAK -.SH NAME -libkeccak_state_create - Allocate and initialise hash state -.SH SYNOPSIS -.nf -#include - -libkeccak_state_t *libkeccak_state_create(const libkeccak_spec_t *\fIspec\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_destroy.3 b/man3/libkeccak_state_destroy.3 deleted file mode 100644 index 2df1f49..0000000 --- a/man3/libkeccak_state_destroy.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_STATE_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_state_destroy - Destroys a hash state with erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_destroy(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_duplicate.3 b/man3/libkeccak_state_duplicate.3 deleted file mode 100644 index dfd0612..0000000 --- a/man3/libkeccak_state_duplicate.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH LIBKECCAK_STATE_DUPLICATE 3 LIBKECCAK -.SH NAME -libkeccak_state_duplicate - Allocate a duplicate hash state -.SH SYNOPSIS -.nf -#include - -libkeccak_state_t *libkeccak_state_duplicate(const libkeccak_state_t *\fIsrc\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_fast_destroy.3 b/man3/libkeccak_state_fast_destroy.3 deleted file mode 100644 index f346611..0000000 --- a/man3/libkeccak_state_fast_destroy.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_STATE_FAST_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_state_fast_destroy - Destroys a hash state without erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_fast_destroy(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_fast_free.3 b/man3/libkeccak_state_fast_free.3 deleted file mode 100644 index 01d0ed8..0000000 --- a/man3/libkeccak_state_fast_free.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK -.SH NAME -libkeccak_state_fast_free - Destroys and deallocates a hash state without erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_fast_free(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_free.3 b/man3/libkeccak_state_free.3 deleted file mode 100644 index 8761d54..0000000 --- a/man3/libkeccak_state_free.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_STATE_FREE 3 LIBKECCAK -.SH NAME -libkeccak_state_free - Destroys and deallocates a hash state with erasure -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_free(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_initialise.3 b/man3/libkeccak_state_initialise.3 deleted file mode 100644 index cef4d3d..0000000 --- a/man3/libkeccak_state_initialise.3 +++ /dev/null @@ -1,54 +0,0 @@ -.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_state_initialise - Initialise hash state -.SH SYNOPSIS -.nf -#include - -int libkeccak_state_initialise(libkeccak_state_t *\fIstate\fP, const libkeccak_spec_t *\fIspec\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_marshal.3 b/man3/libkeccak_state_marshal.3 deleted file mode 100644 index ae21d17..0000000 --- a/man3/libkeccak_state_marshal.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_STATE_MARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_state_marshal - Marshals a hash state -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_state_marshal(const libkeccak_state_t *\fIstate\fP, void *\fIdata\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_marshal () -function marshals -.I *state -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) diff --git a/man3/libkeccak_state_marshal_size.3 b/man3/libkeccak_state_marshal_size.3 deleted file mode 100644 index 9eca42b..0000000 --- a/man3/libkeccak_state_marshal_size.3 +++ /dev/null @@ -1,31 +0,0 @@ -.TH LIBKECCAK_STATE_MARSHAL_SIZE 3 LIBKECCAK -.SH NAME -libkeccak_state_marshal_size - Calculates the marshal-size of a hash state -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_state_marshal_size(const libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_reset.3 b/man3/libkeccak_state_reset.3 deleted file mode 100644 index 566bd6b..0000000 --- a/man3/libkeccak_state_reset.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH LIBKECCAK_STATE_RESET 3 LIBKECCAK -.SH NAME -libkeccak_state_reset - Reinitialise hash state -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_reset(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_unmarshal.3 b/man3/libkeccak_state_unmarshal.3 deleted file mode 100644 index 8643164..0000000 --- a/man3/libkeccak_state_unmarshal.3 +++ /dev/null @@ -1,34 +0,0 @@ -.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_state_unmarshal - Unharshals a hash state -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_state_unmarshal(libkeccak_state_t *\fIstate\fP, const void *\fIdata\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_unmarshal_skip.3 b/man3/libkeccak_state_unmarshal_skip.3 deleted file mode 100644 index 9fb9336..0000000 --- a/man3/libkeccak_state_unmarshal_skip.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH LIBKECCAK_STATE_UNMARSHAL_SKIP 3 LIBKECCAK -.SH NAME -libkeccak_state_unmarshal_skip - Calculates the marshal-size of a marshalled hash state -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_state_unmarshal_skip(const void *\fIdata\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_wipe.3 b/man3/libkeccak_state_wipe.3 deleted file mode 100644 index 1ae2759..0000000 --- a/man3/libkeccak_state_wipe.3 +++ /dev/null @@ -1,32 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe - Securely erase sensitive data -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_wipe(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_wipe_message.3 b/man3/libkeccak_state_wipe_message.3 deleted file mode 100644 index 7d53afb..0000000 --- a/man3/libkeccak_state_wipe_message.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE_MESSAGE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe_message - Securely erase the message chunk buffer -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_wipe_message(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_state_wipe_sponge.3 b/man3/libkeccak_state_wipe_sponge.3 deleted file mode 100644 index 31d6c66..0000000 --- a/man3/libkeccak_state_wipe_sponge.3 +++ /dev/null @@ -1,30 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE_SPONGE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe_sponge - Securely erase the Keccak sponge state -.SH SYNOPSIS -.nf -#include - -void libkeccak_state_wipe_sponge(libkeccak_state_t *\fIstate\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_unhex.3 b/man3/libkeccak_unhex.3 deleted file mode 100644 index c7dc9bc..0000000 --- a/man3/libkeccak_unhex.3 +++ /dev/null @@ -1,48 +0,0 @@ -.TH LIBKECCAK_UNHEX 3 LIBKECCAK -.SH NAME -libkeccak_unhex - Converts a hexadecimal hashsum to binary -.SH SYNOPSIS -.nf -#include - -void libkeccak_unhex(void *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP); -.fi -.PP -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) diff --git a/man3/libkeccak_update.3 b/man3/libkeccak_update.3 deleted file mode 100644 index 4e9f584..0000000 --- a/man3/libkeccak_update.3 +++ /dev/null @@ -1,89 +0,0 @@ -.TH LIBKECCAK_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_update - Partially hash a message with erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_update(libkeccak_state_t *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); -.fi -.PP -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. -.PP -.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, \(dq\(dq, binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf(\(dq%s\en\(dq, 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) diff --git a/man7/libkeccak.7 b/man7/libkeccak.7 deleted file mode 100644 index 0a6ef04..0000000 --- a/man7/libkeccak.7 +++ /dev/null @@ -1,70 +0,0 @@ -.TH LIBKECCAK 7 LIBKECCAK -.SH NAME -libkeccak - Keccak-family hashing library -.SH DESCRIPTION -.BR libkeccak -is a bit-oriented lanewise implementation of the Keccak-family with -support for extend output size, state marshalling, algorithm tuning with -implicit parameters, secure erasure of sensitive data, and HMAC. -.SH FUTURE DIRECTION -Keccak-3200 may be implemented in the future. -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_degeneralise_spec (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_wipe_message (3), -.BR libkeccak_state_wipe_sponge (3), -.BR libkeccak_state_wipe (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_create (3), -.BR libkeccak_state_fast_free (3), -.BR libkeccak_state_free (3), -.BR libkeccak_state_copy (3), -.BR libkeccak_state_duplicate (3), -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_state_unmarshal_skip (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (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_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_unhex (3), -.BR libkeccak_hmac_set_key (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_copy (3), -.BR libkeccak_hmac_duplicate (3), -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_unmarshal_skip (3), -.BR libkeccak_hmac_fast_update (3), -.BR libkeccak_hmac_update (3), -.BR libkeccak_hmac_fast_digest (3), -.BR libkeccak_hmac_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se -- cgit v1.2.3-70-g09d2