From f14ba70de62cbd47e074756b1f1aec1f3b77a02d Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sun, 15 Sep 2024 00:47:51 +0200 Subject: Move man pages into man3/ and man7/ MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- Makefile | 124 ++++++++++----------- README | 2 +- libkeccak.7 | 67 ----------- libkeccak_behex_lower.3 | 45 -------- libkeccak_behex_upper.3 | 44 -------- libkeccak_cshake_initialise.3 | 126 --------------------- libkeccak_cshake_suffix.3 | 45 -------- libkeccak_degeneralise_spec.3 | 123 -------------------- libkeccak_digest.3 | 157 -------------------------- libkeccak_fast_digest.3 | 160 --------------------------- libkeccak_fast_squeeze.3 | 35 ------ libkeccak_fast_update.3 | 101 ----------------- libkeccak_generalised_spec_initialise.3 | 42 ------- libkeccak_generalised_sum_fd.3 | 137 ----------------------- libkeccak_hmac_copy.3 | 38 ------- libkeccak_hmac_create.3 | 47 -------- libkeccak_hmac_destroy.3 | 38 ------- libkeccak_hmac_digest.3 | 97 ---------------- libkeccak_hmac_duplicate.3 | 41 ------- libkeccak_hmac_fast_destroy.3 | 38 ------- libkeccak_hmac_fast_digest.3 | 98 ---------------- libkeccak_hmac_fast_free.3 | 46 -------- libkeccak_hmac_fast_update.3 | 53 --------- libkeccak_hmac_free.3 | 46 -------- libkeccak_hmac_initialise.3 | 51 --------- libkeccak_hmac_marshal.3 | 37 ------- libkeccak_hmac_reset.3 | 45 -------- libkeccak_hmac_set_key.3 | 35 ------ libkeccak_hmac_unmarshal.3 | 46 -------- libkeccak_hmac_update.3 | 50 --------- libkeccak_hmac_wipe.3 | 31 ------ libkeccak_keccaksum_fd.3 | 113 ------------------- libkeccak_rawshakesum_fd.3 | 108 ------------------ libkeccak_sha3sum_fd.3 | 105 ------------------ libkeccak_shakesum_fd.3 | 108 ------------------ libkeccak_simple_squeeze.3 | 34 ------ libkeccak_spec_check.3 | 92 --------------- libkeccak_spec_cshake.3 | 48 -------- libkeccak_spec_rawshake.3 | 48 -------- libkeccak_spec_sha3.3 | 47 -------- libkeccak_spec_shake.3 | 48 -------- libkeccak_squeeze.3 | 44 -------- libkeccak_state_copy.3 | 38 ------- 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 | 57 ---------- libkeccak_state_marshal.3 | 36 ------ libkeccak_state_reset.3 | 32 ------ libkeccak_state_unmarshal.3 | 47 -------- libkeccak_state_wipe.3 | 32 ------ libkeccak_state_wipe_message.3 | 30 ----- libkeccak_state_wipe_sponge.3 | 30 ----- libkeccak_unhex.3 | 48 -------- libkeccak_update.3 | 100 ----------------- libkeccak_zerocopy_chunksize.3 | 40 ------- libkeccak_zerocopy_digest.3 | 136 ----------------------- libkeccak_zerocopy_update.3 | 89 --------------- man3/libkeccak_behex_lower.3 | 45 ++++++++ man3/libkeccak_behex_upper.3 | 44 ++++++++ man3/libkeccak_cshake_initialise.3 | 126 +++++++++++++++++++++ man3/libkeccak_cshake_suffix.3 | 45 ++++++++ man3/libkeccak_degeneralise_spec.3 | 123 ++++++++++++++++++++ man3/libkeccak_digest.3 | 157 ++++++++++++++++++++++++++ man3/libkeccak_fast_digest.3 | 160 +++++++++++++++++++++++++++ man3/libkeccak_fast_squeeze.3 | 35 ++++++ man3/libkeccak_fast_update.3 | 101 +++++++++++++++++ man3/libkeccak_generalised_spec_initialise.3 | 42 +++++++ man3/libkeccak_generalised_sum_fd.3 | 137 +++++++++++++++++++++++ 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 | 37 +++++++ man3/libkeccak_hmac_reset.3 | 45 ++++++++ man3/libkeccak_hmac_set_key.3 | 35 ++++++ man3/libkeccak_hmac_unmarshal.3 | 46 ++++++++ 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 | 34 ++++++ man3/libkeccak_spec_check.3 | 92 +++++++++++++++ man3/libkeccak_spec_cshake.3 | 48 ++++++++ man3/libkeccak_spec_rawshake.3 | 48 ++++++++ man3/libkeccak_spec_sha3.3 | 47 ++++++++ man3/libkeccak_spec_shake.3 | 48 ++++++++ man3/libkeccak_squeeze.3 | 44 ++++++++ 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 | 57 ++++++++++ man3/libkeccak_state_marshal.3 | 36 ++++++ man3/libkeccak_state_reset.3 | 32 ++++++ man3/libkeccak_state_unmarshal.3 | 47 ++++++++ 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 | 100 +++++++++++++++++ man3/libkeccak_zerocopy_chunksize.3 | 40 +++++++ man3/libkeccak_zerocopy_digest.3 | 136 +++++++++++++++++++++++ man3/libkeccak_zerocopy_update.3 | 89 +++++++++++++++ man7/libkeccak.7 | 67 +++++++++++ 120 files changed, 3742 insertions(+), 3742 deletions(-) delete mode 100644 libkeccak.7 delete mode 100644 libkeccak_behex_lower.3 delete mode 100644 libkeccak_behex_upper.3 delete mode 100644 libkeccak_cshake_initialise.3 delete mode 100644 libkeccak_cshake_suffix.3 delete mode 100644 libkeccak_degeneralise_spec.3 delete mode 100644 libkeccak_digest.3 delete mode 100644 libkeccak_fast_digest.3 delete mode 100644 libkeccak_fast_squeeze.3 delete mode 100644 libkeccak_fast_update.3 delete mode 100644 libkeccak_generalised_spec_initialise.3 delete mode 100644 libkeccak_generalised_sum_fd.3 delete mode 100644 libkeccak_hmac_copy.3 delete mode 100644 libkeccak_hmac_create.3 delete mode 100644 libkeccak_hmac_destroy.3 delete mode 100644 libkeccak_hmac_digest.3 delete mode 100644 libkeccak_hmac_duplicate.3 delete mode 100644 libkeccak_hmac_fast_destroy.3 delete mode 100644 libkeccak_hmac_fast_digest.3 delete mode 100644 libkeccak_hmac_fast_free.3 delete mode 100644 libkeccak_hmac_fast_update.3 delete mode 100644 libkeccak_hmac_free.3 delete mode 100644 libkeccak_hmac_initialise.3 delete mode 100644 libkeccak_hmac_marshal.3 delete mode 100644 libkeccak_hmac_reset.3 delete mode 100644 libkeccak_hmac_set_key.3 delete mode 100644 libkeccak_hmac_unmarshal.3 delete mode 100644 libkeccak_hmac_update.3 delete mode 100644 libkeccak_hmac_wipe.3 delete mode 100644 libkeccak_keccaksum_fd.3 delete mode 100644 libkeccak_rawshakesum_fd.3 delete mode 100644 libkeccak_sha3sum_fd.3 delete mode 100644 libkeccak_shakesum_fd.3 delete mode 100644 libkeccak_simple_squeeze.3 delete mode 100644 libkeccak_spec_check.3 delete mode 100644 libkeccak_spec_cshake.3 delete mode 100644 libkeccak_spec_rawshake.3 delete mode 100644 libkeccak_spec_sha3.3 delete mode 100644 libkeccak_spec_shake.3 delete mode 100644 libkeccak_squeeze.3 delete mode 100644 libkeccak_state_copy.3 delete mode 100644 libkeccak_state_create.3 delete mode 100644 libkeccak_state_destroy.3 delete mode 100644 libkeccak_state_duplicate.3 delete mode 100644 libkeccak_state_fast_destroy.3 delete mode 100644 libkeccak_state_fast_free.3 delete mode 100644 libkeccak_state_free.3 delete mode 100644 libkeccak_state_initialise.3 delete mode 100644 libkeccak_state_marshal.3 delete mode 100644 libkeccak_state_reset.3 delete mode 100644 libkeccak_state_unmarshal.3 delete mode 100644 libkeccak_state_wipe.3 delete mode 100644 libkeccak_state_wipe_message.3 delete mode 100644 libkeccak_state_wipe_sponge.3 delete mode 100644 libkeccak_unhex.3 delete mode 100644 libkeccak_update.3 delete mode 100644 libkeccak_zerocopy_chunksize.3 delete mode 100644 libkeccak_zerocopy_digest.3 delete mode 100644 libkeccak_zerocopy_update.3 create mode 100644 man3/libkeccak_behex_lower.3 create mode 100644 man3/libkeccak_behex_upper.3 create mode 100644 man3/libkeccak_cshake_initialise.3 create mode 100644 man3/libkeccak_cshake_suffix.3 create mode 100644 man3/libkeccak_degeneralise_spec.3 create mode 100644 man3/libkeccak_digest.3 create mode 100644 man3/libkeccak_fast_digest.3 create mode 100644 man3/libkeccak_fast_squeeze.3 create mode 100644 man3/libkeccak_fast_update.3 create mode 100644 man3/libkeccak_generalised_spec_initialise.3 create mode 100644 man3/libkeccak_generalised_sum_fd.3 create mode 100644 man3/libkeccak_hmac_copy.3 create mode 100644 man3/libkeccak_hmac_create.3 create mode 100644 man3/libkeccak_hmac_destroy.3 create mode 100644 man3/libkeccak_hmac_digest.3 create mode 100644 man3/libkeccak_hmac_duplicate.3 create mode 100644 man3/libkeccak_hmac_fast_destroy.3 create mode 100644 man3/libkeccak_hmac_fast_digest.3 create mode 100644 man3/libkeccak_hmac_fast_free.3 create mode 100644 man3/libkeccak_hmac_fast_update.3 create mode 100644 man3/libkeccak_hmac_free.3 create mode 100644 man3/libkeccak_hmac_initialise.3 create mode 100644 man3/libkeccak_hmac_marshal.3 create mode 100644 man3/libkeccak_hmac_reset.3 create mode 100644 man3/libkeccak_hmac_set_key.3 create mode 100644 man3/libkeccak_hmac_unmarshal.3 create mode 100644 man3/libkeccak_hmac_update.3 create mode 100644 man3/libkeccak_hmac_wipe.3 create mode 100644 man3/libkeccak_keccaksum_fd.3 create mode 100644 man3/libkeccak_rawshakesum_fd.3 create mode 100644 man3/libkeccak_sha3sum_fd.3 create mode 100644 man3/libkeccak_shakesum_fd.3 create mode 100644 man3/libkeccak_simple_squeeze.3 create mode 100644 man3/libkeccak_spec_check.3 create mode 100644 man3/libkeccak_spec_cshake.3 create mode 100644 man3/libkeccak_spec_rawshake.3 create mode 100644 man3/libkeccak_spec_sha3.3 create mode 100644 man3/libkeccak_spec_shake.3 create mode 100644 man3/libkeccak_squeeze.3 create mode 100644 man3/libkeccak_state_copy.3 create mode 100644 man3/libkeccak_state_create.3 create mode 100644 man3/libkeccak_state_destroy.3 create mode 100644 man3/libkeccak_state_duplicate.3 create mode 100644 man3/libkeccak_state_fast_destroy.3 create mode 100644 man3/libkeccak_state_fast_free.3 create mode 100644 man3/libkeccak_state_free.3 create mode 100644 man3/libkeccak_state_initialise.3 create mode 100644 man3/libkeccak_state_marshal.3 create mode 100644 man3/libkeccak_state_reset.3 create mode 100644 man3/libkeccak_state_unmarshal.3 create mode 100644 man3/libkeccak_state_wipe.3 create mode 100644 man3/libkeccak_state_wipe_message.3 create mode 100644 man3/libkeccak_state_wipe_sponge.3 create mode 100644 man3/libkeccak_unhex.3 create mode 100644 man3/libkeccak_update.3 create mode 100644 man3/libkeccak_zerocopy_chunksize.3 create mode 100644 man3/libkeccak_zerocopy_digest.3 create mode 100644 man3/libkeccak_zerocopy_update.3 create mode 100644 man7/libkeccak.7 diff --git a/Makefile b/Makefile index 62dc927..6db74cf 100644 --- a/Makefile +++ b/Makefile @@ -83,67 +83,67 @@ SUBHDR =\ libkeccak/util.h MAN3 =\ - libkeccak_behex_lower.3\ - libkeccak_behex_upper.3\ - libkeccak_cshake_initialise.3\ - libkeccak_cshake_suffix.3\ - libkeccak_degeneralise_spec.3\ - libkeccak_digest.3\ - libkeccak_fast_digest.3\ - libkeccak_fast_squeeze.3\ - libkeccak_fast_update.3\ - libkeccak_generalised_spec_initialise.3\ - libkeccak_generalised_sum_fd.3\ - libkeccak_hmac_copy.3\ - libkeccak_hmac_create.3\ - libkeccak_hmac_destroy.3\ - libkeccak_hmac_digest.3\ - libkeccak_hmac_duplicate.3\ - libkeccak_hmac_fast_destroy.3\ - libkeccak_hmac_fast_digest.3\ - libkeccak_hmac_fast_free.3\ - libkeccak_hmac_fast_update.3\ - libkeccak_hmac_free.3\ - libkeccak_hmac_initialise.3\ - libkeccak_hmac_marshal.3\ - libkeccak_hmac_reset.3\ - libkeccak_hmac_set_key.3\ - libkeccak_hmac_unmarshal.3\ - libkeccak_hmac_update.3\ - libkeccak_hmac_wipe.3\ - libkeccak_keccaksum_fd.3\ - libkeccak_rawshakesum_fd.3\ - libkeccak_sha3sum_fd.3\ - libkeccak_shakesum_fd.3\ - libkeccak_simple_squeeze.3\ - libkeccak_spec_check.3\ - libkeccak_spec_cshake.3\ - libkeccak_spec_rawshake.3\ - libkeccak_spec_sha3.3\ - libkeccak_spec_shake.3\ - libkeccak_squeeze.3\ - libkeccak_state_copy.3\ - libkeccak_state_create.3\ - libkeccak_state_destroy.3\ - libkeccak_state_duplicate.3\ - libkeccak_state_fast_destroy.3\ - libkeccak_state_fast_free.3\ - libkeccak_state_free.3\ - libkeccak_state_initialise.3\ - libkeccak_state_marshal.3\ - libkeccak_state_reset.3\ - libkeccak_state_unmarshal.3\ - libkeccak_state_wipe.3\ - libkeccak_state_wipe_message.3\ - libkeccak_state_wipe_sponge.3\ - libkeccak_unhex.3\ - libkeccak_update.3\ - libkeccak_zerocopy_chunksize.3\ - libkeccak_zerocopy_digest.3\ - libkeccak_zerocopy_update.3 + man3/libkeccak_behex_lower.3\ + man3/libkeccak_behex_upper.3\ + man3/libkeccak_cshake_initialise.3\ + man3/libkeccak_cshake_suffix.3\ + man3/libkeccak_degeneralise_spec.3\ + man3/libkeccak_digest.3\ + man3/libkeccak_fast_digest.3\ + man3/libkeccak_fast_squeeze.3\ + man3/libkeccak_fast_update.3\ + man3/libkeccak_generalised_spec_initialise.3\ + man3/libkeccak_generalised_sum_fd.3\ + man3/libkeccak_hmac_copy.3\ + man3/libkeccak_hmac_create.3\ + man3/libkeccak_hmac_destroy.3\ + man3/libkeccak_hmac_digest.3\ + man3/libkeccak_hmac_duplicate.3\ + man3/libkeccak_hmac_fast_destroy.3\ + man3/libkeccak_hmac_fast_digest.3\ + man3/libkeccak_hmac_fast_free.3\ + man3/libkeccak_hmac_fast_update.3\ + man3/libkeccak_hmac_free.3\ + man3/libkeccak_hmac_initialise.3\ + man3/libkeccak_hmac_marshal.3\ + man3/libkeccak_hmac_reset.3\ + man3/libkeccak_hmac_set_key.3\ + man3/libkeccak_hmac_unmarshal.3\ + man3/libkeccak_hmac_update.3\ + man3/libkeccak_hmac_wipe.3\ + man3/libkeccak_keccaksum_fd.3\ + man3/libkeccak_rawshakesum_fd.3\ + man3/libkeccak_sha3sum_fd.3\ + man3/libkeccak_shakesum_fd.3\ + man3/libkeccak_simple_squeeze.3\ + man3/libkeccak_spec_check.3\ + man3/libkeccak_spec_cshake.3\ + man3/libkeccak_spec_rawshake.3\ + man3/libkeccak_spec_sha3.3\ + man3/libkeccak_spec_shake.3\ + man3/libkeccak_squeeze.3\ + man3/libkeccak_state_copy.3\ + man3/libkeccak_state_create.3\ + man3/libkeccak_state_destroy.3\ + man3/libkeccak_state_duplicate.3\ + man3/libkeccak_state_fast_destroy.3\ + man3/libkeccak_state_fast_free.3\ + man3/libkeccak_state_free.3\ + man3/libkeccak_state_initialise.3\ + man3/libkeccak_state_marshal.3\ + man3/libkeccak_state_reset.3\ + man3/libkeccak_state_unmarshal.3\ + man3/libkeccak_state_wipe.3\ + man3/libkeccak_state_wipe_message.3\ + man3/libkeccak_state_wipe_sponge.3\ + man3/libkeccak_unhex.3\ + man3/libkeccak_update.3\ + man3/libkeccak_zerocopy_chunksize.3\ + man3/libkeccak_zerocopy_digest.3\ + man3/libkeccak_zerocopy_update.3 MAN7 =\ - libkeccak.7 + man7/libkeccak.7 all: libkeccak.a libkeccak.$(LIBEXT) test benchmark @@ -208,9 +208,9 @@ uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBMAJOREXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBEXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.a" - -cd -- "$(DESTDIR)$(PREFIX)/include/" && rm -f $(SUBHDIR) - -cd -- "$(DESTDIR)$(MANPREFIX)/man3" && rm -f -- $(MAN3) - -cd -- "$(DESTDIR)$(MANPREFIX)/man7" && rm -f -- $(MAN7) + -cd -- "$(DESTDIR)$(PREFIX)/include/" && rm -f $(SUBHDR) libkeccak.h + -rmdir -- "$(DESTDIR)$(PREFIX)/include/libkeccak" + -cd -- "$(DESTDIR)$(MANPREFIX)" && rm -f -- $(MAN3) $(MAN7) -rm -rf -- "$(DESTDIR)$(PREFIX)/share/licenses/libkeccak" clean: diff --git a/README b/README index 712f7fd..f2a9878 100644 --- a/README +++ b/README @@ -12,4 +12,4 @@ RATIONALE and let it be bit-oriented. SEE ALSO - sha3sum, libblake(7), libsha2(7), libsha1(7) + sha3sum, libblake(7), libsha2(7), libsha1(7), libhashsum(7) diff --git a/libkeccak.7 b/libkeccak.7 deleted file mode 100644 index 34c9dba..0000000 --- a/libkeccak.7 +++ /dev/null @@ -1,67 +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_cshake (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 (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_zerocopy_update (3), -.BR libkeccak_update (3), -.BR libkeccak_cshake_suffix (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_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 (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_fast_update (3), -.BR libkeccak_hmac_update (3), -.BR libkeccak_hmac_fast_digest (3), -.BR libkeccak_hmac_digest (3) diff --git a/libkeccak_behex_lower.3 b/libkeccak_behex_lower.3 deleted file mode 100644 index 2078790..0000000 --- a/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/libkeccak_behex_upper.3 b/libkeccak_behex_upper.3 deleted file mode 100644 index b5c67bb..0000000 --- a/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/libkeccak_cshake_initialise.3 b/libkeccak_cshake_initialise.3 deleted file mode 100644 index a18f1bf..0000000 --- a/libkeccak_cshake_initialise.3 +++ /dev/null @@ -1,126 +0,0 @@ -.TH LIBKECCAK_CSHAKE_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_cshake_initialise - Initialise a sponge for cSHAKE hashing -.SH SYNOPSIS -.nf -#include - -void libkeccak_cshake_initialise(struct libkeccak_state *restrict \fIstate\fP, - const void *\fIn_text\fP, size_t \fIn_len\fP, size_t \fIn_bits\fP, const char *\fIn_suffix\fP, - const void *\fIs_text\fP, size_t \fIs_len\fP, size_t \fIs_bits\fP, const char *\fIs_suffix\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_cshake_suffix () -function shall be called immediately -after the -.BR libkeccak_state_initialise (3) -function (before -.BR libkeccak_update (3) -or -.BR libkeccak_digest (3), -or any variant of those functions), -to provide the initialisation blocks, -containing customisation data, to the -Keccak sponge. -.PP -The value of the -.I state -parameter shall be an initialised state -to feed the initialisation blocks to. -.PP -The value of the -.I n_text -parameter shall be the function-name -bit-string, represented in raw bytes; -.I n_len -shall be value no greater than the -number of whole bytes in -.I n_text -and -.I n_bits -shall be the number of bits in -.I n_text -sans the bytes covered by -.IR n_len , -that is, the number of bits in -.I n_text -minus -.IR (nlen_*8) . -.I n_suffix -shall be either -.I NULL -or an appendix of bits to -.I n_suffix -(neither -.I n_len -nor -.I n_bits -shall count these), stored as a NUL-terminated -string of the ASCII digits -.B 1 -and -.BR 0 . -.PP -The value of the -.I s_text -parameter shall be the customisation -bit-string, represented in raw bytes; -.I s_len -shall be value no greater than the -number of whole bytes in -.I s_text -and -.I s_bits -shall be the number of bits in -.I s_text -sans the bytes covered by -.IR s_len , -that is, the number of bits in -.I s_text -minus -.IR (nles_*8) . -.I s_suffix -shall be either -.I NULL -or an appendix of bits to -.I s_suffix -(neither -.I s_len -nor -.I s_bits -shall count these), stored as a NUL-terminated -string of the ASCII digits -.B 1 -and -.BR 0 . -.PP -For the -.I n_suffix -and -.I s_suffix -parameters, -.I NULL -is treated as the empty string. -.SH RETURN VALUES -The -.BR libkeccak_cshake_suffix () -function does not return a value. -.SH ERRORS -The -.BR libkeccak_cshake_suffix () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_spec_cshake (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_zerocopy_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_digest (3), -.BR libkeccak_digest (3) diff --git a/libkeccak_cshake_suffix.3 b/libkeccak_cshake_suffix.3 deleted file mode 100644 index b390134..0000000 --- a/libkeccak_cshake_suffix.3 +++ /dev/null @@ -1,45 +0,0 @@ -.TH LIBKECCAK_CSHAKE_SUFFIX 3 LIBKECCAK -.SH NAME -libkeccak_cshake_suffix - Get message suffix for cSHAKE hashing -.SH SYNOPSIS -.nf -#include - -const char *libkeccak_cshake_suffix(size_t \fInlen\fP, size_t \fIslen\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_cshake_suffix () -function returns a string of '1':s and '0':s -representing the bits the the message suffixed -that shall be used. -Canonically, the values of the -.I nlen -and -.I slen -parameters shall be the length of the cSHAKE -function-name bit-string and the cSHAKE -customisation bit-string, however, the function -will only check whether these values are zero -or non-zero. -.SH RETURN VALUES -The -.BR libkeccak_cshake_suffix () -function returns a statically allocated, -read-only, message suffix bit-string -that shall be used. -.SH ERRORS -The -.BR libkeccak_cshake_suffix () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_spec_cshake (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_digest (3), -.BR libkeccak_digest (3) diff --git a/libkeccak_degeneralise_spec.3 b/libkeccak_degeneralise_spec.3 deleted file mode 100644 index e694147..0000000 --- a/libkeccak_degeneralise_spec.3 +++ /dev/null @@ -1,123 +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(struct libkeccak_generalised_spec *\fIspec\fP, struct libkeccak_spec *\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 -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) */ -}; -.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. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_BITRATE_CAPACITY_INCONSISTENCY -The sum of the bitrate and the capacity does not equal -the state size (25 times the word size). -.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 struct libkeccak_spec -to specify settings for Keccak[c = 512]: -.PP -.nf -int r; -struct libkeccak_spec spec; -struct libkeccak_generalised_spec 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_cshake (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_digest.3 b/libkeccak_digest.3 deleted file mode 100644 index 90c76c5..0000000 --- a/libkeccak_digest.3 +++ /dev/null @@ -1,157 +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(struct libkeccak_state *\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), -.BR libkeccak_fast_update (3), -or -.BR libkeccak_zerocopy_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), or the return of the -.BR libkeccak_cshake_suffix (3) -function (for cSHAKE), 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 -struct libkeccak_state state; -struct libkeccak_spec 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 NOTES -For cSHAKE, the -.BR libkeccak_cshake_initialise (3), -must be called, once, immediately after -state initialisation; before the first -call to any of the -.BR libkeccak_fast_update (), -.BR libkeccak_zerocopy_update (), -.BR libkeccak_update (), -and -.BR libkeccak_digest () -functions. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_cshake_suffix (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_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 deleted file mode 100644 index c4925e4..0000000 --- a/libkeccak_fast_digest.3 +++ /dev/null @@ -1,160 +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(struct libkeccak_state *\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), -.BR libkeccak_fast_update (3), -or -.BR libkeccak_zerocopy_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), or the return of the -.BR libkeccak_cshake_suffix (3) -function (for cSHAKE), 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 -struct libkeccak_state state; -struct libkeccak_spec 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 NOTES -For cSHAKE, the -.BR libkeccak_cshake_initialise (3), -must be called, once, immediately after -state initialisation; before the first -call to any of the -.BR libkeccak_fast_update (), -.BR libkeccak_zerocopy_update (), -.BR libkeccak_update (), -and -.BR libkeccak_digest_digest () -functions. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_zerocopy_update (3), -.BR libkeccak_update (3), -.BR libkeccak_cshake_suffix (3), -.BR libkeccak_digest (3), -.BR libkeccak_zerocopy_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 deleted file mode 100644 index 5be6cd6..0000000 --- a/libkeccak_fast_squeeze.3 +++ /dev/null @@ -1,35 +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(struct libkeccak_state *\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_zerocopy_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_squeeze (3) diff --git a/libkeccak_fast_update.3 b/libkeccak_fast_update.3 deleted file mode 100644 index 5d38b0d..0000000 --- a/libkeccak_fast_update.3 +++ /dev/null @@ -1,101 +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(struct libkeccak_state *\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 -struct libkeccak_state state; -struct libkeccak_spec 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 NOTES -For cSHAKE, the -.BR libkeccak_cshake_initialise (3), -must be called, once, immediately after -state initialisation; before the first -call to the -.BR libkeccak_fast_update () -function. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_zerocopy_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_digest (3), -.BR libkeccak_digest (3) diff --git a/libkeccak_generalised_spec_initialise.3 b/libkeccak_generalised_spec_initialise.3 deleted file mode 100644 index acfa173..0000000 --- a/libkeccak_generalised_spec_initialise.3 +++ /dev/null @@ -1,42 +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(struct libkeccak_generalised_spec *\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_cshake (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 deleted file mode 100644 index 9f5341a..0000000 --- a/libkeccak_generalised_sum_fd.3 +++ /dev/null @@ -1,137 +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, struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\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 unless -.I spec -is -.IR NULL . -.BR libkeccak_generalised_sum_fd () -initialises -.I *state -itself unless -.I spec -is -.IR NULL . -Therefore there would be a memory leak if -.I *state -is already initialised and -.I spec -is -.RI non- NULL . -.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 -struct libkeccak_state state; -struct libkeccak_spec 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_cshake (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_copy.3 b/libkeccak_hmac_copy.3 deleted file mode 100644 index eb80c6e..0000000 --- a/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(struct libkeccak_hmac_state *\fIdest\fP, const struct libkeccak_hmac_state *\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 struct libkeccak_hmac_state -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_create.3 b/libkeccak_hmac_create.3 deleted file mode 100644 index d804f31..0000000 --- a/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 - -struct libkeccak_hmac_state *libkeccak_hmac_create(const struct libkeccak_spec *\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 struct libkeccak_hmac_state * -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 struct libkeccak_hmac_state * -(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 deleted file mode 100644 index e2d5b1c..0000000 --- a/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(struct libkeccak_hmac_state *\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 deleted file mode 100644 index 9c0ee6b..0000000 --- a/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(struct libkeccak_hmac_state *\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_duplicate.3 b/libkeccak_hmac_duplicate.3 deleted file mode 100644 index b1cdc30..0000000 --- a/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 - -struct libkeccak_hmac_state *libkeccak_hmac_duplicate(const struct libkeccak_hmac_state *\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 struct libkeccak_hmac_state -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 deleted file mode 100644 index 05a8e2e..0000000 --- a/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(struct libkeccak_hmac_state *\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 deleted file mode 100644 index 6f21b70..0000000 --- a/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(struct libkeccak_hmac_state *\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_free.3 b/libkeccak_hmac_fast_free.3 deleted file mode 100644 index 87cb556..0000000 --- a/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(struct libkeccak_hmac_state *\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 deleted file mode 100644 index ca62baf..0000000 --- a/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(struct libkeccak_state *\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_free.3 b/libkeccak_hmac_free.3 deleted file mode 100644 index 91b103e..0000000 --- a/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(struct libkeccak_hmac_state *\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 deleted file mode 100644 index db3590f..0000000 --- a/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(struct libkeccak_hmac_state *\fIstate\fP, const struct libkeccak_spec *\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_spec_cshake (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 deleted file mode 100644 index 29ca9ea..0000000 --- a/libkeccak_hmac_marshal.3 +++ /dev/null @@ -1,37 +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 struct libkeccak_hmac_state *\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 -Specific -.I NULL -as -.I data -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_unmarshal (3) diff --git a/libkeccak_hmac_reset.3 b/libkeccak_hmac_reset.3 deleted file mode 100644 index 963ad4c..0000000 --- a/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(struct libkeccak_hmac_state *\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 deleted file mode 100644 index f961ade..0000000 --- a/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(struct libkeccak_hmac_state *\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_unmarshal.3 b/libkeccak_hmac_unmarshal.3 deleted file mode 100644 index 7224282..0000000 --- a/libkeccak_hmac_unmarshal.3 +++ /dev/null @@ -1,46 +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(struct libkeccak_hmac_state *\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 . -.I state -may be -.IR NULL . -.SH RETURN VALUES -The -.BR libkeccak_hmac_unmarshal () -returns the number of bytes reads from -.I data -upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -If -.I state -is -.IR NULL , -the number the function will always be -successful and return a positive value, -this value is the number of bytes that -make un the marshalled state. -.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 (3) diff --git a/libkeccak_hmac_update.3 b/libkeccak_hmac_update.3 deleted file mode 100644 index e34bb98..0000000 --- a/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(struct libkeccak_state *\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_wipe.3 b/libkeccak_hmac_wipe.3 deleted file mode 100644 index ceee5d7..0000000 --- a/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(struct libkeccak_hmac_state *\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_keccaksum_fd.3 b/libkeccak_keccaksum_fd.3 deleted file mode 100644 index 82d1fb9..0000000 --- a/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, struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\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 -struct libkeccak_state state; -struct libkeccak_spec 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 deleted file mode 100644 index 5678389..0000000 --- a/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, struct libkeccak_state *\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 -struct libkeccak_state 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 deleted file mode 100644 index d27618d..0000000 --- a/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, struct libkeccak_state *\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 -struct libkeccak_state 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 deleted file mode 100644 index 58b980d..0000000 --- a/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, struct libkeccak_state *\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 -struct libkeccak_state 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 deleted file mode 100644 index 0ddfaea..0000000 --- a/libkeccak_simple_squeeze.3 +++ /dev/null @@ -1,34 +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(struct libkeccak_state *\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_zerocopy_digest (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) diff --git a/libkeccak_spec_check.3 b/libkeccak_spec_check.3 deleted file mode 100644 index 3b5c9df..0000000 --- a/libkeccak_spec_check.3 +++ /dev/null @@ -1,92 +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 struct libkeccak_spec *\fIspec\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_check () -function validates the parameters of -.IR *spec , -so that unusable configurations can be detected. -It is recommended to call this function after calling -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_cshake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -or, especially, after settings the parameters -manually for Keccak hashing. -.PP -.nf -struct libkeccak_spec { - long int bitrate; /* bitrate (in bits) */ - long int capacity; /* capacity (in bits) */ - long int output; /* output size (in bits) */ -}; -.fi -.SH RETURN VALUES -The -.BR libkeccak_spec_check () -function returns 0 if the settings are usable. Otherwise -it will return one of the following constants. -.PP -.TP -.B LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE -The specified bitrate was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 -The specified bitrate was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE -The specified capacity was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 -The specified capacity was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE -The specified output size was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE -The state size, that is the sum of the bitrate -and the capacity, exceeded the supported limit -(currently at 1600 bits.) -.TP -.B LIBKECCAK_SPEC_ERROR_STATE_MOD_25 -The state size, that is the sum of the bitrate -and the capacity, in bits, was not equivalent -to 0 modulus 25. Meaning the state size cannot -cover all lanes equivalently. -.TP -.B LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT -The word size, that is the state size divided -by 25, is not a power of 2. -.TP -.B LIBKECCAK_SPEC_ERROR_WORD_MOD_8 -The word size, that is the state size divided -by 25, is not quivalent to 0 modulus 8, that -is, it is not in whole bytes. -.PP -Note that there may be more than one error. Only the first -detected is returned. -.SH ERRORS -The -.BR libkeccak_spec_check () -function cannot fail. -.fi -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_cshake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) diff --git a/libkeccak_spec_cshake.3 b/libkeccak_spec_cshake.3 deleted file mode 100644 index dfd8ee9..0000000 --- a/libkeccak_spec_cshake.3 +++ /dev/null @@ -1,48 +0,0 @@ -.TH LIBKECCAK_SPEC_CSHAKE 3 LIBKECCAK -.SH NAME -libkeccak_spec_cshake - Configure cSHAKE hashing parameters -.SH SYNOPSIS -.nf -#include - -void libkeccak_spec_cshake(struct libkeccak_spec *\fIspec\fP, long int \fIx\fP, long int \fId\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_cshake () -function sets -.I *spec -to specify the Keccak parameters used for cSHAKE 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_cshake () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_spec_cshake () -function cannot fail. -.SH EXAMPLE -This example configure a -.B struct libkeccak_spec -to specify the Keccak parameters used for cSHAKE256(, 512): -.PP -.nf -struct libkeccak_spec spec; -libkeccak_spec_cshake(&spec, 256, 512); -.fi -.SH SEE ALSO -.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), -.BR libkeccak_hmac_initialise (3) diff --git a/libkeccak_spec_rawshake.3 b/libkeccak_spec_rawshake.3 deleted file mode 100644 index 5d810b2..0000000 --- a/libkeccak_spec_rawshake.3 +++ /dev/null @@ -1,48 +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(struct libkeccak_spec *\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 struct libkeccak_spec -to specify the Keccak parameters used for RawSHAKE256(, 512): -.PP -.nf -struct libkeccak_spec spec; -libkeccak_spec_rawshake(&spec, 256, 512); -.fi -.SH SEE ALSO -.BR libkeccak_spec_cshake (3), -.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 deleted file mode 100644 index 9cafbf6..0000000 --- a/libkeccak_spec_sha3.3 +++ /dev/null @@ -1,47 +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(struct libkeccak_spec *\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 struct libkeccak_spec -to specify the Keccak parameters used for SHA3-256: -.PP -.nf -struct libkeccak_spec spec; -libkeccak_spec_sha3(&spec, 256); -.fi -.SH SEE ALSO -.BR libkeccak_spec_cshake (3), -.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 deleted file mode 100644 index c98962f..0000000 --- a/libkeccak_spec_shake.3 +++ /dev/null @@ -1,48 +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(struct libkeccak_spec *\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 struct libkeccak_spec -to specify the Keccak parameters used for SHAKE256(, 512): -.PP -.nf -struct libkeccak_spec spec; -libkeccak_spec_shake(&spec, 256, 512); -.fi -.SH SEE ALSO -.BR libkeccak_spec_cshake (3), -.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 deleted file mode 100644 index 1510bb3..0000000 --- a/libkeccak_squeeze.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_squeeze - Runs the squeeze phase -.SH SYNOPSIS -.nf -#include - -void libkeccak_squeeze(struct libkeccak_state *\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_zerocopy_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3) diff --git a/libkeccak_state_copy.3 b/libkeccak_state_copy.3 deleted file mode 100644 index 84f6352..0000000 --- a/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(struct libkeccak_state *\fIdest\fP, const struct libkeccak_state *\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 struct libkeccak_state -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_create.3 b/libkeccak_state_create.3 deleted file mode 100644 index d037435..0000000 --- a/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 - -struct libkeccak_state *libkeccak_state_create(const struct libkeccak_spec *\fIspec\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_create () -function allocates a new -.I struct libkeccak_state * -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 struct libkeccak_state * -(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 deleted file mode 100644 index 34365f1..0000000 --- a/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(struct libkeccak_state *\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 deleted file mode 100644 index ef0bcba..0000000 --- a/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 - -struct libkeccak_state *libkeccak_state_duplicate(const struct libkeccak_state *\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 struct libkeccak_state -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 struct libkeccak_state* -(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 deleted file mode 100644 index bcfdc42..0000000 --- a/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(struct libkeccak_state *\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 deleted file mode 100644 index 63eac25..0000000 --- a/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(struct libkeccak_state *\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 deleted file mode 100644 index 529276e..0000000 --- a/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(struct libkeccak_state *\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 deleted file mode 100644 index 3c63af7..0000000 --- a/libkeccak_state_initialise.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_state_initialise - Initialise hash state -.SH SYNOPSIS -.nf -#include - -int libkeccak_state_initialise(struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\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_zerocopy_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_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_cshake (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 (3), -.BR libkeccak_hmac_initialise (3) diff --git a/libkeccak_state_marshal.3 b/libkeccak_state_marshal.3 deleted file mode 100644 index 0599b5a..0000000 --- a/libkeccak_state_marshal.3 +++ /dev/null @@ -1,36 +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 struct libkeccak_state *\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 -Specific -.I NULL -as -.I data -to get minimum usable allocation size for -.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_unmarshal (3) diff --git a/libkeccak_state_reset.3 b/libkeccak_state_reset.3 deleted file mode 100644 index e847501..0000000 --- a/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(struct libkeccak_state *\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 deleted file mode 100644 index 6198e3a..0000000 --- a/libkeccak_state_unmarshal.3 +++ /dev/null @@ -1,47 +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(struct libkeccak_state *\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 . -.I state -may be -.IR NULL . -.SH RETURN VALUES -The -.BR libkeccak_state_unmarshal () -returns the number of bytes reads from -.I data -upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -If -.I state -is -.IR NULL , -the number the function will always be -successful and return a positive value, -this value is the number of bytes that -make un the marshalled state. -.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 (3) diff --git a/libkeccak_state_wipe.3 b/libkeccak_state_wipe.3 deleted file mode 100644 index 9028dcc..0000000 --- a/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(struct libkeccak_state *\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_message.3 b/libkeccak_state_wipe_message.3 deleted file mode 100644 index 27c838a..0000000 --- a/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(struct libkeccak_state *\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_sponge.3 b/libkeccak_state_wipe_sponge.3 deleted file mode 100644 index b36e5b4..0000000 --- a/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(struct libkeccak_state *\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_unhex.3 b/libkeccak_unhex.3 deleted file mode 100644 index c7dc9bc..0000000 --- a/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/libkeccak_update.3 b/libkeccak_update.3 deleted file mode 100644 index 384e492..0000000 --- a/libkeccak_update.3 +++ /dev/null @@ -1,100 +0,0 @@ -.TH LIBKECCAK_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_update - Partially hash a message with erasure -.SH SYNOPSIS -.nf -#include - -int libkeccak_update(struct libkeccak_state *\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 -struct libkeccak_state state; -struct libkeccak_spec 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 NOTES -For cSHAKE, the -.BR libkeccak_cshake_initialise (3), -must be called, once, immediately after -state initialisation; before the first -call to the -.BR libkeccak_update () -function. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_zerocopy_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_digest (3), -.BR libkeccak_digest (3) diff --git a/libkeccak_zerocopy_chunksize.3 b/libkeccak_zerocopy_chunksize.3 deleted file mode 100644 index b507c7f..0000000 --- a/libkeccak_zerocopy_chunksize.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH LIBKECCAK_ZEROCOPY_CHUNKSIZE 3 LIBKECCAK -.SH NAME -libkeccak_zerocopy_chunksize - Get chunk size for zero-copy processing -.RB ( ADVANCED ) -.SH SYNOPSIS -.nf -#include - -size_t libkeccak_zerocopy_chunksize(struct libkeccak_state *\fIstate\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_zerocopy_chunksize () -function returns the number of bytes the sponge -in the -.I state -parameter processes per round. Input to the -.BR libkeccak_zerocopy_update (3) -function must be an integer multiple of this -number, and memory allocated for the -.BR libkeccak_zerocopy_digest (3) -function must also be a multiple of this -number (further restrictions apply, see -.BR libkeccak_zerocopy_digest (3) -for more details.) -.SH RETURN VALUES -The -.BR libkeccak_zerocopy_chunksize () -function returns the number of bytes that -the sponge processes per processing round. -.SH ERRORS -The -.BR libkeccak_zerocopy_chunksize () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_zerocopy_update (3), -.BR libkeccak_zerocopy_digest (3) diff --git a/libkeccak_zerocopy_digest.3 b/libkeccak_zerocopy_digest.3 deleted file mode 100644 index 6b752fb..0000000 --- a/libkeccak_zerocopy_digest.3 +++ /dev/null @@ -1,136 +0,0 @@ -.TH LIBKECCAK_ZEROCOPY_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_zerocopy_digest - Complete the hashing of a message without copying -.RB ( ADVANCED ) -.SH SYNOPSIS -.LP -.nf -#include - -void libkeccak_zerocopy_digest(struct libkeccak_state *\fIstate\fP, 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_zerocopy_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_zerocopy_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), or the return of the -.BR libkeccak_cshake_suffix (3) -function (for cSHAKE), 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 -.BR libkeccak_zerocopy_digest () -will write at and beyond -.IR &msg[msglen] . -The caller must make sure that enough memory is allocated -for the -.I suffix -as well as padding of at least 2 bits, for -.IR msg . -The sum of -.IR msglen , -the bits specified in -.IR suffix , -and the padded, shall, in bytes, be an integer multiple of -the bitrate divided by eight, which is returned by the -.BR libkeccak_zerocopy_chunksize (3) -function. -.SH RETURN VALUES -The -.BR libkeccak_zerocopy_digest () -function does not return a value. -.SH ERRORS -The -.BR libkeccak_zerocopy_digest () -function cannot fail. -.SH NOTES -Calling the -.BR libkeccak_zerocopy_digest (3) -function after the -.BR libkeccak_update (3) -or -.BR libkeccak_fast_update (3) -functions, with the same -.I state -argument, may cause the message to be misread. -.SH NOTES -For cSHAKE, the -.BR libkeccak_cshake_initialise (3), -must be called, once, immediately after -state initialisation; before the first -call to any of the -.BR libkeccak_fast_update (), -.BR libkeccak_zerocopy_update (), -.BR libkeccak_update (), -and -.BR libkeccak_zerocopy_digest () -functions. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_zerocopy_chunksize (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_zerocopy_update (3), -.BR libkeccak_update (3), -.BR libkeccak_cshake_suffix (3), -.BR libkeccak_digest (3), -.BR libkeccak_zerocopy_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) diff --git a/libkeccak_zerocopy_update.3 b/libkeccak_zerocopy_update.3 deleted file mode 100644 index b4086a0..0000000 --- a/libkeccak_zerocopy_update.3 +++ /dev/null @@ -1,89 +0,0 @@ -.TH LIBKECCAK_ZEROCOPY_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_zerocopy_update - Partially hash a message without copying -.RB ( ADVANCED ) -.SH SYNOPSIS -.nf -#include - -void libkeccak_zerocopy_update(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); -.fi -.PP -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_zerocopy_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 -As a restriction specific to the -.BR libkeccak_zerocopy_update () -function, the -.I msglen -argument must be an integer multiple of the bitrate -divided by eight. This is returned by the -.BR libkeccak_zerocopy_chunksize (3) -function. The -.BR libkeccak_update (3) -or -.BR libkeccak_fast_update (3) -functions can be used to avoid this restriction, -but these, unlike the -.BR libkeccak_zerocopy_update () -function, will copy the message and move around -copied data. -.SH RETURN VALUES -The -.BR libkeccak_zerocopy_update () -function does not return a value. -.SH ERRORS -The -.BR libkeccak_zerocopy_update () -function cannot fail. -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.PP -It is safe call the -.BR libkeccak_zerocopy_update () -function before the -.BR libkeccak_update (3), -.BR libkeccak_fast_update (3) -.BR libkeccak_digest (3) -and -.BR libkeccak_fast_digest (3) -functions with the same -.I state -argument. However, calling the -.BR libkeccak_zerocopy_update () -function after the -.BR libkeccak_update (3) -or -.BR libkeccak_fast_update (3) -functions may cause the message -to be misread. -.SH NOTES -For cSHAKE, the -.BR libkeccak_cshake_initialise (3), -must be called, once, immediately after -state initialisation; before the first -call to the -.BR libkeccak_zerocopy_update () -function. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_cshake_initialise (3), -.BR libkeccak_zerocopy_chunksize (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_zerocopy_digest (3), -.BR libkeccak_digest (3) diff --git a/man3/libkeccak_behex_lower.3 b/man3/libkeccak_behex_lower.3 new file mode 100644 index 0000000..2078790 --- /dev/null +++ b/man3/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/man3/libkeccak_behex_upper.3 b/man3/libkeccak_behex_upper.3 new file mode 100644 index 0000000..b5c67bb --- /dev/null +++ b/man3/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/man3/libkeccak_cshake_initialise.3 b/man3/libkeccak_cshake_initialise.3 new file mode 100644 index 0000000..a18f1bf --- /dev/null +++ b/man3/libkeccak_cshake_initialise.3 @@ -0,0 +1,126 @@ +.TH LIBKECCAK_CSHAKE_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_cshake_initialise - Initialise a sponge for cSHAKE hashing +.SH SYNOPSIS +.nf +#include + +void libkeccak_cshake_initialise(struct libkeccak_state *restrict \fIstate\fP, + const void *\fIn_text\fP, size_t \fIn_len\fP, size_t \fIn_bits\fP, const char *\fIn_suffix\fP, + const void *\fIs_text\fP, size_t \fIs_len\fP, size_t \fIs_bits\fP, const char *\fIs_suffix\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_cshake_suffix () +function shall be called immediately +after the +.BR libkeccak_state_initialise (3) +function (before +.BR libkeccak_update (3) +or +.BR libkeccak_digest (3), +or any variant of those functions), +to provide the initialisation blocks, +containing customisation data, to the +Keccak sponge. +.PP +The value of the +.I state +parameter shall be an initialised state +to feed the initialisation blocks to. +.PP +The value of the +.I n_text +parameter shall be the function-name +bit-string, represented in raw bytes; +.I n_len +shall be value no greater than the +number of whole bytes in +.I n_text +and +.I n_bits +shall be the number of bits in +.I n_text +sans the bytes covered by +.IR n_len , +that is, the number of bits in +.I n_text +minus +.IR (nlen_*8) . +.I n_suffix +shall be either +.I NULL +or an appendix of bits to +.I n_suffix +(neither +.I n_len +nor +.I n_bits +shall count these), stored as a NUL-terminated +string of the ASCII digits +.B 1 +and +.BR 0 . +.PP +The value of the +.I s_text +parameter shall be the customisation +bit-string, represented in raw bytes; +.I s_len +shall be value no greater than the +number of whole bytes in +.I s_text +and +.I s_bits +shall be the number of bits in +.I s_text +sans the bytes covered by +.IR s_len , +that is, the number of bits in +.I s_text +minus +.IR (nles_*8) . +.I s_suffix +shall be either +.I NULL +or an appendix of bits to +.I s_suffix +(neither +.I s_len +nor +.I s_bits +shall count these), stored as a NUL-terminated +string of the ASCII digits +.B 1 +and +.BR 0 . +.PP +For the +.I n_suffix +and +.I s_suffix +parameters, +.I NULL +is treated as the empty string. +.SH RETURN VALUES +The +.BR libkeccak_cshake_suffix () +function does not return a value. +.SH ERRORS +The +.BR libkeccak_cshake_suffix () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_spec_cshake (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_zerocopy_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_digest (3), +.BR libkeccak_digest (3) diff --git a/man3/libkeccak_cshake_suffix.3 b/man3/libkeccak_cshake_suffix.3 new file mode 100644 index 0000000..b390134 --- /dev/null +++ b/man3/libkeccak_cshake_suffix.3 @@ -0,0 +1,45 @@ +.TH LIBKECCAK_CSHAKE_SUFFIX 3 LIBKECCAK +.SH NAME +libkeccak_cshake_suffix - Get message suffix for cSHAKE hashing +.SH SYNOPSIS +.nf +#include + +const char *libkeccak_cshake_suffix(size_t \fInlen\fP, size_t \fIslen\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_cshake_suffix () +function returns a string of '1':s and '0':s +representing the bits the the message suffixed +that shall be used. +Canonically, the values of the +.I nlen +and +.I slen +parameters shall be the length of the cSHAKE +function-name bit-string and the cSHAKE +customisation bit-string, however, the function +will only check whether these values are zero +or non-zero. +.SH RETURN VALUES +The +.BR libkeccak_cshake_suffix () +function returns a statically allocated, +read-only, message suffix bit-string +that shall be used. +.SH ERRORS +The +.BR libkeccak_cshake_suffix () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_spec_cshake (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_digest (3), +.BR libkeccak_digest (3) diff --git a/man3/libkeccak_degeneralise_spec.3 b/man3/libkeccak_degeneralise_spec.3 new file mode 100644 index 0000000..e694147 --- /dev/null +++ b/man3/libkeccak_degeneralise_spec.3 @@ -0,0 +1,123 @@ +.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(struct libkeccak_generalised_spec *\fIspec\fP, struct libkeccak_spec *\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 +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) */ +}; +.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. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_BITRATE_CAPACITY_INCONSISTENCY +The sum of the bitrate and the capacity does not equal +the state size (25 times the word size). +.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 struct libkeccak_spec +to specify settings for Keccak[c = 512]: +.PP +.nf +int r; +struct libkeccak_spec spec; +struct libkeccak_generalised_spec 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_cshake (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 new file mode 100644 index 0000000..90c76c5 --- /dev/null +++ b/man3/libkeccak_digest.3 @@ -0,0 +1,157 @@ +.TH LIBKECCAK_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_digest - Complete the hashing of a message with erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_digest(struct libkeccak_state *\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), +.BR libkeccak_fast_update (3), +or +.BR libkeccak_zerocopy_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), or the return of the +.BR libkeccak_cshake_suffix (3) +function (for cSHAKE), 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 +struct libkeccak_state state; +struct libkeccak_spec 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 NOTES +For cSHAKE, the +.BR libkeccak_cshake_initialise (3), +must be called, once, immediately after +state initialisation; before the first +call to any of the +.BR libkeccak_fast_update (), +.BR libkeccak_zerocopy_update (), +.BR libkeccak_update (), +and +.BR libkeccak_digest () +functions. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_cshake_suffix (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_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 new file mode 100644 index 0000000..c4925e4 --- /dev/null +++ b/man3/libkeccak_fast_digest.3 @@ -0,0 +1,160 @@ +.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(struct libkeccak_state *\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), +.BR libkeccak_fast_update (3), +or +.BR libkeccak_zerocopy_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), or the return of the +.BR libkeccak_cshake_suffix (3) +function (for cSHAKE), 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 +struct libkeccak_state state; +struct libkeccak_spec 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 NOTES +For cSHAKE, the +.BR libkeccak_cshake_initialise (3), +must be called, once, immediately after +state initialisation; before the first +call to any of the +.BR libkeccak_fast_update (), +.BR libkeccak_zerocopy_update (), +.BR libkeccak_update (), +and +.BR libkeccak_digest_digest () +functions. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_zerocopy_update (3), +.BR libkeccak_update (3), +.BR libkeccak_cshake_suffix (3), +.BR libkeccak_digest (3), +.BR libkeccak_zerocopy_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 new file mode 100644 index 0000000..5be6cd6 --- /dev/null +++ b/man3/libkeccak_fast_squeeze.3 @@ -0,0 +1,35 @@ +.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(struct libkeccak_state *\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_zerocopy_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 new file mode 100644 index 0000000..5d38b0d --- /dev/null +++ b/man3/libkeccak_fast_update.3 @@ -0,0 +1,101 @@ +.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(struct libkeccak_state *\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 +struct libkeccak_state state; +struct libkeccak_spec 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 NOTES +For cSHAKE, the +.BR libkeccak_cshake_initialise (3), +must be called, once, immediately after +state initialisation; before the first +call to the +.BR libkeccak_fast_update () +function. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_zerocopy_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_digest (3), +.BR libkeccak_digest (3) diff --git a/man3/libkeccak_generalised_spec_initialise.3 b/man3/libkeccak_generalised_spec_initialise.3 new file mode 100644 index 0000000..acfa173 --- /dev/null +++ b/man3/libkeccak_generalised_spec_initialise.3 @@ -0,0 +1,42 @@ +.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(struct libkeccak_generalised_spec *\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_cshake (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 new file mode 100644 index 0000000..9f5341a --- /dev/null +++ b/man3/libkeccak_generalised_sum_fd.3 @@ -0,0 +1,137 @@ +.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, struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\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 unless +.I spec +is +.IR NULL . +.BR libkeccak_generalised_sum_fd () +initialises +.I *state +itself unless +.I spec +is +.IR NULL . +Therefore there would be a memory leak if +.I *state +is already initialised and +.I spec +is +.RI non- NULL . +.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 +struct libkeccak_state state; +struct libkeccak_spec 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_cshake (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 new file mode 100644 index 0000000..eb80c6e --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\fIdest\fP, const struct libkeccak_hmac_state *\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 struct libkeccak_hmac_state +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 new file mode 100644 index 0000000..d804f31 --- /dev/null +++ b/man3/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 + +struct libkeccak_hmac_state *libkeccak_hmac_create(const struct libkeccak_spec *\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 struct libkeccak_hmac_state * +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 struct libkeccak_hmac_state * +(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 new file mode 100644 index 0000000..e2d5b1c --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..9c0ee6b --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..b1cdc30 --- /dev/null +++ b/man3/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 + +struct libkeccak_hmac_state *libkeccak_hmac_duplicate(const struct libkeccak_hmac_state *\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 struct libkeccak_hmac_state +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 new file mode 100644 index 0000000..05a8e2e --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..6f21b70 --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..87cb556 --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..ca62baf --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..91b103e --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..db3590f --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\fIstate\fP, const struct libkeccak_spec *\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_spec_cshake (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 new file mode 100644 index 0000000..29ca9ea --- /dev/null +++ b/man3/libkeccak_hmac_marshal.3 @@ -0,0 +1,37 @@ +.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 struct libkeccak_hmac_state *\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 +Specific +.I NULL +as +.I data +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_unmarshal (3) diff --git a/man3/libkeccak_hmac_reset.3 b/man3/libkeccak_hmac_reset.3 new file mode 100644 index 0000000..963ad4c --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..f961ade --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..7224282 --- /dev/null +++ b/man3/libkeccak_hmac_unmarshal.3 @@ -0,0 +1,46 @@ +.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(struct libkeccak_hmac_state *\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 . +.I state +may be +.IR NULL . +.SH RETURN VALUES +The +.BR libkeccak_hmac_unmarshal () +returns the number of bytes reads from +.I data +upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +If +.I state +is +.IR NULL , +the number the function will always be +successful and return a positive value, +this value is the number of bytes that +make un the marshalled state. +.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 (3) diff --git a/man3/libkeccak_hmac_update.3 b/man3/libkeccak_hmac_update.3 new file mode 100644 index 0000000..e34bb98 --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..ceee5d7 --- /dev/null +++ b/man3/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(struct libkeccak_hmac_state *\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 new file mode 100644 index 0000000..82d1fb9 --- /dev/null +++ b/man3/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, struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\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 +struct libkeccak_state state; +struct libkeccak_spec 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 new file mode 100644 index 0000000..5678389 --- /dev/null +++ b/man3/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, struct libkeccak_state *\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 +struct libkeccak_state 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 new file mode 100644 index 0000000..d27618d --- /dev/null +++ b/man3/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, struct libkeccak_state *\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 +struct libkeccak_state 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 new file mode 100644 index 0000000..58b980d --- /dev/null +++ b/man3/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, struct libkeccak_state *\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 +struct libkeccak_state 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 new file mode 100644 index 0000000..0ddfaea --- /dev/null +++ b/man3/libkeccak_simple_squeeze.3 @@ -0,0 +1,34 @@ +.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(struct libkeccak_state *\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_zerocopy_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 new file mode 100644 index 0000000..3b5c9df --- /dev/null +++ b/man3/libkeccak_spec_check.3 @@ -0,0 +1,92 @@ +.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK +.SH NAME +libkeccak_spec_check - Validate hashing parameters +.SH SYNOPSIS +.nf +#include + +int libkeccak_spec_check(const struct libkeccak_spec *\fIspec\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_check () +function validates the parameters of +.IR *spec , +so that unusable configurations can be detected. +It is recommended to call this function after calling +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_cshake (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +or, especially, after settings the parameters +manually for Keccak hashing. +.PP +.nf +struct libkeccak_spec { + long int bitrate; /* bitrate (in bits) */ + long int capacity; /* capacity (in bits) */ + long int output; /* output size (in bits) */ +}; +.fi +.SH RETURN VALUES +The +.BR libkeccak_spec_check () +function returns 0 if the settings are usable. Otherwise +it will return one of the following constants. +.PP +.TP +.B LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE +The specified bitrate was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 +The specified bitrate was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE +The specified capacity was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 +The specified capacity was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE +The specified output size was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE +The state size, that is the sum of the bitrate +and the capacity, exceeded the supported limit +(currently at 1600 bits.) +.TP +.B LIBKECCAK_SPEC_ERROR_STATE_MOD_25 +The state size, that is the sum of the bitrate +and the capacity, in bits, was not equivalent +to 0 modulus 25. Meaning the state size cannot +cover all lanes equivalently. +.TP +.B LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT +The word size, that is the state size divided +by 25, is not a power of 2. +.TP +.B LIBKECCAK_SPEC_ERROR_WORD_MOD_8 +The word size, that is the state size divided +by 25, is not quivalent to 0 modulus 8, that +is, it is not in whole bytes. +.PP +Note that there may be more than one error. Only the first +detected is returned. +.SH ERRORS +The +.BR libkeccak_spec_check () +function cannot fail. +.fi +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_cshake (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) diff --git a/man3/libkeccak_spec_cshake.3 b/man3/libkeccak_spec_cshake.3 new file mode 100644 index 0000000..dfd8ee9 --- /dev/null +++ b/man3/libkeccak_spec_cshake.3 @@ -0,0 +1,48 @@ +.TH LIBKECCAK_SPEC_CSHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_cshake - Configure cSHAKE hashing parameters +.SH SYNOPSIS +.nf +#include + +void libkeccak_spec_cshake(struct libkeccak_spec *\fIspec\fP, long int \fIx\fP, long int \fId\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_cshake () +function sets +.I *spec +to specify the Keccak parameters used for cSHAKE 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_cshake () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_spec_cshake () +function cannot fail. +.SH EXAMPLE +This example configure a +.B struct libkeccak_spec +to specify the Keccak parameters used for cSHAKE256(, 512): +.PP +.nf +struct libkeccak_spec spec; +libkeccak_spec_cshake(&spec, 256, 512); +.fi +.SH SEE ALSO +.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), +.BR libkeccak_hmac_initialise (3) diff --git a/man3/libkeccak_spec_rawshake.3 b/man3/libkeccak_spec_rawshake.3 new file mode 100644 index 0000000..5d810b2 --- /dev/null +++ b/man3/libkeccak_spec_rawshake.3 @@ -0,0 +1,48 @@ +.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters +.SH SYNOPSIS +.nf +#include + +void libkeccak_spec_rawshake(struct libkeccak_spec *\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 struct libkeccak_spec +to specify the Keccak parameters used for RawSHAKE256(, 512): +.PP +.nf +struct libkeccak_spec spec; +libkeccak_spec_rawshake(&spec, 256, 512); +.fi +.SH SEE ALSO +.BR libkeccak_spec_cshake (3), +.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 new file mode 100644 index 0000000..9cafbf6 --- /dev/null +++ b/man3/libkeccak_spec_sha3.3 @@ -0,0 +1,47 @@ +.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK +.SH NAME +libkeccak_spec_sha3 - Configure SHA-3 hashing parameters +.SH SYNOPSIS +.nf +#include + +void libkeccak_spec_sha3(struct libkeccak_spec *\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 struct libkeccak_spec +to specify the Keccak parameters used for SHA3-256: +.PP +.nf +struct libkeccak_spec spec; +libkeccak_spec_sha3(&spec, 256); +.fi +.SH SEE ALSO +.BR libkeccak_spec_cshake (3), +.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 new file mode 100644 index 0000000..c98962f --- /dev/null +++ b/man3/libkeccak_spec_shake.3 @@ -0,0 +1,48 @@ +.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_shake - Configure SHAKE hashing parameters +.SH SYNOPSIS +.nf +#include + +void libkeccak_spec_shake(struct libkeccak_spec *\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 struct libkeccak_spec +to specify the Keccak parameters used for SHAKE256(, 512): +.PP +.nf +struct libkeccak_spec spec; +libkeccak_spec_shake(&spec, 256, 512); +.fi +.SH SEE ALSO +.BR libkeccak_spec_cshake (3), +.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 new file mode 100644 index 0000000..1510bb3 --- /dev/null +++ b/man3/libkeccak_squeeze.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_squeeze - Runs the squeeze phase +.SH SYNOPSIS +.nf +#include + +void libkeccak_squeeze(struct libkeccak_state *\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_zerocopy_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 new file mode 100644 index 0000000..84f6352 --- /dev/null +++ b/man3/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(struct libkeccak_state *\fIdest\fP, const struct libkeccak_state *\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 struct libkeccak_state +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 new file mode 100644 index 0000000..d037435 --- /dev/null +++ b/man3/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 + +struct libkeccak_state *libkeccak_state_create(const struct libkeccak_spec *\fIspec\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_create () +function allocates a new +.I struct libkeccak_state * +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 struct libkeccak_state * +(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 new file mode 100644 index 0000000..34365f1 --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..ef0bcba --- /dev/null +++ b/man3/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 + +struct libkeccak_state *libkeccak_state_duplicate(const struct libkeccak_state *\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 struct libkeccak_state +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 struct libkeccak_state* +(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 new file mode 100644 index 0000000..bcfdc42 --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..63eac25 --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..529276e --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..3c63af7 --- /dev/null +++ b/man3/libkeccak_state_initialise.3 @@ -0,0 +1,57 @@ +.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_state_initialise - Initialise hash state +.SH SYNOPSIS +.nf +#include + +int libkeccak_state_initialise(struct libkeccak_state *\fIstate\fP, const struct libkeccak_spec *\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_zerocopy_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_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_cshake (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 (3), +.BR libkeccak_hmac_initialise (3) diff --git a/man3/libkeccak_state_marshal.3 b/man3/libkeccak_state_marshal.3 new file mode 100644 index 0000000..0599b5a --- /dev/null +++ b/man3/libkeccak_state_marshal.3 @@ -0,0 +1,36 @@ +.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 struct libkeccak_state *\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 +Specific +.I NULL +as +.I data +to get minimum usable allocation size for +.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_unmarshal (3) diff --git a/man3/libkeccak_state_reset.3 b/man3/libkeccak_state_reset.3 new file mode 100644 index 0000000..e847501 --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..6198e3a --- /dev/null +++ b/man3/libkeccak_state_unmarshal.3 @@ -0,0 +1,47 @@ +.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_state_unmarshal - Unharshals a hash state +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_state_unmarshal(struct libkeccak_state *\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 . +.I state +may be +.IR NULL . +.SH RETURN VALUES +The +.BR libkeccak_state_unmarshal () +returns the number of bytes reads from +.I data +upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +If +.I state +is +.IR NULL , +the number the function will always be +successful and return a positive value, +this value is the number of bytes that +make un the marshalled state. +.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 (3) diff --git a/man3/libkeccak_state_wipe.3 b/man3/libkeccak_state_wipe.3 new file mode 100644 index 0000000..9028dcc --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..27c838a --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..b36e5b4 --- /dev/null +++ b/man3/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(struct libkeccak_state *\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 new file mode 100644 index 0000000..c7dc9bc --- /dev/null +++ b/man3/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/man3/libkeccak_update.3 b/man3/libkeccak_update.3 new file mode 100644 index 0000000..384e492 --- /dev/null +++ b/man3/libkeccak_update.3 @@ -0,0 +1,100 @@ +.TH LIBKECCAK_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_update - Partially hash a message with erasure +.SH SYNOPSIS +.nf +#include + +int libkeccak_update(struct libkeccak_state *\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 +struct libkeccak_state state; +struct libkeccak_spec 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 NOTES +For cSHAKE, the +.BR libkeccak_cshake_initialise (3), +must be called, once, immediately after +state initialisation; before the first +call to the +.BR libkeccak_update () +function. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_zerocopy_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_digest (3), +.BR libkeccak_digest (3) diff --git a/man3/libkeccak_zerocopy_chunksize.3 b/man3/libkeccak_zerocopy_chunksize.3 new file mode 100644 index 0000000..b507c7f --- /dev/null +++ b/man3/libkeccak_zerocopy_chunksize.3 @@ -0,0 +1,40 @@ +.TH LIBKECCAK_ZEROCOPY_CHUNKSIZE 3 LIBKECCAK +.SH NAME +libkeccak_zerocopy_chunksize - Get chunk size for zero-copy processing +.RB ( ADVANCED ) +.SH SYNOPSIS +.nf +#include + +size_t libkeccak_zerocopy_chunksize(struct libkeccak_state *\fIstate\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_zerocopy_chunksize () +function returns the number of bytes the sponge +in the +.I state +parameter processes per round. Input to the +.BR libkeccak_zerocopy_update (3) +function must be an integer multiple of this +number, and memory allocated for the +.BR libkeccak_zerocopy_digest (3) +function must also be a multiple of this +number (further restrictions apply, see +.BR libkeccak_zerocopy_digest (3) +for more details.) +.SH RETURN VALUES +The +.BR libkeccak_zerocopy_chunksize () +function returns the number of bytes that +the sponge processes per processing round. +.SH ERRORS +The +.BR libkeccak_zerocopy_chunksize () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_zerocopy_update (3), +.BR libkeccak_zerocopy_digest (3) diff --git a/man3/libkeccak_zerocopy_digest.3 b/man3/libkeccak_zerocopy_digest.3 new file mode 100644 index 0000000..6b752fb --- /dev/null +++ b/man3/libkeccak_zerocopy_digest.3 @@ -0,0 +1,136 @@ +.TH LIBKECCAK_ZEROCOPY_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_zerocopy_digest - Complete the hashing of a message without copying +.RB ( ADVANCED ) +.SH SYNOPSIS +.LP +.nf +#include + +void libkeccak_zerocopy_digest(struct libkeccak_state *\fIstate\fP, 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_zerocopy_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_zerocopy_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), or the return of the +.BR libkeccak_cshake_suffix (3) +function (for cSHAKE), 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 +.BR libkeccak_zerocopy_digest () +will write at and beyond +.IR &msg[msglen] . +The caller must make sure that enough memory is allocated +for the +.I suffix +as well as padding of at least 2 bits, for +.IR msg . +The sum of +.IR msglen , +the bits specified in +.IR suffix , +and the padded, shall, in bytes, be an integer multiple of +the bitrate divided by eight, which is returned by the +.BR libkeccak_zerocopy_chunksize (3) +function. +.SH RETURN VALUES +The +.BR libkeccak_zerocopy_digest () +function does not return a value. +.SH ERRORS +The +.BR libkeccak_zerocopy_digest () +function cannot fail. +.SH NOTES +Calling the +.BR libkeccak_zerocopy_digest (3) +function after the +.BR libkeccak_update (3) +or +.BR libkeccak_fast_update (3) +functions, with the same +.I state +argument, may cause the message to be misread. +.SH NOTES +For cSHAKE, the +.BR libkeccak_cshake_initialise (3), +must be called, once, immediately after +state initialisation; before the first +call to any of the +.BR libkeccak_fast_update (), +.BR libkeccak_zerocopy_update (), +.BR libkeccak_update (), +and +.BR libkeccak_zerocopy_digest () +functions. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_zerocopy_chunksize (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_zerocopy_update (3), +.BR libkeccak_update (3), +.BR libkeccak_cshake_suffix (3), +.BR libkeccak_digest (3), +.BR libkeccak_zerocopy_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) diff --git a/man3/libkeccak_zerocopy_update.3 b/man3/libkeccak_zerocopy_update.3 new file mode 100644 index 0000000..b4086a0 --- /dev/null +++ b/man3/libkeccak_zerocopy_update.3 @@ -0,0 +1,89 @@ +.TH LIBKECCAK_ZEROCOPY_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_zerocopy_update - Partially hash a message without copying +.RB ( ADVANCED ) +.SH SYNOPSIS +.nf +#include + +void libkeccak_zerocopy_update(struct libkeccak_state *\fIstate\fP, const void *\fImsg\fP, size_t \fImsglen\fP); +.fi +.PP +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_zerocopy_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 +As a restriction specific to the +.BR libkeccak_zerocopy_update () +function, the +.I msglen +argument must be an integer multiple of the bitrate +divided by eight. This is returned by the +.BR libkeccak_zerocopy_chunksize (3) +function. The +.BR libkeccak_update (3) +or +.BR libkeccak_fast_update (3) +functions can be used to avoid this restriction, +but these, unlike the +.BR libkeccak_zerocopy_update () +function, will copy the message and move around +copied data. +.SH RETURN VALUES +The +.BR libkeccak_zerocopy_update () +function does not return a value. +.SH ERRORS +The +.BR libkeccak_zerocopy_update () +function cannot fail. +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.PP +It is safe call the +.BR libkeccak_zerocopy_update () +function before the +.BR libkeccak_update (3), +.BR libkeccak_fast_update (3) +.BR libkeccak_digest (3) +and +.BR libkeccak_fast_digest (3) +functions with the same +.I state +argument. However, calling the +.BR libkeccak_zerocopy_update () +function after the +.BR libkeccak_update (3) +or +.BR libkeccak_fast_update (3) +functions may cause the message +to be misread. +.SH NOTES +For cSHAKE, the +.BR libkeccak_cshake_initialise (3), +must be called, once, immediately after +state initialisation; before the first +call to the +.BR libkeccak_zerocopy_update () +function. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_cshake_initialise (3), +.BR libkeccak_zerocopy_chunksize (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_digest (3), +.BR libkeccak_digest (3) diff --git a/man7/libkeccak.7 b/man7/libkeccak.7 new file mode 100644 index 0000000..34c9dba --- /dev/null +++ b/man7/libkeccak.7 @@ -0,0 +1,67 @@ +.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_cshake (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 (3), +.BR libkeccak_state_unmarshal (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_zerocopy_update (3), +.BR libkeccak_update (3), +.BR libkeccak_cshake_suffix (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_zerocopy_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 (3), +.BR libkeccak_hmac_unmarshal (3), +.BR libkeccak_hmac_fast_update (3), +.BR libkeccak_hmac_update (3), +.BR libkeccak_hmac_fast_digest (3), +.BR libkeccak_hmac_digest (3) -- cgit v1.2.3-70-g09d2