From 3e1864aa14a33a3c917537a241f6a032cfcacf78 Mon Sep 17 00:00:00 2001 From: Mattias Andrée Date: Sat, 14 Oct 2017 01:01:14 +0200 Subject: General improvements MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Signed-off-by: Mattias Andrée --- .gitignore | 8 +- DEPENDENCIES | 7 +- Makefile | 502 ++++------- benchmark-flags | 116 +++ benchmark.c | 139 +++ config.mk | 13 + doc/info/libkeccak.texinfo | 1069 ----------------------- doc/info/macros.texinfo | 10 - doc/man/libkeccak.7 | 70 -- doc/man/libkeccak_behex_lower.3 | 50 -- doc/man/libkeccak_behex_upper.3 | 50 -- doc/man/libkeccak_degeneralise_spec.3 | 124 --- doc/man/libkeccak_digest.3 | 145 --- doc/man/libkeccak_fast_digest.3 | 146 ---- doc/man/libkeccak_fast_squeeze.3 | 39 - doc/man/libkeccak_fast_update.3 | 96 -- doc/man/libkeccak_generalised_spec_initialise.3 | 46 - doc/man/libkeccak_generalised_sum_fd.3 | 132 --- doc/man/libkeccak_hmac_copy.3 | 44 - doc/man/libkeccak_hmac_create.3 | 53 -- doc/man/libkeccak_hmac_destroy.3 | 43 - doc/man/libkeccak_hmac_digest.3 | 103 --- doc/man/libkeccak_hmac_duplicate.3 | 46 - doc/man/libkeccak_hmac_fast_destroy.3 | 43 - doc/man/libkeccak_hmac_fast_digest.3 | 104 --- doc/man/libkeccak_hmac_fast_free.3 | 51 -- doc/man/libkeccak_hmac_fast_update.3 | 59 -- doc/man/libkeccak_hmac_free.3 | 51 -- doc/man/libkeccak_hmac_initialise.3 | 57 -- doc/man/libkeccak_hmac_marshal.3 | 44 - doc/man/libkeccak_hmac_marshal_size.3 | 36 - doc/man/libkeccak_hmac_reset.3 | 51 -- doc/man/libkeccak_hmac_set_key.3 | 41 - doc/man/libkeccak_hmac_unmarshal.3 | 39 - doc/man/libkeccak_hmac_unmarshal_skip.3 | 40 - doc/man/libkeccak_hmac_update.3 | 56 -- doc/man/libkeccak_hmac_wipe.3 | 36 - doc/man/libkeccak_keccaksum_fd.3 | 119 --- doc/man/libkeccak_rawshakesum_fd.3 | 115 --- doc/man/libkeccak_sha3sum_fd.3 | 111 --- doc/man/libkeccak_shakesum_fd.3 | 115 --- doc/man/libkeccak_simple_squeeze.3 | 38 - doc/man/libkeccak_spec_check.3 | 95 -- doc/man/libkeccak_spec_rawshake.3 | 53 -- doc/man/libkeccak_spec_sha3.3 | 51 -- doc/man/libkeccak_spec_shake.3 | 52 -- doc/man/libkeccak_squeeze.3 | 48 - doc/man/libkeccak_state_copy.3 | 44 - doc/man/libkeccak_state_create.3 | 46 - doc/man/libkeccak_state_destroy.3 | 43 - doc/man/libkeccak_state_duplicate.3 | 46 - doc/man/libkeccak_state_fast_destroy.3 | 43 - doc/man/libkeccak_state_fast_free.3 | 51 -- doc/man/libkeccak_state_free.3 | 51 -- doc/man/libkeccak_state_initialise.3 | 60 -- doc/man/libkeccak_state_marshal.3 | 41 - doc/man/libkeccak_state_marshal_size.3 | 36 - doc/man/libkeccak_state_reset.3 | 37 - doc/man/libkeccak_state_unmarshal.3 | 39 - doc/man/libkeccak_state_unmarshal_skip.3 | 40 - doc/man/libkeccak_state_wipe.3 | 37 - doc/man/libkeccak_state_wipe_message.3 | 35 - doc/man/libkeccak_state_wipe_sponge.3 | 35 - doc/man/libkeccak_unhex.3 | 53 -- doc/man/libkeccak_update.3 | 95 -- libkeccak.h | 13 + libkeccak.texinfo | 403 +++++++++ libkeccak/digest.c | 596 +++++++++++++ libkeccak/digest.h | 100 +++ libkeccak/files.c | 57 ++ libkeccak/files.h | 115 +++ libkeccak/generalised-spec.c | 111 +++ libkeccak/generalised-spec.h | 142 +++ libkeccak/hex.c | 65 ++ libkeccak/hex.h | 44 + libkeccak/internal.h | 26 + libkeccak/mac/hmac.c | 418 +++++++++ libkeccak/mac/hmac.h | 393 +++++++++ libkeccak/spec.h | 177 ++++ libkeccak/state.c | 175 ++++ libkeccak/state.h | 295 +++++++ man/libkeccak.7 | 70 ++ man/libkeccak_behex_lower.3 | 50 ++ man/libkeccak_behex_upper.3 | 50 ++ man/libkeccak_degeneralise_spec.3 | 124 +++ man/libkeccak_digest.3 | 145 +++ man/libkeccak_fast_digest.3 | 146 ++++ man/libkeccak_fast_squeeze.3 | 39 + man/libkeccak_fast_update.3 | 96 ++ man/libkeccak_generalised_spec_initialise.3 | 46 + man/libkeccak_generalised_sum_fd.3 | 132 +++ man/libkeccak_hmac_copy.3 | 44 + man/libkeccak_hmac_create.3 | 53 ++ man/libkeccak_hmac_destroy.3 | 43 + man/libkeccak_hmac_digest.3 | 103 +++ man/libkeccak_hmac_duplicate.3 | 46 + man/libkeccak_hmac_fast_destroy.3 | 43 + man/libkeccak_hmac_fast_digest.3 | 104 +++ man/libkeccak_hmac_fast_free.3 | 51 ++ man/libkeccak_hmac_fast_update.3 | 59 ++ man/libkeccak_hmac_free.3 | 51 ++ man/libkeccak_hmac_initialise.3 | 57 ++ man/libkeccak_hmac_marshal.3 | 44 + man/libkeccak_hmac_marshal_size.3 | 36 + man/libkeccak_hmac_reset.3 | 51 ++ man/libkeccak_hmac_set_key.3 | 41 + man/libkeccak_hmac_unmarshal.3 | 39 + man/libkeccak_hmac_unmarshal_skip.3 | 40 + man/libkeccak_hmac_update.3 | 56 ++ man/libkeccak_hmac_wipe.3 | 36 + man/libkeccak_keccaksum_fd.3 | 119 +++ man/libkeccak_rawshakesum_fd.3 | 115 +++ man/libkeccak_sha3sum_fd.3 | 111 +++ man/libkeccak_shakesum_fd.3 | 115 +++ man/libkeccak_simple_squeeze.3 | 38 + man/libkeccak_spec_check.3 | 95 ++ man/libkeccak_spec_rawshake.3 | 53 ++ man/libkeccak_spec_sha3.3 | 51 ++ man/libkeccak_spec_shake.3 | 52 ++ man/libkeccak_squeeze.3 | 48 + man/libkeccak_state_copy.3 | 44 + man/libkeccak_state_create.3 | 46 + man/libkeccak_state_destroy.3 | 43 + man/libkeccak_state_duplicate.3 | 46 + man/libkeccak_state_fast_destroy.3 | 43 + man/libkeccak_state_fast_free.3 | 51 ++ man/libkeccak_state_free.3 | 51 ++ man/libkeccak_state_initialise.3 | 60 ++ man/libkeccak_state_marshal.3 | 41 + man/libkeccak_state_marshal_size.3 | 36 + man/libkeccak_state_reset.3 | 37 + man/libkeccak_state_unmarshal.3 | 39 + man/libkeccak_state_unmarshal_skip.3 | 40 + man/libkeccak_state_wipe.3 | 37 + man/libkeccak_state_wipe_message.3 | 35 + man/libkeccak_state_wipe_sponge.3 | 35 + man/libkeccak_unhex.3 | 53 ++ man/libkeccak_update.3 | 95 ++ src/benchmark-flags | 116 --- src/benchmark.c | 139 --- src/libkeccak.h | 13 - src/libkeccak/digest.c | 588 ------------- src/libkeccak/digest.h | 100 --- src/libkeccak/files.c | 57 -- src/libkeccak/files.h | 115 --- src/libkeccak/generalised-spec.c | 111 --- src/libkeccak/generalised-spec.h | 142 --- src/libkeccak/hex.c | 65 -- src/libkeccak/hex.h | 44 - src/libkeccak/internal.h | 26 - src/libkeccak/mac/hmac.c | 418 --------- src/libkeccak/mac/hmac.h | 393 --------- src/libkeccak/spec.h | 177 ---- src/libkeccak/state.c | 175 ---- src/libkeccak/state.h | 295 ------- src/test.c | 662 -------------- test.c | 662 ++++++++++++++ 157 files changed, 7770 insertions(+), 8570 deletions(-) create mode 100755 benchmark-flags create mode 100644 benchmark.c create mode 100644 config.mk delete mode 100644 doc/info/libkeccak.texinfo delete mode 100644 doc/info/macros.texinfo delete mode 100644 doc/man/libkeccak.7 delete mode 100644 doc/man/libkeccak_behex_lower.3 delete mode 100644 doc/man/libkeccak_behex_upper.3 delete mode 100644 doc/man/libkeccak_degeneralise_spec.3 delete mode 100644 doc/man/libkeccak_digest.3 delete mode 100644 doc/man/libkeccak_fast_digest.3 delete mode 100644 doc/man/libkeccak_fast_squeeze.3 delete mode 100644 doc/man/libkeccak_fast_update.3 delete mode 100644 doc/man/libkeccak_generalised_spec_initialise.3 delete mode 100644 doc/man/libkeccak_generalised_sum_fd.3 delete mode 100644 doc/man/libkeccak_hmac_copy.3 delete mode 100644 doc/man/libkeccak_hmac_create.3 delete mode 100644 doc/man/libkeccak_hmac_destroy.3 delete mode 100644 doc/man/libkeccak_hmac_digest.3 delete mode 100644 doc/man/libkeccak_hmac_duplicate.3 delete mode 100644 doc/man/libkeccak_hmac_fast_destroy.3 delete mode 100644 doc/man/libkeccak_hmac_fast_digest.3 delete mode 100644 doc/man/libkeccak_hmac_fast_free.3 delete mode 100644 doc/man/libkeccak_hmac_fast_update.3 delete mode 100644 doc/man/libkeccak_hmac_free.3 delete mode 100644 doc/man/libkeccak_hmac_initialise.3 delete mode 100644 doc/man/libkeccak_hmac_marshal.3 delete mode 100644 doc/man/libkeccak_hmac_marshal_size.3 delete mode 100644 doc/man/libkeccak_hmac_reset.3 delete mode 100644 doc/man/libkeccak_hmac_set_key.3 delete mode 100644 doc/man/libkeccak_hmac_unmarshal.3 delete mode 100644 doc/man/libkeccak_hmac_unmarshal_skip.3 delete mode 100644 doc/man/libkeccak_hmac_update.3 delete mode 100644 doc/man/libkeccak_hmac_wipe.3 delete mode 100644 doc/man/libkeccak_keccaksum_fd.3 delete mode 100644 doc/man/libkeccak_rawshakesum_fd.3 delete mode 100644 doc/man/libkeccak_sha3sum_fd.3 delete mode 100644 doc/man/libkeccak_shakesum_fd.3 delete mode 100644 doc/man/libkeccak_simple_squeeze.3 delete mode 100644 doc/man/libkeccak_spec_check.3 delete mode 100644 doc/man/libkeccak_spec_rawshake.3 delete mode 100644 doc/man/libkeccak_spec_sha3.3 delete mode 100644 doc/man/libkeccak_spec_shake.3 delete mode 100644 doc/man/libkeccak_squeeze.3 delete mode 100644 doc/man/libkeccak_state_copy.3 delete mode 100644 doc/man/libkeccak_state_create.3 delete mode 100644 doc/man/libkeccak_state_destroy.3 delete mode 100644 doc/man/libkeccak_state_duplicate.3 delete mode 100644 doc/man/libkeccak_state_fast_destroy.3 delete mode 100644 doc/man/libkeccak_state_fast_free.3 delete mode 100644 doc/man/libkeccak_state_free.3 delete mode 100644 doc/man/libkeccak_state_initialise.3 delete mode 100644 doc/man/libkeccak_state_marshal.3 delete mode 100644 doc/man/libkeccak_state_marshal_size.3 delete mode 100644 doc/man/libkeccak_state_reset.3 delete mode 100644 doc/man/libkeccak_state_unmarshal.3 delete mode 100644 doc/man/libkeccak_state_unmarshal_skip.3 delete mode 100644 doc/man/libkeccak_state_wipe.3 delete mode 100644 doc/man/libkeccak_state_wipe_message.3 delete mode 100644 doc/man/libkeccak_state_wipe_sponge.3 delete mode 100644 doc/man/libkeccak_unhex.3 delete mode 100644 doc/man/libkeccak_update.3 create mode 100644 libkeccak.h create mode 100644 libkeccak.texinfo create mode 100644 libkeccak/digest.c create mode 100644 libkeccak/digest.h create mode 100644 libkeccak/files.c create mode 100644 libkeccak/files.h create mode 100644 libkeccak/generalised-spec.c create mode 100644 libkeccak/generalised-spec.h create mode 100644 libkeccak/hex.c create mode 100644 libkeccak/hex.h create mode 100644 libkeccak/internal.h create mode 100644 libkeccak/mac/hmac.c create mode 100644 libkeccak/mac/hmac.h create mode 100644 libkeccak/spec.h create mode 100644 libkeccak/state.c create mode 100644 libkeccak/state.h create mode 100644 man/libkeccak.7 create mode 100644 man/libkeccak_behex_lower.3 create mode 100644 man/libkeccak_behex_upper.3 create mode 100644 man/libkeccak_degeneralise_spec.3 create mode 100644 man/libkeccak_digest.3 create mode 100644 man/libkeccak_fast_digest.3 create mode 100644 man/libkeccak_fast_squeeze.3 create mode 100644 man/libkeccak_fast_update.3 create mode 100644 man/libkeccak_generalised_spec_initialise.3 create mode 100644 man/libkeccak_generalised_sum_fd.3 create mode 100644 man/libkeccak_hmac_copy.3 create mode 100644 man/libkeccak_hmac_create.3 create mode 100644 man/libkeccak_hmac_destroy.3 create mode 100644 man/libkeccak_hmac_digest.3 create mode 100644 man/libkeccak_hmac_duplicate.3 create mode 100644 man/libkeccak_hmac_fast_destroy.3 create mode 100644 man/libkeccak_hmac_fast_digest.3 create mode 100644 man/libkeccak_hmac_fast_free.3 create mode 100644 man/libkeccak_hmac_fast_update.3 create mode 100644 man/libkeccak_hmac_free.3 create mode 100644 man/libkeccak_hmac_initialise.3 create mode 100644 man/libkeccak_hmac_marshal.3 create mode 100644 man/libkeccak_hmac_marshal_size.3 create mode 100644 man/libkeccak_hmac_reset.3 create mode 100644 man/libkeccak_hmac_set_key.3 create mode 100644 man/libkeccak_hmac_unmarshal.3 create mode 100644 man/libkeccak_hmac_unmarshal_skip.3 create mode 100644 man/libkeccak_hmac_update.3 create mode 100644 man/libkeccak_hmac_wipe.3 create mode 100644 man/libkeccak_keccaksum_fd.3 create mode 100644 man/libkeccak_rawshakesum_fd.3 create mode 100644 man/libkeccak_sha3sum_fd.3 create mode 100644 man/libkeccak_shakesum_fd.3 create mode 100644 man/libkeccak_simple_squeeze.3 create mode 100644 man/libkeccak_spec_check.3 create mode 100644 man/libkeccak_spec_rawshake.3 create mode 100644 man/libkeccak_spec_sha3.3 create mode 100644 man/libkeccak_spec_shake.3 create mode 100644 man/libkeccak_squeeze.3 create mode 100644 man/libkeccak_state_copy.3 create mode 100644 man/libkeccak_state_create.3 create mode 100644 man/libkeccak_state_destroy.3 create mode 100644 man/libkeccak_state_duplicate.3 create mode 100644 man/libkeccak_state_fast_destroy.3 create mode 100644 man/libkeccak_state_fast_free.3 create mode 100644 man/libkeccak_state_free.3 create mode 100644 man/libkeccak_state_initialise.3 create mode 100644 man/libkeccak_state_marshal.3 create mode 100644 man/libkeccak_state_marshal_size.3 create mode 100644 man/libkeccak_state_reset.3 create mode 100644 man/libkeccak_state_unmarshal.3 create mode 100644 man/libkeccak_state_unmarshal_skip.3 create mode 100644 man/libkeccak_state_wipe.3 create mode 100644 man/libkeccak_state_wipe_message.3 create mode 100644 man/libkeccak_state_wipe_sponge.3 create mode 100644 man/libkeccak_unhex.3 create mode 100644 man/libkeccak_update.3 delete mode 100755 src/benchmark-flags delete mode 100644 src/benchmark.c delete mode 100644 src/libkeccak.h delete mode 100644 src/libkeccak/digest.c delete mode 100644 src/libkeccak/digest.h delete mode 100644 src/libkeccak/files.c delete mode 100644 src/libkeccak/files.h delete mode 100644 src/libkeccak/generalised-spec.c delete mode 100644 src/libkeccak/generalised-spec.h delete mode 100644 src/libkeccak/hex.c delete mode 100644 src/libkeccak/hex.h delete mode 100644 src/libkeccak/internal.h delete mode 100644 src/libkeccak/mac/hmac.c delete mode 100644 src/libkeccak/mac/hmac.h delete mode 100644 src/libkeccak/spec.h delete mode 100644 src/libkeccak/state.c delete mode 100644 src/libkeccak/state.h delete mode 100644 src/test.c create mode 100644 test.c diff --git a/.gitignore b/.gitignore index 292c1b2..e98a781 100644 --- a/.gitignore +++ b/.gitignore @@ -1,15 +1,19 @@ *~ *\#* -bin/ -obj/ *.o *.out *.so +*.so.* *.su *.gch *.a +*.dylib +*.dylib.* *.info *.pdf *.ps *.dvi *.test +/benchmark +/test +/benchfile diff --git a/DEPENDENCIES b/DEPENDENCIES index 87e6858..5cd97da 100644 --- a/DEPENDENCIES +++ b/DEPENDENCIES @@ -6,7 +6,7 @@ RUNTIME DEPENDENCIES: BUILD DEPENDENCIES: libc - gcc + c99 make coreutils binutils @@ -26,12 +26,11 @@ BENCHMARK DEPENDENCIES: make coreutils median - grep (only needed for src/benchmark-flags) - sed (only needed for src/benchmark-flags) + grep (only needed for ./benchmark-flags) + sed (only needed for ./benchmark-flags) INSTALL DEPENDENCIES: make coreutils - diff --git a/Makefile b/Makefile index 74a95f0..43cc089 100644 --- a/Makefile +++ b/Makefile @@ -1,39 +1,16 @@ -# Copying and distribution of this file, with or without modification, -# are permitted in any medium without royalty provided the copyright -# notice and this notice are preserved. This file is offered as-is, -# without any warranty. - - -# The package path prefix, if you want to install to another root, set DESTDIR to that root. -PREFIX = /usr -# The library path excluding prefix. -LIB = /lib -# The library header path excluding prefix. -INCLUDE = /include -# The resource path excluding prefix. -DATA = /share -# The library path including prefix. -LIBDIR = $(PREFIX)$(LIB) -# The library header including prefix. -INCLUDEDIR = $(PREFIX)$(INCLUDE) -# The resource path including prefix. -DATADIR = $(PREFIX)$(DATA) -# The generic documentation path including prefix. -DOCDIR = $(DATADIR)/doc -# The info manual documentation path including prefix. -INFODIR = $(DATADIR)/info -# The man pages path including prefix. -MANDIR = $(DATADIR)/man -# The section 3 man pages path including prefix. -MAN3DIR = $(MANDIR)/man3 -# The section 7 man pages path including prefix. -MAN7DIR = $(MANDIR)/man7 -# The license base path including prefix. -LICENSEDIR = $(DATADIR)/licenses - -# The name of the package as it should be installed. -PKGNAME = libkeccak +.NONPOSIX: +CONFIGFILE = config.mk + + +# for Linux +LIBEXT = so +LIBFLAGS = -shared -Wl,-soname,libkeccak.$(LIBEXT).$(LIB_MAJOR) +# for Mac OS +# LIBEXT = dylib +# LIBFLAGS = -dynamiclib + +include $(CONFIGFILE) # The version of the library. @@ -43,313 +20,188 @@ LIB_VERSION = $(LIB_MAJOR).$(LIB_MINOR) -WARN = -Wall -Wextra -pedantic -Wdouble-promotion -Wformat=2 -Winit-self -Wmissing-include-dirs \ - -Wtrampolines -Wfloat-equal -Wshadow -Wmissing-prototypes -Wmissing-declarations \ - -Wredundant-decls -Wnested-externs -Winline -Wno-variadic-macros -Wswitch-default \ - -Wpadded -Wsync-nand -Wunsafe-loop-optimizations -Wcast-align -Wstrict-overflow \ - -Wdeclaration-after-statement -Wundef -Wbad-function-cast -Wcast-qual -Wwrite-strings \ - -Wlogical-op -Waggregate-return -Wstrict-prototypes -Wold-style-definition -Wpacked \ - -Wvector-operation-performance -Wunsuffixed-float-constants -Wsuggest-attribute=const \ - -Wsuggest-attribute=noreturn -Wsuggest-attribute=pure -Wsuggest-attribute=format \ - -Wnormalized=nfkc - -# These have not been extensively tested but appear to: -# * Produce produce false warnings -# * Slowdown the library's performance -# -flto -flto-compression-level -flto-partition={1to1,balanced,mix,none} -flto-report -flto-report-wpa -fwpa -COPTIMISE = -falign-functions=0 -fkeep-inline-functions -fmerge-all-constants -Ofast -LDOPTIMISE = - -FLAGS = -std=gnu99 $(WARN) +OBJ =\ + libkeccak/digest.o\ + libkeccak/files.o\ + libkeccak/generalised-spec.o\ + libkeccak/hex.o\ + libkeccak/state.o\ + libkeccak/mac/hmac.o - -LIB_OBJ = digest files generalised-spec hex state mac/hmac +HDR =\ + libkeccak.h\ + libkeccak/digest.h\ + libkeccak/files.h\ + libkeccak/generalised-spec.h\ + libkeccak/hex.h\ + libkeccak/spec.h\ + libkeccak/state.h\ + libkeccak/internal.h\ + libkeccak/mac/hmac.h MAN3 =\ - libkeccak_behex_lower\ - libkeccak_behex_upper\ - libkeccak_degeneralise_spec\ - libkeccak_digest\ - libkeccak_fast_digest\ - libkeccak_fast_squeeze\ - libkeccak_fast_update\ - libkeccak_generalised_spec_initialise\ - libkeccak_generalised_sum_fd\ - libkeccak_hmac_copy\ - libkeccak_hmac_create\ - libkeccak_hmac_destroy\ - libkeccak_hmac_digest\ - libkeccak_hmac_duplicate\ - libkeccak_hmac_fast_destroy\ - libkeccak_hmac_fast_digest\ - libkeccak_hmac_fast_free\ - libkeccak_hmac_fast_update\ - libkeccak_hmac_free\ - libkeccak_hmac_initialise\ - libkeccak_hmac_marshal\ - libkeccak_hmac_marshal_size\ - libkeccak_hmac_reset\ - libkeccak_hmac_set_key\ - libkeccak_hmac_unmarshal\ - libkeccak_hmac_unmarshal_skip\ - libkeccak_hmac_update\ - libkeccak_hmac_wipe\ - libkeccak_keccaksum_fd\ - libkeccak_rawshakesum_fd\ - libkeccak_sha3sum_fd\ - libkeccak_shakesum_fd\ - libkeccak_simple_squeeze\ - libkeccak_spec_check\ - libkeccak_spec_rawshake\ - libkeccak_spec_sha3\ - libkeccak_spec_shake\ - libkeccak_squeeze\ - libkeccak_state_copy\ - libkeccak_state_create\ - libkeccak_state_destroy\ - libkeccak_state_duplicate\ - libkeccak_state_fast_destroy\ - libkeccak_state_fast_free\ - libkeccak_state_free\ - libkeccak_state_initialise\ - libkeccak_state_marshal\ - libkeccak_state_marshal_size\ - libkeccak_state_reset\ - libkeccak_state_unmarshal\ - libkeccak_state_unmarshal_skip\ - libkeccak_state_wipe\ - libkeccak_state_wipe_message\ - libkeccak_state_wipe_sponge\ - libkeccak_unhex\ - libkeccak_update - - -.PHONY: default -default: lib test info - -.PHONY: all -all: lib test benchmark doc - - -.PHONY: lib -lib: so a - - -.PHONY: so -so: bin/libkeccak.so.$(LIB_VERSION) bin/libkeccak.so.$(LIB_MAJOR) bin/libkeccak.so - -obj/libkeccak/%.o: src/libkeccak/%.c src/libkeccak.h src/libkeccak/*.h src/libkeccak/*/*.h - @mkdir -p $$(dirname $@) - $(CC) $(FLAGS) $(COPTIMISE) -fPIC -c -o $@ $< $(CFLAGS) $(CPPFLAGS) - -bin/libkeccak.so.$(LIB_VERSION): $(foreach O,$(LIB_OBJ),obj/libkeccak/$(O).o) - @mkdir -p bin - $(CC) $(FLAGS) $(LDOPTIMISE) -shared -Wl,-soname,libkeccak.so.$(LIB_MAJOR) -o $@ $^ $(LDFLAGS) - -bin/libkeccak.so.$(LIB_MAJOR): - @mkdir -p bin - ln -sf libkeccak.so.$(LIB_VERSION) $@ - -bin/libkeccak.so: - @mkdir -p bin - ln -sf libkeccak.so.$(LIB_VERSION) $@ - - -.PHONY: a -a: bin/libkeccak.a - -bin/libkeccak.a: $(foreach O,$(LIB_OBJ),obj/libkeccak/$(O).o) - @mkdir -p bin - ar rcs $@ $^ - - -.PHONY: test -test: bin/test - -bin/test: obj/test.o bin/libkeccak.so bin/libkeccak.so.$(LIB_MAJOR) bin/libkeccak.so.$(LIB_VERSION) - $(CC) $(FLAGS) -o $@ $< -Lbin -lkeccak $(LDFLAGS) - -obj/test.o: src/test.c src/libkeccak/*.h src/libkeccak.h - @mkdir -p obj - $(CC) $(FLAGS) -Isrc -O3 -c -o $@ $< $(CFLAGS) $(CPPFLAGS) - - -.PHONY: benchmark -benchmark: bin/benchmark - -bin/benchmark: obj/benchmark.o bin/libkeccak.so bin/libkeccak.so.$(LIB_MAJOR) bin/libkeccak.so.$(LIB_VERSION) - $(CC) $(FLAGS) -o $@ $< -Lbin -lkeccak $(LDFLAGS) - -obj/benchmark.o: src/benchmark.c src/libkeccak/*.h src/libkeccak.h - @mkdir -p obj - $(CC) $(FLAGS) -Isrc -O3 -c -o $@ $< $(CFLAGS) $(CPPFLAGS) - - -.PHONY: doc -doc: info pdf ps dvi - -.PHONY: info -info: bin/libkeccak.info - -.PHONY: pdf -pdf: bin/libkeccak.pdf - -.PHONY: ps -ps: bin/libkeccak.ps - -.PHONY: dvi -dvi: bin/libkeccak.dvi - - -bin/%.info: doc/info/%.texinfo doc/info/*.texinfo - @mkdir -p bin - $(MAKEINFO) $(TEXIFLAGS) $< - mv $*.info bin - -bin/%.pdf: doc/info/%.texinfo doc/info/*.texinfo + libkeccak_behex_lower.3\ + libkeccak_behex_upper.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_marshal_size.3\ + libkeccak_hmac_reset.3\ + libkeccak_hmac_set_key.3\ + libkeccak_hmac_unmarshal.3\ + libkeccak_hmac_unmarshal_skip.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_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_marshal_size.3\ + libkeccak_state_reset.3\ + libkeccak_state_unmarshal.3\ + libkeccak_state_unmarshal_skip.3\ + libkeccak_state_wipe.3\ + libkeccak_state_wipe_message.3\ + libkeccak_state_wipe_sponge.3\ + libkeccak_unhex.3\ + libkeccak_update.3 + +MAN7 =\ + libkeccak_update.7 + + +all: libkeccak.a libkeccak.$(LIBEXT) test benchmark + +$(OBJ): $(HDR) +.c.o: + $(CC) -fPIC -c -o $@ $< $(CFLAGS) $(CPPFLAGS) + +libkeccak.$(LIBEXT): $(OBJ) + $(CC) -shared -Wl,-soname,libkeccak.$(LIBEXT).$(LIB_MAJOR) -o $@ $^ $(LDFLAGS) + +libkeccak.a: $(OBJ) + $(AR) rc $@ $? + $(AR) -s $@ + + +test: test.o libkeccak.a + $(CC) $(FLAGS) -o $@ $^ $(LDFLAGS) + +test.o: test.c $(HDR) + $(CC) $(FLAGS) -O3 -c -o $@ test.c $(CFLAGS) $(CPPFLAGS) + +benchmark: benchmark.o libkeccak.a + $(CC) $(FLAGS) -o $@ $^ $(LDFLAGS) + +benchmark.o: benchmark.c $(HDR) + $(CC) $(FLAGS) -O3 -c -o $@ benchmark.c $(CFLAGS) $(CPPFLAGS) + + +info: libkeccak.info +libkeccak.info: libkeccak.texinfo + $(MAKEINFO) $(TEXIFLAGS) libkeccak.texinfo + +pdf: libkeccak.pdf +libkeccak.pdf: libkeccak.texinfo @! test -d obj/pdf || rm -rf obj/pdf - @mkdir -p obj/pdf bin - cd obj/pdf && texi2pdf $(TEXIFLAGS) ../../$< < /dev/null - mv obj/pdf/$*.pdf $@ + @mkdir -p obj/pdf + cd obj/pdf && texi2pdf $(TEXIFLAGS) ../../libkeccak.texinfo < /dev/null + mv obj/pdf/$@ $@ -bin/%.dvi: doc/info/%.texinfo doc/info/*.texinfo +dvi: libkeccak.dvi +libkeccak.dvi: libkeccak.texinfo @! test -d obj/dvi || rm -rf obj/dvi - @mkdir -p obj/dvi bin - cd obj/dvi && $(TEXI2DVI) $(TEXIFLAGS) ../../$< < /dev/null - mv obj/dvi/$*.dvi $@ + @mkdir -p obj/dvi + cd obj/dvi && $(TEXI2DVI) $(TEXIFLAGS) ../../libkeccak.texinfo < /dev/null + mv obj/dvi/$@ $@ -bin/%.ps: doc/info/%.texinfo doc/info/*.texinfo +ps: libkeccak.ps +libkeccak.ps: libkeccak.texinfo @! test -d obj/ps || rm -rf obj/ps - @mkdir -p obj/ps bin - cd obj/ps && texi2pdf $(TEXIFLAGS) --ps ../../$< < /dev/null - mv obj/ps/$*.ps $@ - + @mkdir -p obj/ps + cd obj/ps && texi2pdf $(TEXIFLAGS) --ps ../../libkeccak.texinfo < /dev/null + mv obj/ps/$@ $@ -.PHONY: check -check: bin/test bin/libkeccak.so bin/libkeccak.so.$(LIB_MAJOR) bin/libkeccak.so.$(LIB_VERSION) +check: test @test $$(sha256sum .testfile | cut -d ' ' -f 1) = \ e21d814d21ca269246849cc105faec1a71ac7d1cdb1a86023254f49d51b47231 || \ ( echo 'The file .testfile is incorrect, test will fail!' ; false ) - env LD_LIBRARY_PATH=bin valgrind --leak-check=full bin/test - test $$(env LD_LIBRARY_PATH=bin valgrind bin/test 2>&1 >/dev/null | wc -l) = 14 + valgrind --leak-check=full ./test + test $$(valgrind ./test 2>&1 >/dev/null | wc -l) = 14 # Using valgrind 3.10.0, its output to standard error should consist of 14 lines, # the test itself never prints to standard error. +benchfile: + dd if=/dev/urandom bs=1000 count=50 > $@ + +run-benchmark: benchmark benchfile + for i in $$(seq 7) ; do ./benchmark ; done | median + +install: libkeccak.$(LIBEXT) libkeccak.a + mkdir -p -- "$(DESTDIR)$(PREFIX)/lib" + cp -- libkeccak.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBEXT).$(LIB_VERSION)" + ln -sf -- libkeccak.$(LIBEXT).$(LIB_VERSION) "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBEXT).$(LIB_MAJOR)" + ln -sf -- libkeccak.$(LIBEXT).$(LIB_VERSION) "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBEXT)" + cp -- libkeccak.a "$(DESTDIR)$(PREFIX)/lib/libkeccak.a" + mkdir -p -- "$(DESTDIR)$(PREFIX)/include/libkeccak/mac" + for f in $(HDR); do cp -- "$$f" "$(DESTDIR)$(PREFIX)/include/$$f" || exit 1; done + mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3" + mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7" + cd man && cp -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3" + cd man && cp -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7" + mkdir -p -- "$(DESTDIR)$(PREFIX)/share/licenses/libkeccak" + cp -- LICENSE "$(DESTDIR)$(PREFIX)/share/licenses/libkeccak/" -.PHONY: run-benchmark -run-benchmark: bin/benchmark bin/libkeccak.so bin/libkeccak.so.$(LIB_MAJOR) bin/libkeccak.so.$(LIB_VERSION) - for i in $$(seq 7) ; do env LD_LIBRARY_PATH=bin bin/benchmark ; done | median - - - -.PHONY: install -install: install-base install-info install-man - -.PHONY: install-all -install-all: install-base install-doc - -.PHONY: install-base -install-base: install-lib install-copyright - -.PHONY: install-lib -install-lib: install-headers install-dynamic-lib install-static-lib - -.PHONY: install-headers -install-headers: - install -dm755 -- "$(DESTDIR)$(INCLUDEDIR)" - install -dm755 -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak" - install -dm755 -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/mac" - install -m644 -- src/libkeccak.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak.h" - install -m644 -- src/libkeccak/digest.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/digest.h" - install -m644 -- src/libkeccak/files.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/files.h" - install -m644 -- src/libkeccak/generalised-spec.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/generalised-spec.h" - install -m644 -- src/libkeccak/hex.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/hex.h" - install -m644 -- src/libkeccak/spec.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/spec.h" - install -m644 -- src/libkeccak/state.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/state.h" - install -m644 -- src/libkeccak/internal.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/internal.h" - install -m644 -- src/libkeccak/mac/hmac.h "$(DESTDIR)$(INCLUDEDIR)/libkeccak/mac/hmac.h" - -.PHONY: install-dynamic-lib -install-dynamic-lib: bin/libkeccak.so.$(LIB_VERSION) - install -dm755 -- "$(DESTDIR)$(LIBDIR)" - install -m755 -- bin/libkeccak.so.$(LIB_VERSION) "$(DESTDIR)$(LIBDIR)/libkeccak.so.$(LIB_VERSION)" - ln -sf -- libkeccak.so.$(LIB_VERSION) "$(DESTDIR)$(LIBDIR)/libkeccak.so.$(LIB_MAJOR)" - ln -sf -- libkeccak.so.$(LIB_VERSION) "$(DESTDIR)$(LIBDIR)/libkeccak.so" - -.PHONY: install-static-lib -install-static-lib: bin/libkeccak.a - install -dm755 -- "$(DESTDIR)$(LIBDIR)" - install -m644 -- bin/libkeccak.a "$(DESTDIR)$(LIBDIR)/libkeccak.a" - -.PHONY: install-copyright -install-copyright: install-license - -.PHONY: install-license -install-license: - install -dm755 -- "$(DESTDIR)$(LICENSEDIR)/$(PKGNAME)" - install -m644 -- LICENSE "$(DESTDIR)$(LICENSEDIR)/$(PKGNAME)/LICENSE" - -.PHONY: install-doc -install-doc: install-info install-pdf install-ps install-dvi install-man - -.PHONY: install-info -install-info: bin/libkeccak.info - install -dm755 -- "$(DESTDIR)$(INFODIR)" - install -m644 -- $< "$(DESTDIR)$(INFODIR)/libkeccak.info" - -.PHONY: install-pdf -install-pdf: bin/libkeccak.pdf - install -dm755 -- "$(DESTDIR)$(DOCDIR)" - install -m644 -- $< "$(DESTDIR)$(DOCDIR)/libkeccak.pdf" - -.PHONY: install-ps -install-ps: bin/libkeccak.ps - install -dm755 -- "$(DESTDIR)$(DOCDIR)" - install -m644 -- $< "$(DESTDIR)$(DOCDIR)/libkeccak.ps" - -.PHONY: install-dvi -install-dvi: bin/libkeccak.dvi - install -dm755 -- "$(DESTDIR)$(DOCDIR)" - install -m644 -- $< "$(DESTDIR)$(DOCDIR)/libkeccak.dvi" - -.PHONY: install-man -install-man: - install -dm755 -- "$(DESTDIR)$(MAN7DIR)" - install -m644 -- doc/man/libkeccak.7 "$(DESTDIR)$(MAN7DIR)/libkeccak.7" - install -dm755 -- "$(DESTDIR)$(MAN3DIR)" - install -m644 -- $(foreach P,$(MAN3),doc/man/$(P).3) "$(DESTDIR)$(MAN3DIR)" - -.PHONY: uninstall uninstall: - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/digest.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/files.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/generalised-spec.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/hex.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/spec.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/state.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/internal.h" - -rm -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/mac/hmac.h" - -rmdir -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak/mac" - -rmdir -- "$(DESTDIR)$(INCLUDEDIR)/libkeccak" - -rm -- "$(DESTDIR)$(LIBDIR)/libkeccak.so.$(LIB_VERSION)" - -rm -- "$(DESTDIR)$(LIBDIR)/libkeccak.so.$(LIB_MAJOR)" - -rm -- "$(DESTDIR)$(LIBDIR)/libkeccak.so" - -rm -- "$(DESTDIR)$(LIBDIR)/libkeccak.a" - -rm -- "$(DESTDIR)$(INFODIR)/libkeccak.info" - -rm -- "$(DESTDIR)$(DOCDIR)/libkeccak.pdf" - -rm -- "$(DESTDIR)$(DOCDIR)/libkeccak.ps" - -rm -- "$(DESTDIR)$(DOCDIR)/libkeccak.dvi" - -rm -- "$(DESTDIR)$(MAN7DIR)/libkeccak.7" - -rm -- $(foreach P,$(MAN3),"$(DESTDIR)$(MAN3DIR)/$(P).3") - -rm -- "$(DESTDIR)$(LICENSEDIR)/$(PKGNAME)/COPYING" - -rm -- "$(DESTDIR)$(LICENSEDIR)/$(PKGNAME)/LICENSE" - -rmdir -- "$(DESTDIR)$(LICENSEDIR)/$(PKGNAME)" - - - -.PHONY: clean + -rm -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBEXT).$(LIB_VERSION)" + -rm -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBEXT).$(LIB_MAJOR)" + -rm -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.$(LIBEXT)" + -rm -- "$(DESTDIR)$(PREFIX)/lib/libkeccak.a" + -cd "$(DESTDIR)$(PREFIX)/include" && rm -- $(HDR) + -rmdir -- "$(DESTDIR)$(PREFIX)/include/libkeccak/mac" + -rmdir -- "$(DESTDIR)$(PREFIX)/include/libkeccak" + -cd -- "$(DESTDIR)$(MANPREFIX)/man3" && rm -- $(MAN3) + -cd -- "$(DESTDIR)$(MANPREFIX)/man7" && rm -- $(MAN7) + -rm -- "$(DESTDIR)$(PREFIX)/share/licenses/libkeccak/LICENSE" + -rmdir -- "$(DESTDIR)$(PREFIX)/share/licenses/libkeccak" + clean: - -rm -r obj bin + -rm -r -- *.o libkeccak/*.o libkeccak/mac/*.o + -rm -r -- *.su libkeccak/*.su libkeccak/mac/*.su + -rm -- *.info *.pdf *.ps *.dvi *.a libkeccak.$(LIBEXT)* test benchmark benchfile + +.SUFFIXES: .c.o +.PHONY: all info pdf ps dvi check run-benchmark install uninstall clean diff --git a/benchmark-flags b/benchmark-flags new file mode 100755 index 0000000..1168ec0 --- /dev/null +++ b/benchmark-flags @@ -0,0 +1,116 @@ +#!/bin/sh +# See LICENSE file for copyright and license details. + +set -e + +export LD_LIBRARY_PATH=bin +if test "${TRIES}" = ""; then + TRIES=10 +fi + +# List all flags that affect the object files +list_test_flags() { + cat <.benchmark.so.far + +while true; do + exec 3>.benchmarks + + for _try in $(seq ${TRIES}); do + for test_flag in "" ${test_flags}; do + flags="${test_flag} ${base_flags}" + make -B all COPTIMISE="${flags}" CPPFLAGS="${cppflags} $*" + make check + if test "${test_flag}" = ""; then + test_flag=zzz + fi + echo "$(bin/benchmark || echo error) ${test_flag}" >&3 + done + done + + exec 3<&- + + ! grep ^error .benchmarks >/dev/null 2>/dev/null + + good_flag="$(median < .benchmarks | sort -n | cut -d ' ' -f 2 | sed 1q)" + if test "${good_flag}" = zzz || test $pass = 2; then + if test $pass = 1; then + pass=2 + base_flags="$(echo "${base_flags}" | sed -e 's/ -O0//')" + test_flags="-O0 -O1 -O2 -O3 -Ofast -Os" + else + if ! test "${good_flag}" = zzz; then + base_flags="${base_flags} ${good_flag}" + echo "${good_flag}" >&4 + fi + echo + echo + echo "Good flags:" + echo "${base_flags}" + exec 4<&- + exit 0 + fi + else + echo "${good_flag}" >&4 + base_flags="${base_flags} ${good_flag}" + test_flags="$(echo "${test_flags}" | sed -e "s/ ${good_flag} / /")" + fi +done + +# None of these GCC flags affect the object files. +# -faggressive-loop-optimizations -fauto-inc-dec -fbranch-target-load-optimize +# -fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves -fcheck-data-deps +# -fcombine-stack-adjustments -fconserve-stack -fcompare-elim -fcprop-registers +# -fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules -fcx-limited-range -fdce +# -fdelete-null-pointer-checks -fdevirtualize -fdevirtualize-speculatively -fdse +# -fearly-inlining -fipa-sra -ffat-lto-objects -fbranch-probabilities +# -fassociative-math -fforward-propagate -ffunction-sections -fforward-propagate +# -ffast-math -ffinite-math-only -ffloat-store -fgcse -fgcse-after-reload -fgcse-las +# -fgcse-lm -fgraphite-identity -fgcse-sm -fhoist-adjacent-loads -fif-conversion +# -fif-conversion2 -findirect-inlining -finline-functions -finline-functions-called-once +# -finline-small-functions -fipa-cp -fipa-cp-clone -fipa-pta -fipa-profile +# -fipa-pure-const -fipa-reference -fira-hoist-pressure -fira-loop-pressure +# -fno-ira-share-save-slots -fno-ira-share-spill-slots -fisolate-erroneous-paths-dereference +# -fisolate-erroneous-paths-attribute -fivopts -fkeep-static-consts -flive-range-shrinkage +# -floop-block -floop-interchange -floop-strip-mine -floop-nest-optimize +# -floop-parallelize-all -fmodulo-sched -fmodulo-sched-allow-regmoves -fmove-loop-invariants +# -fno-branch-count-reg -fno-defer-pop -fno-function-cse -fno-guess-branch-probability +# -fno-defer-pop -fno-function-cse -fno-guess-branch-probability -fno-inline -fno-math-errno +# -fno-peephole -fno-peephole2 -fno-sched-interblock -fno-sched-spec -fno-signed-zeros +# -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss +# -foptimize-sibling-calls -fpartial-inlining -fpeel-loops -fpredictive-commoning +# -fprefetch-loop-arrays -fprofile-report -fprofile-use -fprofile-values +# -fprofile-reorder-functions -freciprocal-math -free -frename-registers -freorder-blocks +# -frerun-cse-after-loop -freschedule-modulo-scheduled-loops -frounding-math +# -fsched2-use-superblocks -fsched-pressure -fsched-spec-load -fsched-spec-load-dangerous +# -fsched-group-heuristic -fsched-critical-path-heuristic -fsched-spec-insn-heuristic +# -fsched-rank-heuristic -fsched-last-insn-heuristic -fsched-dep-count-heuristic +# -fselective-scheduling -fselective-scheduling2 -fsel-sched-pipelining +# -fsel-sched-pipelining-outer-loops -fshrink-wrap -fsignaling-nans +# -fsingle-precision-constant -fstrict-overflow -fthread-jumps -ftracer -ftree-bit-ccp +# -ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-copyrename -ftree-dce +# -ftree-dominator-opts -ftree-dse -ftree-forwprop -ftree-fre -ftree-loop-if-convert +# -ftree-loop-if-convert-stores -ftree-loop-im -ftree-phiprop -ftree-loop-distribution +# -ftree-loop-distribute-patterns -ftree-loop-ivcanon -ftree-loop-linear +# -ftree-loop-optimize -ftree-loop-vectorize -ftree-pre -ftree-partial-pre -ftree-pta +# -ftree-reassoc -ftree-sink -ftree-slsr -ftree-sra -ftree-vectorize -ftree-vrp +# -funit-at-a-time -funroll-all-loops -funroll-loops -funsafe-loop-optimizations +# -funsafe-math-optimizations -funswitch-loops -fvariable-expansion-in-unroller +# -fvect-cost-model -fvpt -fweb -fprofile-correction -freorder-functions +# -fschedule-insns -fschedule-insns2 -fsplit-ivs-in-unroller -fsplit-wide-types +# -fstrict-aliasing -ftree-coalesce-vars -ftree-copy-prop -ftree-switch-conversion +# -ftree-switch-conversion -ftree-tail-merge -ftree-coalesce-inlined-vars +# -falign-jumps=0 -falign-labels=0 -falign-loops=0 -ftree-parallelize-loops=10 +# -fsched-stalled-insns-dep=0 -fsched-stalled-insns=0 + diff --git a/benchmark.c b/benchmark.c new file mode 100644 index 0000000..20344d9 --- /dev/null +++ b/benchmark.c @@ -0,0 +1,139 @@ +/* See LICENSE file for copyright and license details. */ +#include + +#include +#include +#include +#include +#include + + +#ifndef MESSAGE_FILE +# define MESSAGE_FILE "benchfile" +#endif +#ifndef MESSAGE_LEN +# define MESSAGE_LEN 50000 +#endif + + +#ifndef BITRATE +# define BITRATE 1024 +#endif +#ifndef CAPACITY +# define CAPACITY 576 +#endif +#ifndef OUTPUT +# define OUTPUT 512 +#endif + +#ifndef UPDATE_RUNS +# define UPDATE_RUNS 100 +#endif +#ifndef FAST_SQUEEZE_RUNS +# define FAST_SQUEEZE_RUNS 100 +#endif +#ifndef SLOW_SQUEEZE_RUNS +# define SLOW_SQUEEZE_RUNS 100 +#endif +#ifndef RERUNS +# define RERUNS 50 +#endif + + + +/** + * Benchmark, will print the number of nanoseconds + * spent with hashing algorithms and representation + * conversion from binary to hexadecimal. The latter + * can be compiled out by compiling with -DIGNORE_BEHEXING. + * + * @return Zero on success, 1 on error + */ +int +main(void) +{ + char message[MESSAGE_LEN]; + libkeccak_spec_t spec; + libkeccak_state_t state; + char hashsum[OUTPUT / 8]; +#ifndef IGNORE_BEHEXING + char hexsum[OUTPUT / 8 * 2 + 1]; +#endif + struct timespec start, end; + long i, r; + + /* Fill message with content from the file. */ + int fd; + ssize_t got; + size_t ptr; + if (fd = open(MESSAGE_FILE, O_RDONLY), fd < 0) + return perror("open"), 1; + for (ptr = 0; ptr < MESSAGE_LEN; ptr += (size_t)got) + if (got = read(fd, message, MESSAGE_LEN - ptr), got <= 0) + return perror("read"), close(fd), 1; + close(fd); + + /* Initialise state. */ + spec.bitrate = BITRATE; + spec.capacity = CAPACITY; + spec.output = OUTPUT; + if (libkeccak_state_initialise(&state, &spec)) + return perror("libkeccak_state_initialise"), 1; + + /* Get start-time. */ + if (clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start) < 0) + return perror("clock_gettime"), 1; + + /* Run benchmarking loop. */ + for (r = 0; r < RERUNS; r++) { + /* Updates. */ +#if UPDATE_RUNS > 0 + for (i = 0; i < UPDATE_RUNS; i++) + if (libkeccak_fast_update(&state, message, MESSAGE_LEN) < 0) + return perror("libkeccak_update"), 1; +#endif + + /* Digest. */ + if (libkeccak_fast_digest(&state, NULL, 0, 0, NULL, hashsum) < 0) + return perror("libkeccak_digest"), 1; +#ifndef IGNORE_BEHEXING + libkeccak_behex_lower(hexsum, hashsum, OUTPUT / 8); +#endif + + /* Fast squeezes. */ +#if FAST_SQUEEZE_RUNS > 0 + libkeccak_fast_squeeze(&state, FAST_SQUEEZE_RUNS); +#endif + + /* Slow squeezes. */ +#if SLOW_SQUEEZE_RUNS > 0 + for (i = 0; i < SLOW_SQUEEZE_RUNS; i++) { + libkeccak_squeeze(&state, hashsum); +# ifndef IGNORE_BEHEXING + libkeccak_behex_lower(hexsum, hashsum, OUTPUT / 8); +# endif + } +#endif + } + + /* Get end-time. */ + if (clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end) < 0) + return perror("clock_gettime"), -1; + + /* Print execution-time. */ + end.tv_sec -= start.tv_sec; + end.tv_nsec -= start.tv_nsec; + if (end.tv_nsec < 0) { + end.tv_sec--; + end.tv_nsec += 1000000000L; + } + printf("%03li%09li\n", (long)(end.tv_sec), end.tv_nsec); + + /* Release resources and exit. */ + libkeccak_state_fast_destroy(&state); + return 0; + +#if (UPDATE_RUNS == 0) && (SLOW_SQUEEZE_RUNS == 0) + (void) i; +#endif +} diff --git a/config.mk b/config.mk new file mode 100644 index 0000000..fee0853 --- /dev/null +++ b/config.mk @@ -0,0 +1,13 @@ +PREFIX = /usr +MANPREFIX = $(DATADIR)/man + +# These have not been extensively tested but appear to: +# * Produce produce false warnings +# * Slowdown the library's performance +# -flto -flto-compression-level -flto-partition={1to1,balanced,mix,none} -flto-report -flto-report-wpa -fwpa +CCOPTIMISE = -falign-functions=0 -fkeep-inline-functions -fmerge-all-constants -Ofast +LDOPTIMISE = + +CFLAGS = -std=c99 -Wall -Wextra $(CCOPTIMISE) +CPPFLAGS = -D_DEFAULT_SOURCE -D_BSD_SOURCE -D_XOPEN_SOURCE=700 +LDFLAGS = $(LDOPTIMISE) diff --git a/doc/info/libkeccak.texinfo b/doc/info/libkeccak.texinfo deleted file mode 100644 index 68bf147..0000000 --- a/doc/info/libkeccak.texinfo +++ /dev/null @@ -1,1069 +0,0 @@ -\input texinfo @c -*-texinfo-*- -@c %**start of header -@documentencoding UTF-8 -@include macros.texinfo -@copying -@c -------------------------------------------------------------------------------- -Copyright @copyright{} 2015, 2017 @w{Mattias Andrée @e{maandree@@kth.se}} - -@quotation -Permission to use, copy, modify, and/or distribute this document for any purpose -with or without fee is hereby granted, provided that the above copyright notice -and this permission notice appear in all copies. -@end quotation -@c -------------------------------------------------------------------------------- -@end copying - - -@setfilename libkeccak.info -@settitle libkeccak -- Library for the Keccak-family hash functions -@documentlanguage en_GB -@finalout -@frenchspacing on -@afourpaper - -@c @paragraphindent asis -@c @firstparagraphindent none -@c @exampleindent asis - -@dircategory Libraries -@direntry -* libkeccak: (libkeccak). Library for the Keccak-family hash functions. -@end direntry - -@documentdescription -Developer reference manual for libkeccak, a library -for hashing with Keccak, SHA-3 RawSHAKE and SHAKE, -with support for bit-oriented data. -@end documentdescription -@c %**end of header - - - -@ifnottex -@node Top -@top libkeccak -- Library for the Keccak-family hash functions -@insertcopying -@end ifnottex - -@titlepage -@title libkeccak -@subtitle Library for the Keccak-family hash functions - -@author by Mattias Andrée (maandree) - -@page -@center `Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! …' -@vskip 0pt plus 1filll -@insertcopying -@end titlepage - -@contents - - - -@menu -* Overview:: Brief overview of libkeccak. -* Linking:: How to use libkeccak in your software. -* Selecting hash function:: Selecting and tuning the function. -* State of the hashing:: The structure used to keep track of the hashing process. -* Hashing messages:: Functions used to hash a message. -* Hexadecimal hashes:: Converting between binary and hexadecimal. -* Hashing files:: Functions used to hash entire files. -* Message authentication:: Functions used for message authentication codes. -* Examples:: Examples of how to use libkeccak. - -* Concept index:: Index of concepts. -* Data type index:: Index of data types. -* Function index:: Index of functions. -@end menu - - - -@node Overview -@chapter Overview - -@cpindex Orientation -libkeccak is a free software bit-oriented implementation -of the cryptographic hash function Keccak and its subsets -SHA-3 (Secure Hash Algorithm@tie{}3), RawSHAKE and SHAKE. - -Being bit-oriented means that it supports messages of length -consisting of a non-whole number of bytes. - -@cpindex Uses -Keccak is a generic and tunable cryptographic hash function -that can be used for all customary tasks that required a -cryptographic hash function: -@itemize @bullet{} -@item -Password verification@footnote{Using additional squeezes, but not using iterated hashing.} -@item -Proof-of-work -@item -File and data identification -@item -Data integrity -@item -Pseudorandom number generation@footnote{Although not too random, since entropi is not utilised.} -@item -Key derivation -@end itemize - -libkeccak support secure erasure of sensitive data, -marshalling of hashing state, and indefinite output length. -It also has builting functions for hashing files and -wrapping the hash functions with HMAC@footnote{Although -doing so is unnecessary because the key can securely be -prepended to the message when using Keccak to produce -a message authentication code.}. This library implements -the Keccak algorithm using a lanewise implementation. - -@cpindex Limitations -This implementation is limited to state sizes up to, -and including, 1600 bits. - - - -@node Linking -@chapter Linking - -@cpindex Compiling -libkeccak's API is C standard library independent. This means -that libkeccak does not need to be compiled with the same -C standard library as software using it. However, the header -files contain @code{__attributes__}:s for GCC, if these are -incompatible with your compiler, your should temporarily define -a macro named @code{__attributes__} to remove all attributes. - -@cpindex @command{pkg-config} -@cpindex Linking -Because of libkeccak's simplicity it does not have a pkg-config -file. Instead, you only need to specify the flag @code{-lkeccak} -when linking your binaries. No flags are required during compilation -(of object files.) - -To make libkeccak's API available, include the header file -@file{} in your source files. - - - -@node Selecting hash function -@chapter Selecting hash function - -@cpindex Parameters -@cpindex Tuning -Keccak-based hash functions have three parameters: -@itemize @bullet{} -@item -the bitrate, -@item -the capacity, and -@item -the output size. -@end itemize -@noindent -Selecting these is the first step when using the library. - -@tpindex libkeccak_spec_t -@tpindex struct libkeccak_spec -The structure @code{libkeccak_spec_t} (@code{struct libkeccak_spec}), -is to specify these parameters. For the less tunable functions -SHA-3, RawSHAKE and SHAKE, these values can be set with the functions -@table @code -@item libkeccak_spec_sha3 -@fnindex libkeccak_spec_sha3 -@cpindex SHA-3 -@cpindex Secure Hash Algorithm 3 -Sets the parameters for SHA-3. It has two parameters: -@itemize @bullet{} -@item -Pointer to the @code{libkeccak_spec_t} where the settings shall be stored. -@item -The output size, that is the value appended to the name. -@end itemize - -@item libkeccak_spec_rawshake -@fnindex libkeccak_spec_rawshake -@cpindex RawSHAKE -Sets the parameters for RawSHAKE (or SHAKE). It has three parameters: -@itemize @bullet{} -@item -Pointer to the @code{libkeccak_spec_t} where the settings shall be stored. -@item -The semicapacity, that is the value appended to the name. -@item -The output size. -@end itemize - -@item libkeccak_spec_shake -@fnindex libkeccak_spec_shake -@cpindex SHAKE -Identical to @code{libkeccak_spec_rawshake}. Intended for SHAKE -rather than RawSHAKE. -@end table - -@fnindex libkeccak_spec_check -@cpindex Keccak -For Keccak, these values shall be selected individually by hand. -Once the values have been selected, they can be checked for errors -with the function @code{libkeccak_spec_check}. It takes a pointer -to the specifications as its only parameters and returns zero if -there are no errors. If however there are errors, one of the values, -with somewhat self-explanatory names,@footnote{Their meaning is -documented in the header file @file{}.} will -be returned: -@itemize @bullet{} -@item -@code{LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE} -@item -@code{LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8} -@item -@code{LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE} -@item -@code{LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8} -@item -@code{LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE} -@item -@code{LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE} -@item -@code{LIBKECCAK_SPEC_ERROR_STATE_MOD_25} -@item -@code{LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT} -@item -@code{LIBKECCAK_SPEC_ERROR_WORD_MOD_8} -@end itemize - -@tpindex libkeccak_spec_t -@tpindex struct libkeccak_spec -@code{libkeccak_spec_t}'s members are: -@table @code -@item bitrate -The bitrate, in bits. -@item capacity -The capacity, in bits. -@item output -The output size, in bits. -@end table - -@tpindex libkeccak_generalised_spec_t -@tpindex struct libkeccak_generalised_spec -It is also possible to select some but not all of the parameters. -For this, the structure @code{libkeccak_generalised_spec_t} -(@code{struct libkeccak_generalised_spec}) is used. It extends -@code{libkeccak_spec_t} with two additional parameters -@table @code -@item state_size -The state size, in bits. -@item word_size -The word size, in bits. -@end table - -@fnindex libkeccak_generalised_spec_initialise -By feeding a pointer to a @code{libkeccak_generalised_spec_t}, -to the function @code{libkeccak_generalised_spec_initialise}, -all its members are set to @code{LIBKECCAK_GENERALISED_SPEC_AUTOMATIC}, -a sentinel value that specifies that the parameter shall be -set automatically, to its default that depends on the other -parameters. - -Once the members of a @code{libkeccak_generalised_spec_t} has -been set, it can be converted to a @code{libkeccak_spec_t}, -which is necessary for using the specifications. When doing -so, automatic values will be given a proper value. - -@fnindex libkeccak_degeneralise_spec -To do this, the function @code{libkeccak_degeneralise_spec} -is used. It takes two parameters: -@itemize @bullet{} -@item -Input pointer to the @code{libkeccak_generalised_spec_t}. -@item -Output pointer to a @code{libkeccak_spec_t}. -@end itemize -@noindent -On success, zero is returned, otherwise one of the values, with -somewhat self-explanatory names,@footnote{Their meaning is documented -in the header file @file{}.} will be -returned: -@itemize @bullet{} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8} -@item -@code{LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE} -@end itemize - - - -@node State of the hashing -@chapter State of the hashing - -@tpindex libkeccak_state_t -@tpindex struct libkeccak_state -@cpindex Hashing -@cpindex State -Hashing of a message is done by feeding segments of the -message to functions until all of the message has been -processed, and than the users may repeat the last phase -any number of times. Because functions are called multiple -times, the state of the process need to be stored in -a state structure. The structure used in libkeccak to -keep track of the state is called @code{libkeccak_state_t} -(@code{struct libkeccak_state}). - -@fnindex libkeccak_state_initialise -@cpindex Initialise -Before you can use the functions for hashing a message, -you must allocate a state and initialise it. -To initialise a state, use the function -@code{libkeccak_state_initialise}. Its first argument -should be a pointer to the state variable, that is, -a @code{libkeccak_state_t*}. The second argument should -be a pointer to the specifications, that is, a -@code{const libkeccak_spec_t*}, see @ref{Selecting hash function}. -@code{libkeccak_state_initialise} till return zero -upon successful completion, and otherwise set -@code{errno} to describe the error and return @code{-1}. - -@fnindex libkeccak_state_destroy -@fnindex libkeccak_state_fast_destroy -@fnindex libkeccak_state_wipe -@fnindex libkeccak_state_wipe_sponge -@fnindex libkeccak_state_wipe_message -@cpindex Cleanup -Once done with a state structure, you should release -allocated resources that are stored in the structure. -This can be done either by calling the function -@code{libkeccak_state_destroy} or by calling the function -@code{libkeccak_state_fast_destroy}. These two functions -are almost identical, both takes a pointer to the -state as its only parameter, and neither return a value. -However, @code{libkeccak_state_fast_destroy} will only -release allocations used by the state; @code{libkeccak_state_destroy} -will also securely release all sensitive information -in the state, by calling the function @code{libkeccak_state_wipe}: -the state of the sponge, by calling the function -@code{libkeccak_state_wipe_sponge}, and the message -buffer, by calling the function @code{libkeccak_state_wipe_message}. -@code{libkeccak_state_wipe}, @code{libkeccak_state_wipe_sponge} -and @code{libkeccak_state_wipe_message} takes a -pointer to the state as their only parameter, and -none of them have a return value. - -@fnindex libkeccak_state_reset -@cpindex Reuse -An alternative to destroying a state, you can reset -it if you want to reuse it to hash another message -using the same hashing function specifications. -This is done by calling @code{libkeccak_state_reset} -instead of @code{libkeccak_state_fast_destroy}. -It takes a pointer to the state as its only parameter -and does not return a value. - -@cpindex Initialise -@cpindex Cleanup -@cpindex Allocation -If you want to use dynamic instead of static allocation -for the state, instead of calling @code{malloc} and -@code{free} yourself, libkeccak offers functions that -does this for you: -@table @code -@item libkeccak_state_create -@fnindex libkeccak_state_create -@fnindex libkeccak_state_initialise -Identical to @code{libkeccak_state_initialise}, except -it does have the first parameter, but it has the second -parameter (the specifications). It returns a pointer -to the allocate state upon successful completion, and -returns @code{NULL} on error, in which case, @code{errno} -is set to describe the error. - -@item libkeccak_state_fast_free -@fnindex libkeccak_state_fast_free -@fnindex libkeccak_state_fast_destroy -Identical to @code{libkeccak_state_fast_destroy}, except -it also frees the allocation of the state. - -@item libkeccak_state_free -@fnindex libkeccak_state_free -@fnindex libkeccak_state_destroy -Identical to @code{libkeccak_state_destroy}, except -it also frees the allocation of the state. -@end table - -@cpindex Duplication -@cpindex Allocation -libkeccak also has two functions for copying a state: -@table @code -@item libkeccak_state_copy -@fnindex libkeccak_state_copy -Takes an output pointer to a state as its first parameter, -and a pointer to the state to copy as its second parameter. -The content of the second parameter will be duplicated into -the first parameter. The state passed in the first parameter -must not be initialised, lest you will suffer a memory leak. -The function returns zero upon successful completion, and -on error, sets @code{errno} to describe the error and returns -@code{-1}. - -@item libkeccak_state_duplicate -@fnindex libkeccak_state_duplicate -Identical to @code{libkeccak_state_copy}, except it only -has one parameter, a pointer to the state to copy, and -returns a pointer to a state it has allocated and copied -the state to. On error, @code{errno} is set to describe the -error and @code{NULL} is returned. -@end table - -@cpindex Marshal -@cpindex Serialisation -@cpindex Unmarshal -@cpindex Deserialisation -The library also offers functions for marshalling a state, -which can be useful when implementing programs that can -reexecuted into updated version of itself. -@table @code -@item libkeccak_state_marshal_size -@fnindex libkeccak_state_marshal_size -Takes a pointer to a state to marshal as its only parameter, -and returns the number of bytes required to marshal it. - -@item libkeccak_state_marshal -@fnindex libkeccak_state_marshal -Takes a pointer to a state to marshal as its first parameter, -and the buffer, to where the state shall be marshalled, as -its second parameter. The function will marshal the state -into the buffer and return the number of bytes written, -which will be the same as @code{libkeccak_state_marshal_size} -returns for the state. - -@item libkeccak_state_unmarshal -@fnindex libkeccak_state_unmarshal -Takes an output pointer for the unmarshalled state as its -first parameter, and the buffer where the state is marshalled -as its second parameter. The function will unmarshal the -state from the buffer and store it into the pointer passed -to the first parameter. The function will then return the -number of read bytes, which will be the same as -@code{libkeccak_state_marshal_size} and @code{libkeccak_state_marshal} -returned for the state when it was marshalled, as what they -will return if called again with the unmarshalled function. -On error, @code{errno} is set to describe the error and zero -is returned. - -@item libkeccak_state_unmarshal_skip -@fnindex libkeccak_state_unmarshal_skip -Figures out how many bytes the marshalled state uses, -so that the buffers pointer can be incremented with -this value to skip pass the marshalled state. -@end table - - - -@node Hashing messages -@chapter Hashing messages - -@fnindex libkeccak_update -@fnindex libkeccak_digest -@fnindex libkeccak_fast_update -@fnindex libkeccak_fast_digest -@cpindex Hashing -Once a state has been initialised, a message can be hashed. -To hash a message the functions @code{libkeccak_update} and -@code{libkeccak_digest} are used, or its variants that do -not securely release sensitive information: -@code{libkeccak_fast_update} and @code{libkeccak_fast_digest}, -these are otherwise identical to @code{libkeccak_update} -and @code{libkeccak_fast_update}, respectively. -@table @code -@item libkeccak_update -@fnindex libkeccak_update -@fnindex libkeccak_fast_update -This function shall be called while you do not know that -you have reached the end of the message. It has three -parameters: -@itemize @bullet{} -@item -A pointer to the state. See @ref{State of the hashing}. -@item -The beginning of the chunk of the message to process. -@item -The number of bytes in the message to process. -@end itemize -Note that a part of the message is input, not necessarily -the entire message. The chunks must be input sequentially. -The function returns zero upon success completion. On error, -@code{errno} is set to describe the error and @code{-1} is -returned. The input chunk should not be empty. - -@item libkeccak_digest -@fnindex libkeccak_digest -@fnindex libkeccak_fast_digest -This function shall be called either with the last chunk -of the message, or when all chunks as been input to -@code{libkeccak_update} or @code{libkeccak_fast_update}. -The function's first three parameters are the same as -for @code{libkeccak_update}, however, the chunk may be -@code{NULL} and then length zero if all chunks have -been processed by @code{libkeccak_update} or @code{libkeccak_fast_update}. -However, it also has three additional parameters: -@itemize @bullet{} -@item -The number of bits at the end of the message that -are not covered by the third argument. This enables -messages of non-whole byte length. -@item -A NUL-terminated string of ASCII ones and zeroes, -describing the additional bits to suffix the message; -or @code{NULL} if none. This is used to select between -Keccak, SHA-3, RawSHAKE and SHAKE. Use one of the constants: -@table @asis -@item @code{LIBKECCAK_SHA3_SUFFIX} or @code{"01"} -@cpindex SHA-3 -@cpindex Secure Hash Algorithm 3 -For SHA-3. -@item @code{LIBKECCAK_RAWSHAKE_SUFFIX} or @code{"11"} -@cpindex RawSHAKE -For RawSHAKE. -@item @code{LIBKECCAK_SHAKE_SUFFIX} or @code{"1111"} -@cpindex SHAKE -For SHAKE. -@item @code{NULL} or @code{""} -@cpindex Keccak -For Keccak. -@end table -@item -@cpindex Output size -@cpindex Hash size -@cpindex Size, hash -Output buffer for the hash, in binary. Should be -allocated to fit @code{(state.n + 7) / 8} @w{@code{char}:s}, -where @code{state} is the state variable. Alternatively -it may be @code{NULL}, in which case the hash is not -retrieved. -@end itemize -The function returns zero upon success completion. On error, -@code{errno} is set to describe the error and @code{-1} is -returned. The input chunk should not be empty. -@end table - -@cpindex Key derivation -@cpindex Pseudorandom number generation -@cpindex Random number generation -@cpindex Output, extended -@cpindex Extended output -libkeccak also has three functions for repeating the squeeze -phase. Neither of these function have a return value, and -their first parameter is a pointer to the state. -@table @code -@item libkeccak_simple_squeeze -@fnindex libkeccak_simple_squeeze -Perform a number of additional rounds of @w{@sc{Keccak}--@i{f}}. -The number of rounds is specified in the second parameter. -@item libkeccak_fast_squeeze -@fnindex libkeccak_fast_squeeze -Perform a number of additional rounds of @w{@sc{Keccak}--@i{f}}. -The number will be exactly enough to get a number of additional -digests. The number of digests is specified in the second parameter. -@item libkeccak_squeeze -@fnindex libkeccak_squeeze -Squeeze out another digest. The hash will be stored in the -second parameter, which should be allocated to fit -@code{(state.n + 7) / 8} @w{@code{char}:s}. -@end table - - - -@node Hexadecimal hashes -@chapter Hexadecimal hashes - -@fnindex libkeccak_digest -@fnindex libkeccak_fast_digest -@fnindex libkeccak_squeeze -@cpindex Conversion -@cpindex Binary hash -@cpindex Hexadecimal hash -@cpindex Presentation, hash -@cpindex Hash, presentation -The functions that return hashes: @code{libkeccak_digest}, -@code{libkeccak_fast_digest} and @code{libkeccak_squeeze}, -store the hashes in binary format. However, it must often -preferred to have hashes in hexadecimal, so that they are -human-readable. This library hash two functions for -converting from binary to hexadecimal, and one function -for converting from hexadecimal to binary. Neither of -these functions have a return value. -@table @code -@item libkeccak_behex_lower -@itemx libkeccak_behex_upper -@fnindex libkeccak_behex_lower -@fnindex libkeccak_behex_upper -Convert from binary to hexadecimal. @code{libkeccak_behex_lower} -converts to lowercase hexadecimal, and @code{libkeccak_behex_upper} -converts to uppercase hexadecimal. Their first parameter -is the output buffer for the hexadecimal representation, -which will be NUL-terminated, it should be allocated to -fit @code{2 * n + 1} @w{@code{char}:s}, where @code{n} is -the length of the input hash. The second parameter is -the input hash, in binary. The third, and final, parameter -is the length of the input bash. - -@item libkeccak_unhex -@fnindex libkeccak_unhex -Convert from hexadecimal to binary. Both uppercase and -lowercase, as well as mixed case, is supported as input. -The first parameter is the output buffer for the binary -representation, it should be allocated to fit -@code{strlen(hashsum) / 2} @w{@code{char}:s}, where -@code{hashsum} is the hash in hexadecimal, the input; -this is the number of bytes that will be stored in -the output. The second, and final, parameter is the -hash in hexadecimal, with must be NUL-terminated, -and have an even length. -@end table - - - -@node Hashing files -@chapter Hashing files - -@cpindex Files -@cpindex Hash files -libkeccak provides functions for calculating -hashes of files directly, from a file descriptor. - -@fnindex libkeccak_generalised_sum_fd -The generalised function is named -@code{libkeccak_generalised_sum_fd}. It has -five parameters: -@itemize @bullet{} -@item -The file descriptor. -@item -A pointer to a state variable. Must not be -initalised, lest you will suffer a memory leak. -@item -The specifications for the hashing functions. -@item -The message suffix. -@item -The output buffer for the binary hash. -It must have an allocation size of at least -@code{(spec->output / 8) * sizeof(char)}, -where @code{spec} is the third argument, or -be @code{NULL}. -@end itemize -@code{libkeccak_generalised_sum_fd} returns -zero upon successful completion. On error, -@code{errno} is set to describe the error, -and @code{-1} is returned. - -There are also algorithm specific functions. -@table @code -@item libkeccak_keccaksum_fd -@fnindex libkeccak_keccaksum_fd -This function is used for Keccak without message -suffix. It is identical to @code{libkeccak_generalised_sum_fd} -sans the fourth parameter (the message suffix.) - -@item libkeccak_sha3sum_fd -@fnindex libkeccak_sha3sum_fd -This function is used for SHA-3. It is similar -to @code{libkeccak_generalised_sum_fd}, however -it does not have the fourth parameter, and the -third parameter is simple the the output size. -The output buffer must have and allocation size -of at least @code{(output / 8) * sizeof(char)}, -where @code{output} is the third parameter, or -be @code{NULL}. - -@item libkeccak_rawshakesum_fd -@fnindex libkeccak_rawshakesum_fd -This function is used for RawSHAKE, it is -otherwise identical to @code{libkeccak_sha3sum_fd}, -except it as a parameter for the semicapacity -before the output size, that is to say, as its -third parameter. - -@item libkeccak_shakesum_fd -@fnindex libkeccak_shakesum_fd -This function is used for SHAKE, it is -otherwise identical to @code{libkeccak_rawshakesum_fd}. -@end table - - - -@node Message authentication -@chapter Message authentication - -@cpindex Message authentication code -@cpindex MAC -@cpindex HMAC -@cpindex Keyed-hash message authentication code -libkeccak supports HMAC. Note that secure message -authentication codes can be trivially be created -with Keccak by simple prepending the key to the -message; although it will not be HMAC. This makes -Keccak a good hash function alternative for people -who knows next to nothing about cryptography. - -@tpindex libkeccak_hmac_state_t -@tpindex struct libkeccak_hmac_state -To keep track of the hashing state, the structure -@code{libkeccak_hmac_state_t} (@code{struct libkeccak_hmac_state}) -is used. It has a number of methods analogous to -those for @code{libkeccak_state_t}: -@table @code -@item libkeccak_hmac_initialise -@fnindex libkeccak_hmac_initialise -Has for parameters: pointer to a @code{libkeccak_hmac_state_t} -to initialise, hashing specifications (@code{const libkeccak_spec_t*}), -binary key, and the length of the key. - -@item libkeccak_hmac_create -@fnindex libkeccak_hmac_create -Similar to @code{libkeccak_hmac_initialise}. It does -not have a @code{libkeccak_hmac_state_t*} as an output -parameter, rather it returns one. - -@item libkeccak_hmac_reset -@fnindex libkeccak_hmac_reset -Resets the sponge and the sets the key, by -calling @code{libkeccak_hmac_set_key}. It -has three parameters: pointer to the -@code{libkeccak_hmac_state_t}, the binary key, -and the length of the key. -The key will not be set if the second -argument is @code{NULL}. - -@item libkeccak_hmac_wipe -@fnindex libkeccak_hmac_wipe -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_destroy -@fnindex libkeccak_hmac_fast_destroy -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_destroy -@fnindex libkeccak_hmac_destroy -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_free -@fnindex libkeccak_hmac_fast_free -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_free -@fnindex libkeccak_hmac_free -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_copy -@fnindex libkeccak_hmac_copy -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_duplicate -@fnindex libkeccak_hmac_duplicate -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_marshal_size -@fnindex libkeccak_hmac_marshal_size -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_marshal -@fnindex libkeccak_hmac_marshal -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_unmarshal -@fnindex libkeccak_hmac_unmarshal -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_unmarshal_skip -@fnindex libkeccak_hmac_unmarshal_skip -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_update -@fnindex libkeccak_hmac_fast_update -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_update -@fnindex libkeccak_hmac_update -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_fast_digest -@fnindex libkeccak_hmac_fast_digest -Perfectly analogous to the @code{libkeccak_state_t} counterpart. - -@item libkeccak_hmac_digest -@fnindex libkeccak_hmac_digest -Perfectly analogous to the @code{libkeccak_state_t} counterpart. -@end table - -@fnindex libkeccak_hmac_set_key -It also has the method @code{libkeccak_hmac_set_key} which -can be used set the key. This function is identical to -@code{libkeccak_hmac_reset}, except it will not reset the -sponge, and the second argument must not be @code{NULL}. - - - -@node Examples -@chapter Examples -@cpindex Example - -@cartouche -@cpindex Configure state -@tpindex libkeccak_spec_t -@tpindex libkeccak_generalised_spec_t -@fnindex libkeccak_generalised_spec_initialise -@fnindex libkeccak_degeneralise_spec -@fnindex libkeccak_spec_check -This examples configure a @code{libkeccak_spec_t} to specify settings for Keccak[c = 512]. -@example -int r; -libkeccak_spec_t spec; -libkeccak_generalised_spec_t gspec; -libkeccak_generalised_spec_initialise(&gspec); -gspec.capacity = 512; -if ((r = libkeccak_degeneralise_spec(&gspec, &spec))) - goto fail_degeneralise_spec; -if ((r = libkeccak_spec_check(&spec))); - goto fail_spec_check; -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash -@cpindex Hash, calculate -@cpindex Configure state -@cpindex Hexadecimal hash -@tpindex libkeccak_state_t -@tpindex libkeccak_spec_t -@fnindex libkeccak_state_initialise -@fnindex libkeccak_update -@fnindex libkeccak_digest -@fnindex libkeccak_behex_lower -@fnindex libkeccak_state_destroy -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. -@example -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; -char chunk[4 << 10]; -ssize_t len; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; -if (libkeccak_state_initialise(&state, &spec) < 0) - goto fail; - -for (;;) @{ - len = read(STDIN_FILENO, chunk, sizeof(chunk)); - - if ((len < 0) && (errno == EINTR)) - continue; - if (len < 0) - goto fail; - if (len == 0) - break; - - if (libkeccak_update(&state, chunk, (size_t)len) < 0) - goto fail; -@} -if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Configure state, RawSHAKE -@cpindex RawSHAKE, configure state -@tpindex libkeccak_spec_t -@fnindex libkeccak_spec_rawshake -This example configure a @code{libkeccak_spec_t} to specify -the Keccak parameters used for RawSHAKE256(, 512). -@example -libkeccak_spec_t spec; -libkeccak_spec_rawshake(&spec, 256, 512); -@end example -@end cartouche - -@cartouche -@cpindex Configure state, SHA-3 -@cpindex SHA-3, configure state -@tpindex libkeccak_spec_t -@fnindex libkeccak_spec_sha3 -This example configure a @code{libkeccak_spec_t} to specify -the Keccak parameters used for SHA3-256. -@example -libkeccak_spec_t spec; -libkeccak_spec_sha3(&spec, 256); -@end example -@end cartouche - -@cartouche -@cpindex Configure state, SHAKE -@cpindex SHAKE, configure state -@tpindex libkeccak_spec_t -@fnindex libkeccak_spec_shake -This example configure a @code{libkeccak_spec_t} to specify -the Keccak parameters used for SHAKE256(, 512). -@example -libkeccak_spec_t spec; -libkeccak_spec_shake(&spec, 256, 512); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, SHA-3, from file -@cpindex Hash, calculate, SHA-3, from file -@cpindex SHA-3, calculate hash, from file -@cpindex File, calculate hash, SHA-3 -@fnindex libkeccak_sha3sum_fd -This example calculates the SHA3-256 hash of the input from -stdin, and prints the hash, in hexadecimal form, to stdout. -@example -libkeccak_state_t state; -if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, RawSHAKE, from file -@cpindex Hash, calculate, RawSHAKE, from file -@cpindex RawSHAKE, calculate hash, from file -@cpindex File, calculate hash, RawSHAKE -@fnindex libkeccak_rawshakesum_fd -This example calculates the RawSHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -@example -libkeccak_state_t state; -if (libkeccak_rawshakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, SHAKE, from file -@cpindex Hash, calculate, SHAKE, from file -@cpindex SHAKE, calculate hash, from file -@cpindex File, calculate hash, SHAKE -@fnindex libkeccak_shakesum_fd -This example calculates the SHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -@example -libkeccak_state_t state; -if (libkeccak_shakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, Keccak, from file -@cpindex Hash, calculate, Keccak, from file -@cpindex Keccak, calculate hash, from file -@cpindex File, calculate hash, Keccak -@tpindex libkeccak_spec_t -@fnindex libkeccak_keccaksum_fd -@fnindex libkeccak_behex_lower -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. -@example -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; - -if (libkeccak_keccaksum_fd(STDIN_FILENO, &state, &spec, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - -@cartouche -@cpindex Calculate hash, from file -@cpindex Hash, calculate, from file -@cpindex Calculate hash, from file -@cpindex File, calculate hash -@tpindex libkeccak_spec_t -@fnindex libkeccak_generalised_sum_fd -@fnindex libkeccak_behex_lower -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. -@example -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; - -if (libkeccak_generalised_sum_fd(STDIN_FILENO, &state, - &spec, NULL, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\n", hexhash); -libkeccak_state_destroy(&state); -@end example -@end cartouche - - - -@node Concept index -@unnumbered Concept index -@printindex cp - -@node Data type index -@unnumbered Data type index -@printindex tp - -@node Function index -@unnumbered Function index -@printindex fn - - -@bye diff --git a/doc/info/macros.texinfo b/doc/info/macros.texinfo deleted file mode 100644 index 4ec5d68..0000000 --- a/doc/info/macros.texinfo +++ /dev/null @@ -1,10 +0,0 @@ -@iftex -@macro e{a} -(@email{\a\}) -@end macro -@end iftex -@ifnottex -@macro e{a} -@email{\a\} -@end macro -@end ifnottex diff --git a/doc/man/libkeccak.7 b/doc/man/libkeccak.7 deleted file mode 100644 index 0a6ef04..0000000 --- a/doc/man/libkeccak.7 +++ /dev/null @@ -1,70 +0,0 @@ -.TH LIBKECCAK 7 LIBKECCAK -.SH NAME -libkeccak - Keccak-family hashing library -.SH DESCRIPTION -.BR libkeccak -is a bit-oriented lanewise implementation of the Keccak-family with -support for extend output size, state marshalling, algorithm tuning with -implicit parameters, secure erasure of sensitive data, and HMAC. -.SH FUTURE DIRECTION -Keccak-3200 may be implemented in the future. -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_degeneralise_spec (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_wipe_message (3), -.BR libkeccak_state_wipe_sponge (3), -.BR libkeccak_state_wipe (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_create (3), -.BR libkeccak_state_fast_free (3), -.BR libkeccak_state_free (3), -.BR libkeccak_state_copy (3), -.BR libkeccak_state_duplicate (3), -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_state_unmarshal_skip (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_unhex (3), -.BR libkeccak_hmac_set_key (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_copy (3), -.BR libkeccak_hmac_duplicate (3), -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_unmarshal_skip (3), -.BR libkeccak_hmac_fast_update (3), -.BR libkeccak_hmac_update (3), -.BR libkeccak_hmac_fast_digest (3), -.BR libkeccak_hmac_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_behex_lower.3 b/doc/man/libkeccak_behex_lower.3 deleted file mode 100644 index 85bc843..0000000 --- a/doc/man/libkeccak_behex_lower.3 +++ /dev/null @@ -1,50 +0,0 @@ -.TH LIBKECCAK_BEHEX_LOWER 3 LIBKECCAK -.SH NAME -libkeccak_behex_lower - Converts a binary hashsum to lowercase hexadecimal -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_behex_lower(char *restrict \fIoutput\fP, - const char *restrict \fIhashsum\fP, size_t \fIn\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_behex_lower () -function -converts a binary hashsum, stored in -.IR hashsum , -to lowercase hexadecimal, and stores the -hexadecimal representation in -.IR output . -.PP -.I output -will be terminated by a NUL-character. -.PP -The -.I n -parameter specifies the number of bytes -the binary hashsum is comprised. -.I output -needs an allocation size of (2 * -.I n -+ 1). -.SH RETURN VALUES -The -.BR libkeccak_behex_lower () -function does return any value. -.SH ERRORS -The -.BR libkeccak_behex_lower () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_behex_upper (3), -.BR libkeccak_unhex (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_behex_upper.3 b/doc/man/libkeccak_behex_upper.3 deleted file mode 100644 index 7925efc..0000000 --- a/doc/man/libkeccak_behex_upper.3 +++ /dev/null @@ -1,50 +0,0 @@ -.TH LIBKECCAK_BEHEX_UPPER 3 LIBKECCAK -.SH NAME -libkeccak_behex_upper - Converts a binary hashsum to uppercase hexadecimal -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_behex_upper(char *restrict \fIoutput\fP, - const char *restrict \fIhashsum\fP, size_t \fIn\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_behex_upper () -function -converts a binary hashsum, stored in -.IR hashsum , -to uppercase hexadecimal, and stores the -hexadecimal representation in -.IR output . -.PP -.I output -will be terminated by a NUL-character. -.PP -The -.I n -parameter specifies the number of bytes -the binary hashsum is comprised. -.I output -needs an allocation size of (2 * -.I n -+ 1). -.SH RETURN VALUES -The -.BR libkeccak_behex_upper () -function does return any value. -.SH ERRORS -The -.BR libkeccak_behex_upper () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_unhex (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_degeneralise_spec.3 b/doc/man/libkeccak_degeneralise_spec.3 deleted file mode 100644 index 38a1b73..0000000 --- a/doc/man/libkeccak_degeneralise_spec.3 +++ /dev/null @@ -1,124 +0,0 @@ -.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK -.SH NAME -libkeccak_degeneralise_spec - Set all specification parameters to automatic -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *\fIspec\fP, - libkeccak_spec_t *\fIoutput_spec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_degeneralise_spec () -function will resolve automatic parameters in -.I *spec -and translates the parameters to -.IR *output_spec , -so that it can be used for hashing. -.PP -The function will modify both -.I *spec -and -.IR *output_spec . -.PP -You should call the -.BR libkeccak_spec_check (3) -function after calling -.BR libkeccak_degeneralise_spec (). -.PP -.nf -typedef struct libkeccak_generalised_spec { - long int bitrate; /* bitrate (in bits) */ - long int capacity; /* capacity (in bits) */ - long int output; /* output size (in bits) */ - long int state_size; /* state size (in bits) */ - long int word_size; /* word size (in bits) */ -} libkeccak_generalised_spec_t; -.fi -.SH RETURN VALUES -The -.BR libkeccak_degeneralise_spec () -function returns 0 if the settings are usable. Otherwise -it will return one of the following constants. -.PP -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE -The specified state size is non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE -The specified state size exceeded the supported limit -(currently at 1600 bits.) -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25 -The specified state size, in bits, was not equivalent -to 0 modulus 25. Meaning the state size cannot -cover all lanes equivalently. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE -The specified word size is non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE -The specified word size exceeded the supported limit -(currently at 64 bits.) -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY -The specified state size is not exactly 25 times larger -than the word size. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE -The specified capacity was non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8 -The specified capacity was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE -The specified bitrate was non-positive. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8 -The specified bitrate was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE -The specified output size was non-positive. -.PP -Note that there may be more than one error. Only the first -detected is returned. -.SH ERRORS -The -.BR libkeccak_degeneralise_spec () -function cannot fail. -.fi -.SH EXAMPLE -This examples configure a -.B libkeccak_spec_t -to specify settings for Keccak[c = 512]: -.LP -.nf -int r; -libkeccak_spec_t spec; -libkeccak_generalised_spec_t gspec; -libkeccak_generalised_spec_initialise(&gspec); -gspec.capacity = 512; -if ((r = libkeccak_degeneralise_spec(&gspec, &spec))) - goto fail_degeneralise_spec; -if ((r = libkeccak_spec_check(&spec))); - goto fail_spec_check; -.fi -.SH SEE ALSO -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_digest.3 b/doc/man/libkeccak_digest.3 deleted file mode 100644 index 33b0479..0000000 --- a/doc/man/libkeccak_digest.3 +++ /dev/null @@ -1,145 +0,0 @@ -.TH LIBKECCAK_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_digest - Complete the hashing of a message with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_digest () -function absorbs the last part of (or all of) a message, -and returns the hash of the entire message. The last part -of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_update (3) -function or the -.BR libkeccak_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s -and '0':s, representing the bits that should be appended to -the message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.I hashsum -is -.I NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_digest () -function may fail for any reason specified by the function -.BR malloc (3). -.SH EXAMPLE -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -.LP -.nf -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; -char chunk[4 << 10]; -ssize_t len; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; -if (libkeccak_state_initialise(&state, &spec) < 0) - goto fail; - -for (;;) { - len = read(STDIN_FILENO, chunk, sizeof(chunk)); - - if ((len < 0) && (errno == EINTR)) - continue; - if (len < 0) - goto fail; - if (len == 0) - break; - - if (libkeccak_update(&state, chunk, (size_t)len) < 0) - goto fail; -} -if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_fast_digest.3 b/doc/man/libkeccak_fast_digest.3 deleted file mode 100644 index d5c55a5..0000000 --- a/doc/man/libkeccak_fast_digest.3 +++ /dev/null @@ -1,146 +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 -.P -int -libkeccak_fast_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_fast_digest () -function absorbs the last part of (or all of) a message, -and returns the hash of the entire message. The last part -of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_update (3) -function or the -.BR libkeccak_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s and '0':s, -representing the bits that should be appended to the -message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.IR hashsum -is -.IR NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_fast_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.SH RETURN VALUES -The -.BR libkeccak_fast_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_fast_digest () -function may fail for any reason specified by the function -.BR realloc (3). -.SH EXAMPLE -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -.LP -.nf -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; -char chunk[4 << 10]; -ssize_t len; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; -if (libkeccak_state_initialise(&state, &spec) < 0) - goto fail; - -for (;;) { - len = read(STDIN_FILENO, chunk, sizeof(chunk)); - - if ((len < 0) && (errno == EINTR)) - continue; - if (len < 0) - goto fail; - if (len == 0) - break; - - if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0) - goto fail; -} -if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_fast_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_fast_squeeze.3 b/doc/man/libkeccak_fast_squeeze.3 deleted file mode 100644 index d782a95..0000000 --- a/doc/man/libkeccak_fast_squeeze.3 +++ /dev/null @@ -1,39 +0,0 @@ -.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_fast_squeeze - Runs the squeeze phase a number of times -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_fast_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_fast_squeeze () -function runs the Keccak squeeze phase, on the the hash -process described by -.IR *state , -as many times are required to get -.I times -additional digests. -.SH RETURN VALUES -The -.BR libkeccak_fast_squeeze () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_fast_squeeze () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_digest (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_fast_update.3 b/doc/man/libkeccak_fast_update.3 deleted file mode 100644 index c619e7d..0000000 --- a/doc/man/libkeccak_fast_update.3 +++ /dev/null @@ -1,96 +0,0 @@ -.TH LIBKECCAK_FAST_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_fast_update - Partially hash a message without erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_fast_update () -function continues (or starts) hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_fast_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.SH RETURN VALUES -The -.BR libkeccak_fast_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_fast_update () -function may fail for any reason specified by the function -.BR realloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH EXAMPLE -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -.LP -.nf -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; -char chunk[4 << 10]; -ssize_t len; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; -if (libkeccak_state_initialise(&state, &spec) < 0) - goto fail; - -for (;;) { - len = read(STDIN_FILENO, chunk, sizeof(chunk)); - - if ((len < 0) && (errno == EINTR)) - continue; - if (len < 0) - goto fail; - if (len == 0) - break; - - if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0) - goto fail; -} -if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_fast_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_generalised_spec_initialise.3 b/doc/man/libkeccak_generalised_spec_initialise.3 deleted file mode 100644 index 42bd62f..0000000 --- a/doc/man/libkeccak_generalised_spec_initialise.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_GENERALISED_SPEC_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_generalised_spec_initialise - Set all specification parameters to automatic -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_generalised_spec_initialise () -function initialises -.IR *spec , -so that all parameters are configured to be -automatically selected. -.PP -Automatic selection means that value will be set -to the default, which depends on the other settings. -.PP -Specifically, all members of -.IR *spec , -will be set to -.BR LIBKECCAK_GENERALISED_SPEC_AUTOMATIC . -.SH RETURN VALUES -The -.BR libkeccak_generalised_spec_initialise () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_generalised_spec_initialise () -function cannot fail. -.fi -.SH SEE ALSO -.BR libkeccak_degeneralise_spec (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_generalised_sum_fd.3 b/doc/man/libkeccak_generalised_sum_fd.3 deleted file mode 100644 index 98e6329..0000000 --- a/doc/man/libkeccak_generalised_sum_fd.3 +++ /dev/null @@ -1,132 +0,0 @@ -.TH LIBKECCAK_GENERALISED_SUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_generalised_sum_fd - Calculate the hash of a file -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_generalised_sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP, - const char *\fIsuffix\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_generalised_sum_fd () -function calculates the hash of a file, whose file desriptor is -specified by -.I fd -(and should be at the beginning of the file.) The hash algorithm -is specified by -.I *spec -and -.IR suffix , -where -.I *spec -is the tuning of the algorithm and -.I suffix -is the bits append to the message (or -.I NULL -if none.) -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( spec->output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_generalised_sum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_generalised_sum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_generalised_sum_fd () -function may fail for any reason, except those resulting -in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_generalised_sum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_generalised_sum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_generalised_sum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_generalised_sum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_generalised_sum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -.LP -.nf -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; - -if (libkeccak_generalised_sum_fd(STDIN_FILENO, &state, &spec, NULL, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_copy.3 b/doc/man/libkeccak_hmac_copy.3 deleted file mode 100644 index f3939f5..0000000 --- a/doc/man/libkeccak_hmac_copy.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_HMAC_COPY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_copy - Copies an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_hmac_copy(libkeccak_hmac_state_t *\fIdest\fP, - const libkeccak_hmac_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_copy () -function initialises -.I *dest -to be identical to -.IR *src . -This includes all members of the -.B libkeccak_hmac_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_hmac_copy () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_copy () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_duplicate (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_create.3 b/doc/man/libkeccak_hmac_create.3 deleted file mode 100644 index fcb99cb..0000000 --- a/doc/man/libkeccak_hmac_create.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH LIBKECCAK_HMAC_CREATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_create - Allocate and initialise HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -libkeccak_hmac_state_t * -libkeccak_hmac_create(const libkeccak_spec_t *\fIspec\fP, const char *\fIkey\fP, - size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_create () -function allocates a new -.I libkeccak_hmac_state_t* -with one initialised element, and sets the -algorithm tuning parameters to those specified by -.IR *spec , -and the key to -.I key -of length -.IR key_length . -.SH RETURN VALUES -The -.BR libkeccak_hmac_create () -function returns a newly allocated -.I libkeccak_hmac_state_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_create () -function may fail for any specified for the functions -.BR malloc (3) -and -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_duplicate (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_destroy.3 b/doc/man/libkeccak_hmac_destroy.3 deleted file mode 100644 index 2f3bbf8..0000000 --- a/doc/man/libkeccak_hmac_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_HMAC_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_destroy - Destroys an HMAC-hashing state with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_hmac_destroy(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_hmac_destroy () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_digest.3 b/doc/man/libkeccak_hmac_digest.3 deleted file mode 100644 index 66d35d4..0000000 --- a/doc/man/libkeccak_hmac_digest.3 +++ /dev/null @@ -1,103 +0,0 @@ -.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK -.SH NAME -libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_hmac_digest(libkeccak_hmac_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_digest () -function absorbes the last part of (or all of) a message, -and returns the HMAC hash of the entire message. The last -part of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_hmac_update (3) -function or the -.BR libkeccak_hmac_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s -and '0':s, representing the bits that should be appended -to the message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.I hashsum -is -.I NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_hmac_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_hmac_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_digest () -function may fail for any reason specified by the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_update (3), -.BR libkeccak_hmac_fast_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_duplicate.3 b/doc/man/libkeccak_hmac_duplicate.3 deleted file mode 100644 index 70c994c..0000000 --- a/doc/man/libkeccak_hmac_duplicate.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_HMAC_DUPLICATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_duplicate - Allocate a duplicate an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -libkeccak_hmac_state_t * -libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_duplicate () -function allocates a new hash state and initialises -it to be identical to -.IR *src . -This includes all members of the -.B libkeccak_hmac_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_hmac_duplicate () -function returns a newly allocated -.I libkeccak_hmac_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_duplicate () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_copy (3), -.BR libkeccak_hmac_create (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_destroy.3 b/doc/man/libkeccak_hmac_fast_destroy.3 deleted file mode 100644 index d2af66e..0000000 --- a/doc/man/libkeccak_hmac_fast_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_destroy - Destroys an HMAC-hashing state without erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_hamc_fast_destroy(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_hmac_fast_destroy () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_fast_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_digest.3 b/doc/man/libkeccak_hmac_fast_digest.3 deleted file mode 100644 index 008477c..0000000 --- a/doc/man/libkeccak_hmac_fast_digest.3 +++ /dev/null @@ -1,104 +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 -.LP -.nf -#include -.P -int -libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *\fIstate\fP, - const char *\fImsg\fP, size_t \fImsglen\fP, size_t \fIbits\fP, - const char *\fIsuffix\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_digest () -function absorbes the last part of (or all of) a message, -and returns the HMAC hash of the entire message. The last -part of the message is specified by the -.I msg -parameter, and its byte-size is specified by the -.I msglen -parameter. If all of the message has already be processed -by calls to the -.BR libkeccak_hmac_update (3) -function or the -.BR libkeccak_hmac_fast_update (3) -function (with the same pointer on -.IR state ,) -.I msg -and -.I msglen -should be set to -.I NULL -and 0, respectively. -.PP -If the message is not comprised a whole number of bytes, -the number of bits, modulus 8, in the message should be -specified in the -.I bits -parameter. -.I msglen -must only count the number of whole bytes, that is, the -floor of the number of bits in the message divided by 8. -.PP -.I suffix -should be a NUL-terminated string of ASCII '1':s -and '0':s, representing the bits that should be appended -to the message. If this string is empty, -.I NULL -may be used instead. This is used to select hash algorithm. -For pure Keccak, -.I NULL -or "" is used. For the other algorithms the constants -.B LIBKECCAK_SHA3_SUFFIX -(for SHA-3), -.B LIBKECCAK_RAWSHAKE_SUFFIX -(for RawSHAKE), and -.B LIBKECCAK_SHAKE_SUFFIX -(for SHAKE) are used. -.PP -The hash of the message will be stored to -.IR hashsum , -unless -.I hashsum -is -.I NULL -(which increases the performance of the call.) A total of -.RI (( state->n -+ 7) / 8) bytes will be written to the beginning of -.IR hashsum . -Therefore, -.I hashsum -needs at least an allocation size of that number of bytes. -.PP -The -.BR libkeccak_hmac_fast_digest () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_digest () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_fast_digest () -function may fail for any reason specified by the function -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_fast_update (3), -.BR libkeccak_hmac_fast_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_free.3 b/doc/man/libkeccak_hmac_fast_free.3 deleted file mode 100644 index b4817ce..0000000 --- a/doc/man/libkeccak_hmac_fast_free.3 +++ /dev/null @@ -1,51 +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 -.LP -.nf -#include -.P -void -libkeccak_hmac_fast_free(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_free () -function releases the allocations stored in -.IR *state , -and also released the allocation of -.IR state . -.PP -The -.BR libkeccak_hmac_fast_free () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_fast_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_hmac_fast_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_fast_update.3 b/doc/man/libkeccak_hmac_fast_update.3 deleted file mode 100644 index 43077d3..0000000 --- a/doc/man/libkeccak_hmac_fast_update.3 +++ /dev/null @@ -1,59 +0,0 @@ -.TH LIBKECCAK_HMAC_FAST_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_fast_update - Partially HMAC-hash a message without erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_hmac_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_fast_update () -function continues (or starts) HMAC-hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_hmac_fast_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_hmac_fast_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_fast_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as quickly as possible, -rather than ensuring that the information in the old -allocation is securely removed if a new allocation is required. -.BR realloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_fast_digest (3), -.BR libkeccak_hmac_update (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_free.3 b/doc/man/libkeccak_hmac_free.3 deleted file mode 100644 index d1f9c84..0000000 --- a/doc/man/libkeccak_hmac_free.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_HMAC_FREE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_free - Destroys and deallocates an HMAC-hashing state with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_hmac_free(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_free () -function releases the allocations stored in -.IR *state , -and also release the allocation of -.IR state . -.PP -The -.BR libkeccak_hmac_free () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_hmac_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_hmac_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3), -.BR libkeccak_hmac_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_initialise.3 b/doc/man/libkeccak_hmac_initialise.3 deleted file mode 100644 index de514e9..0000000 --- a/doc/man/libkeccak_hmac_initialise.3 +++ /dev/null @@ -1,57 +0,0 @@ -.TH LIBKECCAK_HMAC_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_initialise - Initialise HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_hmac_initialise(libkeccak_hmac_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP, - const char *\fIkey\fP, size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_initialise () -function initialises -.I *state -and sets the algorithm tuning parameters to -those specified by -.IR *spec , -and the key to -.I key -of length -.IR key_length . -.SH RETURN VALUES -The -.BR libkeccak_hmac_initialise () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_initialise () -function may fail for any specified for the functions -.BR malloc (3) -and -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_destroy (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_copy (3), -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_marshal.3 b/doc/man/libkeccak_hmac_marshal.3 deleted file mode 100644 index b7270f6..0000000 --- a/doc/man/libkeccak_hmac_marshal.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_HMAC_MARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_hmac_marshal - Marshals an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_hmac_marshal(const libkeccak_hmac_state_t *\fIstate\fP, - char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_marshal () -function marshals -.I *state -into the beginning of -.IR data . -.PP -Use the -.BR libkeccak_hmac_marshal_size (3) -function to get minimum usable allocation size -for -.IR data . -.SH RETURN VALUES -The -.BR libkeccak_hmac_marshal () -returns the number of bytes written to -.IR data . -.SH ERRORS -The -.BR libkeccak_hmac_marshal () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_marshal_size.3 b/doc/man/libkeccak_hmac_marshal_size.3 deleted file mode 100644 index 5195b81..0000000 --- a/doc/man/libkeccak_hmac_marshal_size.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH LIBKECCAK_HMAC_MARSHAL_SIZE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_marshal_size - Calculates the marshal-size of an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_marshal_size () -function calculates the number of bytes required -to marshal -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_hmac_marshal_size () -returns a positive value: the number of -bytes required to marshal the specified state. -.SH ERRORS -The -.BR libkeccak_hmac_marshal_size () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal (3), -.BR libkeccak_hmac_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_reset.3 b/doc/man/libkeccak_hmac_reset.3 deleted file mode 100644 index d5634d9..0000000 --- a/doc/man/libkeccak_hmac_reset.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_HMAC_RESET 3 LIBKECCAK -.SH NAME -libkeccak_hmac_reset - Reinitialise a HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_hmac_reset(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, - size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_reset () -function reinitialises an HMAC-hashing state with a new key. -.I key_length -is the length of the key in bits. If -.I key -is -.IR NULL , -the key remains unchanged. -.SH RETURN VALUES -The -.BR libkeccak_hmac_reset () -function returns 0 successful completion. -On error -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_reset () -function may fail for any specified for the functions -.BR malloc (3) -and -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_set_key (3), -.BR libkeccak_hmac_wipe (3), -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_destroy (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_set_key.3 b/doc/man/libkeccak_hmac_set_key.3 deleted file mode 100644 index 2f4682d..0000000 --- a/doc/man/libkeccak_hmac_set_key.3 +++ /dev/null @@ -1,41 +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 -.LP -.nf -#include -.P -int -libkeccak_hmac_set_key(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, - size_t \fIkey_length\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_set_key () -function sets the key for a HMAC-hashing state without reseting -the state of the underlaying hashing-algorithm. -.I key_length -is the length of the key in bits. -.SH RETURN VALUES -The -.BR libkeccak_hmac_set_key () -function returns 0 successful completion. -On error -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_set_key () -function may fail for any specified for the function -.BR realloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_unmarshal.3 b/doc/man/libkeccak_hmac_unmarshal.3 deleted file mode 100644 index 64e8f24..0000000 --- a/doc/man/libkeccak_hmac_unmarshal.3 +++ /dev/null @@ -1,39 +0,0 @@ -.TH LIBKECCAK_HMAC_UNMARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_hmac_unmarshal - Unharshals an HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *\fIstate\fP, - const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_unmarshal () -function unmarshals an HMAC-hashing state from the beginning of -.IR data . -and stores it in -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_hmac_unmarshal () -returns the number of bytes reads from -.IR data x. -.SH ERRORS -The -.BR libkeccak_hmac_unmarshal () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_unmarshal_skip.3 b/doc/man/libkeccak_hmac_unmarshal_skip.3 deleted file mode 100644 index 30e7ccf..0000000 --- a/doc/man/libkeccak_hmac_unmarshal_skip.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH LIBKECCAK_HMAC_UNMARSHAL_SKIP 3 LIBKECCAK -.SH NAME -libkeccak_hmac_unmarshal_skip - Calculates the marshal-size of a marshalled HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_hmac_unmarshal_skip(const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_unmarshal_skip () -function gets the number of bytes with which -the HMAC-hashing state in the beginning of -.I data -is store stored. This is useful if you do not -want to unmarshal the state. -.SH RETURN VALUES -The -.BR libkeccak_hmac_unmarshal_skip () -returns a positive value: the number of -bytes to skip forward to skip pass the -hash state stored at the beginning of -the buffer. -.SH ERRORS -The -.BR libkeccak_hmac_unmarshal_skip () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_marshal_size (3), -.BR libkeccak_hmac_marshal (3), -.BR libkeccak_hmac_unmarshal (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_update.3 b/doc/man/libkeccak_hmac_update.3 deleted file mode 100644 index daaf3fb..0000000 --- a/doc/man/libkeccak_hmac_update.3 +++ /dev/null @@ -1,56 +0,0 @@ -.TH LIBKECCAK_HMAC_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_update - Partially HMAC-hash a message with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_hmac_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_update () -function continues (or starts) HMAC-hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_hmac_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_hmac_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_hmac_update () -function may fail for any reason specified by the function -.BR malloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH SEE ALSO -.BR libkeccak_hmac_create (3), -.BR libkeccak_hmac_initialise (3), -.BR libkeccak_hmac_digest (3), -.BR libkeccak_hmac_fast_update (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_hmac_wipe.3 b/doc/man/libkeccak_hmac_wipe.3 deleted file mode 100644 index bad351b..0000000 --- a/doc/man/libkeccak_hmac_wipe.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH LIBKECCAK_HMAC_WIPE 3 LIBKECCAK -.SH NAME -libkeccak_hmac_wipe - Securely erase sensitive data from a HMAC-hashing state -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_hmac_wipe(libkeccak_hmac_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_hmac_wipe () -function securely erases data that may be -sensitive: the buffer and the state of the -underlaying hash-algorithm. -.SH RETURN VALUES -The -.BR libkeccak_hmac_wipe () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_hmac_wipe () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_hmac_fast_free (3), -.BR libkeccak_hmac_free (3), -.BR libkeccak_hmac_fast_destroy (3), -.BR libkeccak_hmac_destroy (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_keccaksum_fd.3 b/doc/man/libkeccak_keccaksum_fd.3 deleted file mode 100644 index 2fc1b21..0000000 --- a/doc/man/libkeccak_keccaksum_fd.3 +++ /dev/null @@ -1,119 +0,0 @@ -.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_keccaksum_fd - Calculate a Keccak hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_keccaksum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_keccaksum_fd () -function calculates a Keccak hashsum of a file, whose file -desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm tuning is specified by -.IR *spec . -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( spec->output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_keccaksum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_keccaksum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_keccaksum_fd () -function may fail for any reason, except those resulting -in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_keccaksum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_keccaksum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_keccaksum_fd () -does not stop if interrupted -.RI ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_keccaksum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_keccaksum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -.LP -.nf -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; - -if (libkeccak_keccaksum_fd(STDIN_FILENO, &state, &spec, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_rawshakesum_fd.3 b/doc/man/libkeccak_rawshakesum_fd.3 deleted file mode 100644 index 27c4f45..0000000 --- a/doc/man/libkeccak_rawshakesum_fd.3 +++ /dev/null @@ -1,115 +0,0 @@ -.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_rawshakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - long int \fIsemicapacity\fP, long int \fIoutput\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_rawshakesum_fd () -function calculates a RawSHAKE hashsum of a file, whose -file desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm is tuned by the -.I semicapacity -and -.I output -parameters; they specify the half of the capacity and -the output size, respectively, in bits. -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_rawshakesum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_rawshakesum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_rawshakesum_fd () -function may fail for any reason, except those resulting in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_rawshakesum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_rawshakesum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_rawshakesum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_rawshakesum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_rawshakesum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the RawSHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -.LP -.nf -libkeccak_state_t state; -if (libkeccak_rawshakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_sha3sum_fd.3 b/doc/man/libkeccak_sha3sum_fd.3 deleted file mode 100644 index e8c4fc0..0000000 --- a/doc/man/libkeccak_sha3sum_fd.3 +++ /dev/null @@ -1,111 +0,0 @@ -.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_sha3sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIoutput\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_sha3sum_fd () -function calculates a SHA-3 hashsum of a file, whose file -desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm is tuned by the -.I output -parameter; it specifies the output size, in bits. -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_sha3sum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_sha3sum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_sha3sum_fd () -function may fail for any reason, except those resulting in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_sha3sum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_sha3sum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_sha3sum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_sha3sum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_sha3sum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the SHA3-256 hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -.LP -.nf -libkeccak_state_t state; -if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_shakesum_fd.3 b/doc/man/libkeccak_shakesum_fd.3 deleted file mode 100644 index 0d89f39..0000000 --- a/doc/man/libkeccak_shakesum_fd.3 +++ /dev/null @@ -1,115 +0,0 @@ -.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK -.SH NAME -libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, - long int \fIsemicapacity\fP, long int \fIoutput\fP, - char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_shakesum_fd () -function calculates a SHAKE hashsum of a file, whose file -desriptor is specified by -.I fd -(and should be at the beginning of the file.) The hash -algorithm is tuned by the -.I semicapacity -and -.I output -parameters; they specify the half of the capacity and the -output size, respectively, in bits. -.PP -The hash is stored in binary form to -.IR hashsum . -.I hashsum -should have an allocation size of at least -.RI ((( output -+ 7) / 8) * sizeof(char)). -.PP -.I *state -should not be initialised. -.BR libkeccak_shakesum_fd () -initialises -.I *state -itself. Therefore there would be a memory leak if -.I *state -is already initialised. -.SH RETURN VALUES -The -.BR libkeccak_shakesum_fd () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_shakesum_fd () -function may fail for any reason, except those resulting in -.I errno -being set to -.BR EINTR , -specified for the functions -.BR read (2), -.BR malloc (3), -and -.BR realloc (3). -.SH NOTES -Be aware, -.BR libkeccak_shakesum_fd () -hashes the file until the end has been reached. For pipes -and sockets and this means until the file has been closed. -But for character devices, this usually means never. -Attempting to hash files in /dev is therefore usually a -bad idea. -.BR libkeccak_shakesum_fd () -does not check for the file length or file type before -hashing as this could limit what you can do, and make -the library more complex. -.PP -.BR libkeccak_shakesum_fd () -does not stop if interrupted -.RB ( read (2) -returns -.BR EINTR .) -.PP -.BR libkeccak_shakesum_fd () -assumes all information is non-sensitive, and will -therefore not perform any secure erasure of information. -.PP -.BR libkeccak_shakesum_fd () -does not validate the tuning of the algorithm. -.SH EXAMPLE -This example calculates the SHAKE256(, 512) hash of the input -from stdin, and prints the hash, in hexadecimal form, to stdout. -.LP -.nf -libkeccak_state_t state; -if (libkeccak_shakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) - goto fail; -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_simple_squeeze.3 b/doc/man/libkeccak_simple_squeeze.3 deleted file mode 100644 index 52605ed..0000000 --- a/doc/man/libkeccak_simple_squeeze.3 +++ /dev/null @@ -1,38 +0,0 @@ -.TH LIBKECCAK_SIMPLE_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_simple_squeeze - Runs Keccak-f a number of times -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_simple_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_simple_squeeze () -function runs Keccak-f -.I times -times on the hashing -process described by -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_simple_squeeze () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_simple_squeeze () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_digest (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_fast_squeeze (3), -.BR libkeccak_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_check.3 b/doc/man/libkeccak_spec_check.3 deleted file mode 100644 index 9fc70f6..0000000 --- a/doc/man/libkeccak_spec_check.3 +++ /dev/null @@ -1,95 +0,0 @@ -.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK -.SH NAME -libkeccak_spec_check - Validate hashing parameters -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_spec_check(const libkeccak_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_check () -function validates the parameters of -.IR *spec , -so that unusable configurations can be detected. -It is recommended to call this function after calling -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -or, especially, after settings the parameters -manually for Keccak hashing. -.PP -.nf -typedef struct libkeccak_spec { - long int bitrate; /* bitrate (in bits) */ - long int capacity; /* capacity (in bits) */ - long int output; /* output size (in bits) */ -} libkeccak_spec_t; -.fi -.SH RETURN VALUES -The -.BR libkeccak_spec_check () -function returns 0 if the settings are usable. Otherwise -it will return one of the following constants. -.PP -.TP -.B LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE -The specified bitrate was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 -The specified bitrate was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE -The specified capacity was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 -The specified capacity was not equivalent to 0 -modulus 8, that is, it was not in whole bytes. -.TP -.B LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE -The specified output size was non-positive. -.TP -.B LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE -The state size, that is the sum of the bitrate -and the capacity, exceeded the supported limit -(currently at 1600 bits.) -.TP -.B LIBKECCAK_SPEC_ERROR_STATE_MOD_25 -The state size, that is the sum of the bitrate -and the capacity, in bits, was not equivalent -to 0 modulus 25. Meaning the state size cannot -cover all lanes equivalently. -.TP -.B LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT -The word size, that is the state size divided -by 25, is not a power of 2. -.TP -.B LIBKECCAK_SPEC_ERROR_WORD_MOD_8 -The word size, that is the state size divided -by 25, is not quivalent to 0 modulus 8, that -is, it is not in whole bytes. -.PP -Note that there may be more than one error. Only the first -detected is returned. -.SH ERRORS -The -.BR libkeccak_spec_check () -function cannot fail. -.fi -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_rawshake.3 b/doc/man/libkeccak_spec_rawshake.3 deleted file mode 100644 index 6f60c36..0000000 --- a/doc/man/libkeccak_spec_rawshake.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK -.SH NAME -libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_spec_rawshake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, - long int \fId\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_rawshake () -function sets -.I *spec -to specify the Keccak parameters used for RawSHAKE hashing -with the semicapacity specified, in bits, via the -.I x -parameter, and the output size specified, in bits, via the -.I d -parameter. -.SH RETURN VALUES -The -.BR libkeccak_spec_rawshake () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_spec_rawshake () -function cannot fail. -.SH EXAMPLE -This example configure a -.B libkeccak_spec_t -to specify the Keccak parameters used for RawSHAKE256(, 512): -.LP -.nf -libkeccak_spec_t spec; -libkeccak_spec_rawshake(&spec, 256, 512); -.fi -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_sha3.3 b/doc/man/libkeccak_spec_sha3.3 deleted file mode 100644 index 8e07a7d..0000000 --- a/doc/man/libkeccak_spec_sha3.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK -.SH NAME -libkeccak_spec_sha3 - Configure SHA-3 hashing parameters -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_spec_sha3(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_sha3 () -function sets -.I *spec -to specify the Keccak parameters -used for SHA-3 hashing with the output size specified, -in bits, via the -.I x -parameter. -.SH RETURN VALUES -The -.BR libkeccak_spec_sha3 () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_spec_sha3 () -function cannot fail. -.SH EXAMPLE -This example configure a -.B libkeccak_spec_t -to specify the Keccak parameters used for SHA3-256: -.LP -.nf -libkeccak_spec_t spec; -libkeccak_spec_sha3(&spec, 256); -.fi -.SH SEE ALSO -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_spec_shake.3 b/doc/man/libkeccak_spec_shake.3 deleted file mode 100644 index 9e2d763..0000000 --- a/doc/man/libkeccak_spec_shake.3 +++ /dev/null @@ -1,52 +0,0 @@ -.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK -.SH NAME -libkeccak_spec_shake - Configure SHAKE hashing parameters -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_spec_shake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_spec_shake () -function sets -.I *spec -to specify the Keccak parameters used for SHAKE hashing -with the semicapacity specified, in bits, via the -.I x -parameter, and the output size specified, in bits, via the -.I d -parameter. -.SH RETURN VALUES -The -.BR libkeccak_spec_shake () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_spec_shake () -function cannot fail. -.SH EXAMPLE -This example configure a -.B libkeccak_spec_t -to specify the Keccak parameters used for SHAKE256(, 512): -.LP -.nf -libkeccak_spec_t spec; -libkeccak_spec_shake(&spec, 256, 512); -.fi -.SH SEE ALSO -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_squeeze.3 b/doc/man/libkeccak_squeeze.3 deleted file mode 100644 index c6c8d01..0000000 --- a/doc/man/libkeccak_squeeze.3 +++ /dev/null @@ -1,48 +0,0 @@ -.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK -.SH NAME -libkeccak_squeeze - Runs the squeeze phase -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_squeeze(libkeccak_state_t *\fIstate\fP, char *\fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_squeeze () -function runs the Keccak squeeze phase, on the the hash -process described by -.IR *state , -on stores a new digest, in binary form, in -.IR hashsum . -.PP -.I hashsum -has the same requirement as for the -.BR libkeccak_digest (3) -and -.BR libkeccak_fast_digest (3) -functions: it must have an allocation size of at least -.RI (( state->n -+ 7) / 8) bytes. However, it may not be -.IR NULL . -.SH RETURN VALUES -The -.BR libkeccak_squeeze () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_squeeze () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_digest (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_simple_squeeze (3), -.BR libkeccak_fast_squeeze (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_copy.3 b/doc/man/libkeccak_state_copy.3 deleted file mode 100644 index c9283ca..0000000 --- a/doc/man/libkeccak_state_copy.3 +++ /dev/null @@ -1,44 +0,0 @@ -.TH LIBKECCAK_STATE_COPY 3 LIBKECCAK -.SH NAME -libkeccak_state_copy - Copies hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_state_copy(libkeccak_state_t *\fIdest\fP, - const libkeccak_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_copy () -function initialises -.I *dest -to be identical to -.IR *src . -This includes all members of the -.B libkeccak_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_copy () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_copy () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_duplicate (3), -.BR libkeccak_state_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_create.3 b/doc/man/libkeccak_state_create.3 deleted file mode 100644 index 77880a3..0000000 --- a/doc/man/libkeccak_state_create.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_STATE_CREATE 3 LIBKECCAK -.SH NAME -libkeccak_state_create - Allocate and initialise hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -libkeccak_state_t * -libkeccak_state_create(const libkeccak_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_create () -function allocates a new -.I libkeccak_state_t* -with one initialised element, and sets the algorithm -tuning parameters to those specified by -.IR *spec . -.SH RETURN VALUES -The -.BR libkeccak_state_create () -function returns a newly allocated -.I libkeccak_state_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_create () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_free (3), -.BR libkeccak_state_fast_free (3) -.BR libkeccak_state_duplicate (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_destroy.3 b/doc/man/libkeccak_state_destroy.3 deleted file mode 100644 index 0a78215..0000000 --- a/doc/man/libkeccak_state_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_STATE_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_state_destroy - Destroys a hash state with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_state_destroy(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_state_destroy () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_free (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_duplicate.3 b/doc/man/libkeccak_state_duplicate.3 deleted file mode 100644 index 54c9be3..0000000 --- a/doc/man/libkeccak_state_duplicate.3 +++ /dev/null @@ -1,46 +0,0 @@ -.TH LIBKECCAK_STATE_DUPLICATE 3 LIBKECCAK -.SH NAME -libkeccak_state_duplicate - Allocate a duplicate hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -libkeccak_state_t * -libkeccak_state_duplicate(const libkeccak_state_t *\fIsrc\fP); -.fi -.P -Link with -.IR -lkeccak P. -.SH DESCRIPTION -The -.BR libkeccak_state_duplicate () -function allocates a new hash state and initialises it -to be identical to -.IR *src . -This includes all members of the -.B libkeccak_state_t -structure, including the state of the sponge and the -message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_duplicate () -function returns a newly allocated -.I libkeccak_state_t* -(of one initialised element) upon successful completion. -On error, -.I NULL -is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_duplicate () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_copy (3), -.BR libkeccak_state_create (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_fast_destroy.3 b/doc/man/libkeccak_state_fast_destroy.3 deleted file mode 100644 index e04ca86..0000000 --- a/doc/man/libkeccak_state_fast_destroy.3 +++ /dev/null @@ -1,43 +0,0 @@ -.TH LIBKECCAK_STATE_FAST_DESTROY 3 LIBKECCAK -.SH NAME -libkeccak_state_fast_destroy - Destroys a hash state without erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_state_fast_destroy(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_fast_destroy () -function releases the allocations stored in -.IR *state , -without releasing the allocation of -.I state -itself. -.PP -The -.BR libkeccak_state_fast_destroy () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_fast_destroy () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_fast_destroy () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_fast_free (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_fast_free.3 b/doc/man/libkeccak_state_fast_free.3 deleted file mode 100644 index e617e21..0000000 --- a/doc/man/libkeccak_state_fast_free.3 +++ /dev/null @@ -1,51 +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 -.LP -.nf -#include -.P -void -libkeccak_state_fast_free(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_fast_free () -function releases the allocations stored in -.IR *state , -and also released the allocation of -.IR state . -.PP -The -.BR libkeccak_state_fast_free () -function does not securely erase sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_fast_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_fast_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_state_fast_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_free (3), -.BR libkeccak_state_create (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_free.3 b/doc/man/libkeccak_state_free.3 deleted file mode 100644 index e6dd3f8..0000000 --- a/doc/man/libkeccak_state_free.3 +++ /dev/null @@ -1,51 +0,0 @@ -.TH LIBKECCAK_STATE_FREE 3 LIBKECCAK -.SH NAME -libkeccak_state_free - Destroys and deallocates a hash state with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_state_free(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_free () -function releases the allocations stored in -.IR *state , -and also release the allocation of -.IR state . -.PP -The -.BR libkeccak_state_free () -function securely erases sensitive data. -.SH RETURN VALUES -The -.BR libkeccak_state_free () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_free () -function cannot fail. -.SH NOTES -A double call to -.BR libkeccak_state_free () -will either result in a double free, -which is must likely to crash the process, -or free an allocation (that was created -between the calls) that was not intended -to be freed, resulting in undefined behaviour. -.SH SEE ALSO -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_fast_free (3), -.BR libkeccak_state_create (3), -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_initialise.3 b/doc/man/libkeccak_state_initialise.3 deleted file mode 100644 index 2620686..0000000 --- a/doc/man/libkeccak_state_initialise.3 +++ /dev/null @@ -1,60 +0,0 @@ -.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK -.SH NAME -libkeccak_state_initialise - Initialise hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_state_initialise(libkeccak_state_t *\fIstate\fP, - const libkeccak_spec_t *\fIspec\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_initialise () -function initialises -.I *state -and sets the algorithm tuning parameters to those -specified by -.IR *spec . -.SH RETURN VALUES -The -.BR libkeccak_state_initialise () -function returns 0 upon successful completion. -On error, -1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_state_initialise () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_create (3), -.BR libkeccak_state_reset (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_copy (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3), -.BR libkeccak_generalised_sum_fd (3), -.BR libkeccak_keccaksum_fd (3), -.BR libkeccak_sha3sum_fd (3), -.BR libkeccak_rawshakesum_fd (3), -.BR libkeccak_shakesum_fd (3), -.BR libkeccak_spec_sha3 (3), -.BR libkeccak_spec_shake (3), -.BR libkeccak_spec_rawshake (3), -.BR libkeccak_spec_check (3), -.BR libkeccak_generalised_spec_initialise (3), -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_hmac_initialise (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_marshal.3 b/doc/man/libkeccak_state_marshal.3 deleted file mode 100644 index f5d5e05..0000000 --- a/doc/man/libkeccak_state_marshal.3 +++ /dev/null @@ -1,41 +0,0 @@ -.TH LIBKECCAK_STATE_MARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_state_marshal - Marshals a hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_state_marshal(const libkeccak_state_t *\fIstate\fP, char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_marshal () -function marshals \fI*state\fP into the beginning of -.IR data . -.PP -Use the -.BR libkeccak_state_marshal_size (3) -function to get minimum usable allocation size -for -.IR data . -.SH RETURN VALUES -The -.BR libkeccak_state_marshal () -returns the number of bytes written to -.IR data . -.SH ERRORS -The -.BR libkeccak_state_marshal () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_state_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_marshal_size.3 b/doc/man/libkeccak_state_marshal_size.3 deleted file mode 100644 index 8ebb16a..0000000 --- a/doc/man/libkeccak_state_marshal_size.3 +++ /dev/null @@ -1,36 +0,0 @@ -.TH LIBKECCAK_STATE_MARSHAL_SIZE 3 LIBKECCAK -.SH NAME -libkeccak_state_marshal_size - Calculates the marshal-size of a hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_state_marshal_size(const libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_marshal_size () -function calculates the number of bytes required -to marshal -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_state_marshal_size () -returns a positive value: the number of -bytes required to marshal the specified state. -.SH ERRORS -The -.BR libkeccak_state_marshal_size () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal (3), -.BR libkeccak_state_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_reset.3 b/doc/man/libkeccak_state_reset.3 deleted file mode 100644 index 60bb778..0000000 --- a/doc/man/libkeccak_state_reset.3 +++ /dev/null @@ -1,37 +0,0 @@ -.TH LIBKECCAK_STATE_RESET 3 LIBKECCAK -.SH NAME -libkeccak_state_reset - Reinitialise hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_state_reset(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_reset () -function reinitialises -.IR *state , -but keeps the -tuning, so it can be used to hash another message. -.SH RETURN VALUES -The -.BR libkeccak_state_reset () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_reset () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_wipe (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_unmarshal.3 b/doc/man/libkeccak_state_unmarshal.3 deleted file mode 100644 index 5a9e59b..0000000 --- a/doc/man/libkeccak_state_unmarshal.3 +++ /dev/null @@ -1,39 +0,0 @@ -.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK -.SH NAME -libkeccak_state_unmarshal - Unharshals a hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_state_unmarshal(libkeccak_state_t *\fIstate\fP, const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_unmarshal () -function unmarshals a hash state from the beginning -of -.IR data . -and stores it in -.IR *state . -.SH RETURN VALUES -The -.BR libkeccak_state_unmarshal () -returns the number of bytes reads from -.IR data . -.SH ERRORS -The -.BR libkeccak_state_unmarshal () -function may fail for any specified for the function -.BR malloc (3). -.SH SEE ALSO -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal_skip (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_unmarshal_skip.3 b/doc/man/libkeccak_state_unmarshal_skip.3 deleted file mode 100644 index b87386c..0000000 --- a/doc/man/libkeccak_state_unmarshal_skip.3 +++ /dev/null @@ -1,40 +0,0 @@ -.TH LIBKECCAK_STATE_UNMARSHAL_SKIP 3 LIBKECCAK -.SH NAME -libkeccak_state_unmarshal_skip - Calculates the marshal-size of a marshalled hash state -.SH SYNOPSIS -.LP -.nf -#include -.P -size_t -libkeccak_state_unmarshal_skip(const char *\fIdata\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_unmarshal_skip () -function gets the number of bytes with which -the hash state in the beginning of -.I data -is store stored. This is useful if you do not -want to unmarshal the state. -.SH RETURN VALUES -The -.BR libkeccak_state_unmarshal_skip () -returns a positive value: the number of -bytes to skip forward to skip pass the -hash state stored at the beginning of -the buffer. -.SH ERRORS -The -.BR libkeccak_state_unmarshal_skip () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_marshal_size (3), -.BR libkeccak_state_marshal (3), -.BR libkeccak_state_unmarshal (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_wipe.3 b/doc/man/libkeccak_state_wipe.3 deleted file mode 100644 index 664cd51..0000000 --- a/doc/man/libkeccak_state_wipe.3 +++ /dev/null @@ -1,37 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe - Securely erase sensitive data -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_state_wipe(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_wipe () -function securely erases data that may be -sensitive: the state of the Keccak sponge, -and the message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_wipe () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_wipe () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_wipe_message (3), -.BR libkeccak_state_wipe_sponge (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_wipe_message.3 b/doc/man/libkeccak_state_wipe_message.3 deleted file mode 100644 index c734560..0000000 --- a/doc/man/libkeccak_state_wipe_message.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE_MESSAGE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe_message - Securely erase the message chunk buffer -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_state_wipe_message(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_wipe_message () -function securely erases the message chunk buffer. -.SH RETURN VALUES -The -.BR libkeccak_state_wipe_message () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_wipe_message () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_wipe_sponge (3), -.BR libkeccak_state_wipe (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_state_wipe_sponge.3 b/doc/man/libkeccak_state_wipe_sponge.3 deleted file mode 100644 index 4651fc0..0000000 --- a/doc/man/libkeccak_state_wipe_sponge.3 +++ /dev/null @@ -1,35 +0,0 @@ -.TH LIBKECCAK_STATE_WIPE_SPONGE 3 LIBKECCAK -.SH NAME -libkeccak_state_wipe_sponge - Securely erase the Keccak sponge state -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_state_wipe_sponge(libkeccak_state_t *\fIstate\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_state_wipe_sponge () -function securely erases the state of the Keccak sponge. -.SH RETURN VALUES -The -.BR libkeccak_state_wipe_sponge () -function does not return any value. -.SH ERRORS -The -.BR libkeccak_state_wipe_sponge () -function cannot fail. -.SH SEE ALSO -.BR libkeccak_state_wipe_message (3), -.BR libkeccak_state_wipe (3), -.BR libkeccak_state_fast_destroy (3), -.BR libkeccak_state_destroy (3), -.BR libkeccak_state_reset (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_unhex.3 b/doc/man/libkeccak_unhex.3 deleted file mode 100644 index 93cde63..0000000 --- a/doc/man/libkeccak_unhex.3 +++ /dev/null @@ -1,53 +0,0 @@ -.TH LIBKECCAK_UNHEX 3 LIBKECCAK -.SH NAME -libkeccak_unhex - Converts a hexadecimal hashsum to binary -.SH SYNOPSIS -.LP -.nf -#include -.P -void -libkeccak_unhex(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_unhex () -function -converts a hexadecimal hashsum, stored in -.IR hashsum , -to binary, and stores the binary representation in -.IR output . -.PP -.I hashsum -must be terminated by a NUL-character. It may be -in either lowercase or uppercase, or a mixture -thereof. -.I output -will not be terminated. -.PP -(\fBstrlen\fP(\fIhashsum\fP) / 2) bytes will be -written to the beginning of -.IR Ioutput . -It should therefore have an allocation of at least -that number of bytes. -.SH RETURN VALUES -The -.BR libkeccak_unhex () -function does return any value. -.SH ERRORS -The -.BR libkeccak_unhex () -function cannot fail. -.SH NOTES -.I hashsum -must have an even number of digits -(characters excluding the terminating NUL-character.) -.SH SEE ALSO -.BR libkeccak_behex_lower (3), -.BR libkeccak_behex_upper (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/doc/man/libkeccak_update.3 b/doc/man/libkeccak_update.3 deleted file mode 100644 index d83f74b..0000000 --- a/doc/man/libkeccak_update.3 +++ /dev/null @@ -1,95 +0,0 @@ -.TH LIBKECCAK_UPDATE 3 LIBKECCAK -.SH NAME -libkeccak_update - Partially hash a message with erasure -.SH SYNOPSIS -.LP -.nf -#include -.P -int -libkeccak_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, - size_t \fImsglen\fP); -.fi -.P -Link with -.IR -lkeccak . -.SH DESCRIPTION -The -.BR libkeccak_update () -function continues (or starts) hashing a message. -The current state of the hashing is stored in -.IR *state , -and will be updated. The message specified by the -.I msg -parameter with the byte-size specified by the -.I msglen -parameter, will be hashed. -.PP -The -.BR libkeccak_update () -function may reallocate the state's message chunk buffer. -When doing so, it attempts to do so as securely as possible, -rather than as fast as possible. -.SH RETURN VALUES -The -.BR libkeccak_update () -function returns 0 upon successful completion. On error, --1 is returned and -.I errno -is set to describe the error. -.SH ERRORS -The -.BR libkeccak_update () -function may fail for any reason specified by the function -.BR malloc (3). -.SH NOTES -Neither parameter by be -.I NULL -or 0. -.SH EXAMPLE -This example calculates the Keccak[b = 1024, c = 576, n = 256] -hash of the input from stdin, and prints the hash, in hexadecimal -form, to stdout. -.LP -.nf -libkeccak_state_t state; -libkeccak_spec_t spec; -char binhash[256 / 8]; -char hexhash[256 / 8 * 2 + 1]; -char chunk[4 << 10]; -ssize_t len; - -spec.bitrate = 1024; -spec.capacity = 576; -spec.output = 256; -if (libkeccak_state_initialise(&state, &spec) < 0) - goto fail; - -for (;;) { - len = read(STDIN_FILENO, chunk, sizeof(chunk)); - - if ((len < 0) && (errno == EINTR)) - continue; - if (len < 0) - goto fail; - if (len == 0) - break; - - if (libkeccak_update(&state, chunk, (size_t)len) < 0) - goto fail; -} -if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0) - goto fail; - -libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); -printf("%s\\n", hexhash); -libkeccak_state_destroy(&state); -.fi -.SH SEE ALSO -.BR libkeccak_state_initialise (3), -.BR libkeccak_fast_update (3), -.BR libkeccak_fast_digest (3), -.BR libkeccak_digest (3) -.SH BUGS -Please report bugs to https://github.com/maandree/libkeccak/issues or to -maandree@kth.se diff --git a/libkeccak.h b/libkeccak.h new file mode 100644 index 0000000..7c71801 --- /dev/null +++ b/libkeccak.h @@ -0,0 +1,13 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_H +#define LIBKECCAK_H 1 + +#include "libkeccak/spec.h" +#include "libkeccak/generalised-spec.h" +#include "libkeccak/state.h" +#include "libkeccak/digest.h" +#include "libkeccak/hex.h" +#include "libkeccak/files.h" +#include "libkeccak/mac/hmac.h" + +#endif diff --git a/libkeccak.texinfo b/libkeccak.texinfo new file mode 100644 index 0000000..7640da9 --- /dev/null +++ b/libkeccak.texinfo @@ -0,0 +1,403 @@ +\input texinfo @c -*-texinfo-*- +@c %**start of header +@documentencoding UTF-8 +@iftex +@macro e{a} +(@email{\a\}) +@end macro +@end iftex +@ifnottex +@macro e{a} +@email{\a\} +@end macro +@end ifnottex +@copying +@c -------------------------------------------------------------------------------- +Copyright @copyright{} 2015, 2017 @w{Mattias Andrée @e{maandree@@kth.se}} + +@quotation +Permission to use, copy, modify, and/or distribute this document for any purpose +with or without fee is hereby granted, provided that the above copyright notice +and this permission notice appear in all copies. +@end quotation +@c -------------------------------------------------------------------------------- +@end copying + + +@setfilename libkeccak.info +@settitle libkeccak -- Library for the Keccak-family hash functions +@documentlanguage en_GB +@finalout +@frenchspacing on +@afourpaper + +@c @paragraphindent asis +@c @firstparagraphindent none +@c @exampleindent asis + +@dircategory Libraries +@direntry +* libkeccak: (libkeccak). Library for the Keccak-family hash functions. +@end direntry + +@documentdescription +Developer reference manual for libkeccak, a library +for hashing with Keccak, SHA-3 RawSHAKE and SHAKE, +with support for bit-oriented data. +@end documentdescription +@c %**end of header + + + +@ifnottex +@node Top +@top libkeccak -- Library for the Keccak-family hash functions +@insertcopying +@end ifnottex + +@titlepage +@title libkeccak +@subtitle Library for the Keccak-family hash functions + +@author by Mattias Andrée (maandree) + +@page +@center `Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! Kecak! …' +@vskip 0pt plus 1filll +@insertcopying +@end titlepage + +@contents + + + +@menu +* Overview:: Brief overview of libkeccak. +* Linking:: How to use libkeccak in your software. +* Selecting hash function:: Selecting and tuning the function. +* State of the hashing:: The structure used to keep track of the hashing process. +* Hashing messages:: Functions used to hash a message. +* Hexadecimal hashes:: Converting between binary and hexadecimal. +* Hashing files:: Functions used to hash entire files. +* Message authentication:: Functions used for message authentication codes. +* Examples:: Examples of how to use libkeccak. + +* Concept index:: Index of concepts. +* Data type index:: Index of data types. +* Function index:: Index of functions. +@end menu + + + +@node Overview +@chapter Overview + +@cpindex Orientation +libkeccak is a free software bit-oriented implementation +of the cryptographic hash function Keccak and its subsets +SHA-3 (Secure Hash Algorithm@tie{}3), RawSHAKE and SHAKE. + +Being bit-oriented means that it supports messages of length +consisting of a non-whole number of bytes. + +@cpindex Uses +Keccak is a generic and tunable cryptographic hash function +that can be used for all customary tasks that required a +cryptographic hash function: +@itemize @bullet{} +@item +Password verification@footnote{Using additional squeezes, but not using iterated hashing.} +@item +Proof-of-work +@item +File and data identification +@item +Data integrity +@item +Pseudorandom number generation@footnote{Although not too random, since entropi is not utilised.} +@item +Key derivation +@end itemize + +libkeccak support secure erasure of sensitive data, +marshalling of hashing state, and indefinite output length. +It also has builting functions for hashing files and +wrapping the hash functions with HMAC@footnote{Although +doing so is unnecessary because the key can securely be +prepended to the message when using Keccak to produce +a message authentication code.}. This library implements +the Keccak algorithm using a lanewise implementation. + +@cpindex Limitations +This implementation is limited to state sizes up to, +and including, 1600 bits. + + + +@node Linking +@chapter Linking + +@cpindex Compiling +libkeccak's API is C standard library independent. This means +that libkeccak does not need to be compiled with the same +C standard library as software using it. However, the header +files contain @code{__attributes__}:s for GCC, therefore it +can be beneficial to use GCC, however any C99 compiler will work. + +@cpindex @command{pkg-config} +@cpindex Linking +Because of libkeccak's simplicity it does not have a pkg-config +file. Instead, you only need to specify the flag @code{-lkeccak} +when linking your binaries. No flags are required during compilation +(of object files.) + +To make libkeccak's API available, include the header file +@file{} in your source files. + + + +@node Selecting hash function +@chapter Selecting hash function + +@cpindex Parameters +@cpindex Tuning +Keccak-based hash functions have three parameters: +@itemize @bullet{} +@item +the bitrate, +@item +the capacity, and +@item +the output size. +@end itemize +@noindent +Selecting these is the first step when using the library. + +@tpindex libkeccak_spec_t +@tpindex struct libkeccak_spec +The structure @code{libkeccak_spec_t} (@code{struct libkeccak_spec}), +is to specify these parameters. For the less tunable functions +SHA-3, RawSHAKE and SHAKE, these values can be set with the functions +@table @code +@item libkeccak_spec_sha3 +@fnindex libkeccak_spec_sha3 +@cpindex SHA-3 +@cpindex Secure Hash Algorithm 3 +Sets the parameters for SHA-3. It has two parameters: +@itemize @bullet{} +@item +Pointer to the @code{libkeccak_spec_t} where the settings shall be stored. +@item +The output size, that is the value appended to the name. +@end itemize + +@item libkeccak_spec_rawshake +@fnindex libkeccak_spec_rawshake +@cpindex RawSHAKE +Sets the parameters for RawSHAKE (or SHAKE). It has three parameters: +@itemize @bullet{} +@item +Pointer to the @code{libkeccak_spec_t} where the settings shall be stored. +@item +The semicapacity, that is the value appended to the name. +@item +The output size. +@end itemize + +@item libkeccak_spec_shake +@fnindex libkeccak_spec_shake +@cpindex SHAKE +Identical to @code{libkeccak_spec_rawshake}. Intended for SHAKE +rather than RawSHAKE. +@end table + +@fnindex libkeccak_spec_check +@cpindex Keccak +For Keccak, these values shall be selected individually by hand. +Once the values have been selected, they can be checked for errors +with the function @code{libkeccak_spec_check}. It takes a pointer +to the specifications as its only parameters and returns zero if +there are no errors. If however there are errors, one of the values, +with somewhat self-explanatory names,@footnote{Their meaning is +documented in the header file @file{}.} will +be returned: +@itemize @bullet{} +@item +@code{LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE} +@item +@code{LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8} +@item +@code{LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE} +@item +@code{LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8} +@item +@code{LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE} +@item +@code{LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE} +@item +@code{LIBKECCAK_SPEC_ERROR_STATE_MOD_25} +@item +@code{LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT} +@item +@code{LIBKECCAK_SPEC_ERROR_WORD_MOD_8} +@end itemize + +@tpindex libkeccak_spec_t +@tpindex struct libkeccak_spec +@code{libkeccak_spec_t}'s members are: +@table @code +@item bitrate +The bitrate, in bits. +@item capacity +The capacity, in bits. +@item output +The output size, in bits. +@end table + +@tpindex libkeccak_generalised_spec_t +@tpindex struct libkeccak_generalised_spec +It is also possible to select some but not all of the parameters. +For this, the structure @code{libkeccak_generalised_spec_t} +(@code{struct libkeccak_generalised_spec}) is used. It extends +@code{libkeccak_spec_t} with two additional parameters +@table @code +@item state_size +The state size, in bits. +@item word_size +The word size, in bits. +@end table + +@fnindex libkeccak_generalised_spec_initialise +By feeding a pointer to a @code{libkeccak_generalised_spec_t}, +to the function @code{libkeccak_generalised_spec_initialise}, +all its members are set to @code{LIBKECCAK_GENERALISED_SPEC_AUTOMATIC}, +a sentinel value that specifies that the parameter shall be +set automatically, to its default that depends on the other +parameters. + +Once the members of a @code{libkeccak_generalised_spec_t} has +been set, it can be converted to a @code{libkeccak_spec_t}, +which is necessary for using the specifications. When doing +so, automatic values will be given a proper value. + +@fnindex libkeccak_degeneralise_spec +To do this, the function @code{libkeccak_degeneralise_spec} +is used. It takes two parameters: +@itemize @bullet{} +@item +Input pointer to the @code{libkeccak_generalised_spec_t}. +@item +Output pointer to a @code{libkeccak_spec_t}. +@end itemize +@noindent +On success, zero is returned, otherwise one of the values, with +somewhat self-explanatory names,@footnote{Their meaning is documented +in the header file @file{}.} will be +returned: +@itemize @bullet{} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8} +@item +@code{LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE} +@end itemize + + + +@node State of the hashing +@chapter State of the hashing + +@tpindex libkeccak_state_t +@tpindex struct libkeccak_state +@cpindex Hashing +@cpindex State +Hashing of a message is done by feeding segments of the +message to functions until all of the message has been +processed, and than the users may repeat the last phase +any number of times. Because functions are called multiple +times, the state of the process need to be stored in +a state structure. The structure used in libkeccak to +keep track of the state is called @code{libkeccak_state_t} +(@code{struct libkeccak_state}). + +@fnindex libkeccak_state_initialise +@cpindex Initialise +Before you can use the functions for hashing a message, +you must allocate a state and initialise it. +To initialise a state, use the function +@code{libkeccak_state_initialise}. Its first argument +should be a pointer to the state variable, that is, +a @code{libkeccak_state_t*}. The second argument should +be a pointer to the specifications, that is, a +@code{const libkeccak_spec_t*}, see @ref{Selecting hash function}. +@code{libkeccak_state_initialise} till return zero +upon successful completion, and otherwise set +@code{errno} to describe the error and return @code{-1}. + +@fnindex libkeccak_state_destroy +@fnindex libkeccak_state_fast_destroy +@fnindex libkeccak_state_wipe +@fnindex libkeccak_state_wipe_sponge +@fnindex libkeccak_state_wipe_message +@cpindex Cleanup +Once done with a state structure, you should release +allocated resources that are stored in the structure. +This can be done either by calling the function +@code{libkeccak_state_destroy} or by calling the function +@code{libkeccak_state_fast_destroy}. These two functions +are almost identical, both takes a pointer to the +state as its only parameter, and neither return a value. +However, @code{libkeccak_state_fast_destroy} will only +release allocations used by the state; @code{libkeccak_state_destroy} +will also securely release all sensitive information +in the state, by calling the function @code{libkeccak_state_wipe}: +the state of the sponge, by calling the function +@code{libkeccak_state_wipe_sponge}, and the message +buffer, by calling the function @code{libkeccak_state_wipe_message}. +@code{libkeccak_state_wipe}, @code{libkeccak_state_wipe_sponge} +and @code{libkeccak_state_wipe_message} takes a +pointer to the state as their only parameter, and +none of them have a return value. + +@fnindex libkeccak_state_reset +@cpindex Reuse +An alternative to destroying a state, you can reset +it if you want to reuse it to hash another message +using the same hashing function specifications. +This is done by calling @code{libkeccak_state_reset} +instead of @code{libkeccak_state_fast_destroy}. +It takes a pointer to the state as its only parameter +and does not return a value. + +@cpindex Initialise +@cpindex Cleanup +@cpindex Allocation +If you want to use dynamic instead of static allocation +for the state, instead of calling @code{malloc} and +@code{free} yourself, libkeccak offers functions that +does this for you: +@table @code +@item libkeccak_state_create +@fnindex libkeccak_state_create +@fnindex libkeccak_state_initialise +Identical to @code{libkeccak_state_initialise}, except +it does have the first parameter, but it has the second +parameter (the specifications). It returns a pointer +to the allocate state upon successful completion, and diff --git a/libkeccak/digest.c b/libkeccak/digest.c new file mode 100644 index 0000000..26a2587 --- /dev/null +++ b/libkeccak/digest.c @@ -0,0 +1,596 @@ +/* See LICENSE file for copyright and license details. */ +#include "digest.h" + +#include "state.h" + + + +/** + * X-macro-enabled listing of all intergers in [0, 4] + */ +#define LIST_5 X(0) X(1) X(2) X(3) X(4) + +/** + * X-macro-enabled listing of all intergers in [0, 7] + */ +#define LIST_8 LIST_5 X(5) X(6) X(7) + +/** + * X-macro-enabled listing of all intergers in [0, 23] + */ +#define LIST_24 LIST_8 X(8) X(9) X(10) X(11) X(12) X(13) X(14) X(15)\ + X(16) X(17) X(18) X(19) X(20) X(21) X(22) X(23) + +/** + * X-macro-enabled listing of all intergers in [0, 24] + */ +#define LIST_25 LIST_24 X(24) + + + +#define X(N) (N % 5) * 5 + N / 5, +/** + * The order the lanes should be read when absorbing or squeezing, + * it transposes the lanes in the sponge + */ +static const long LANE_TRANSPOSE_MAP[] = { LIST_25 }; +#undef X + + + +/** + * Keccak-f round constants + */ +static const uint_fast64_t RC[] = { + 0x0000000000000001ULL, 0x0000000000008082ULL, 0x800000000000808AULL, 0x8000000080008000ULL, + 0x000000000000808BULL, 0x0000000080000001ULL, 0x8000000080008081ULL, 0x8000000000008009ULL, + 0x000000000000008AULL, 0x0000000000000088ULL, 0x0000000080008009ULL, 0x000000008000000AULL, + 0x000000008000808BULL, 0x800000000000008BULL, 0x8000000000008089ULL, 0x8000000000008003ULL, + 0x8000000000008002ULL, 0x8000000000000080ULL, 0x000000000000800AULL, 0x800000008000000AULL, + 0x8000000080008081ULL, 0x8000000000008080ULL, 0x0000000080000001ULL, 0x8000000080008008ULL +}; + + +/** + * Rotate a word + * + * @param x:int_fast64_t The value to rotate + * @param n:long Rotation steps, may be zero mod `w` + * @param w:long `state->w` + * @param wmod:int_fast64_t `state->wmod` + * @return :int_fast64_t The value rotated + */ +#define rotate(x, n, w, wmod) ((((x) >> ((w) - ((n) % (w)))) | ((x) << ((n) % (w)))) & (wmod)) + + +/** + * Rotate a 64-bit word + * + * @param x:int_fast64_t The value to rotate + * @param n:long Rotation steps, may not be zero + * @return :int_fast64_t The value rotated + */ +#define rotate64(x, n) ((int_fast64_t)(((uint64_t)(x) >> (64L - (n))) | ((uint64_t)(x) << (n)))) + + +/** + * Perform one round of computation + * + * @param state The hashing state + * @param rc The round contant for this round + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, hot))) +static void +libkeccak_f_round(register libkeccak_state_t *restrict state, register int_fast64_t rc) +{ + int_fast64_t *restrict A = state->S; + int_fast64_t B[25]; + int_fast64_t C[5]; + int_fast64_t da, db, dc, dd, de; + int_fast64_t wmod = state->wmod; + long w = state->w; + + /* θ step (step 1 of 3). */ +#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; + LIST_5; +#undef X + + /* θ step (step 2 of 3). */ + da = C[4] ^ rotate(C[1], 1, w, wmod); + dd = C[2] ^ rotate(C[4], 1, w, wmod); + db = C[0] ^ rotate(C[2], 1, w, wmod); + de = C[3] ^ rotate(C[0], 1, w, wmod); + dc = C[1] ^ rotate(C[3], 1, w, wmod); + + /* ρ and π steps, with last two part of θ. */ +#define X(bi, ai, dv, r) B[bi] = rotate(A[ai] ^ dv, r, w, wmod) + B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); + X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); + X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); + X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); + X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); +#undef X + + /* ξ step. */ +#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); + LIST_25; +#undef X + + /* ι step. */ + A[0] ^= rc; +} + + +/** + * 64-bit word version of `libkeccak_f_round` + * + * @param state The hashing state + * @param rc The round contant for this round + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, hot))) +static void +libkeccak_f_round64(register libkeccak_state_t *restrict state, register int_fast64_t rc) +{ + int_fast64_t *restrict A = state->S; + int_fast64_t B[25]; + int_fast64_t C[5]; + int_fast64_t da, db, dc, dd, de; + + /* θ step (step 1 of 3). */ +#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; + LIST_5; +#undef X + + /* θ step (step 2 of 3). */ + da = C[4] ^ rotate64(C[1], 1); + dd = C[2] ^ rotate64(C[4], 1); + db = C[0] ^ rotate64(C[2], 1); + de = C[3] ^ rotate64(C[0], 1); + dc = C[1] ^ rotate64(C[3], 1); + + /* ρ and π steps, with last two part of θ. */ +#define X(bi, ai, dv, r) B[bi] = rotate64(A[ai] ^ dv, r) + B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); + X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); + X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); + X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); + X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); +#undef X + + /* ξ step. */ +#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); + LIST_25; +#undef X + + /* ι step. */ + A[0] ^= rc; +} + + +/** + * Convert a chunk of bytes to a lane + * + * @param state The hashing state + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, gnu_inline))) +static inline void +libkeccak_f(register libkeccak_state_t *restrict state) +{ + register long i = 0; + register long nr = state->nr; + register long wmod = state->wmod; + if (nr == 24) { + for (; i < nr; i++) + libkeccak_f_round64(state, (int_fast64_t)(RC[i])); + } else { + for (; i < nr; i++) + libkeccak_f_round(state, (int_fast64_t)(RC[i] & wmod)); + } +} + + +/** + * Convert a chunk of bytes to a lane + * + * @param message The message + * @param msglen The length of the message + * @param rr Bitrate in bytes + * @param ww Word size in bytes + * @param off The offset in the message + * @return The lane + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, pure, warn_unused_result, gnu_inline))) +static inline int_fast64_t +libkeccak_to_lane(register const char *restrict message, register size_t msglen, + register long rr, register long ww, size_t off) +{ + register long n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); + int_fast64_t rc = 0; + message += off; + while (ww--) { + rc <<= 8; + rc |= __builtin_expect(ww < n, 1) ? (int_fast64_t)(unsigned char)(message[ww]) : 0L; + } + return rc; +} + + +/** + * 64-bit lane version of `libkeccak_to_lane` + * + * @param message The message + * @param msglen The length of the message + * @param rr Bitrate in bytes + * @param off The offset in the message + * @return The lane + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, pure, hot, warn_unused_result, gnu_inline))) +static inline int_fast64_t +libkeccak_to_lane64(register const char* restrict message, register size_t msglen, + register long rr, size_t off) +{ + register long n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); + int_fast64_t rc = 0; + message += off; +#define X(N) if (__builtin_expect(N < n, 1)) rc |= (int_fast64_t)(unsigned char)(message[N]) << (N * 8);\ + else return rc; + LIST_8; +#undef X + return rc; +} + + +/** + * pad 10*1 + * + * @param state The hashing state, `state->M` and `state->mptr` will be updated, + * `state->M` should have `state->r / 8` bytes left over at the end + * @param bits The number of bits in the end of the message that does not make a whole byte + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, gnu_inline))) +static inline void +libkeccak_pad10star1(register libkeccak_state_t *restrict state, register size_t bits) +{ + register size_t r = (size_t)(state->r); + register size_t nrf = state->mptr - !!bits; + register size_t len = (nrf << 3) | bits; + register size_t ll = len % r; + register char b = (char)(bits ? (state->M[nrf] | (1 << bits)) : 1); + + if (r - 8 <= ll && ll <= r - 2) { + state->M[nrf] = (char)(b ^ 0x80); + state->mptr = nrf + 1; + } else { + len = ++nrf << 3; + len = (len - (len % r) + (r - 8)) >> 3; + state->mptr = len + 1; + + state->M[nrf - 1] = b; + __builtin_memset(state->M + nrf, 0, (len - nrf) * sizeof(char)); + state->M[len] = (char)0x80; + } +} + + +/** + * Perform the absorption phase + * + * @param state The hashing state + * @param len The number of bytes from `state->M` to absorb + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) +static void +libkeccak_absorption_phase(register libkeccak_state_t *restrict state, register size_t len) +{ + register long rr = state->r >> 3; + register long ww = state->w >> 3; + register long n = (long)len / rr; + register const char* restrict message = state->M; + if (__builtin_expect(ww >= 8, 1)) { /* ww > 8 is impossible, it is just for optimisation possibilities. */ + while (n--) { +#define X(N) state->S[N] ^= libkeccak_to_lane64(message, len, rr, (size_t)(LANE_TRANSPOSE_MAP[N] * 8)); + LIST_25; +#undef X + libkeccak_f(state); + message += (size_t)rr; + len -= (size_t)rr; + } + } else { + while (n--) { +#define X(N) state->S[N] ^= libkeccak_to_lane(message, len, rr, ww, (size_t)(LANE_TRANSPOSE_MAP[N] * ww)); + LIST_25; +#undef X + libkeccak_f(state); + message += (size_t)rr; + len -= (size_t)rr; + } + } +} + + +/** + * Perform the squeezing phase + * + * @param state The hashing state + * @param rr The bitrate in bytes + * @param nn The output size in bytes, rounded up to whole bytes + * @param ww The word size in bytes + * @param hashsum Output parameter for the hashsum + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, hot))) +static void +libkeccak_squeezing_phase(register libkeccak_state_t *restrict state, long rr, + long nn, long ww, register char *restrict hashsum) +{ + register int_fast64_t v; + register long ni = rr / ww; + auto long olen = state->n; + auto long i, j = 0; + register long k; + while (olen > 0) { + for (i = 0; i < ni && j < nn; i++) { + v = state->S[LANE_TRANSPOSE_MAP[i]]; + for (k = 0; k++ < ww && j++ < nn; v >>= 8) + *hashsum++ = (char)v; + } + if (olen -= state->r, olen > 0) + libkeccak_f(state); + } + if (state->n & 7) + hashsum[-1] &= (char)((1 << (state->n & 7)) - 1); +} + + +/** + * Absorb more of the message to the Keccak sponge + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message + * @return Zero on success, -1 on error + */ +int +libkeccak_fast_update(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen) +{ + size_t len; + auto char *restrict new; + + if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { + state->mlen += msglen; + new = realloc(state->M, state->mlen * sizeof(char)); + if (!new) + return state->mlen -= msglen, -1; + state->M = new; + } + + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + len = state->mptr; + len -= state->mptr % (size_t)((state->r * state->b) >> 3); + state->mptr -= len; + + libkeccak_absorption_phase(state, len); + __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); + + return 0; +} + + +/** + * Absorb more of the message to the Keccak sponge + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message + * @return Zero on success, -1 on error + */ +int +libkeccak_update(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen) +{ + size_t len; + auto char *restrict new; + + if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { + state->mlen += msglen; + new = malloc(state->mlen * sizeof(char)); + if (new == NULL) + return state->mlen -= msglen, -1; + libkeccak_state_wipe_message(state); + free(state->M); + state->M = new; + } + + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + len = state->mptr; + len -= state->mptr % (size_t)((state->r * state->b) >> 3); + state->mptr -= len; + + libkeccak_absorption_phase(state, len); + __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); + + return 0; +} + + +/** + * Absorb the last part of the message and squeeze the Keccak sponge + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL` + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_fast_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum) +{ + auto char *restrict new; + register long rr = state->r >> 3; + auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; + register size_t ext; + register long i; + + if (msg == NULL) + msglen = bits = 0; + else + msglen += bits >> 3, bits &= 7; + + ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; + if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { + state->mlen += ext; + new = realloc(state->M, state->mlen * sizeof(char)); + if (!new) + return state->mlen -= ext, -1; + state->M = new; + } + + if (msglen) + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + + if (bits) + state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); + if (__builtin_expect(!!suffix_len, 1)) { + if (bits == 0) + state->M[state->mptr] = 0; + while (suffix_len--) { + state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); + if (bits == 8) + bits = 0, state->M[++(state->mptr)] = 0; + } + } + if (bits) + state->mptr++; + + libkeccak_pad10star1(state, bits); + libkeccak_absorption_phase(state, state->mptr); + + if (hashsum) { + libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); + } else { + for (i = (state->n - 1) / state->r; i--;) + libkeccak_f(state); + } + + return 0; +} + + +/** + * Absorb the last part of the message and squeeze the Keccak sponge + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL` + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum) +{ + auto char *restrict new; + register long rr = state->r >> 3; + auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; + register size_t ext; + register long i; + + if (msg == NULL) + msglen = bits = 0; + else + msglen += bits >> 3, bits &= 7; + + ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; + if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { + state->mlen += ext; + new = malloc(state->mlen * sizeof(char)); + if (!new) + return state->mlen -= ext, -1; + libkeccak_state_wipe_message(state); + free(state->M); + state->M = new; + } + + if (msglen) + __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); + state->mptr += msglen; + + if (bits) + state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); + if (__builtin_expect(!!suffix_len, 1)) { + if (bits == 0) + state->M[state->mptr] = 0; + while (suffix_len--) { + state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); + if (bits == 8) + bits = 0, state->M[++(state->mptr)] = 0; + } + } + if (bits) + state->mptr++; + + libkeccak_pad10star1(state, bits); + libkeccak_absorption_phase(state, state->mptr); + + if (hashsum) { + libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); + } else { + for (i = (state->n - 1) / state->r; i--;) + libkeccak_f(state); + } + + return 0; +} + + +/** + * Force some rounds of Keccak-f + * + * @param state The hashing state + * @param times The number of rounds + */ +void +libkeccak_simple_squeeze(register libkeccak_state_t *restrict state, register long times) +{ + while (times--) + libkeccak_f(state); +} + + +/** + * Squeeze as much as is needed to get a digest a number of times + * + * @param state The hashing state + * @param times The number of digests + */ +void +libkeccak_fast_squeeze(register libkeccak_state_t *restrict state, register long times) +{ + times *= (state->n - 1) / state->r + 1; + while (times--) + libkeccak_f(state); +} + + +/** + * Squeeze out another digest + * + * @param state The hashing state + * @param hashsum Output parameter for the hashsum + */ +void +libkeccak_squeeze(register libkeccak_state_t *restrict state, register char* restrict hashsum) +{ + libkeccak_f(state); + libkeccak_squeezing_phase(state, state->r >> 3, (state->n + 7) >> 3, state->w >> 3, hashsum); +} diff --git a/libkeccak/digest.h b/libkeccak/digest.h new file mode 100644 index 0000000..832f0c0 --- /dev/null +++ b/libkeccak/digest.h @@ -0,0 +1,100 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_DIGEST_H +#define LIBKECCAK_DIGEST_H 1 + +#include "state.h" +#include "internal.h" + + +/** + * Absorb more of the message to the Keccak sponge + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) +int libkeccak_fast_update(libkeccak_state_t *restrict state, const char* restrict msg, size_t msglen); + + +/** + * Absorb more of the message to the Keccak sponge + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) +int libkeccak_update(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen); + + +/** + * Absorb the last part of the message and squeeze the Keccak sponge + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL` + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) +int libkeccak_fast_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum); + + +/** + * Absorb the last part of the message and squeeze the Keccak sponge + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL` + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) +int libkeccak_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum); + + +/** + * Force some rounds of Keccak-f + * + * @param state The hashing state + * @param times The number of rounds + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) +void libkeccak_simple_squeeze(register libkeccak_state_t *restrict state, register long times); + + +/** + * Squeeze as much as is needed to get a digest a number of times + * + * @param state The hashing state + * @param times The number of digests + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) +void libkeccak_fast_squeeze(register libkeccak_state_t *restrict state, register long times); + + +/** + * Squeeze out another digest + * + * @param state The hashing state + * @param hashsum Output parameter for the hashsum + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) +void libkeccak_squeeze(register libkeccak_state_t *restrict state, register char* restrict hashsum); + + +#endif + diff --git a/libkeccak/files.c b/libkeccak/files.c new file mode 100644 index 0000000..22d12f3 --- /dev/null +++ b/libkeccak/files.c @@ -0,0 +1,57 @@ +/* See LICENSE file for copyright and license details. */ +#include "files.h" + +#include +#include +#include +#include +#include + + + +/** + * Calculate a Keccak-family hashsum of a file, + * the content of the file is assumed non-sensitive + * + * @param fd The file descriptor of the file to hash + * @param state The hashing state, should not be initialised (memory leak otherwise) + * @param spec Specifications for the hashing algorithm + * @param suffix The data suffix, see `libkeccak_digest` + * @param hashsum Output array for the hashsum, have an allocation size of + * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_generalised_sum_fd(int fd, libkeccak_state_t *restrict state, + const libkeccak_spec_t *restrict spec, + const char *restrict suffix, char *restrict hashsum) +{ + ssize_t got; + struct stat attr; + size_t blksize = 4096; + char *restrict chunk; + + if (libkeccak_state_initialise(state, spec) < 0) + return -1; + + if (fstat(fd, &attr) == 0) + if (attr.st_blksize > 0) + blksize = (size_t)(attr.st_blksize); + + chunk = alloca(blksize); + + for (;;) { + got = read(fd, chunk, blksize); + if (got < 0) { + if (errno == EINTR) + continue; + return -1; + } + if (got == 0) + break; + if (libkeccak_fast_update(state, chunk, (size_t)got) < 0) + return -1; + } + + return libkeccak_fast_digest(state, NULL, 0, 0, suffix, hashsum); +} diff --git a/libkeccak/files.h b/libkeccak/files.h new file mode 100644 index 0000000..92038fb --- /dev/null +++ b/libkeccak/files.h @@ -0,0 +1,115 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_FILES_H +#define LIBKECCAK_FILES_H 1 + +#include "../libkeccak.h" +#include "internal.h" + + +/** + * Calculate a Keccak-family hashsum of a file, + * the content of the file is assumed non-sensitive + * + * @param fd The file descriptor of the file to hash + * @param state The hashing state, should not be initialised (memory leak otherwise) + * @param spec Specifications for the hashing algorithm + * @param suffix The data suffix, see `libkeccak_digest` + * @param hashsum Output array for the hashsum, have an allocation size of + * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2, 3)))) +int libkeccak_generalised_sum_fd(int fd, libkeccak_state_t *restrict state, + const libkeccak_spec_t *restrict spec, + const char *restrict suffix, char *restrict hashsum); + + +/** + * Calculate the Keccak hashsum of a file, + * the content of the file is assumed non-sensitive + * + * @param fd The file descriptor of the file to hash + * @param state The hashing state, should not be initialised (memory leak otherwise) + * @param spec Specifications for the hashing algorithm + * @param hashsum Output array for the hashsum, have an allocation size of + * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2, 3), artificial, gnu_inline))) +static inline int +libkeccak_keccaksum_fd(int fd, libkeccak_state_t *restrict state, + const libkeccak_spec_t *restrict spec, char *restrict hashsum) +{ + return libkeccak_generalised_sum_fd(fd, state, spec, NULL, hashsum); +} + + +/** + * Calculate the SHA3 hashsum of a file, + * the content of the file is assumed non-sensitive + * + * @param fd The file descriptor of the file to hash + * @param state The hashing state, should not be initialised (memory leak otherwise) + * @param output The output size parameter for the hashing algorithm + * @param hashsum Output array for the hashsum, have an allocation size of + * at least `((output + 7) / 8) * sizeof(char)`, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2), artificial, gnu_inline))) +static inline int +libkeccak_sha3sum_fd(int fd, libkeccak_state_t *restrict state, + long output, char *restrict hashsum) +{ + libkeccak_spec_t spec; + libkeccak_spec_sha3(&spec, output); + return libkeccak_generalised_sum_fd(fd, state, &spec, LIBKECCAK_SHA3_SUFFIX, hashsum); +} + + +/** + * Calculate the RawSHAKE hashsum of a file, + * the content of the file is assumed non-sensitive + * + * @param fd The file descriptor of the file to hash + * @param state The hashing state, should not be initialised (memory leak otherwise) + * @param semicapacity The semicapacity parameter for the hashing algorithm + * @param output The output size parameter for the hashing algorithm + * @param hashsum Output array for the hashsum, have an allocation size of + * at least `((output + 7) / 8) * sizeof(char)`, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2), artificial, gnu_inline))) +static inline int +libkeccak_rawshakesum_fd(int fd, libkeccak_state_t *restrict state, + long semicapacity, long output, char *restrict hashsum) +{ + libkeccak_spec_t spec; + libkeccak_spec_rawshake(&spec, semicapacity, output); + return libkeccak_generalised_sum_fd(fd, state, &spec, LIBKECCAK_RAWSHAKE_SUFFIX, hashsum); +} + + +/** + * Calculate the SHAKE hashsum of a file, + * the content of the file is assumed non-sensitive + * + * @param fd The file descriptor of the file to hash + * @param state The hashing state, should not be initialised (memory leak otherwise) + * @param semicapacity The semicapacity parameter for the hashing algorithm + * @param output The output size parameter for the hashing algorithm + * @param hashsum Output array for the hashsum, have an allocation size of + * at least `((output + 7) / 8) * sizeof(char)`, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2), artificial, gnu_inline))) +static inline int +libkeccak_shakesum_fd(int fd, libkeccak_state_t *restrict state, + long semicapacity, long output, char *restrict hashsum) +{ + libkeccak_spec_t spec; + libkeccak_spec_shake(&spec, semicapacity, output); + return libkeccak_generalised_sum_fd(fd, state, &spec, LIBKECCAK_SHAKE_SUFFIX, hashsum); +} + + +#endif diff --git a/libkeccak/generalised-spec.c b/libkeccak/generalised-spec.c new file mode 100644 index 0000000..9dfa918 --- /dev/null +++ b/libkeccak/generalised-spec.c @@ -0,0 +1,111 @@ +/* See LICENSE file for copyright and license details. */ +#include "generalised-spec.h" + +#ifdef __GNUC__ +# pragma GCC diagnostic push +# pragma GCC diagnostic ignored "-Wmaybe-uninitialized" +#endif + +#define have(v) (spec->v != LIBKECCAK_GENERALISED_SPEC_AUTOMATIC) +#define copy(v) (v = spec->v) +#define deft(v, dv) (have_##v ? v : (dv)) + + + +/** + * Convert a `libkeccak_generalised_spec_t` to a `libkeccak_spec_t` + * + * If you are interrested in finding errors, you should call + * `libkeccak_spec_check(output)` if this function returns zero + * + * @param spec The generalised input specifications, will be update with resolved automatic values + * @param output_spec The specification datastructure to fill in + * @return Zero if `spec` is valid, a `LIBKECCAK_GENERALISED_SPEC_ERROR_*` if an error was found + */ +int +libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *restrict spec, + libkeccak_spec_t *restrict output_spec) +{ + long state_size, word_size, capacity, bitrate, output; + const int have_state_size = have(state_size); + const int have_word_size = have(word_size); + const int have_capacity = have(capacity); + const int have_bitrate = have(bitrate); + const int have_output = have(output); + + + if (have_state_size) { + copy(state_size); + if (state_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE; + if (state_size > 1600) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE; + if (state_size % 25) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25; + } + + if (have_word_size) { + copy(word_size); + if (word_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE; + if (word_size > 64) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE; + if (have_state_size && state_size != word_size * 25) + return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY; + else if (!have_state_size) + spec->state_size = 1, state_size = word_size * 25; + } + + if (have_capacity) { + copy(capacity); + if (capacity <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE; + if (capacity & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8; + } + + if (have_bitrate) { + copy(bitrate); + if (bitrate <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE; + if (bitrate & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8; + } + + if (have_output) { + copy(output); + if (output <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE; + } + + + if (!have_bitrate && !have_capacity && !have_output) { + state_size = deft(state_size, 1600L); + output = ((state_size << 5) / 100L + 7L) & ~0x07L; + bitrate = output << 1; + capacity = state_size - bitrate; + output = output >= 8 ? output : 8; + } else if (!have_bitrate && !have_capacity) { + bitrate = 1024; + capacity = 1600 - 1024; + state_size = deft(state_size, bitrate + capacity); + } else if (!have_bitrate) { + state_size = deft(state_size, 1600L); + bitrate = state_size - capacity; + output = deft(output, capacity == 8 ? 8 : (capacity << 1)); + } else if (!have_capacity) { + state_size = deft(state_size, 1600L); + capacity = state_size - bitrate; + output = deft(output, capacity == 8 ? 8 : (capacity << 1)); + } else { + state_size = deft(state_size, bitrate + capacity); + output = deft(output, capacity == 8 ? 8 : (capacity << 1)); + } + + spec->capacity = output_spec->capacity = capacity; + spec->bitrate = output_spec->bitrate = bitrate; + spec->output = output_spec->output = output; + spec->state_size = state_size; + spec->word_size = state_size / 25; + + return 0; +} + + +#undef deft +#undef copy +#undef have + +#ifdef __GNUC__ +# pragma GCC diagnostic pop +#endif diff --git a/libkeccak/generalised-spec.h b/libkeccak/generalised-spec.h new file mode 100644 index 0000000..2725961 --- /dev/null +++ b/libkeccak/generalised-spec.h @@ -0,0 +1,142 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_GENERALISED_SPEC_H +#define LIBKECCAK_GENERALISED_SPEC_H 1 + +#include "spec.h" +#include "internal.h" + +#include + + + +/** + * Value for `libkeccak_generalised_spec_t` member that + * is used to automatically select the value + */ +#define LIBKECCAK_GENERALISED_SPEC_AUTOMATIC (-65536L) + + +/** + * Invalid `libkeccak_generalised_spec_t.state_size`: non-positive + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE 1 + +/** + * Invalid `libkeccak_generalised_spec_t.state_size`: larger than 1600 + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE 2 + +/** + * Invalid `libkeccak_generalised_spec_t.state_size`: not a multiple of 25 + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25 3 + +/** + * Invalid `libkeccak_generalised_spec_t.word_size`: non-positive + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE 4 + +/** + * Invalid `libkeccak_generalised_spec_t.word_size`: larger than 1600 / 25 + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE 5 + +/** + * Invalid `libkeccak_generalised_spec_t.word_size` and + * `libkeccak_generalised_spec_t.state_size`: `.word_size * 25 != .state_size` + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY 6 + +/** + * Invalid `libkeccak_generalised_spec_t.capacity`: non-positive + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE 7 + +/** + * Invalid `libkeccak_generalised_spec_t.capacity`: not a multiple of 8 + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8 8 + +/** + * Invalid `libkeccak_generalised_spec_t.bitrate`: non-positive + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE 9 + +/** + * Invalid `libkeccak_generalised_spec_t.bitrate`: not a multiple of 8 + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8 10 + +/** + * Invalid `libkeccak_generalised_spec_t.output`: non-positive + */ +#define LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE 11 + + + +/** + * Generalised datastructure that describes the + * parameters that should be used when hashing + */ +typedef struct libkeccak_generalised_spec +{ + /** + * The bitrate + */ + long bitrate; + + /** + * The capacity + */ + long capacity; + + /** + * The output size + */ + long output; + + /** + * The state size + */ + long state_size; + + /** + * The word size + */ + long word_size; + +} libkeccak_generalised_spec_t; + + + +/** + * Set all specification parameters to automatic + * + * @param spec The specification datastructure to fill in + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused))) +static inline void +libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *restrict spec) +{ + spec->bitrate = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; + spec->capacity = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; + spec->output = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; + spec->state_size = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; + spec->word_size = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; +} + + +/** + * Convert a `libkeccak_generalised_spec_t` to a `libkeccak_spec_t` + * + * @param spec The generalised input specifications, will be update with resolved automatic values + * @param output_spec The specification datastructure to fill in + * @return Zero if `spec` is valid, a `LIBKECCAK_GENERALISED_SPEC_ERROR_*` if an error was found + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) +int libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *restrict spec, + libkeccak_spec_t *restrict output_spec); + + +#endif + diff --git a/libkeccak/hex.c b/libkeccak/hex.c new file mode 100644 index 0000000..7531223 --- /dev/null +++ b/libkeccak/hex.c @@ -0,0 +1,65 @@ +/* See LICENSE file for copyright and license details. */ +#include "hex.h" + +#include + + + +/** + * Convert a binary hashsum to lower case hexadecimal representation + * + * @param output Output array, should have an allocation size of at least `2 * n + 1` + * @param hashsum The hashsum to convert + * @param n The size of `hashsum` + */ +void +libkeccak_behex_lower(char *restrict output, const char *restrict hashsum, size_t n) +{ + output[2 * n] = '\0'; + while (n--) { + output[2 * n + 0] = "0123456789abcdef"[(hashsum[n] >> 4) & 15]; + output[2 * n + 1] = "0123456789abcdef"[(hashsum[n] >> 0) & 15]; + } +} + + +/** + * Convert a binary hashsum to upper case hexadecimal representation + * + * @param output Output array, should have an allocation size of at least `2 * n + 1` + * @param hashsum The hashsum to convert + * @param n The size of `hashsum` + */ +void +libkeccak_behex_upper(char *restrict output, const char *restrict hashsum, size_t n) +{ + output[2 * n] = '\0'; + while (n--) { + output[2 * n + 0] = "0123456789ABCDEF"[(hashsum[n] >> 4) & 15]; + output[2 * n + 1] = "0123456789ABCDEF"[(hashsum[n] >> 0) & 15]; + } +} + + +/** + * Convert a hexadecimal hashsum (both lower case, upper + * case and mixed is supported) to binary representation + * + * @param output Output array, should have an allocation size of at least `strlen(hashsum) / 2` + * @param hashsum The hashsum to convert + */ +void +libkeccak_unhex(char *restrict output, const char *restrict hashsum) +{ + size_t n = strlen(hashsum) / 2; + char a, b; + while (n--) { + a = hashsum[2 * n + 0]; + b = hashsum[2 * n + 1]; + + a = (char)((a & 15) + (a > '9' ? 9 : 0)); + b = (char)((b & 15) + (b > '9' ? 9 : 0)); + + output[n] = (char)((a << 4) | b); + } +} diff --git a/libkeccak/hex.h b/libkeccak/hex.h new file mode 100644 index 0000000..25375d5 --- /dev/null +++ b/libkeccak/hex.h @@ -0,0 +1,44 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_HEX_H +#define LIBKECCAK_HEX_H 1 + +#include "internal.h" + +#include + + +/** + * Convert a binary hashsum to lower case hexadecimal representation + * + * @param output Output array, should have an allocation size of at least `2 * n + 1` + * @param hashsum The hashsum to convert + * @param n The size of `hashsum` + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) +void libkeccak_behex_lower(char *restrict output, const char *restrict hashsum, size_t n); + + +/** + * Convert a binary hashsum to upper case hexadecimal representation + * + * @param output Output array, should have an allocation size of at least `2 * n + 1` + * @param hashsum The hashsum to convert + * @param n The size of `hashsum` + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) +void libkeccak_behex_upper(char *restrict output, const char *restrict hashsum, size_t n); + + +/** + * Convert a hexadecimal hashsum (both lower case, upper + * case and mixed is supported) to binary representation + * + * @param output Output array, should have an allocation size of at least `strlen(hashsum) / 2` + * @param hashsum The hashsum to convert + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) +void libkeccak_unhex(char *restrict output, const char *restrict hashsum); + + +#endif + diff --git a/libkeccak/internal.h b/libkeccak/internal.h new file mode 100644 index 0000000..466abf9 --- /dev/null +++ b/libkeccak/internal.h @@ -0,0 +1,26 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_INTERNAL_H +#define LIBKECCAK_INTERNAL_H 1 + + +/** + * Only include some C code (not for CPP directives) + * if compiling with GCC. + */ +#ifdef __GNUC__ +# define LIBKECCAK_GCC_ONLY(x) x +#else +# define LIBKECCAK_GCC_ONLY(x) +#endif + + +/* Use built in functions and branching optimisation if available */ +#ifndef __GNUC__ +# define __builtin_expect(expression, expect) expression +# define __builtin_memset(dest, c, n) memset(dest, c, n) +# define __builtin_memcpy(dest, src, n) memcpy(dest, src, n) +# define __builtin_memmove(dest, src, n) memmove(dest, src, n) +#endif + + +#endif diff --git a/libkeccak/mac/hmac.c b/libkeccak/mac/hmac.c new file mode 100644 index 0000000..ee3bc6a --- /dev/null +++ b/libkeccak/mac/hmac.c @@ -0,0 +1,418 @@ +/* See LICENSE file for copyright and license details. */ +#include "hmac.h" + +#include "../digest.h" + + + +/** + * The outer pad pattern + */ +#define OUTER_PAD 0x5C + +/** + * The inner pad pattern + */ +#define INNER_PAD 0x36 + + + +static void *(*volatile my_explicit_memset)(void *, int, size_t) = memset; +static __attribute__((optimize("-O0"))) void +my_explicit_bzero(void *ptr, size_t size) +{ + (*my_explicit_memset)(ptr, 0, size); +} + + +/** + * Change the HMAC-hashing key on the state + * + * @param state The state that should be reset + * @param key The new key + * @param key_length The length of key, in bits + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_set_key(libkeccak_hmac_state_t *restrict state, const char *restrict key, size_t key_length) +{ + size_t i, size, new_key_length, key_bytes; + char *old; + + size = (size_t)(state->sponge.r) > key_length ? (size_t)(state->sponge.r) : key_length; + new_key_length = size; + size = (size + 7) >> 3; + key_bytes = (key_length + 7) >> 3; + + if (size != key_bytes) { + state->key_opad = realloc(old = state->key_opad, 2 * size); + if (!state->key_opad) + return state->key_opad = old, -1; + state->key_ipad = state->key_opad + size / sizeof(char); + } + + memcpy(state->key_opad, key, key_bytes); + if (key_length & 7) + state->key_opad[(key_bytes >> 3) - 1] &= (1 << (key_length & 7)) - 1; + + if ((size_t)(state->sponge.r) > key_length) + __builtin_memset(state->key_opad + key_bytes / sizeof(char), 0, size - key_bytes); + + for (i = 0; i < size; i++) { + state->key_ipad[i] = state->key_opad[i] ^ INNER_PAD; + state->key_opad[i] ^= OUTER_PAD; + } + + state->key_length = new_key_length; + + return 0; +} + + +/** + * Wipe sensitive data wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_hmac_wipe(volatile libkeccak_hmac_state_t *restrict state) +{ + volatile char *restrict key_pads; + size_t i, size; + key_pads = state->key_opad; + size = 2 * ((state->key_length + 7) >> 3); + libkeccak_state_wipe(&state->sponge); + for (i = 0; i < size; i++) + key_pads[i] = 0; + state->leftover = 0; + __builtin_memset(state->buffer, 0, state->buffer_size); +} + + +/** + * Make a copy of an HMAC hashing-state + * + * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) + * @param src The state to duplicate + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_copy(libkeccak_hmac_state_t *restrict dest, const libkeccak_hmac_state_t *restrict src) +{ + size_t size; + + dest->key_opad = NULL; + dest->key_ipad = NULL; + + if (libkeccak_state_copy(&dest->sponge, &src->sponge) < 0) + return -1; + + dest->key_length = src->key_length; + dest->leftover = src->leftover; + + size = (src->key_length + 7) >> 3; + dest->key_opad = malloc(2 * size); + if (dest->key_opad == NULL) + return libkeccak_state_destroy(&dest->sponge), -1; + dest->key_ipad = dest->key_opad + size / sizeof(char); + + memcpy(dest->key_opad, src->key_opad, size); + memcpy(dest->key_ipad, src->key_ipad, size); + + return 0; +} + + +/** + * Unmarshal a `libkeccak_hmac_state_t` from a buffer + * + * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) + * @param data The input buffer + * @return The number of bytes read from `data`, 0 on error + */ +size_t +libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *restrict state, const char *restrict data) +{ + size_t parsed, size, i; + + state->key_opad = NULL; + state->key_ipad = NULL; + + parsed = libkeccak_state_unmarshal(&state->sponge, data); + if (parsed == 0) + return 0; + + data += parsed / sizeof(char); + state->key_length = *(const size_t *)data; + data += sizeof(size_t) / sizeof(char); + size = (state->key_length + 7) >> 3; + + state->key_opad = malloc(2 * size); + if (state->key_opad == NULL) + return libkeccak_state_destroy(&state->sponge), -1; + memcpy(state->key_opad, data, size); + data += size / sizeof(char); + + if (data[0]) { + state->key_ipad = state->key_opad + size / sizeof(char); + memcpy(state->key_ipad, state->key_opad, size); + for (i = 0; i < size / sizeof(char); i++) + state->key_ipad[i] ^= (char)(OUTER_PAD ^ INNER_PAD); + } + + state->leftover = data[1]; + state->buffer = NULL; + state->buffer_size = 0; + + return parsed + sizeof(size_t) + size + 2 * sizeof(char); +} + + +/** + * Absorb more, or the first part, of the message + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message, in bytes + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_fast_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen) +{ + char *old; + size_t i; + int n, cn; + + if (state->key_ipad) { + if (libkeccak_fast_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) + return -1; + if (state->key_length & 7) + state->leftover = state->key_ipad[state->key_length >> 3]; + state->key_ipad = NULL; + } + + if (!msg || !msglen) + return 0; + + if (!(state->key_length & 7)) + return libkeccak_fast_update(&state->sponge, msg, msglen); + + if (msglen != state->buffer_size) { + state->buffer = realloc(old = state->buffer, msglen); + if (!state->buffer) + return state->buffer = old, -1; + state->buffer_size = msglen; + } + + n = (int)(state->key_length & 7); + cn = 8 - n; + for (i = 1; i < msglen; i++) + state->buffer[i] = (((unsigned char)(msg[i - 1])) >> cn) | (msg[i] << n); + state->buffer[0] = (state->leftover & ((1 << n) - 1)) | (msg[0] << n); + state->leftover = ((unsigned char)(msg[msglen - 1])) >> cn; + + return libkeccak_fast_update(&state->sponge, state->buffer, msglen); +} + + +/** + * Absorb more, or the first part, of the message + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message, in bytes + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen) +{ + size_t i; + int n, cn, r; + + if (state->key_ipad) { + if (libkeccak_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) + return -1; + if (state->key_length & 7) + state->leftover = state->key_ipad[state->key_length >> 3]; + state->key_ipad = NULL; + } + + if (!msg || !msglen) + return 0; + + if (!(state->key_length & 7)) + return libkeccak_update(&state->sponge, msg, msglen); + + if (msglen != state->buffer_size) { + free(state->buffer); + state->buffer = malloc(state->buffer_size = msglen); + if (!state->buffer) + return -1; + } + + n = (int)(state->key_length & 7); + cn = 8 - n; + for (i = 1; i < msglen; i++) + state->buffer[i] = (((unsigned char)(msg[i - 1])) >> cn) | (msg[i] << n); + state->buffer[0] = (state->leftover & ((1 << n) - 1)) | (msg[0] << n); + state->leftover = ((unsigned char)(msg[msglen - 1])) >> cn; + + r = libkeccak_update(&state->sponge, state->buffer, msglen); + my_explicit_bzero(state->buffer, msglen); + return r; +} + + +/** + * Absorb the last part of the message and fetch the hash + * without wiping sensitive data when possible + * + * You may use `&state->sponge` for continued squeezing + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL`, may be modified + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum) +{ + size_t hashsize = state->sponge.n >> 3; + char *tmp = malloc(((state->sponge.n + 7) >> 3) * sizeof(char)); + char leftover[2]; + size_t newlen; + + if (!tmp) + return -1; + + if (!(state->key_length & 7)) { + if (libkeccak_fast_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) + goto fail; + goto stage_2; + } + + if (libkeccak_hmac_fast_update(state, msg, msglen) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= msg[msglen] >> (state->key_length & 7); + leftover[1] = ((unsigned char)(msg[msglen])) << (8 - (state->key_length & 7)); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_2: + bits = state->sponge.n & 7; + state->key_ipad = state->key_opad; + if (libkeccak_hmac_fast_update(state, NULL, 0) < 0) + goto fail; + + if (!(state->key_length & 7)) { + if (libkeccak_fast_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) + goto fail; + goto stage_3; + } + + if (libkeccak_hmac_fast_update(state, tmp, hashsize) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= tmp[hashsize] >> (state->key_length & 7); + leftover[1] = ((unsigned char)(tmp[hashsize])) << (8 - (state->key_length & 7)); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_3: + free(tmp); + return 0; +fail: + free(tmp); + return -1; +} + + +/** + * Absorb the last part of the message and fetch the hash + * and wipe sensitive data when possible + * + * You may use `&state->sponge` for continued squeezing + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL`, may be modified + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +int +libkeccak_hmac_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum) +{ + size_t hashsize = state->sponge.n >> 3; + char *tmp = malloc(((state->sponge.n + 7) >> 3) * sizeof(char)); + char leftover[2]; + size_t newlen; + + if (!tmp) + return -1; + + if (!(state->key_length & 7)) { + if (libkeccak_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) + goto fail; + goto stage_2; + } + + if (libkeccak_hmac_update(state, msg, msglen) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= msg[msglen] >> (state->key_length & 7); + leftover[1] = ((unsigned char)(msg[msglen])) << (8 - (state->key_length & 7)); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_2: + bits = state->sponge.n & 7; + state->key_ipad = state->key_opad; + if (libkeccak_hmac_update(state, NULL, 0) < 0) + goto fail; + + if (!(state->key_length & 7)) { + if (libkeccak_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) + goto fail; + goto stage_3; + } + + if (libkeccak_hmac_update(state, tmp, hashsize) < 0) + goto fail; + leftover[0] = state->leftover; + if (bits) { + leftover[0] |= tmp[hashsize] >> (state->key_length & 7); + leftover[1] = ((unsigned char)(tmp[hashsize])) << (8 - (state->key_length & 7)); + } + newlen = (state->key_length & 7) + bits; + if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) + goto fail; + +stage_3: + my_explicit_bzero(tmp, ((state->sponge.n + 7) >> 3) * sizeof(char)); + free(tmp); + return 0; + fail: + my_explicit_bzero(tmp, ((state->sponge.n + 7) >> 3) * sizeof(char)); + free(tmp); + return -1; +} + diff --git a/libkeccak/mac/hmac.h b/libkeccak/mac/hmac.h new file mode 100644 index 0000000..2681e61 --- /dev/null +++ b/libkeccak/mac/hmac.h @@ -0,0 +1,393 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_MAC_HMAC_H +#define LIBKECCAK_MAC_HMAC_H 1 + +/* + * The Keccak hash-function, that was selected by NIST as the SHA-3 competition winner, + * doesn't need this nested approach and can be used to generate a MAC by simply prepending + * the key to the message. [http://keccak.noekeon.org] + */ + +#include "../spec.h" +#include "../state.h" +#include "../internal.h" + +#include +#include +#include +#include +#include + + + +/** + * Datastructure that describes the state of an HMAC-hashing process + */ +typedef struct libkeccak_hmac_state +{ + /** + * The key right-padded and XOR:ed with the outer pad + */ + char *restrict key_opad; + + /** + * The key right-padded and XOR:ed with the inner pad + */ + char *restrict key_ipad; + /* Not marshalled, implicitly unmarshalled using `key_opad`. */ + /* Shares allocation with `key_opad`, do not `free`. */ + + /** + * The length of key, but at least the input block size, in bits + */ + size_t key_length; + + /** + * The state of the underlaying hash-algorithm + */ + libkeccak_state_t sponge; + + /** + * Buffer used to temporarily store bit shift message if + * `.key_length` is not zero modulus 8 + */ + char *restrict buffer; + + /** + * The allocation size of `.buffer` + */ + size_t buffer_size; + + /** + * Part of feed key, message or digest that have not been passed yet + */ + char leftover; + + char __pad[sizeof(void*) / sizeof(char) - 1]; + +} libkeccak_hmac_state_t; + + + +/** + * Change the HMAC-hashing key on the state + * + * @param state The state that should be reset + * @param key The new key + * @param key_length The length of key, in bits + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1), unused))) +int libkeccak_hmac_set_key(libkeccak_hmac_state_t *restrict state, const char *restrict key, size_t key_length); + + +/** + * Initialise an HMAC hashing-state according to hashing specifications + * + * @param state The state that should be initialised + * @param spec The specifications for the state + * @param key The key + * @param key_length The length of key, in bits + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) +static inline int +libkeccak_hmac_initialise(libkeccak_hmac_state_t *restrict state, const libkeccak_spec_t *restrict spec, + const char *restrict key, size_t key_length) +{ + if (libkeccak_state_initialise(&state->sponge, spec) < 0) + return -1; + if (libkeccak_hmac_set_key(state, key, key_length) < 0) + return libkeccak_state_destroy(&state->sponge), -1; + state->leftover = 0; + state->buffer = NULL; + state->buffer_size = 0; + return 0; +} + + +/** + * Wrapper for `libkeccak_hmac_initialise` that also allocates the states + * + * @param spec The specifications for the state + * @param key The key + * @param key_length The length of key, in bits + * @return The state, `NULL` on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) +static inline libkeccak_hmac_state_t * +libkeccak_hmac_create(const libkeccak_spec_t *restrict spec, + const char *restrict key, size_t key_length) +{ + libkeccak_hmac_state_t *restrict state = malloc(sizeof(libkeccak_hmac_state_t)); + if (!state || libkeccak_hmac_initialise(state, spec, key, key_length)) + return free(state), NULL; + return state; +} + + +/** + * Reset an HMAC-hashing state according to hashing specifications, + * you can choose whether to change the key + * + * @param state The state that should be reset + * @param key The new key, `NULL` to keep the old key + * @param key_length The length of key, in bits, ignored if `key == NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1), unused))) +static inline int +libkeccak_hmac_reset(libkeccak_hmac_state_t *restrict state, const char *restrict key, size_t key_length) +{ + libkeccak_state_reset(&state->sponge); + return key ? libkeccak_hmac_set_key(state, key, key_length) : 0; +} + + +/** + * Wipe sensitive data wihout freeing any data + * + * @param state The state that should be wipe + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, optimize("-O0")))) +void libkeccak_hmac_wipe(volatile libkeccak_hmac_state_t *restrict state); + + +/** + * Release resources allocation for an HMAC hashing-state without wiping sensitive data + * + * @param state The state that should be destroyed + */ +static inline void +libkeccak_hmac_fast_destroy(libkeccak_hmac_state_t *restrict state) +{ + if (!state) + return; + free(state->key_opad); + state->key_opad = NULL; + state->key_ipad = NULL; + state->key_length = 0; + free(state->buffer); + state->buffer = NULL; + state->buffer_size = 0; +} + + +/** + * Release resources allocation for an HMAC hasing-state and wipe sensitive data + * + * @param state The state that should be destroyed + */ +LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) +static inline void +libkeccak_hmac_destroy(volatile libkeccak_hmac_state_t *restrict state) +{ + if (!state) + return; + libkeccak_hmac_wipe(state); + free(state->key_opad); + state->key_opad = NULL; + state->key_ipad = NULL; + state->key_length = 0; + state->leftover = 0; + free(state->buffer); + state->buffer = NULL; + state->buffer_size = 0; +} + + +/** + * Wrapper for `libkeccak_fast_destroy` that also frees the allocation of the state + * + * @param state The state that should be freed + */ +LIBKECCAK_GCC_ONLY(__attribute__((unused))) +static inline void +libkeccak_hmac_fast_free(libkeccak_hmac_state_t *restrict state) +{ + libkeccak_hmac_fast_destroy(state); + free(state); +} + + +/** + * Wrapper for `libkeccak_hmac_destroy` that also frees the allocation of the state + * + * @param state The state that should be freed + */ +LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) +static inline void +libkeccak_hmac_free(volatile libkeccak_hmac_state_t *restrict state) +{ +#ifdef __GNUC__ +# pragma GCC diagnostic push +# pragma GCC diagnostic ignored "-Wcast-qual" +#endif + libkeccak_hmac_destroy(state); + free((libkeccak_hmac_state_t*)state); +#ifdef __GNUC__ +# pragma GCC diagnostic pop +#endif +} + + +/** + * Make a copy of an HMAC hashing-state + * + * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) + * @param src The state to duplicate + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) +int libkeccak_hmac_copy(libkeccak_hmac_state_t *restrict dest, const libkeccak_hmac_state_t *restrict src); + + +/** + * A wrapper for `libkeccak_hmac_copy` that also allocates the duplicate + * + * @param src The state to duplicate + * @return The duplicate, `NULL` on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) +static inline libkeccak_hmac_state_t * +libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *restrict src) +{ + libkeccak_hmac_state_t* restrict dest = malloc(sizeof(libkeccak_hmac_state_t)); + if (!dest || libkeccak_hmac_copy(dest, src)) + return libkeccak_hmac_free(dest), NULL; + return dest; +} + + +/** + * Calculates the allocation size required for the second argument + * of `libkeccak_hmac_marshal` (`char* restrict data)`) + * + * @param state The state as it will be marshalled by a subsequent call to `libkeccak_hamc_marshal` + * @return The allocation size needed for the buffer to which the state will be marshalled + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused, warn_unused_result, pure))) +static inline size_t +libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *restrict state) +{ + return libkeccak_state_marshal_size(&state->sponge) + sizeof(size_t) + + ((state->key_length + 7) >> 3) + 2 * sizeof(char); +} + + +/** + * Marshal a `libkeccak_hmac_state_t` into a buffer + * + * @param state The state to marshal + * @param data The output buffer + * @return The number of bytes stored to `data` + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) +static inline size_t +libkeccak_hmac_marshal(const libkeccak_hmac_state_t *restrict state, char *restrict data) +{ + size_t written = libkeccak_state_marshal(&state->sponge, data); + data += written / sizeof(char); + *(size_t *)data = state->key_length; + data += sizeof(size_t) / sizeof(char); + memcpy(data, state->key_opad, (state->key_length + 7) >> 3); + data += ((state->key_length + 7) >> 3) / sizeof(char); + data[0] = (char)!!state->key_ipad; + data[1] = state->leftover; + return written + sizeof(size_t) + ((state->key_length + 7) >> 3) + 2 * sizeof(char); +} + + +/** + * Unmarshal a `libkeccak_hmac_state_t` from a buffer + * + * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) + * @param data The input buffer + * @return The number of bytes read from `data`, 0 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) +size_t libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *restrict state, const char *restrict data); + + +/** + * Gets the number of bytes the `libkeccak_hmac_state_t` stored + * at the beginning of `data` occupies + * + * @param data The data buffer + * @return The byte size of the stored state + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, warn_unused_result, pure))) +static inline size_t +libkeccak_hmac_unmarshal_skip(const char *restrict data) +{ + size_t skip = libkeccak_state_unmarshal_skip(data); + data += skip / sizeof(char); + return skip + sizeof(size_t) + *(const size_t *)data + 2 * sizeof(char); +} + + +/** + * Absorb more, or the first part, of the message + * without wiping sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message, in bytes + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) +int libkeccak_hmac_fast_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen); + + +/** + * Absorb more, or the first part, of the message + * and wipe sensitive data when possible + * + * @param state The hashing state + * @param msg The partial message + * @param msglen The length of the partial message, in bytes + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) +int libkeccak_hmac_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen); + + +/** + * Absorb the last part of the message and fetch the hash + * without wiping sensitive data when possible + * + * You may use `&state->sponge` for continued squeezing + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL`, may be modified + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) +int libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum); + + +/** + * Absorb the last part of the message and fetch the hash + * and wipe sensitive data when possible + * + * You may use `&state->sponge` for continued squeezing + * + * @param state The hashing state + * @param msg The rest of the message, may be `NULL`, may be modified + * @param msglen The length of the partial message + * @param bits The number of bits at the end of the message not covered by `msglen` + * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination + * @param hashsum Output parameter for the hashsum, may be `NULL` + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) +int libkeccak_hmac_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, + size_t bits, const char *restrict suffix, char *restrict hashsum); + + +#endif diff --git a/libkeccak/spec.h b/libkeccak/spec.h new file mode 100644 index 0000000..8d73c52 --- /dev/null +++ b/libkeccak/spec.h @@ -0,0 +1,177 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_SPEC_H +#define LIBKECCAK_SPEC_H 1 + +#include "internal.h" + +#include +#include + + +/** + * Message suffix for SHA3 hashing + */ +#define LIBKECCAK_SHA3_SUFFIX "01" + +/** + * Message suffix for RawSHAKE hashing + */ +#define LIBKECCAK_RAWSHAKE_SUFFIX "11" + +/** + * Message suffix for SHAKE hashing + */ +#define LIBKECCAK_SHAKE_SUFFIX "1111" + + +/** + * Invalid `libkeccak_spec_t.bitrate`: non-positive + */ +#define LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE 1 + +/** + * Invalid `libkeccak_spec_t.bitrate`: not a multiple of 8 + */ +#define LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 2 + +/** + * Invalid `libkeccak_spec_t.capacity`: non-positive + */ +#define LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE 3 + +/** + * Invalid `libkeccak_spec_t.capacity`: not a multiple of 8 + */ +#define LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 4 + +/** + * Invalid `libkeccak_spec_t.output`: non-positive + */ +#define LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE 5 + +/** + * Invalid `libkeccak_spec_t` values: `.bitrate + `.capacity` + * is greater 1600 which is the largest supported state size + */ +#define LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE 6 + +/** + * Invalid `libkeccak_spec_t` values: + * `.bitrate + `.capacity` is not a multiple of 25 + */ +#define LIBKECCAK_SPEC_ERROR_STATE_MOD_25 7 + +/** + * Invalid `libkeccak_spec_t` values: `.bitrate + `.capacity` + * is a not a 2-potent multiple of 25 + */ +#define LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT 8 + +/** + * Invalid `libkeccak_spec_t` values: `.bitrate + `.capacity` + * is a not multiple of 100, and thus the word size is not + * a multiple of 8 + */ +#define LIBKECCAK_SPEC_ERROR_WORD_MOD_8 9 + + + +/** + * Datastructure that describes the parameters + * that should be used when hashing + */ +typedef struct libkeccak_spec { + /** + * The bitrate + */ + long bitrate; + + /** + * The capacity + */ + long capacity; + + /** + * The output size + */ + long output; + +} libkeccak_spec_t; + + + +/** + * Fill in a `libkeccak_spec_t` for a SHA3-x hashing + * + * @param spec The specifications datastructure to fill in + * @param x The value of x in `SHA3-x`, the output size + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) +static inline void +libkeccak_spec_sha3(libkeccak_spec_t *restrict spec, long x) +{ + spec->bitrate = 1600 - 2 * x; + spec->capacity = 2 * x; + spec->output = x; +} + + +/** + * Fill in a `libkeccak_spec_t` for a RawSHAKEx hashing + * + * @param spec The specifications datastructure to fill in + * @param x The value of x in `RawSHAKEx`, half the capacity + * @param d The output size + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) +static inline void +libkeccak_spec_rawshake(libkeccak_spec_t *restrict spec, long x, long d) +{ + spec->bitrate = 1600 - 2 * x; + spec->capacity = 2 * x; + spec->output = d; +} + + +/** + * Fill in a `libkeccak_spec_t` for a SHAKEx hashing + * + * @param spec:libkeccak_spec_t* The specifications datastructure to fill in + * @param x:long The value of x in `SHAKEx`, half the capacity + * @param d:long The output size + */ +#define libkeccak_spec_shake libkeccak_spec_rawshake + + +/** + * Check for errors in a `libkeccak_spec_t` + * + * @param spec The specifications datastructure to check + * @return Zero if error free, a `LIBKECCAK_SPEC_ERROR_*` if an error was found + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused, warn_unused_result, pure))) +static inline int +libkeccak_spec_check(const libkeccak_spec_t *restrict spec) +{ + long state_size = spec->capacity + spec->bitrate; + int32_t word_size = (int32_t)(state_size / 25); + if (spec->bitrate <= 0) return LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE; + if (spec->bitrate % 8) return LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8; + if (spec->capacity <= 0) return LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE; + if (spec->capacity % 8) return LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8; + if (spec->output <= 0) return LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE; + if (state_size > 1600) return LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE; + if (state_size % 25) return LIBKECCAK_SPEC_ERROR_STATE_MOD_25; + if (word_size % 8) return LIBKECCAK_SPEC_ERROR_WORD_MOD_8; + + /* `(x & -x) != x` assumes two's complement, which of course is always + * satisfied by GCC, however C99 guarantees that `int32_t` exists, + * and it is basically the same thing as `long int`; with one important + * difference: it is guaranteed to use two's complement. */ + if ((word_size & -word_size) != word_size) + return LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT; + + return 0; +} + +#endif diff --git a/libkeccak/state.c b/libkeccak/state.c new file mode 100644 index 0000000..c6360b7 --- /dev/null +++ b/libkeccak/state.c @@ -0,0 +1,175 @@ +/* See LICENSE file for copyright and license details. */ +#include "state.h" + +#include + + + +/** + * Initialise a state according to hashing specifications + * + * @param state The state that should be initialised + * @param spec The specifications for the state + * @return Zero on success, -1 on error + */ +int +libkeccak_state_initialise(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec) +{ + long x; + state->r = spec->bitrate; + state->n = spec->output; + state->c = spec->capacity; + state->b = state->r + state->c; + state->w = x = state->b / 25; + state->l = 0; + if (x & 0xF0L) state->l |= 4, x >>= 4; + if (x & 0x0CL) state->l |= 2, x >>= 2; + if (x & 0x02L) state->l |= 1; + state->nr = 12 + (state->l << 1); + state->wmod = (state->w == 64) ? ~0LL : (int64_t)((1ULL << state->w) - 1); + for (x = 0; x < 25; x++) + state->S[x] = 0; + state->mptr = 0; + state->mlen = (size_t)(state->r * state->b) >> 2; + state->M = malloc(state->mlen * sizeof(char)); + return state->M == NULL ? -1 : 0; +} + + +/** + * Wipe data in the state's message wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_state_wipe_message(volatile libkeccak_state_t *restrict state) +{ + volatile char *restrict M = state->M; + size_t i; + for (i = 0; i < state->mptr; i++) + M[i] = 0; +} + +/** + * Wipe data in the state's sponge wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_state_wipe_sponge(volatile libkeccak_state_t *restrict state) +{ + volatile int64_t *restrict S = state->S; + size_t i; + for (i = 0; i < 25; i++) + S[i] = 0; +} + +/** + * Wipe sensitive data wihout freeing any data + * + * @param state The state that should be wipe + */ +void +libkeccak_state_wipe(volatile libkeccak_state_t *restrict state) +{ + libkeccak_state_wipe_message(state); + libkeccak_state_wipe_sponge(state); +} + + +/** + * Make a copy of a state + * + * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) + * @param src The state to duplicate + * @return Zero on success, -1 on error + */ +int +libkeccak_state_copy(libkeccak_state_t *restrict dest, const libkeccak_state_t *restrict src) +{ + memcpy(dest, src, sizeof(libkeccak_state_t)); + dest->M = malloc(src->mlen * sizeof(char)); + if (!dest->M) + return -1; + memcpy(dest->M, src->M, src->mptr * sizeof(char)); + return 0; +} + + +/** + * Marshal a `libkeccak_state_t` into a buffer + * + * @param state The state to marshal + * @param data The output buffer + * @return The number of bytes stored to `data` + */ +size_t +libkeccak_state_marshal(const libkeccak_state_t *restrict state, char *restrict data) +{ +#define set(type, var) *((type *)data) = state->var, data += sizeof(type) / sizeof(char) + set(long, r); + set(long, c); + set(long, n); + set(long, b); + set(long, w); + set(int64_t, wmod); + set(long, l); + set(long, nr); + memcpy(data, state->S, sizeof(state->S)); + data += sizeof(state->S) / sizeof(char); + set(size_t, mptr); + set(size_t, mlen); + memcpy(data, state->M, state->mptr * sizeof(char)); + data += state->mptr; + return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); +#undef set +} + + +/** + * Unmarshal a `libkeccak_state_t` from a buffer + * + * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) + * @param data The input buffer + * @return The number of bytes read from `data`, 0 on error + */ +size_t +libkeccak_state_unmarshal(libkeccak_state_t *restrict state, const char *restrict data) +{ +#define get(type, var) state->var = *((const type *)data), data += sizeof(type) / sizeof(char) + get(long, r); + get(long, c); + get(long, n); + get(long, b); + get(long, w); + get(int64_t, wmod); + get(long, l); + get(long, nr); + memcpy(state->S, data, sizeof(state->S)); + data += sizeof(state->S) / sizeof(char); + get(size_t, mptr); + get(size_t, mlen); + state->M = malloc(state->mptr * sizeof(char)); + if (!state->M) + return 0; + memcpy(state->M, data, state->mptr * sizeof(char)); + data += state->mptr; + return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); +#undef get +} + + +/** + * Gets the number of bytes the `libkeccak_state_t` stored + * at the beginning of `data` occupies + * + * @param data The data buffer + * @return The byte size of the stored state + */ +size_t +libkeccak_state_unmarshal_skip(const char *restrict data) +{ + data += (7 * sizeof(long) + 26 * sizeof(int64_t)) / sizeof(char); + return sizeof(libkeccak_state_t) - sizeof(char *) + *(const size_t *)data * sizeof(char); +} + diff --git a/libkeccak/state.h b/libkeccak/state.h new file mode 100644 index 0000000..1c4b24e --- /dev/null +++ b/libkeccak/state.h @@ -0,0 +1,295 @@ +/* See LICENSE file for copyright and license details. */ +#ifndef LIBKECCAK_STATE_H +#define LIBKECCAK_STATE_H 1 + +#include "spec.h" +#include "internal.h" + +#include +#include +#include +#include +#include + + + +/** + * Datastructure that describes the state of a hashing process + * + * The `char`-size of the output hashsum is calculated by `(.n + 7) / 8` + */ +typedef struct libkeccak_state { + /** + * The lanes (state/sponge) + */ + int64_t S[25]; + + /** + * The bitrate + */ + long r; + + /** + * The capacity + */ + long c; + + /** + * The output size + */ + long n; + + /** + * The state size + */ + long b; + + /** + * The word size + */ + long w; + + /** + * The word mask + */ + int64_t wmod; + + /** + * ℓ, the binary logarithm of the word size + */ + long l; + + /** + * 12 + 2ℓ, the number of rounds + */ + long nr; + + /** + * Pointer for `M` + */ + size_t mptr; + + /** + * Size of `M` + */ + size_t mlen; + + /** + * Left over water to fill the sponge with at next update + */ + char *M; + +} libkeccak_state_t; + + + +/** + * Initialise a state according to hashing specifications + * + * @param state The state that should be initialised + * @param spec The specifications for the state + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull))) +int libkeccak_state_initialise(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec); + + +/** + * Reset a state according to hashing specifications + * + * @param state The state that should be reset + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused))) +static inline void +libkeccak_state_reset(libkeccak_state_t *restrict state) +{ + state->mptr = 0; + memset(state->S, 0, sizeof(state->S)); +} + + +/** + * Release resources allocation for a state without wiping sensitive data + * + * @param state The state that should be destroyed + */ +static inline void +libkeccak_state_fast_destroy(libkeccak_state_t *restrict state) +{ + if (state == NULL) + return; + free(state->M); + state->M = NULL; +} + + +/** + * Wipe data in the state's message wihout freeing any data + * + * @param state The state that should be wipe + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow, optimize("-O0")))) +void libkeccak_state_wipe_message(volatile libkeccak_state_t *restrict state); + +/** + * Wipe data in the state's sponge wihout freeing any data + * + * @param state The state that should be wipe + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow, optimize("-O0")))) +void libkeccak_state_wipe_sponge(volatile libkeccak_state_t *restrict state); + +/** + * Wipe sensitive data wihout freeing any data + * + * @param state The state that should be wipe + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, optimize("-O0")))) +void libkeccak_state_wipe(volatile libkeccak_state_t *restrict state); + + +/** + * Release resources allocation for a state and wipe sensitive data + * + * @param state The state that should be destroyed + */ +LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) +static inline void +libkeccak_state_destroy(volatile libkeccak_state_t *restrict state) +{ + if (!state) + return; + libkeccak_state_wipe(state); + free(state->M); + state->M = NULL; +} + + +/** + * Wrapper for `libkeccak_state_initialise` that also allocates the states + * + * @param spec The specifications for the state + * @return The state, `NULL` on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) +static inline libkeccak_state_t * +libkeccak_state_create(const libkeccak_spec_t *restrict spec) +{ + libkeccak_state_t *restrict state = malloc(sizeof(libkeccak_state_t)); + if (!state || libkeccak_state_initialise(state, spec)) + return free(state), NULL; + return state; +} + + +/** + * Wrapper for `libkeccak_state_fast_destroy` that also frees the allocation of the state + * + * @param state The state that should be freed + */ +LIBKECCAK_GCC_ONLY(__attribute__((unused))) +static inline void +libkeccak_state_fast_free(libkeccak_state_t *restrict state) +{ + libkeccak_state_fast_destroy(state); + free(state); +} + + +/** + * Wrapper for `libkeccak_state_destroy` that also frees the allocation of the state + * + * @param state The state that should be freed + */ +LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) +static inline void +libkeccak_state_free(volatile libkeccak_state_t *restrict state) +{ +#ifdef __GNUC__ +# pragma GCC diagnostic push +# pragma GCC diagnostic ignored "-Wcast-qual" +#endif + libkeccak_state_destroy(state); + free((libkeccak_state_t *)state); +#ifdef __GNUC__ +# pragma GCC diagnostic pop +#endif +} + + +/** + * Make a copy of a state + * + * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) + * @param src The state to duplicate + * @return Zero on success, -1 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull))) +int libkeccak_state_copy(libkeccak_state_t *restrict dest, const libkeccak_state_t *restrict src); + + +/** + * A wrapper for `libkeccak_state_copy` that also allocates the duplicate + * + * @param src The state to duplicate + * @return The duplicate, `NULL` on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) +static inline libkeccak_state_t * +libkeccak_state_duplicate(const libkeccak_state_t *restrict src) +{ + libkeccak_state_t *restrict dest = malloc(sizeof(libkeccak_state_t)); + if (!dest || libkeccak_state_copy(dest, src)) + return libkeccak_state_free(dest), NULL; + return dest; +} + + +/** + * Calculates the allocation size required for the second argument + * of `libkeccak_state_marshal` (`char* restrict data)`) + * + * @param state The state as it will be marshalled by a subsequent call to `libkeccak_state_marshal` + * @return The allocation size needed for the buffer to which the state will be marshalled + */ +LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused, warn_unused_result, pure))) +static inline size_t +libkeccak_state_marshal_size(const libkeccak_state_t *restrict state) +{ + return sizeof(libkeccak_state_t) - sizeof(char*) + state->mptr * sizeof(char); +} + + +/** + * Marshal a `libkeccak_state_t` into a buffer + * + * @param state The state to marshal + * @param data The output buffer + * @return The number of bytes stored to `data` + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) +size_t libkeccak_state_marshal(const libkeccak_state_t *restrict state, char *restrict data); + + +/** + * Unmarshal a `libkeccak_state_t` from a buffer + * + * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) + * @param data The input buffer + * @return The number of bytes read from `data`, 0 on error + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull))) +size_t libkeccak_state_unmarshal(libkeccak_state_t *restrict state, const char *restrict data); + + +/** + * Gets the number of bytes the `libkeccak_state_t` stored + * at the beginning of `data` occupies + * + * @param data The data buffer + * @return The byte size of the stored state + */ +LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow, warn_unused_result, pure))) +size_t libkeccak_state_unmarshal_skip(const char *restrict data); + +#endif diff --git a/man/libkeccak.7 b/man/libkeccak.7 new file mode 100644 index 0000000..0a6ef04 --- /dev/null +++ b/man/libkeccak.7 @@ -0,0 +1,70 @@ +.TH LIBKECCAK 7 LIBKECCAK +.SH NAME +libkeccak - Keccak-family hashing library +.SH DESCRIPTION +.BR libkeccak +is a bit-oriented lanewise implementation of the Keccak-family with +support for extend output size, state marshalling, algorithm tuning with +implicit parameters, secure erasure of sensitive data, and HMAC. +.SH FUTURE DIRECTION +Keccak-3200 may be implemented in the future. +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_degeneralise_spec (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_wipe_message (3), +.BR libkeccak_state_wipe_sponge (3), +.BR libkeccak_state_wipe (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_create (3), +.BR libkeccak_state_fast_free (3), +.BR libkeccak_state_free (3), +.BR libkeccak_state_copy (3), +.BR libkeccak_state_duplicate (3), +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal (3), +.BR libkeccak_state_unmarshal_skip (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_unhex (3), +.BR libkeccak_hmac_set_key (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_copy (3), +.BR libkeccak_hmac_duplicate (3), +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal (3), +.BR libkeccak_hmac_unmarshal_skip (3), +.BR libkeccak_hmac_fast_update (3), +.BR libkeccak_hmac_update (3), +.BR libkeccak_hmac_fast_digest (3), +.BR libkeccak_hmac_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_behex_lower.3 b/man/libkeccak_behex_lower.3 new file mode 100644 index 0000000..85bc843 --- /dev/null +++ b/man/libkeccak_behex_lower.3 @@ -0,0 +1,50 @@ +.TH LIBKECCAK_BEHEX_LOWER 3 LIBKECCAK +.SH NAME +libkeccak_behex_lower - Converts a binary hashsum to lowercase hexadecimal +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_behex_lower(char *restrict \fIoutput\fP, + const char *restrict \fIhashsum\fP, size_t \fIn\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_behex_lower () +function +converts a binary hashsum, stored in +.IR hashsum , +to lowercase hexadecimal, and stores the +hexadecimal representation in +.IR output . +.PP +.I output +will be terminated by a NUL-character. +.PP +The +.I n +parameter specifies the number of bytes +the binary hashsum is comprised. +.I output +needs an allocation size of (2 * +.I n ++ 1). +.SH RETURN VALUES +The +.BR libkeccak_behex_lower () +function does return any value. +.SH ERRORS +The +.BR libkeccak_behex_lower () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_behex_upper (3), +.BR libkeccak_unhex (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_behex_upper.3 b/man/libkeccak_behex_upper.3 new file mode 100644 index 0000000..7925efc --- /dev/null +++ b/man/libkeccak_behex_upper.3 @@ -0,0 +1,50 @@ +.TH LIBKECCAK_BEHEX_UPPER 3 LIBKECCAK +.SH NAME +libkeccak_behex_upper - Converts a binary hashsum to uppercase hexadecimal +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_behex_upper(char *restrict \fIoutput\fP, + const char *restrict \fIhashsum\fP, size_t \fIn\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_behex_upper () +function +converts a binary hashsum, stored in +.IR hashsum , +to uppercase hexadecimal, and stores the +hexadecimal representation in +.IR output . +.PP +.I output +will be terminated by a NUL-character. +.PP +The +.I n +parameter specifies the number of bytes +the binary hashsum is comprised. +.I output +needs an allocation size of (2 * +.I n ++ 1). +.SH RETURN VALUES +The +.BR libkeccak_behex_upper () +function does return any value. +.SH ERRORS +The +.BR libkeccak_behex_upper () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_unhex (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_degeneralise_spec.3 b/man/libkeccak_degeneralise_spec.3 new file mode 100644 index 0000000..38a1b73 --- /dev/null +++ b/man/libkeccak_degeneralise_spec.3 @@ -0,0 +1,124 @@ +.TH LIBKECCAK_DEGENERALISE_SPEC 3 LIBKECCAK +.SH NAME +libkeccak_degeneralise_spec - Set all specification parameters to automatic +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *\fIspec\fP, + libkeccak_spec_t *\fIoutput_spec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_degeneralise_spec () +function will resolve automatic parameters in +.I *spec +and translates the parameters to +.IR *output_spec , +so that it can be used for hashing. +.PP +The function will modify both +.I *spec +and +.IR *output_spec . +.PP +You should call the +.BR libkeccak_spec_check (3) +function after calling +.BR libkeccak_degeneralise_spec (). +.PP +.nf +typedef struct libkeccak_generalised_spec { + long int bitrate; /* bitrate (in bits) */ + long int capacity; /* capacity (in bits) */ + long int output; /* output size (in bits) */ + long int state_size; /* state size (in bits) */ + long int word_size; /* word size (in bits) */ +} libkeccak_generalised_spec_t; +.fi +.SH RETURN VALUES +The +.BR libkeccak_degeneralise_spec () +function returns 0 if the settings are usable. Otherwise +it will return one of the following constants. +.PP +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE +The specified state size is non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE +The specified state size exceeded the supported limit +(currently at 1600 bits.) +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25 +The specified state size, in bits, was not equivalent +to 0 modulus 25. Meaning the state size cannot +cover all lanes equivalently. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE +The specified word size is non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE +The specified word size exceeded the supported limit +(currently at 64 bits.) +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY +The specified state size is not exactly 25 times larger +than the word size. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE +The specified capacity was non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8 +The specified capacity was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE +The specified bitrate was non-positive. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8 +The specified bitrate was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE +The specified output size was non-positive. +.PP +Note that there may be more than one error. Only the first +detected is returned. +.SH ERRORS +The +.BR libkeccak_degeneralise_spec () +function cannot fail. +.fi +.SH EXAMPLE +This examples configure a +.B libkeccak_spec_t +to specify settings for Keccak[c = 512]: +.LP +.nf +int r; +libkeccak_spec_t spec; +libkeccak_generalised_spec_t gspec; +libkeccak_generalised_spec_initialise(&gspec); +gspec.capacity = 512; +if ((r = libkeccak_degeneralise_spec(&gspec, &spec))) + goto fail_degeneralise_spec; +if ((r = libkeccak_spec_check(&spec))); + goto fail_spec_check; +.fi +.SH SEE ALSO +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_digest.3 b/man/libkeccak_digest.3 new file mode 100644 index 0000000..33b0479 --- /dev/null +++ b/man/libkeccak_digest.3 @@ -0,0 +1,145 @@ +.TH LIBKECCAK_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_digest - Complete the hashing of a message with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_digest () +function absorbs the last part of (or all of) a message, +and returns the hash of the entire message. The last part +of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_update (3) +function or the +.BR libkeccak_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s +and '0':s, representing the bits that should be appended to +the message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_digest () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_digest () +function may fail for any reason specified by the function +.BR malloc (3). +.SH EXAMPLE +This example calculates the Keccak[b = 1024, c = 576, n = 256] +hash of the input from stdin, and prints the hash, in hexadecimal +form, to stdout. +.LP +.nf +libkeccak_state_t state; +libkeccak_spec_t spec; +char binhash[256 / 8]; +char hexhash[256 / 8 * 2 + 1]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_fast_digest.3 b/man/libkeccak_fast_digest.3 new file mode 100644 index 0000000..d5c55a5 --- /dev/null +++ b/man/libkeccak_fast_digest.3 @@ -0,0 +1,146 @@ +.TH LIBKECCAK_FAST_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_fast_digest - Complete the hashing of a message without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_fast_digest(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_fast_digest () +function absorbs the last part of (or all of) a message, +and returns the hash of the entire message. The last part +of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_update (3) +function or the +.BR libkeccak_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s and '0':s, +representing the bits that should be appended to the +message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.IR hashsum +is +.IR NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_fast_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.SH RETURN VALUES +The +.BR libkeccak_fast_digest () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_fast_digest () +function may fail for any reason specified by the function +.BR realloc (3). +.SH EXAMPLE +This example calculates the Keccak[b = 1024, c = 576, n = 256] +hash of the input from stdin, and prints the hash, in hexadecimal +form, to stdout. +.LP +.nf +libkeccak_state_t state; +libkeccak_spec_t spec; +char binhash[256 / 8]; +char hexhash[256 / 8 * 2 + 1]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_fast_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_fast_squeeze.3 b/man/libkeccak_fast_squeeze.3 new file mode 100644 index 0000000..d782a95 --- /dev/null +++ b/man/libkeccak_fast_squeeze.3 @@ -0,0 +1,39 @@ +.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_fast_squeeze - Runs the squeeze phase a number of times +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_fast_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_fast_squeeze () +function runs the Keccak squeeze phase, on the the hash +process described by +.IR *state , +as many times are required to get +.I times +additional digests. +.SH RETURN VALUES +The +.BR libkeccak_fast_squeeze () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_fast_squeeze () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_digest (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_fast_update.3 b/man/libkeccak_fast_update.3 new file mode 100644 index 0000000..c619e7d --- /dev/null +++ b/man/libkeccak_fast_update.3 @@ -0,0 +1,96 @@ +.TH LIBKECCAK_FAST_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_fast_update - Partially hash a message without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_fast_update () +function continues (or starts) hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_fast_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.SH RETURN VALUES +The +.BR libkeccak_fast_update () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_fast_update () +function may fail for any reason specified by the function +.BR realloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.SH EXAMPLE +This example calculates the Keccak[b = 1024, c = 576, n = 256] +hash of the input from stdin, and prints the hash, in hexadecimal +form, to stdout. +.LP +.nf +libkeccak_state_t state; +libkeccak_spec_t spec; +char binhash[256 / 8]; +char hexhash[256 / 8 * 2 + 1]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_fast_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_fast_digest(&state, NULL, 0, 0, "", binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_fast_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_generalised_spec_initialise.3 b/man/libkeccak_generalised_spec_initialise.3 new file mode 100644 index 0000000..42bd62f --- /dev/null +++ b/man/libkeccak_generalised_spec_initialise.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_GENERALISED_SPEC_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_generalised_spec_initialise - Set all specification parameters to automatic +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_generalised_spec_initialise () +function initialises +.IR *spec , +so that all parameters are configured to be +automatically selected. +.PP +Automatic selection means that value will be set +to the default, which depends on the other settings. +.PP +Specifically, all members of +.IR *spec , +will be set to +.BR LIBKECCAK_GENERALISED_SPEC_AUTOMATIC . +.SH RETURN VALUES +The +.BR libkeccak_generalised_spec_initialise () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_generalised_spec_initialise () +function cannot fail. +.fi +.SH SEE ALSO +.BR libkeccak_degeneralise_spec (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_generalised_sum_fd.3 b/man/libkeccak_generalised_sum_fd.3 new file mode 100644 index 0000000..98e6329 --- /dev/null +++ b/man/libkeccak_generalised_sum_fd.3 @@ -0,0 +1,132 @@ +.TH LIBKECCAK_GENERALISED_SUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_generalised_sum_fd - Calculate the hash of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_generalised_sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + const libkeccak_spec_t *\fIspec\fP, + const char *\fIsuffix\fP, char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_generalised_sum_fd () +function calculates the hash of a file, whose file desriptor is +specified by +.I fd +(and should be at the beginning of the file.) The hash algorithm +is specified by +.I *spec +and +.IR suffix , +where +.I *spec +is the tuning of the algorithm and +.I suffix +is the bits append to the message (or +.I NULL +if none.) +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( spec->output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_generalised_sum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_generalised_sum_fd () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_generalised_sum_fd () +function may fail for any reason, except those resulting +in +.I errno +being set to +.BR EINTR , +specified for the functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_generalised_sum_fd () +hashes the file until the end has been reached. For pipes +and sockets and this means until the file has been closed. +But for character devices, this usually means never. +Attempting to hash files in /dev is therefore usually a +bad idea. +.BR libkeccak_generalised_sum_fd () +does not check for the file length or file type before +hashing as this could limit what you can do, and make +the library more complex. +.PP +.BR libkeccak_generalised_sum_fd () +does not stop if interrupted +.RB ( read (2) +returns +.BR EINTR .) +.PP +.BR libkeccak_generalised_sum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_generalised_sum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLE +This example calculates the Keccak[b = 1024, c = 576, n = 256] +hash of the input from stdin, and prints the hash, in hexadecimal +form, to stdout. +.LP +.nf +libkeccak_state_t state; +libkeccak_spec_t spec; +char binhash[256 / 8]; +char hexhash[256 / 8 * 2 + 1]; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; + +if (libkeccak_generalised_sum_fd(STDIN_FILENO, &state, &spec, NULL, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_copy.3 b/man/libkeccak_hmac_copy.3 new file mode 100644 index 0000000..f3939f5 --- /dev/null +++ b/man/libkeccak_hmac_copy.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_HMAC_COPY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_copy - Copies an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_copy(libkeccak_hmac_state_t *\fIdest\fP, + const libkeccak_hmac_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_copy () +function initialises +.I *dest +to be identical to +.IR *src . +This includes all members of the +.B libkeccak_hmac_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_hmac_copy () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_copy () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_duplicate (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_create.3 b/man/libkeccak_hmac_create.3 new file mode 100644 index 0000000..fcb99cb --- /dev/null +++ b/man/libkeccak_hmac_create.3 @@ -0,0 +1,53 @@ +.TH LIBKECCAK_HMAC_CREATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_create - Allocate and initialise HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +libkeccak_hmac_state_t * +libkeccak_hmac_create(const libkeccak_spec_t *\fIspec\fP, const char *\fIkey\fP, + size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_create () +function allocates a new +.I libkeccak_hmac_state_t* +with one initialised element, and sets the +algorithm tuning parameters to those specified by +.IR *spec , +and the key to +.I key +of length +.IR key_length . +.SH RETURN VALUES +The +.BR libkeccak_hmac_create () +function returns a newly allocated +.I libkeccak_hmac_state_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_create () +function may fail for any specified for the functions +.BR malloc (3) +and +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_duplicate (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_destroy.3 b/man/libkeccak_hmac_destroy.3 new file mode 100644 index 0000000..2f3bbf8 --- /dev/null +++ b/man/libkeccak_hmac_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_HMAC_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_destroy - Destroys an HMAC-hashing state with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_hmac_destroy(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_hmac_destroy () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_digest.3 b/man/libkeccak_hmac_digest.3 new file mode 100644 index 0000000..66d35d4 --- /dev/null +++ b/man/libkeccak_hmac_digest.3 @@ -0,0 +1,103 @@ +.TH LIBKECCAK_HMAC_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_hmac_digest - Complete the HMAC-hashing of a message with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_digest(libkeccak_hmac_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP, size_t \fIbits\fP, const char *\fIsuffix\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_digest () +function absorbes the last part of (or all of) a message, +and returns the HMAC hash of the entire message. The last +part of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_hmac_update (3) +function or the +.BR libkeccak_hmac_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s +and '0':s, representing the bits that should be appended +to the message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_hmac_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_hmac_digest () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_digest () +function may fail for any reason specified by the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_update (3), +.BR libkeccak_hmac_fast_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_duplicate.3 b/man/libkeccak_hmac_duplicate.3 new file mode 100644 index 0000000..70c994c --- /dev/null +++ b/man/libkeccak_hmac_duplicate.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_HMAC_DUPLICATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_duplicate - Allocate a duplicate an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +libkeccak_hmac_state_t * +libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_duplicate () +function allocates a new hash state and initialises +it to be identical to +.IR *src . +This includes all members of the +.B libkeccak_hmac_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_hmac_duplicate () +function returns a newly allocated +.I libkeccak_hmac_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_duplicate () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_copy (3), +.BR libkeccak_hmac_create (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_fast_destroy.3 b/man/libkeccak_hmac_fast_destroy.3 new file mode 100644 index 0000000..d2af66e --- /dev/null +++ b/man/libkeccak_hmac_fast_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_HMAC_FAST_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_destroy - Destroys an HMAC-hashing state without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_hamc_fast_destroy(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_hmac_fast_destroy () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_fast_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_fast_digest.3 b/man/libkeccak_hmac_fast_digest.3 new file mode 100644 index 0000000..008477c --- /dev/null +++ b/man/libkeccak_hmac_fast_digest.3 @@ -0,0 +1,104 @@ +.TH LIBKECCAK_HMAC_FAST_DIGEST 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_digest - Complete the HMAC-hashing of a message without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *\fIstate\fP, + const char *\fImsg\fP, size_t \fImsglen\fP, size_t \fIbits\fP, + const char *\fIsuffix\fP, char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_digest () +function absorbes the last part of (or all of) a message, +and returns the HMAC hash of the entire message. The last +part of the message is specified by the +.I msg +parameter, and its byte-size is specified by the +.I msglen +parameter. If all of the message has already be processed +by calls to the +.BR libkeccak_hmac_update (3) +function or the +.BR libkeccak_hmac_fast_update (3) +function (with the same pointer on +.IR state ,) +.I msg +and +.I msglen +should be set to +.I NULL +and 0, respectively. +.PP +If the message is not comprised a whole number of bytes, +the number of bits, modulus 8, in the message should be +specified in the +.I bits +parameter. +.I msglen +must only count the number of whole bytes, that is, the +floor of the number of bits in the message divided by 8. +.PP +.I suffix +should be a NUL-terminated string of ASCII '1':s +and '0':s, representing the bits that should be appended +to the message. If this string is empty, +.I NULL +may be used instead. This is used to select hash algorithm. +For pure Keccak, +.I NULL +or "" is used. For the other algorithms the constants +.B LIBKECCAK_SHA3_SUFFIX +(for SHA-3), +.B LIBKECCAK_RAWSHAKE_SUFFIX +(for RawSHAKE), and +.B LIBKECCAK_SHAKE_SUFFIX +(for SHAKE) are used. +.PP +The hash of the message will be stored to +.IR hashsum , +unless +.I hashsum +is +.I NULL +(which increases the performance of the call.) A total of +.RI (( state->n ++ 7) / 8) bytes will be written to the beginning of +.IR hashsum . +Therefore, +.I hashsum +needs at least an allocation size of that number of bytes. +.PP +The +.BR libkeccak_hmac_fast_digest () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_digest () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_fast_digest () +function may fail for any reason specified by the function +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_fast_update (3), +.BR libkeccak_hmac_fast_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_fast_free.3 b/man/libkeccak_hmac_fast_free.3 new file mode 100644 index 0000000..b4817ce --- /dev/null +++ b/man/libkeccak_hmac_fast_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_free - Destroys and deallocates an HMAC-hashing state without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_hmac_fast_free(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_free () +function releases the allocations stored in +.IR *state , +and also released the allocation of +.IR state . +.PP +The +.BR libkeccak_hmac_fast_free () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_fast_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_hmac_fast_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_fast_update.3 b/man/libkeccak_hmac_fast_update.3 new file mode 100644 index 0000000..43077d3 --- /dev/null +++ b/man/libkeccak_hmac_fast_update.3 @@ -0,0 +1,59 @@ +.TH LIBKECCAK_HMAC_FAST_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_fast_update - Partially HMAC-hash a message without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_fast_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_fast_update () +function continues (or starts) HMAC-hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_hmac_fast_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_hmac_fast_update () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_fast_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as quickly as possible, +rather than ensuring that the information in the old +allocation is securely removed if a new allocation is required. +.BR realloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_fast_digest (3), +.BR libkeccak_hmac_update (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_free.3 b/man/libkeccak_hmac_free.3 new file mode 100644 index 0000000..d1f9c84 --- /dev/null +++ b/man/libkeccak_hmac_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_HMAC_FREE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_free - Destroys and deallocates an HMAC-hashing state with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_hmac_free(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_free () +function releases the allocations stored in +.IR *state , +and also release the allocation of +.IR state . +.PP +The +.BR libkeccak_hmac_free () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_hmac_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_hmac_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3), +.BR libkeccak_hmac_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_initialise.3 b/man/libkeccak_hmac_initialise.3 new file mode 100644 index 0000000..de514e9 --- /dev/null +++ b/man/libkeccak_hmac_initialise.3 @@ -0,0 +1,57 @@ +.TH LIBKECCAK_HMAC_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_initialise - Initialise HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_initialise(libkeccak_hmac_state_t *\fIstate\fP, + const libkeccak_spec_t *\fIspec\fP, + const char *\fIkey\fP, size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_initialise () +function initialises +.I *state +and sets the algorithm tuning parameters to +those specified by +.IR *spec , +and the key to +.I key +of length +.IR key_length . +.SH RETURN VALUES +The +.BR libkeccak_hmac_initialise () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_initialise () +function may fail for any specified for the functions +.BR malloc (3) +and +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_destroy (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_copy (3), +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_marshal.3 b/man/libkeccak_hmac_marshal.3 new file mode 100644 index 0000000..b7270f6 --- /dev/null +++ b/man/libkeccak_hmac_marshal.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_HMAC_MARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_hmac_marshal - Marshals an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_hmac_marshal(const libkeccak_hmac_state_t *\fIstate\fP, + char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_marshal () +function marshals +.I *state +into the beginning of +.IR data . +.PP +Use the +.BR libkeccak_hmac_marshal_size (3) +function to get minimum usable allocation size +for +.IR data . +.SH RETURN VALUES +The +.BR libkeccak_hmac_marshal () +returns the number of bytes written to +.IR data . +.SH ERRORS +The +.BR libkeccak_hmac_marshal () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_unmarshal (3), +.BR libkeccak_hmac_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_marshal_size.3 b/man/libkeccak_hmac_marshal_size.3 new file mode 100644 index 0000000..5195b81 --- /dev/null +++ b/man/libkeccak_hmac_marshal_size.3 @@ -0,0 +1,36 @@ +.TH LIBKECCAK_HMAC_MARSHAL_SIZE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_marshal_size - Calculates the marshal-size of an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_marshal_size () +function calculates the number of bytes required +to marshal +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_hmac_marshal_size () +returns a positive value: the number of +bytes required to marshal the specified state. +.SH ERRORS +The +.BR libkeccak_hmac_marshal_size () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal (3), +.BR libkeccak_hmac_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_reset.3 b/man/libkeccak_hmac_reset.3 new file mode 100644 index 0000000..d5634d9 --- /dev/null +++ b/man/libkeccak_hmac_reset.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_HMAC_RESET 3 LIBKECCAK +.SH NAME +libkeccak_hmac_reset - Reinitialise a HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_reset(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, + size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_reset () +function reinitialises an HMAC-hashing state with a new key. +.I key_length +is the length of the key in bits. If +.I key +is +.IR NULL , +the key remains unchanged. +.SH RETURN VALUES +The +.BR libkeccak_hmac_reset () +function returns 0 successful completion. +On error -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_reset () +function may fail for any specified for the functions +.BR malloc (3) +and +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_set_key (3), +.BR libkeccak_hmac_wipe (3), +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_destroy (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_set_key.3 b/man/libkeccak_hmac_set_key.3 new file mode 100644 index 0000000..2f4682d --- /dev/null +++ b/man/libkeccak_hmac_set_key.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_HMAC_SET_KEY 3 LIBKECCAK +.SH NAME +libkeccak_hmac_set_key - Changes key for a the HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_set_key(libkeccak_hmac_state_t *\fIstate\fP, const char *\fIkey\fP, + size_t \fIkey_length\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_set_key () +function sets the key for a HMAC-hashing state without reseting +the state of the underlaying hashing-algorithm. +.I key_length +is the length of the key in bits. +.SH RETURN VALUES +The +.BR libkeccak_hmac_set_key () +function returns 0 successful completion. +On error -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_set_key () +function may fail for any specified for the function +.BR realloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_unmarshal.3 b/man/libkeccak_hmac_unmarshal.3 new file mode 100644 index 0000000..64e8f24 --- /dev/null +++ b/man/libkeccak_hmac_unmarshal.3 @@ -0,0 +1,39 @@ +.TH LIBKECCAK_HMAC_UNMARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_hmac_unmarshal - Unharshals an HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *\fIstate\fP, + const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_unmarshal () +function unmarshals an HMAC-hashing state from the beginning of +.IR data . +and stores it in +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_hmac_unmarshal () +returns the number of bytes reads from +.IR data x. +.SH ERRORS +The +.BR libkeccak_hmac_unmarshal () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_unmarshal_skip.3 b/man/libkeccak_hmac_unmarshal_skip.3 new file mode 100644 index 0000000..30e7ccf --- /dev/null +++ b/man/libkeccak_hmac_unmarshal_skip.3 @@ -0,0 +1,40 @@ +.TH LIBKECCAK_HMAC_UNMARSHAL_SKIP 3 LIBKECCAK +.SH NAME +libkeccak_hmac_unmarshal_skip - Calculates the marshal-size of a marshalled HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_hmac_unmarshal_skip(const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_unmarshal_skip () +function gets the number of bytes with which +the HMAC-hashing state in the beginning of +.I data +is store stored. This is useful if you do not +want to unmarshal the state. +.SH RETURN VALUES +The +.BR libkeccak_hmac_unmarshal_skip () +returns a positive value: the number of +bytes to skip forward to skip pass the +hash state stored at the beginning of +the buffer. +.SH ERRORS +The +.BR libkeccak_hmac_unmarshal_skip () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_marshal_size (3), +.BR libkeccak_hmac_marshal (3), +.BR libkeccak_hmac_unmarshal (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_update.3 b/man/libkeccak_hmac_update.3 new file mode 100644 index 0000000..daaf3fb --- /dev/null +++ b/man/libkeccak_hmac_update.3 @@ -0,0 +1,56 @@ +.TH LIBKECCAK_HMAC_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_update - Partially HMAC-hash a message with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_update () +function continues (or starts) HMAC-hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_hmac_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_hmac_update () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_hmac_update () +function may fail for any reason specified by the function +.BR malloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.SH SEE ALSO +.BR libkeccak_hmac_create (3), +.BR libkeccak_hmac_initialise (3), +.BR libkeccak_hmac_digest (3), +.BR libkeccak_hmac_fast_update (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_hmac_wipe.3 b/man/libkeccak_hmac_wipe.3 new file mode 100644 index 0000000..bad351b --- /dev/null +++ b/man/libkeccak_hmac_wipe.3 @@ -0,0 +1,36 @@ +.TH LIBKECCAK_HMAC_WIPE 3 LIBKECCAK +.SH NAME +libkeccak_hmac_wipe - Securely erase sensitive data from a HMAC-hashing state +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_hmac_wipe(libkeccak_hmac_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_hmac_wipe () +function securely erases data that may be +sensitive: the buffer and the state of the +underlaying hash-algorithm. +.SH RETURN VALUES +The +.BR libkeccak_hmac_wipe () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_hmac_wipe () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_hmac_fast_free (3), +.BR libkeccak_hmac_free (3), +.BR libkeccak_hmac_fast_destroy (3), +.BR libkeccak_hmac_destroy (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_keccaksum_fd.3 b/man/libkeccak_keccaksum_fd.3 new file mode 100644 index 0000000..2fc1b21 --- /dev/null +++ b/man/libkeccak_keccaksum_fd.3 @@ -0,0 +1,119 @@ +.TH LIBKECCAK_KECCAKSUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_keccaksum_fd - Calculate a Keccak hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_keccaksum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + const libkeccak_spec_t *\fIspec\fP, char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_keccaksum_fd () +function calculates a Keccak hashsum of a file, whose file +desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm tuning is specified by +.IR *spec . +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( spec->output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_keccaksum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_keccaksum_fd () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_keccaksum_fd () +function may fail for any reason, except those resulting +in +.I errno +being set to +.BR EINTR , +specified for the functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_keccaksum_fd () +hashes the file until the end has been reached. For pipes +and sockets and this means until the file has been closed. +But for character devices, this usually means never. +Attempting to hash files in /dev is therefore usually a +bad idea. +.BR libkeccak_keccaksum_fd () +does not check for the file length or file type before +hashing as this could limit what you can do, and make +the library more complex. +.PP +.BR libkeccak_keccaksum_fd () +does not stop if interrupted +.RI ( read (2) +returns +.BR EINTR .) +.PP +.BR libkeccak_keccaksum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_keccaksum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLE +This example calculates the Keccak[b = 1024, c = 576, n = 256] +hash of the input from stdin, and prints the hash, in hexadecimal +form, to stdout. +.LP +.nf +libkeccak_state_t state; +libkeccak_spec_t spec; +char binhash[256 / 8]; +char hexhash[256 / 8 * 2 + 1]; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; + +if (libkeccak_keccaksum_fd(STDIN_FILENO, &state, &spec, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_rawshakesum_fd.3 b/man/libkeccak_rawshakesum_fd.3 new file mode 100644 index 0000000..27c4f45 --- /dev/null +++ b/man/libkeccak_rawshakesum_fd.3 @@ -0,0 +1,115 @@ +.TH LIBKECCAK_RAWSHAKESUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_rawshakesum_fd - Calculate a RawSHAKE hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_rawshakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + long int \fIsemicapacity\fP, long int \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_rawshakesum_fd () +function calculates a RawSHAKE hashsum of a file, whose +file desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm is tuned by the +.I semicapacity +and +.I output +parameters; they specify the half of the capacity and +the output size, respectively, in bits. +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_rawshakesum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_rawshakesum_fd () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_rawshakesum_fd () +function may fail for any reason, except those resulting in +.I errno +being set to +.BR EINTR , +specified for the functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_rawshakesum_fd () +hashes the file until the end has been reached. For pipes +and sockets and this means until the file has been closed. +But for character devices, this usually means never. +Attempting to hash files in /dev is therefore usually a +bad idea. +.BR libkeccak_rawshakesum_fd () +does not check for the file length or file type before +hashing as this could limit what you can do, and make +the library more complex. +.PP +.BR libkeccak_rawshakesum_fd () +does not stop if interrupted +.RB ( read (2) +returns +.BR EINTR .) +.PP +.BR libkeccak_rawshakesum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_rawshakesum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLE +This example calculates the RawSHAKE256(, 512) hash of the input +from stdin, and prints the hash, in hexadecimal form, to stdout. +.LP +.nf +libkeccak_state_t state; +if (libkeccak_rawshakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_sha3sum_fd.3 b/man/libkeccak_sha3sum_fd.3 new file mode 100644 index 0000000..e8c4fc0 --- /dev/null +++ b/man/libkeccak_sha3sum_fd.3 @@ -0,0 +1,111 @@ +.TH LIBKECCAK_SHA3SUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_sha3sum_fd - Calculate a SHA-3 hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_sha3sum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, long int \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_sha3sum_fd () +function calculates a SHA-3 hashsum of a file, whose file +desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm is tuned by the +.I output +parameter; it specifies the output size, in bits. +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_sha3sum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_sha3sum_fd () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_sha3sum_fd () +function may fail for any reason, except those resulting in +.I errno +being set to +.BR EINTR , +specified for the functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_sha3sum_fd () +hashes the file until the end has been reached. For pipes +and sockets and this means until the file has been closed. +But for character devices, this usually means never. +Attempting to hash files in /dev is therefore usually a +bad idea. +.BR libkeccak_sha3sum_fd () +does not check for the file length or file type before +hashing as this could limit what you can do, and make +the library more complex. +.PP +.BR libkeccak_sha3sum_fd () +does not stop if interrupted +.RB ( read (2) +returns +.BR EINTR .) +.PP +.BR libkeccak_sha3sum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_sha3sum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLE +This example calculates the SHA3-256 hash of the input +from stdin, and prints the hash, in hexadecimal form, to stdout. +.LP +.nf +libkeccak_state_t state; +if (libkeccak_sha3sum_fd(STDIN_FILENO, &state, 256, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_shakesum_fd.3 b/man/libkeccak_shakesum_fd.3 new file mode 100644 index 0000000..0d89f39 --- /dev/null +++ b/man/libkeccak_shakesum_fd.3 @@ -0,0 +1,115 @@ +.TH LIBKECCAK_SHAKESUM_FD 3 LIBKECCAK +.SH NAME +libkeccak_shakesum_fd - Calculate a SHAKE hashsum of a file +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_shakesum_fd(int \fIfd\fP, libkeccak_state_t *\fIstate\fP, + long int \fIsemicapacity\fP, long int \fIoutput\fP, + char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_shakesum_fd () +function calculates a SHAKE hashsum of a file, whose file +desriptor is specified by +.I fd +(and should be at the beginning of the file.) The hash +algorithm is tuned by the +.I semicapacity +and +.I output +parameters; they specify the half of the capacity and the +output size, respectively, in bits. +.PP +The hash is stored in binary form to +.IR hashsum . +.I hashsum +should have an allocation size of at least +.RI ((( output ++ 7) / 8) * sizeof(char)). +.PP +.I *state +should not be initialised. +.BR libkeccak_shakesum_fd () +initialises +.I *state +itself. Therefore there would be a memory leak if +.I *state +is already initialised. +.SH RETURN VALUES +The +.BR libkeccak_shakesum_fd () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_shakesum_fd () +function may fail for any reason, except those resulting in +.I errno +being set to +.BR EINTR , +specified for the functions +.BR read (2), +.BR malloc (3), +and +.BR realloc (3). +.SH NOTES +Be aware, +.BR libkeccak_shakesum_fd () +hashes the file until the end has been reached. For pipes +and sockets and this means until the file has been closed. +But for character devices, this usually means never. +Attempting to hash files in /dev is therefore usually a +bad idea. +.BR libkeccak_shakesum_fd () +does not check for the file length or file type before +hashing as this could limit what you can do, and make +the library more complex. +.PP +.BR libkeccak_shakesum_fd () +does not stop if interrupted +.RB ( read (2) +returns +.BR EINTR .) +.PP +.BR libkeccak_shakesum_fd () +assumes all information is non-sensitive, and will +therefore not perform any secure erasure of information. +.PP +.BR libkeccak_shakesum_fd () +does not validate the tuning of the algorithm. +.SH EXAMPLE +This example calculates the SHAKE256(, 512) hash of the input +from stdin, and prints the hash, in hexadecimal form, to stdout. +.LP +.nf +libkeccak_state_t state; +if (libkeccak_shakesum_fd(STDIN_FILENO, &state, 256, 512, binhash) < 0) + goto fail; +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_simple_squeeze.3 b/man/libkeccak_simple_squeeze.3 new file mode 100644 index 0000000..52605ed --- /dev/null +++ b/man/libkeccak_simple_squeeze.3 @@ -0,0 +1,38 @@ +.TH LIBKECCAK_SIMPLE_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_simple_squeeze - Runs Keccak-f a number of times +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_simple_squeeze(libkeccak_state_t *\fIstate\fP, long int \fItimes\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_simple_squeeze () +function runs Keccak-f +.I times +times on the hashing +process described by +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_simple_squeeze () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_simple_squeeze () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_digest (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_fast_squeeze (3), +.BR libkeccak_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_spec_check.3 b/man/libkeccak_spec_check.3 new file mode 100644 index 0000000..9fc70f6 --- /dev/null +++ b/man/libkeccak_spec_check.3 @@ -0,0 +1,95 @@ +.TH LIBKECCAK_SPEC_CHECK 3 LIBKECCAK +.SH NAME +libkeccak_spec_check - Validate hashing parameters +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_spec_check(const libkeccak_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_check () +function validates the parameters of +.IR *spec , +so that unusable configurations can be detected. +It is recommended to call this function after calling +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +or, especially, after settings the parameters +manually for Keccak hashing. +.PP +.nf +typedef struct libkeccak_spec { + long int bitrate; /* bitrate (in bits) */ + long int capacity; /* capacity (in bits) */ + long int output; /* output size (in bits) */ +} libkeccak_spec_t; +.fi +.SH RETURN VALUES +The +.BR libkeccak_spec_check () +function returns 0 if the settings are usable. Otherwise +it will return one of the following constants. +.PP +.TP +.B LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE +The specified bitrate was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 +The specified bitrate was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE +The specified capacity was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 +The specified capacity was not equivalent to 0 +modulus 8, that is, it was not in whole bytes. +.TP +.B LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE +The specified output size was non-positive. +.TP +.B LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE +The state size, that is the sum of the bitrate +and the capacity, exceeded the supported limit +(currently at 1600 bits.) +.TP +.B LIBKECCAK_SPEC_ERROR_STATE_MOD_25 +The state size, that is the sum of the bitrate +and the capacity, in bits, was not equivalent +to 0 modulus 25. Meaning the state size cannot +cover all lanes equivalently. +.TP +.B LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT +The word size, that is the state size divided +by 25, is not a power of 2. +.TP +.B LIBKECCAK_SPEC_ERROR_WORD_MOD_8 +The word size, that is the state size divided +by 25, is not quivalent to 0 modulus 8, that +is, it is not in whole bytes. +.PP +Note that there may be more than one error. Only the first +detected is returned. +.SH ERRORS +The +.BR libkeccak_spec_check () +function cannot fail. +.fi +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_spec_rawshake.3 b/man/libkeccak_spec_rawshake.3 new file mode 100644 index 0000000..6f60c36 --- /dev/null +++ b/man/libkeccak_spec_rawshake.3 @@ -0,0 +1,53 @@ +.TH LIBKECCAK_SPEC_RAWSHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_rawshake - Configure RawSHAKE hashing parameters +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_spec_rawshake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, + long int \fId\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_rawshake () +function sets +.I *spec +to specify the Keccak parameters used for RawSHAKE hashing +with the semicapacity specified, in bits, via the +.I x +parameter, and the output size specified, in bits, via the +.I d +parameter. +.SH RETURN VALUES +The +.BR libkeccak_spec_rawshake () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_spec_rawshake () +function cannot fail. +.SH EXAMPLE +This example configure a +.B libkeccak_spec_t +to specify the Keccak parameters used for RawSHAKE256(, 512): +.LP +.nf +libkeccak_spec_t spec; +libkeccak_spec_rawshake(&spec, 256, 512); +.fi +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_spec_sha3.3 b/man/libkeccak_spec_sha3.3 new file mode 100644 index 0000000..8e07a7d --- /dev/null +++ b/man/libkeccak_spec_sha3.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_SPEC_SHA3 3 LIBKECCAK +.SH NAME +libkeccak_spec_sha3 - Configure SHA-3 hashing parameters +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_spec_sha3(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_sha3 () +function sets +.I *spec +to specify the Keccak parameters +used for SHA-3 hashing with the output size specified, +in bits, via the +.I x +parameter. +.SH RETURN VALUES +The +.BR libkeccak_spec_sha3 () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_spec_sha3 () +function cannot fail. +.SH EXAMPLE +This example configure a +.B libkeccak_spec_t +to specify the Keccak parameters used for SHA3-256: +.LP +.nf +libkeccak_spec_t spec; +libkeccak_spec_sha3(&spec, 256); +.fi +.SH SEE ALSO +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_spec_shake.3 b/man/libkeccak_spec_shake.3 new file mode 100644 index 0000000..9e2d763 --- /dev/null +++ b/man/libkeccak_spec_shake.3 @@ -0,0 +1,52 @@ +.TH LIBKECCAK_SPEC_SHAKE 3 LIBKECCAK +.SH NAME +libkeccak_spec_shake - Configure SHAKE hashing parameters +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_spec_shake(libkeccak_spec_t *\fIspec\fP, long int \fIx\fP, long int \fId\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_spec_shake () +function sets +.I *spec +to specify the Keccak parameters used for SHAKE hashing +with the semicapacity specified, in bits, via the +.I x +parameter, and the output size specified, in bits, via the +.I d +parameter. +.SH RETURN VALUES +The +.BR libkeccak_spec_shake () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_spec_shake () +function cannot fail. +.SH EXAMPLE +This example configure a +.B libkeccak_spec_t +to specify the Keccak parameters used for SHAKE256(, 512): +.LP +.nf +libkeccak_spec_t spec; +libkeccak_spec_shake(&spec, 256, 512); +.fi +.SH SEE ALSO +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_squeeze.3 b/man/libkeccak_squeeze.3 new file mode 100644 index 0000000..c6c8d01 --- /dev/null +++ b/man/libkeccak_squeeze.3 @@ -0,0 +1,48 @@ +.TH LIBKECCAK_FAST_SQUEEZE 3 LIBKECCAK +.SH NAME +libkeccak_squeeze - Runs the squeeze phase +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_squeeze(libkeccak_state_t *\fIstate\fP, char *\fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_squeeze () +function runs the Keccak squeeze phase, on the the hash +process described by +.IR *state , +on stores a new digest, in binary form, in +.IR hashsum . +.PP +.I hashsum +has the same requirement as for the +.BR libkeccak_digest (3) +and +.BR libkeccak_fast_digest (3) +functions: it must have an allocation size of at least +.RI (( state->n ++ 7) / 8) bytes. However, it may not be +.IR NULL . +.SH RETURN VALUES +The +.BR libkeccak_squeeze () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_squeeze () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_digest (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_simple_squeeze (3), +.BR libkeccak_fast_squeeze (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_copy.3 b/man/libkeccak_state_copy.3 new file mode 100644 index 0000000..c9283ca --- /dev/null +++ b/man/libkeccak_state_copy.3 @@ -0,0 +1,44 @@ +.TH LIBKECCAK_STATE_COPY 3 LIBKECCAK +.SH NAME +libkeccak_state_copy - Copies hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_state_copy(libkeccak_state_t *\fIdest\fP, + const libkeccak_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_copy () +function initialises +.I *dest +to be identical to +.IR *src . +This includes all members of the +.B libkeccak_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_copy () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_state_copy () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_duplicate (3), +.BR libkeccak_state_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_create.3 b/man/libkeccak_state_create.3 new file mode 100644 index 0000000..77880a3 --- /dev/null +++ b/man/libkeccak_state_create.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_STATE_CREATE 3 LIBKECCAK +.SH NAME +libkeccak_state_create - Allocate and initialise hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +libkeccak_state_t * +libkeccak_state_create(const libkeccak_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_create () +function allocates a new +.I libkeccak_state_t* +with one initialised element, and sets the algorithm +tuning parameters to those specified by +.IR *spec . +.SH RETURN VALUES +The +.BR libkeccak_state_create () +function returns a newly allocated +.I libkeccak_state_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_state_create () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_free (3), +.BR libkeccak_state_fast_free (3) +.BR libkeccak_state_duplicate (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_destroy.3 b/man/libkeccak_state_destroy.3 new file mode 100644 index 0000000..0a78215 --- /dev/null +++ b/man/libkeccak_state_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_STATE_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_state_destroy - Destroys a hash state with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_destroy(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_state_destroy () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_free (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_duplicate.3 b/man/libkeccak_state_duplicate.3 new file mode 100644 index 0000000..54c9be3 --- /dev/null +++ b/man/libkeccak_state_duplicate.3 @@ -0,0 +1,46 @@ +.TH LIBKECCAK_STATE_DUPLICATE 3 LIBKECCAK +.SH NAME +libkeccak_state_duplicate - Allocate a duplicate hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +libkeccak_state_t * +libkeccak_state_duplicate(const libkeccak_state_t *\fIsrc\fP); +.fi +.P +Link with +.IR -lkeccak P. +.SH DESCRIPTION +The +.BR libkeccak_state_duplicate () +function allocates a new hash state and initialises it +to be identical to +.IR *src . +This includes all members of the +.B libkeccak_state_t +structure, including the state of the sponge and the +message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_duplicate () +function returns a newly allocated +.I libkeccak_state_t* +(of one initialised element) upon successful completion. +On error, +.I NULL +is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_state_duplicate () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_copy (3), +.BR libkeccak_state_create (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_fast_destroy.3 b/man/libkeccak_state_fast_destroy.3 new file mode 100644 index 0000000..e04ca86 --- /dev/null +++ b/man/libkeccak_state_fast_destroy.3 @@ -0,0 +1,43 @@ +.TH LIBKECCAK_STATE_FAST_DESTROY 3 LIBKECCAK +.SH NAME +libkeccak_state_fast_destroy - Destroys a hash state without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_fast_destroy(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_fast_destroy () +function releases the allocations stored in +.IR *state , +without releasing the allocation of +.I state +itself. +.PP +The +.BR libkeccak_state_fast_destroy () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_fast_destroy () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_fast_destroy () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_fast_free (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_fast_free.3 b/man/libkeccak_state_fast_free.3 new file mode 100644 index 0000000..e617e21 --- /dev/null +++ b/man/libkeccak_state_fast_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_STATE_FAST_FREE 3 LIBKECCAK +.SH NAME +libkeccak_state_fast_free - Destroys and deallocates a hash state without erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_fast_free(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_fast_free () +function releases the allocations stored in +.IR *state , +and also released the allocation of +.IR state . +.PP +The +.BR libkeccak_state_fast_free () +function does not securely erase sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_fast_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_fast_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_state_fast_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_free (3), +.BR libkeccak_state_create (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_free.3 b/man/libkeccak_state_free.3 new file mode 100644 index 0000000..e6dd3f8 --- /dev/null +++ b/man/libkeccak_state_free.3 @@ -0,0 +1,51 @@ +.TH LIBKECCAK_STATE_FREE 3 LIBKECCAK +.SH NAME +libkeccak_state_free - Destroys and deallocates a hash state with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_free(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_free () +function releases the allocations stored in +.IR *state , +and also release the allocation of +.IR state . +.PP +The +.BR libkeccak_state_free () +function securely erases sensitive data. +.SH RETURN VALUES +The +.BR libkeccak_state_free () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_free () +function cannot fail. +.SH NOTES +A double call to +.BR libkeccak_state_free () +will either result in a double free, +which is must likely to crash the process, +or free an allocation (that was created +between the calls) that was not intended +to be freed, resulting in undefined behaviour. +.SH SEE ALSO +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_fast_free (3), +.BR libkeccak_state_create (3), +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_initialise.3 b/man/libkeccak_state_initialise.3 new file mode 100644 index 0000000..2620686 --- /dev/null +++ b/man/libkeccak_state_initialise.3 @@ -0,0 +1,60 @@ +.TH LIBKECCAK_STATE_INITIALISE 3 LIBKECCAK +.SH NAME +libkeccak_state_initialise - Initialise hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_state_initialise(libkeccak_state_t *\fIstate\fP, + const libkeccak_spec_t *\fIspec\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_initialise () +function initialises +.I *state +and sets the algorithm tuning parameters to those +specified by +.IR *spec . +.SH RETURN VALUES +The +.BR libkeccak_state_initialise () +function returns 0 upon successful completion. +On error, -1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_state_initialise () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_create (3), +.BR libkeccak_state_reset (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_copy (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3), +.BR libkeccak_generalised_sum_fd (3), +.BR libkeccak_keccaksum_fd (3), +.BR libkeccak_sha3sum_fd (3), +.BR libkeccak_rawshakesum_fd (3), +.BR libkeccak_shakesum_fd (3), +.BR libkeccak_spec_sha3 (3), +.BR libkeccak_spec_shake (3), +.BR libkeccak_spec_rawshake (3), +.BR libkeccak_spec_check (3), +.BR libkeccak_generalised_spec_initialise (3), +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_hmac_initialise (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_marshal.3 b/man/libkeccak_state_marshal.3 new file mode 100644 index 0000000..f5d5e05 --- /dev/null +++ b/man/libkeccak_state_marshal.3 @@ -0,0 +1,41 @@ +.TH LIBKECCAK_STATE_MARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_state_marshal - Marshals a hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_state_marshal(const libkeccak_state_t *\fIstate\fP, char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_marshal () +function marshals \fI*state\fP into the beginning of +.IR data . +.PP +Use the +.BR libkeccak_state_marshal_size (3) +function to get minimum usable allocation size +for +.IR data . +.SH RETURN VALUES +The +.BR libkeccak_state_marshal () +returns the number of bytes written to +.IR data . +.SH ERRORS +The +.BR libkeccak_state_marshal () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_unmarshal (3), +.BR libkeccak_state_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_marshal_size.3 b/man/libkeccak_state_marshal_size.3 new file mode 100644 index 0000000..8ebb16a --- /dev/null +++ b/man/libkeccak_state_marshal_size.3 @@ -0,0 +1,36 @@ +.TH LIBKECCAK_STATE_MARSHAL_SIZE 3 LIBKECCAK +.SH NAME +libkeccak_state_marshal_size - Calculates the marshal-size of a hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_state_marshal_size(const libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_marshal_size () +function calculates the number of bytes required +to marshal +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_state_marshal_size () +returns a positive value: the number of +bytes required to marshal the specified state. +.SH ERRORS +The +.BR libkeccak_state_marshal_size () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal (3), +.BR libkeccak_state_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_reset.3 b/man/libkeccak_state_reset.3 new file mode 100644 index 0000000..60bb778 --- /dev/null +++ b/man/libkeccak_state_reset.3 @@ -0,0 +1,37 @@ +.TH LIBKECCAK_STATE_RESET 3 LIBKECCAK +.SH NAME +libkeccak_state_reset - Reinitialise hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_reset(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_reset () +function reinitialises +.IR *state , +but keeps the +tuning, so it can be used to hash another message. +.SH RETURN VALUES +The +.BR libkeccak_state_reset () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_reset () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_wipe (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_unmarshal.3 b/man/libkeccak_state_unmarshal.3 new file mode 100644 index 0000000..5a9e59b --- /dev/null +++ b/man/libkeccak_state_unmarshal.3 @@ -0,0 +1,39 @@ +.TH LIBKECCAK_STATE_UNMARSHAL 3 LIBKECCAK +.SH NAME +libkeccak_state_unmarshal - Unharshals a hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_state_unmarshal(libkeccak_state_t *\fIstate\fP, const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_unmarshal () +function unmarshals a hash state from the beginning +of +.IR data . +and stores it in +.IR *state . +.SH RETURN VALUES +The +.BR libkeccak_state_unmarshal () +returns the number of bytes reads from +.IR data . +.SH ERRORS +The +.BR libkeccak_state_unmarshal () +function may fail for any specified for the function +.BR malloc (3). +.SH SEE ALSO +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal_skip (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_unmarshal_skip.3 b/man/libkeccak_state_unmarshal_skip.3 new file mode 100644 index 0000000..b87386c --- /dev/null +++ b/man/libkeccak_state_unmarshal_skip.3 @@ -0,0 +1,40 @@ +.TH LIBKECCAK_STATE_UNMARSHAL_SKIP 3 LIBKECCAK +.SH NAME +libkeccak_state_unmarshal_skip - Calculates the marshal-size of a marshalled hash state +.SH SYNOPSIS +.LP +.nf +#include +.P +size_t +libkeccak_state_unmarshal_skip(const char *\fIdata\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_unmarshal_skip () +function gets the number of bytes with which +the hash state in the beginning of +.I data +is store stored. This is useful if you do not +want to unmarshal the state. +.SH RETURN VALUES +The +.BR libkeccak_state_unmarshal_skip () +returns a positive value: the number of +bytes to skip forward to skip pass the +hash state stored at the beginning of +the buffer. +.SH ERRORS +The +.BR libkeccak_state_unmarshal_skip () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_marshal_size (3), +.BR libkeccak_state_marshal (3), +.BR libkeccak_state_unmarshal (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_wipe.3 b/man/libkeccak_state_wipe.3 new file mode 100644 index 0000000..664cd51 --- /dev/null +++ b/man/libkeccak_state_wipe.3 @@ -0,0 +1,37 @@ +.TH LIBKECCAK_STATE_WIPE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe - Securely erase sensitive data +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_wipe(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_wipe () +function securely erases data that may be +sensitive: the state of the Keccak sponge, +and the message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_wipe () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_wipe () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_wipe_message (3), +.BR libkeccak_state_wipe_sponge (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_wipe_message.3 b/man/libkeccak_state_wipe_message.3 new file mode 100644 index 0000000..c734560 --- /dev/null +++ b/man/libkeccak_state_wipe_message.3 @@ -0,0 +1,35 @@ +.TH LIBKECCAK_STATE_WIPE_MESSAGE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe_message - Securely erase the message chunk buffer +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_wipe_message(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_wipe_message () +function securely erases the message chunk buffer. +.SH RETURN VALUES +The +.BR libkeccak_state_wipe_message () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_wipe_message () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_wipe_sponge (3), +.BR libkeccak_state_wipe (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_state_wipe_sponge.3 b/man/libkeccak_state_wipe_sponge.3 new file mode 100644 index 0000000..4651fc0 --- /dev/null +++ b/man/libkeccak_state_wipe_sponge.3 @@ -0,0 +1,35 @@ +.TH LIBKECCAK_STATE_WIPE_SPONGE 3 LIBKECCAK +.SH NAME +libkeccak_state_wipe_sponge - Securely erase the Keccak sponge state +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_state_wipe_sponge(libkeccak_state_t *\fIstate\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_state_wipe_sponge () +function securely erases the state of the Keccak sponge. +.SH RETURN VALUES +The +.BR libkeccak_state_wipe_sponge () +function does not return any value. +.SH ERRORS +The +.BR libkeccak_state_wipe_sponge () +function cannot fail. +.SH SEE ALSO +.BR libkeccak_state_wipe_message (3), +.BR libkeccak_state_wipe (3), +.BR libkeccak_state_fast_destroy (3), +.BR libkeccak_state_destroy (3), +.BR libkeccak_state_reset (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_unhex.3 b/man/libkeccak_unhex.3 new file mode 100644 index 0000000..93cde63 --- /dev/null +++ b/man/libkeccak_unhex.3 @@ -0,0 +1,53 @@ +.TH LIBKECCAK_UNHEX 3 LIBKECCAK +.SH NAME +libkeccak_unhex - Converts a hexadecimal hashsum to binary +.SH SYNOPSIS +.LP +.nf +#include +.P +void +libkeccak_unhex(char *restrict \fIoutput\fP, const char *restrict \fIhashsum\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_unhex () +function +converts a hexadecimal hashsum, stored in +.IR hashsum , +to binary, and stores the binary representation in +.IR output . +.PP +.I hashsum +must be terminated by a NUL-character. It may be +in either lowercase or uppercase, or a mixture +thereof. +.I output +will not be terminated. +.PP +(\fBstrlen\fP(\fIhashsum\fP) / 2) bytes will be +written to the beginning of +.IR Ioutput . +It should therefore have an allocation of at least +that number of bytes. +.SH RETURN VALUES +The +.BR libkeccak_unhex () +function does return any value. +.SH ERRORS +The +.BR libkeccak_unhex () +function cannot fail. +.SH NOTES +.I hashsum +must have an even number of digits +(characters excluding the terminating NUL-character.) +.SH SEE ALSO +.BR libkeccak_behex_lower (3), +.BR libkeccak_behex_upper (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/man/libkeccak_update.3 b/man/libkeccak_update.3 new file mode 100644 index 0000000..d83f74b --- /dev/null +++ b/man/libkeccak_update.3 @@ -0,0 +1,95 @@ +.TH LIBKECCAK_UPDATE 3 LIBKECCAK +.SH NAME +libkeccak_update - Partially hash a message with erasure +.SH SYNOPSIS +.LP +.nf +#include +.P +int +libkeccak_update(libkeccak_state_t *\fIstate\fP, const char *\fImsg\fP, + size_t \fImsglen\fP); +.fi +.P +Link with +.IR -lkeccak . +.SH DESCRIPTION +The +.BR libkeccak_update () +function continues (or starts) hashing a message. +The current state of the hashing is stored in +.IR *state , +and will be updated. The message specified by the +.I msg +parameter with the byte-size specified by the +.I msglen +parameter, will be hashed. +.PP +The +.BR libkeccak_update () +function may reallocate the state's message chunk buffer. +When doing so, it attempts to do so as securely as possible, +rather than as fast as possible. +.SH RETURN VALUES +The +.BR libkeccak_update () +function returns 0 upon successful completion. On error, +-1 is returned and +.I errno +is set to describe the error. +.SH ERRORS +The +.BR libkeccak_update () +function may fail for any reason specified by the function +.BR malloc (3). +.SH NOTES +Neither parameter by be +.I NULL +or 0. +.SH EXAMPLE +This example calculates the Keccak[b = 1024, c = 576, n = 256] +hash of the input from stdin, and prints the hash, in hexadecimal +form, to stdout. +.LP +.nf +libkeccak_state_t state; +libkeccak_spec_t spec; +char binhash[256 / 8]; +char hexhash[256 / 8 * 2 + 1]; +char chunk[4 << 10]; +ssize_t len; + +spec.bitrate = 1024; +spec.capacity = 576; +spec.output = 256; +if (libkeccak_state_initialise(&state, &spec) < 0) + goto fail; + +for (;;) { + len = read(STDIN_FILENO, chunk, sizeof(chunk)); + + if ((len < 0) && (errno == EINTR)) + continue; + if (len < 0) + goto fail; + if (len == 0) + break; + + if (libkeccak_update(&state, chunk, (size_t)len) < 0) + goto fail; +} +if (libkeccak_digest(&state, NULL, 0, 0, "", binhash) < 0) + goto fail; + +libkeccak_behex_lower(hexhash, binhash, sizeof(binhash)); +printf("%s\\n", hexhash); +libkeccak_state_destroy(&state); +.fi +.SH SEE ALSO +.BR libkeccak_state_initialise (3), +.BR libkeccak_fast_update (3), +.BR libkeccak_fast_digest (3), +.BR libkeccak_digest (3) +.SH BUGS +Please report bugs to https://github.com/maandree/libkeccak/issues or to +maandree@kth.se diff --git a/src/benchmark-flags b/src/benchmark-flags deleted file mode 100755 index 1168ec0..0000000 --- a/src/benchmark-flags +++ /dev/null @@ -1,116 +0,0 @@ -#!/bin/sh -# See LICENSE file for copyright and license details. - -set -e - -export LD_LIBRARY_PATH=bin -if test "${TRIES}" = ""; then - TRIES=10 -fi - -# List all flags that affect the object files -list_test_flags() { - cat <.benchmark.so.far - -while true; do - exec 3>.benchmarks - - for _try in $(seq ${TRIES}); do - for test_flag in "" ${test_flags}; do - flags="${test_flag} ${base_flags}" - make -B all COPTIMISE="${flags}" CPPFLAGS="${cppflags} $*" - make check - if test "${test_flag}" = ""; then - test_flag=zzz - fi - echo "$(bin/benchmark || echo error) ${test_flag}" >&3 - done - done - - exec 3<&- - - ! grep ^error .benchmarks >/dev/null 2>/dev/null - - good_flag="$(median < .benchmarks | sort -n | cut -d ' ' -f 2 | sed 1q)" - if test "${good_flag}" = zzz || test $pass = 2; then - if test $pass = 1; then - pass=2 - base_flags="$(echo "${base_flags}" | sed -e 's/ -O0//')" - test_flags="-O0 -O1 -O2 -O3 -Ofast -Os" - else - if ! test "${good_flag}" = zzz; then - base_flags="${base_flags} ${good_flag}" - echo "${good_flag}" >&4 - fi - echo - echo - echo "Good flags:" - echo "${base_flags}" - exec 4<&- - exit 0 - fi - else - echo "${good_flag}" >&4 - base_flags="${base_flags} ${good_flag}" - test_flags="$(echo "${test_flags}" | sed -e "s/ ${good_flag} / /")" - fi -done - -# None of these GCC flags affect the object files. -# -faggressive-loop-optimizations -fauto-inc-dec -fbranch-target-load-optimize -# -fbranch-target-load-optimize2 -fbtr-bb-exclusive -fcaller-saves -fcheck-data-deps -# -fcombine-stack-adjustments -fconserve-stack -fcompare-elim -fcprop-registers -# -fcse-follow-jumps -fcse-skip-blocks -fcx-fortran-rules -fcx-limited-range -fdce -# -fdelete-null-pointer-checks -fdevirtualize -fdevirtualize-speculatively -fdse -# -fearly-inlining -fipa-sra -ffat-lto-objects -fbranch-probabilities -# -fassociative-math -fforward-propagate -ffunction-sections -fforward-propagate -# -ffast-math -ffinite-math-only -ffloat-store -fgcse -fgcse-after-reload -fgcse-las -# -fgcse-lm -fgraphite-identity -fgcse-sm -fhoist-adjacent-loads -fif-conversion -# -fif-conversion2 -findirect-inlining -finline-functions -finline-functions-called-once -# -finline-small-functions -fipa-cp -fipa-cp-clone -fipa-pta -fipa-profile -# -fipa-pure-const -fipa-reference -fira-hoist-pressure -fira-loop-pressure -# -fno-ira-share-save-slots -fno-ira-share-spill-slots -fisolate-erroneous-paths-dereference -# -fisolate-erroneous-paths-attribute -fivopts -fkeep-static-consts -flive-range-shrinkage -# -floop-block -floop-interchange -floop-strip-mine -floop-nest-optimize -# -floop-parallelize-all -fmodulo-sched -fmodulo-sched-allow-regmoves -fmove-loop-invariants -# -fno-branch-count-reg -fno-defer-pop -fno-function-cse -fno-guess-branch-probability -# -fno-defer-pop -fno-function-cse -fno-guess-branch-probability -fno-inline -fno-math-errno -# -fno-peephole -fno-peephole2 -fno-sched-interblock -fno-sched-spec -fno-signed-zeros -# -fno-toplevel-reorder -fno-trapping-math -fno-zero-initialized-in-bss -# -foptimize-sibling-calls -fpartial-inlining -fpeel-loops -fpredictive-commoning -# -fprefetch-loop-arrays -fprofile-report -fprofile-use -fprofile-values -# -fprofile-reorder-functions -freciprocal-math -free -frename-registers -freorder-blocks -# -frerun-cse-after-loop -freschedule-modulo-scheduled-loops -frounding-math -# -fsched2-use-superblocks -fsched-pressure -fsched-spec-load -fsched-spec-load-dangerous -# -fsched-group-heuristic -fsched-critical-path-heuristic -fsched-spec-insn-heuristic -# -fsched-rank-heuristic -fsched-last-insn-heuristic -fsched-dep-count-heuristic -# -fselective-scheduling -fselective-scheduling2 -fsel-sched-pipelining -# -fsel-sched-pipelining-outer-loops -fshrink-wrap -fsignaling-nans -# -fsingle-precision-constant -fstrict-overflow -fthread-jumps -ftracer -ftree-bit-ccp -# -ftree-builtin-call-dce -ftree-ccp -ftree-ch -ftree-copyrename -ftree-dce -# -ftree-dominator-opts -ftree-dse -ftree-forwprop -ftree-fre -ftree-loop-if-convert -# -ftree-loop-if-convert-stores -ftree-loop-im -ftree-phiprop -ftree-loop-distribution -# -ftree-loop-distribute-patterns -ftree-loop-ivcanon -ftree-loop-linear -# -ftree-loop-optimize -ftree-loop-vectorize -ftree-pre -ftree-partial-pre -ftree-pta -# -ftree-reassoc -ftree-sink -ftree-slsr -ftree-sra -ftree-vectorize -ftree-vrp -# -funit-at-a-time -funroll-all-loops -funroll-loops -funsafe-loop-optimizations -# -funsafe-math-optimizations -funswitch-loops -fvariable-expansion-in-unroller -# -fvect-cost-model -fvpt -fweb -fprofile-correction -freorder-functions -# -fschedule-insns -fschedule-insns2 -fsplit-ivs-in-unroller -fsplit-wide-types -# -fstrict-aliasing -ftree-coalesce-vars -ftree-copy-prop -ftree-switch-conversion -# -ftree-switch-conversion -ftree-tail-merge -ftree-coalesce-inlined-vars -# -falign-jumps=0 -falign-labels=0 -falign-loops=0 -ftree-parallelize-loops=10 -# -fsched-stalled-insns-dep=0 -fsched-stalled-insns=0 - diff --git a/src/benchmark.c b/src/benchmark.c deleted file mode 100644 index 1ce7da9..0000000 --- a/src/benchmark.c +++ /dev/null @@ -1,139 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include - -#include -#include -#include -#include -#include - - -#ifndef MESSAGE_FILE -# define MESSAGE_FILE "LICENSE" -#endif -#ifndef MESSAGE_LEN -# define MESSAGE_LEN 34520 -#endif - - -#ifndef BITRATE -# define BITRATE 1024 -#endif -#ifndef CAPACITY -# define CAPACITY 576 -#endif -#ifndef OUTPUT -# define OUTPUT 512 -#endif - -#ifndef UPDATE_RUNS -# define UPDATE_RUNS 100 -#endif -#ifndef FAST_SQUEEZE_RUNS -# define FAST_SQUEEZE_RUNS 100 -#endif -#ifndef SLOW_SQUEEZE_RUNS -# define SLOW_SQUEEZE_RUNS 100 -#endif -#ifndef RERUNS -# define RERUNS 50 -#endif - - - -/** - * Benchmark, will print the number of nanoseconds - * spent with hashing algorithms and representation - * conversion from binary to hexadecimal. The latter - * can be compiled out by compiling with -DIGNORE_BEHEXING. - * - * @return Zero on success, 1 on error - */ -int -main(void) -{ - char message[MESSAGE_LEN]; - libkeccak_spec_t spec; - libkeccak_state_t state; - char hashsum[OUTPUT / 8]; -#ifndef IGNORE_BEHEXING - char hexsum[OUTPUT / 8 * 2 + 1]; -#endif - struct timespec start, end; - long i, r; - - /* Fill message with content from the file. */ - int fd; - ssize_t got; - size_t ptr; - if (fd = open(MESSAGE_FILE, O_RDONLY), fd < 0) - return perror("open"), 1; - for (ptr = 0; ptr < MESSAGE_LEN; ptr += (size_t)got) - if (got = read(fd, message, MESSAGE_LEN - ptr), got <= 0) - return perror("read"), close(fd), 1; - close(fd); - - /* Initialise state. */ - spec.bitrate = BITRATE; - spec.capacity = CAPACITY; - spec.output = OUTPUT; - if (libkeccak_state_initialise(&state, &spec)) - return perror("libkeccak_state_initialise"), 1; - - /* Get start-time. */ - if (clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &start) < 0) - return perror("clock_gettime"), 1; - - /* Run benchmarking loop. */ - for (r = 0; r < RERUNS; r++) { - /* Updates. */ -#if UPDATE_RUNS > 0 - for (i = 0; i < UPDATE_RUNS; i++) - if (libkeccak_fast_update(&state, message, MESSAGE_LEN) < 0) - return perror("libkeccak_update"), 1; -#endif - - /* Digest. */ - if (libkeccak_fast_digest(&state, NULL, 0, 0, NULL, hashsum) < 0) - return perror("libkeccak_digest"), 1; -#ifndef IGNORE_BEHEXING - libkeccak_behex_lower(hexsum, hashsum, OUTPUT / 8); -#endif - - /* Fast squeezes. */ -#if FAST_SQUEEZE_RUNS > 0 - libkeccak_fast_squeeze(&state, FAST_SQUEEZE_RUNS); -#endif - - /* Slow squeezes. */ -#if SLOW_SQUEEZE_RUNS > 0 - for (i = 0; i < SLOW_SQUEEZE_RUNS; i++) { - libkeccak_squeeze(&state, hashsum); -# ifndef IGNORE_BEHEXING - libkeccak_behex_lower(hexsum, hashsum, OUTPUT / 8); -# endif - } -#endif - } - - /* Get end-time. */ - if (clock_gettime(CLOCK_PROCESS_CPUTIME_ID, &end) < 0) - return perror("clock_gettime"), -1; - - /* Print execution-time. */ - end.tv_sec -= start.tv_sec; - end.tv_nsec -= start.tv_nsec; - if (end.tv_nsec < 0) { - end.tv_sec--; - end.tv_nsec += 1000000000L; - } - printf("%03li%09li\n", (long)(end.tv_sec), end.tv_nsec); - - /* Release resources and exit. */ - libkeccak_state_fast_destroy(&state); - return 0; - -#if (UPDATE_RUNS == 0) && (SLOW_SQUEEZE_RUNS == 0) - (void) i; -#endif -} diff --git a/src/libkeccak.h b/src/libkeccak.h deleted file mode 100644 index 7c71801..0000000 --- a/src/libkeccak.h +++ /dev/null @@ -1,13 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_H -#define LIBKECCAK_H 1 - -#include "libkeccak/spec.h" -#include "libkeccak/generalised-spec.h" -#include "libkeccak/state.h" -#include "libkeccak/digest.h" -#include "libkeccak/hex.h" -#include "libkeccak/files.h" -#include "libkeccak/mac/hmac.h" - -#endif diff --git a/src/libkeccak/digest.c b/src/libkeccak/digest.c deleted file mode 100644 index 5f7a32c..0000000 --- a/src/libkeccak/digest.c +++ /dev/null @@ -1,588 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "digest.h" - -#include "state.h" - - - -/** - * X-macro-enabled listing of all intergers in [0, 4] - */ -#define LIST_5 X(0) X(1) X(2) X(3) X(4) - -/** - * X-macro-enabled listing of all intergers in [0, 7] - */ -#define LIST_8 LIST_5 X(5) X(6) X(7) - -/** - * X-macro-enabled listing of all intergers in [0, 23] - */ -#define LIST_24 LIST_8 X(8) X(9) X(10) X(11) X(12) X(13) X(14) X(15)\ - X(16) X(17) X(18) X(19) X(20) X(21) X(22) X(23) - -/** - * X-macro-enabled listing of all intergers in [0, 24] - */ -#define LIST_25 LIST_24 X(24) - - - -#define X(N) (N % 5) * 5 + N / 5, -/** - * The order the lanes should be read when absorbing or squeezing, - * it transposes the lanes in the sponge - */ -static const long LANE_TRANSPOSE_MAP[] = { LIST_25 }; -#undef X - - - -/** - * Keccak-f round constants - */ -static const uint_fast64_t RC[] = { - 0x0000000000000001ULL, 0x0000000000008082ULL, 0x800000000000808AULL, 0x8000000080008000ULL, - 0x000000000000808BULL, 0x0000000080000001ULL, 0x8000000080008081ULL, 0x8000000000008009ULL, - 0x000000000000008AULL, 0x0000000000000088ULL, 0x0000000080008009ULL, 0x000000008000000AULL, - 0x000000008000808BULL, 0x800000000000008BULL, 0x8000000000008089ULL, 0x8000000000008003ULL, - 0x8000000000008002ULL, 0x8000000000000080ULL, 0x000000000000800AULL, 0x800000008000000AULL, - 0x8000000080008081ULL, 0x8000000000008080ULL, 0x0000000080000001ULL, 0x8000000080008008ULL -}; - - -/** - * Rotate a word - * - * @param x:int_fast64_t The value to rotate - * @param n:long Rotation steps, may be zero mod `w` - * @param w:long `state->w` - * @param wmod:int_fast64_t `state->wmod` - * @return :int_fast64_t The value rotated - */ -#define rotate(x, n, w, wmod) ((((x) >> ((w) - ((n) % (w)))) | ((x) << ((n) % (w)))) & (wmod)) - - -/** - * Rotate a 64-bit word - * - * @param x:int_fast64_t The value to rotate - * @param n:long Rotation steps, may not be zero - * @return :int_fast64_t The value rotated - */ -#define rotate64(x, n) ((int_fast64_t)(((uint64_t)(x) >> (64L - (n))) | ((uint64_t)(x) << (n)))) - - -/** - * Perform one round of computation - * - * @param state The hashing state - * @param rc The round contant for this round - */ -static __attribute__((nonnull, nothrow, hot)) void -libkeccak_f_round(register libkeccak_state_t *restrict state, register int_fast64_t rc) -{ - int_fast64_t *restrict A = state->S; - int_fast64_t B[25]; - int_fast64_t C[5]; - int_fast64_t da, db, dc, dd, de; - int_fast64_t wmod = state->wmod; - long w = state->w; - - /* θ step (step 1 of 3). */ -#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; - LIST_5; -#undef X - - /* θ step (step 2 of 3). */ - da = C[4] ^ rotate(C[1], 1, w, wmod); - dd = C[2] ^ rotate(C[4], 1, w, wmod); - db = C[0] ^ rotate(C[2], 1, w, wmod); - de = C[3] ^ rotate(C[0], 1, w, wmod); - dc = C[1] ^ rotate(C[3], 1, w, wmod); - - /* ρ and π steps, with last two part of θ. */ -#define X(bi, ai, dv, r) B[bi] = rotate(A[ai] ^ dv, r, w, wmod) - B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); - X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); - X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); - X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); - X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); -#undef X - - /* ξ step. */ -#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); - LIST_25; -#undef X - - /* ι step. */ - A[0] ^= rc; -} - - -/** - * 64-bit word version of `libkeccak_f_round` - * - * @param state The hashing state - * @param rc The round contant for this round - */ -static __attribute__((nonnull, nothrow, hot)) void -libkeccak_f_round64(register libkeccak_state_t *restrict state, register int_fast64_t rc) -{ - int_fast64_t *restrict A = state->S; - int_fast64_t B[25]; - int_fast64_t C[5]; - int_fast64_t da, db, dc, dd, de; - - /* θ step (step 1 of 3). */ -#define X(N) C[N] = A[N * 5] ^ A[N * 5 + 1] ^ A[N * 5 + 2] ^ A[N * 5 + 3] ^ A[N * 5 + 4]; - LIST_5; -#undef X - - /* θ step (step 2 of 3). */ - da = C[4] ^ rotate64(C[1], 1); - dd = C[2] ^ rotate64(C[4], 1); - db = C[0] ^ rotate64(C[2], 1); - de = C[3] ^ rotate64(C[0], 1); - dc = C[1] ^ rotate64(C[3], 1); - - /* ρ and π steps, with last two part of θ. */ -#define X(bi, ai, dv, r) B[bi] = rotate64(A[ai] ^ dv, r) - B[0] = A[0] ^ da; X( 1, 15, dd, 28); X( 2, 5, db, 1); X( 3, 20, de, 27); X( 4, 10, dc, 62); - X( 5, 6, db, 44); X( 6, 21, de, 20); X( 7, 11, dc, 6); X( 8, 1, da, 36); X( 9, 16, dd, 55); - X(10, 12, dc, 43); X(11, 2, da, 3); X(12, 17, dd, 25); X(13, 7, db, 10); X(14, 22, de, 39); - X(15, 18, dd, 21); X(16, 8, db, 45); X(17, 23, de, 8); X(18, 13, dc, 15); X(19, 3, da, 41); - X(20, 24, de, 14); X(21, 14, dc, 61); X(22, 4, da, 18); X(23, 19, dd, 56); X(24, 9, db, 2); -#undef X - - /* ξ step. */ -#define X(N) A[N] = B[N] ^ ((~(B[(N + 5) % 25])) & B[(N + 10) % 25]); - LIST_25; -#undef X - - /* ι step. */ - A[0] ^= rc; -} - - -/** - * Convert a chunk of bytes to a lane - * - * @param state The hashing state - */ -static inline __attribute__((nonnull, nothrow, gnu_inline)) void -libkeccak_f(register libkeccak_state_t *restrict state) -{ - register long i = 0; - register long nr = state->nr; - register long wmod = state->wmod; - if (nr == 24) { - for (; i < nr; i++) - libkeccak_f_round64(state, (int_fast64_t)(RC[i])); - } else { - for (; i < nr; i++) - libkeccak_f_round(state, (int_fast64_t)(RC[i] & wmod)); - } -} - - -/** - * Convert a chunk of bytes to a lane - * - * @param message The message - * @param msglen The length of the message - * @param rr Bitrate in bytes - * @param ww Word size in bytes - * @param off The offset in the message - * @return The lane - */ -static inline __attribute__((nonnull, nothrow, pure, warn_unused_result, gnu_inline)) int_fast64_t -libkeccak_to_lane(register const char *restrict message, register size_t msglen, - register long rr, register long ww, size_t off) -{ - register long n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); - int_fast64_t rc = 0; - message += off; - while (ww--) { - rc <<= 8; - rc |= __builtin_expect(ww < n, 1) ? (int_fast64_t)(unsigned char)(message[ww]) : 0L; - } - return rc; -} - - -/** - * 64-bit lane version of `libkeccak_to_lane` - * - * @param message The message - * @param msglen The length of the message - * @param rr Bitrate in bytes - * @param off The offset in the message - * @return The lane - */ -static inline __attribute__((nonnull, nothrow, pure, hot, warn_unused_result, gnu_inline)) int_fast64_t -libkeccak_to_lane64(register const char* restrict message, register size_t msglen, - register long rr, size_t off) -{ - register long n = (long)((msglen < (size_t)rr ? msglen : (size_t)rr) - off); - int_fast64_t rc = 0; - message += off; -#define X(N) if (__builtin_expect(N < n, 1)) rc |= (int_fast64_t)(unsigned char)(message[N]) << (N * 8);\ - else return rc; - LIST_8; -#undef X - return rc; -} - - -/** - * pad 10*1 - * - * @param state The hashing state, `state->M` and `state->mptr` will be updated, - * `state->M` should have `state->r / 8` bytes left over at the end - * @param bits The number of bits in the end of the message that does not make a whole byte - */ -static inline __attribute__((nonnull, nothrow, gnu_inline)) void -libkeccak_pad10star1(register libkeccak_state_t *restrict state, register size_t bits) -{ - register size_t r = (size_t)(state->r); - register size_t nrf = state->mptr - !!bits; - register size_t len = (nrf << 3) | bits; - register size_t ll = len % r; - register char b = (char)(bits ? (state->M[nrf] | (1 << bits)) : 1); - - if (r - 8 <= ll && ll <= r - 2) { - state->M[nrf] = (char)(b ^ 0x80); - state->mptr = nrf + 1; - } else { - len = ++nrf << 3; - len = (len - (len % r) + (r - 8)) >> 3; - state->mptr = len + 1; - - state->M[nrf - 1] = b; - __builtin_memset(state->M + nrf, 0, (len - nrf) * sizeof(char)); - state->M[len] = (char)0x80; - } -} - - -/** - * Perform the absorption phase - * - * @param state The hashing state - * @param len The number of bytes from `state->M` to absorb - */ -static __attribute__((nonnull, nothrow)) void -libkeccak_absorption_phase(register libkeccak_state_t *restrict state, register size_t len) -{ - register long rr = state->r >> 3; - register long ww = state->w >> 3; - register long n = (long)len / rr; - register const char* restrict message = state->M; - if (__builtin_expect(ww >= 8, 1)) { /* ww > 8 is impossible, it is just for optimisation possibilities. */ - while (n--) { -#define X(N) state->S[N] ^= libkeccak_to_lane64(message, len, rr, (size_t)(LANE_TRANSPOSE_MAP[N] * 8)); - LIST_25; -#undef X - libkeccak_f(state); - message += (size_t)rr; - len -= (size_t)rr; - } - } else { - while (n--) { -#define X(N) state->S[N] ^= libkeccak_to_lane(message, len, rr, ww, (size_t)(LANE_TRANSPOSE_MAP[N] * ww)); - LIST_25; -#undef X - libkeccak_f(state); - message += (size_t)rr; - len -= (size_t)rr; - } - } -} - - -/** - * Perform the squeezing phase - * - * @param state The hashing state - * @param rr The bitrate in bytes - * @param nn The output size in bytes, rounded up to whole bytes - * @param ww The word size in bytes - * @param hashsum Output parameter for the hashsum - */ -static __attribute__((nonnull, nothrow, hot)) void -libkeccak_squeezing_phase(register libkeccak_state_t *restrict state, long rr, - long nn, long ww, register char *restrict hashsum) -{ - register int_fast64_t v; - register long ni = rr / ww; - auto long olen = state->n; - auto long i, j = 0; - register long k; - while (olen > 0) { - for (i = 0; i < ni && j < nn; i++) { - v = state->S[LANE_TRANSPOSE_MAP[i]]; - for (k = 0; k++ < ww && j++ < nn; v >>= 8) - *hashsum++ = (char)v; - } - if (olen -= state->r, olen > 0) - libkeccak_f(state); - } - if (state->n & 7) - hashsum[-1] &= (char)((1 << (state->n & 7)) - 1); -} - - -/** - * Absorb more of the message to the Keccak sponge - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message - * @return Zero on success, -1 on error - */ -int -libkeccak_fast_update(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen) -{ - size_t len; - auto char *restrict new; - - if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { - state->mlen += msglen; - new = realloc(state->M, state->mlen * sizeof(char)); - if (!new) - return state->mlen -= msglen, -1; - state->M = new; - } - - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - len = state->mptr; - len -= state->mptr % (size_t)((state->r * state->b) >> 3); - state->mptr -= len; - - libkeccak_absorption_phase(state, len); - __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); - - return 0; -} - - -/** - * Absorb more of the message to the Keccak sponge - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message - * @return Zero on success, -1 on error - */ -int -libkeccak_update(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen) -{ - size_t len; - auto char *restrict new; - - if (__builtin_expect(state->mptr + msglen > state->mlen, 0)) { - state->mlen += msglen; - new = malloc(state->mlen * sizeof(char)); - if (new == NULL) - return state->mlen -= msglen, -1; - libkeccak_state_wipe_message(state); - free(state->M); - state->M = new; - } - - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - len = state->mptr; - len -= state->mptr % (size_t)((state->r * state->b) >> 3); - state->mptr -= len; - - libkeccak_absorption_phase(state, len); - __builtin_memmove(state->M, state->M + len, state->mptr * sizeof(char)); - - return 0; -} - - -/** - * Absorb the last part of the message and squeeze the Keccak sponge - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL` - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_fast_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum) -{ - auto char *restrict new; - register long rr = state->r >> 3; - auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; - register size_t ext; - register long i; - - if (msg == NULL) - msglen = bits = 0; - else - msglen += bits >> 3, bits &= 7; - - ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; - if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { - state->mlen += ext; - new = realloc(state->M, state->mlen * sizeof(char)); - if (!new) - return state->mlen -= ext, -1; - state->M = new; - } - - if (msglen) - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - - if (bits) - state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); - if (__builtin_expect(!!suffix_len, 1)) { - if (bits == 0) - state->M[state->mptr] = 0; - while (suffix_len--) { - state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); - if (bits == 8) - bits = 0, state->M[++(state->mptr)] = 0; - } - } - if (bits) - state->mptr++; - - libkeccak_pad10star1(state, bits); - libkeccak_absorption_phase(state, state->mptr); - - if (hashsum) { - libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); - } else { - for (i = (state->n - 1) / state->r; i--;) - libkeccak_f(state); - } - - return 0; -} - - -/** - * Absorb the last part of the message and squeeze the Keccak sponge - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL` - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum) -{ - auto char *restrict new; - register long rr = state->r >> 3; - auto size_t suffix_len = suffix ? __builtin_strlen(suffix) : 0; - register size_t ext; - register long i; - - if (msg == NULL) - msglen = bits = 0; - else - msglen += bits >> 3, bits &= 7; - - ext = msglen + ((bits + suffix_len + 7) >> 3) + (size_t)rr; - if (__builtin_expect(state->mptr + ext > state->mlen, 0)) { - state->mlen += ext; - new = malloc(state->mlen * sizeof(char)); - if (!new) - return state->mlen -= ext, -1; - libkeccak_state_wipe_message(state); - free(state->M); - state->M = new; - } - - if (msglen) - __builtin_memcpy(state->M + state->mptr, msg, msglen * sizeof(char)); - state->mptr += msglen; - - if (bits) - state->M[state->mptr] = msg[msglen] & (char)((1 << bits) - 1); - if (__builtin_expect(!!suffix_len, 1)) { - if (bits == 0) - state->M[state->mptr] = 0; - while (suffix_len--) { - state->M[state->mptr] |= (char)((*suffix++ & 1) << bits++); - if (bits == 8) - bits = 0, state->M[++(state->mptr)] = 0; - } - } - if (bits) - state->mptr++; - - libkeccak_pad10star1(state, bits); - libkeccak_absorption_phase(state, state->mptr); - - if (hashsum) { - libkeccak_squeezing_phase(state, rr, (state->n + 7) >> 3, state->w >> 3, hashsum); - } else { - for (i = (state->n - 1) / state->r; i--;) - libkeccak_f(state); - } - - return 0; -} - - -/** - * Force some rounds of Keccak-f - * - * @param state The hashing state - * @param times The number of rounds - */ -void -libkeccak_simple_squeeze(register libkeccak_state_t *restrict state, register long times) -{ - while (times--) - libkeccak_f(state); -} - - -/** - * Squeeze as much as is needed to get a digest a number of times - * - * @param state The hashing state - * @param times The number of digests - */ -void -libkeccak_fast_squeeze(register libkeccak_state_t *restrict state, register long times) -{ - times *= (state->n - 1) / state->r + 1; - while (times--) - libkeccak_f(state); -} - - -/** - * Squeeze out another digest - * - * @param state The hashing state - * @param hashsum Output parameter for the hashsum - */ -void -libkeccak_squeeze(register libkeccak_state_t *restrict state, register char* restrict hashsum) -{ - libkeccak_f(state); - libkeccak_squeezing_phase(state, state->r >> 3, (state->n + 7) >> 3, state->w >> 3, hashsum); -} diff --git a/src/libkeccak/digest.h b/src/libkeccak/digest.h deleted file mode 100644 index 832f0c0..0000000 --- a/src/libkeccak/digest.h +++ /dev/null @@ -1,100 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_DIGEST_H -#define LIBKECCAK_DIGEST_H 1 - -#include "state.h" -#include "internal.h" - - -/** - * Absorb more of the message to the Keccak sponge - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) -int libkeccak_fast_update(libkeccak_state_t *restrict state, const char* restrict msg, size_t msglen); - - -/** - * Absorb more of the message to the Keccak sponge - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) -int libkeccak_update(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen); - - -/** - * Absorb the last part of the message and squeeze the Keccak sponge - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL` - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) -int libkeccak_fast_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum); - - -/** - * Absorb the last part of the message and squeeze the Keccak sponge - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL` - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) -int libkeccak_digest(libkeccak_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum); - - -/** - * Force some rounds of Keccak-f - * - * @param state The hashing state - * @param times The number of rounds - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) -void libkeccak_simple_squeeze(register libkeccak_state_t *restrict state, register long times); - - -/** - * Squeeze as much as is needed to get a digest a number of times - * - * @param state The hashing state - * @param times The number of digests - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) -void libkeccak_fast_squeeze(register libkeccak_state_t *restrict state, register long times); - - -/** - * Squeeze out another digest - * - * @param state The hashing state - * @param hashsum Output parameter for the hashsum - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) -void libkeccak_squeeze(register libkeccak_state_t *restrict state, register char* restrict hashsum); - - -#endif - diff --git a/src/libkeccak/files.c b/src/libkeccak/files.c deleted file mode 100644 index 22d12f3..0000000 --- a/src/libkeccak/files.c +++ /dev/null @@ -1,57 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "files.h" - -#include -#include -#include -#include -#include - - - -/** - * Calculate a Keccak-family hashsum of a file, - * the content of the file is assumed non-sensitive - * - * @param fd The file descriptor of the file to hash - * @param state The hashing state, should not be initialised (memory leak otherwise) - * @param spec Specifications for the hashing algorithm - * @param suffix The data suffix, see `libkeccak_digest` - * @param hashsum Output array for the hashsum, have an allocation size of - * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_generalised_sum_fd(int fd, libkeccak_state_t *restrict state, - const libkeccak_spec_t *restrict spec, - const char *restrict suffix, char *restrict hashsum) -{ - ssize_t got; - struct stat attr; - size_t blksize = 4096; - char *restrict chunk; - - if (libkeccak_state_initialise(state, spec) < 0) - return -1; - - if (fstat(fd, &attr) == 0) - if (attr.st_blksize > 0) - blksize = (size_t)(attr.st_blksize); - - chunk = alloca(blksize); - - for (;;) { - got = read(fd, chunk, blksize); - if (got < 0) { - if (errno == EINTR) - continue; - return -1; - } - if (got == 0) - break; - if (libkeccak_fast_update(state, chunk, (size_t)got) < 0) - return -1; - } - - return libkeccak_fast_digest(state, NULL, 0, 0, suffix, hashsum); -} diff --git a/src/libkeccak/files.h b/src/libkeccak/files.h deleted file mode 100644 index 92038fb..0000000 --- a/src/libkeccak/files.h +++ /dev/null @@ -1,115 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_FILES_H -#define LIBKECCAK_FILES_H 1 - -#include "../libkeccak.h" -#include "internal.h" - - -/** - * Calculate a Keccak-family hashsum of a file, - * the content of the file is assumed non-sensitive - * - * @param fd The file descriptor of the file to hash - * @param state The hashing state, should not be initialised (memory leak otherwise) - * @param spec Specifications for the hashing algorithm - * @param suffix The data suffix, see `libkeccak_digest` - * @param hashsum Output array for the hashsum, have an allocation size of - * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2, 3)))) -int libkeccak_generalised_sum_fd(int fd, libkeccak_state_t *restrict state, - const libkeccak_spec_t *restrict spec, - const char *restrict suffix, char *restrict hashsum); - - -/** - * Calculate the Keccak hashsum of a file, - * the content of the file is assumed non-sensitive - * - * @param fd The file descriptor of the file to hash - * @param state The hashing state, should not be initialised (memory leak otherwise) - * @param spec Specifications for the hashing algorithm - * @param hashsum Output array for the hashsum, have an allocation size of - * at least `((spec->output + 7) / 8) * sizeof(char)`, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2, 3), artificial, gnu_inline))) -static inline int -libkeccak_keccaksum_fd(int fd, libkeccak_state_t *restrict state, - const libkeccak_spec_t *restrict spec, char *restrict hashsum) -{ - return libkeccak_generalised_sum_fd(fd, state, spec, NULL, hashsum); -} - - -/** - * Calculate the SHA3 hashsum of a file, - * the content of the file is assumed non-sensitive - * - * @param fd The file descriptor of the file to hash - * @param state The hashing state, should not be initialised (memory leak otherwise) - * @param output The output size parameter for the hashing algorithm - * @param hashsum Output array for the hashsum, have an allocation size of - * at least `((output + 7) / 8) * sizeof(char)`, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2), artificial, gnu_inline))) -static inline int -libkeccak_sha3sum_fd(int fd, libkeccak_state_t *restrict state, - long output, char *restrict hashsum) -{ - libkeccak_spec_t spec; - libkeccak_spec_sha3(&spec, output); - return libkeccak_generalised_sum_fd(fd, state, &spec, LIBKECCAK_SHA3_SUFFIX, hashsum); -} - - -/** - * Calculate the RawSHAKE hashsum of a file, - * the content of the file is assumed non-sensitive - * - * @param fd The file descriptor of the file to hash - * @param state The hashing state, should not be initialised (memory leak otherwise) - * @param semicapacity The semicapacity parameter for the hashing algorithm - * @param output The output size parameter for the hashing algorithm - * @param hashsum Output array for the hashsum, have an allocation size of - * at least `((output + 7) / 8) * sizeof(char)`, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2), artificial, gnu_inline))) -static inline int -libkeccak_rawshakesum_fd(int fd, libkeccak_state_t *restrict state, - long semicapacity, long output, char *restrict hashsum) -{ - libkeccak_spec_t spec; - libkeccak_spec_rawshake(&spec, semicapacity, output); - return libkeccak_generalised_sum_fd(fd, state, &spec, LIBKECCAK_RAWSHAKE_SUFFIX, hashsum); -} - - -/** - * Calculate the SHAKE hashsum of a file, - * the content of the file is assumed non-sensitive - * - * @param fd The file descriptor of the file to hash - * @param state The hashing state, should not be initialised (memory leak otherwise) - * @param semicapacity The semicapacity parameter for the hashing algorithm - * @param output The output size parameter for the hashing algorithm - * @param hashsum Output array for the hashsum, have an allocation size of - * at least `((output + 7) / 8) * sizeof(char)`, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(2), artificial, gnu_inline))) -static inline int -libkeccak_shakesum_fd(int fd, libkeccak_state_t *restrict state, - long semicapacity, long output, char *restrict hashsum) -{ - libkeccak_spec_t spec; - libkeccak_spec_shake(&spec, semicapacity, output); - return libkeccak_generalised_sum_fd(fd, state, &spec, LIBKECCAK_SHAKE_SUFFIX, hashsum); -} - - -#endif diff --git a/src/libkeccak/generalised-spec.c b/src/libkeccak/generalised-spec.c deleted file mode 100644 index 9dfa918..0000000 --- a/src/libkeccak/generalised-spec.c +++ /dev/null @@ -1,111 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "generalised-spec.h" - -#ifdef __GNUC__ -# pragma GCC diagnostic push -# pragma GCC diagnostic ignored "-Wmaybe-uninitialized" -#endif - -#define have(v) (spec->v != LIBKECCAK_GENERALISED_SPEC_AUTOMATIC) -#define copy(v) (v = spec->v) -#define deft(v, dv) (have_##v ? v : (dv)) - - - -/** - * Convert a `libkeccak_generalised_spec_t` to a `libkeccak_spec_t` - * - * If you are interrested in finding errors, you should call - * `libkeccak_spec_check(output)` if this function returns zero - * - * @param spec The generalised input specifications, will be update with resolved automatic values - * @param output_spec The specification datastructure to fill in - * @return Zero if `spec` is valid, a `LIBKECCAK_GENERALISED_SPEC_ERROR_*` if an error was found - */ -int -libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *restrict spec, - libkeccak_spec_t *restrict output_spec) -{ - long state_size, word_size, capacity, bitrate, output; - const int have_state_size = have(state_size); - const int have_word_size = have(word_size); - const int have_capacity = have(capacity); - const int have_bitrate = have(bitrate); - const int have_output = have(output); - - - if (have_state_size) { - copy(state_size); - if (state_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE; - if (state_size > 1600) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE; - if (state_size % 25) return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25; - } - - if (have_word_size) { - copy(word_size); - if (word_size <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE; - if (word_size > 64) return LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE; - if (have_state_size && state_size != word_size * 25) - return LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY; - else if (!have_state_size) - spec->state_size = 1, state_size = word_size * 25; - } - - if (have_capacity) { - copy(capacity); - if (capacity <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE; - if (capacity & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8; - } - - if (have_bitrate) { - copy(bitrate); - if (bitrate <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE; - if (bitrate & 7) return LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8; - } - - if (have_output) { - copy(output); - if (output <= 0) return LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE; - } - - - if (!have_bitrate && !have_capacity && !have_output) { - state_size = deft(state_size, 1600L); - output = ((state_size << 5) / 100L + 7L) & ~0x07L; - bitrate = output << 1; - capacity = state_size - bitrate; - output = output >= 8 ? output : 8; - } else if (!have_bitrate && !have_capacity) { - bitrate = 1024; - capacity = 1600 - 1024; - state_size = deft(state_size, bitrate + capacity); - } else if (!have_bitrate) { - state_size = deft(state_size, 1600L); - bitrate = state_size - capacity; - output = deft(output, capacity == 8 ? 8 : (capacity << 1)); - } else if (!have_capacity) { - state_size = deft(state_size, 1600L); - capacity = state_size - bitrate; - output = deft(output, capacity == 8 ? 8 : (capacity << 1)); - } else { - state_size = deft(state_size, bitrate + capacity); - output = deft(output, capacity == 8 ? 8 : (capacity << 1)); - } - - spec->capacity = output_spec->capacity = capacity; - spec->bitrate = output_spec->bitrate = bitrate; - spec->output = output_spec->output = output; - spec->state_size = state_size; - spec->word_size = state_size / 25; - - return 0; -} - - -#undef deft -#undef copy -#undef have - -#ifdef __GNUC__ -# pragma GCC diagnostic pop -#endif diff --git a/src/libkeccak/generalised-spec.h b/src/libkeccak/generalised-spec.h deleted file mode 100644 index 2725961..0000000 --- a/src/libkeccak/generalised-spec.h +++ /dev/null @@ -1,142 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_GENERALISED_SPEC_H -#define LIBKECCAK_GENERALISED_SPEC_H 1 - -#include "spec.h" -#include "internal.h" - -#include - - - -/** - * Value for `libkeccak_generalised_spec_t` member that - * is used to automatically select the value - */ -#define LIBKECCAK_GENERALISED_SPEC_AUTOMATIC (-65536L) - - -/** - * Invalid `libkeccak_generalised_spec_t.state_size`: non-positive - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_NONPOSITIVE 1 - -/** - * Invalid `libkeccak_generalised_spec_t.state_size`: larger than 1600 - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_TOO_LARGE 2 - -/** - * Invalid `libkeccak_generalised_spec_t.state_size`: not a multiple of 25 - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_MOD_25 3 - -/** - * Invalid `libkeccak_generalised_spec_t.word_size`: non-positive - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_NONPOSITIVE 4 - -/** - * Invalid `libkeccak_generalised_spec_t.word_size`: larger than 1600 / 25 - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_WORD_TOO_LARGE 5 - -/** - * Invalid `libkeccak_generalised_spec_t.word_size` and - * `libkeccak_generalised_spec_t.state_size`: `.word_size * 25 != .state_size` - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_STATE_WORD_INCOHERENCY 6 - -/** - * Invalid `libkeccak_generalised_spec_t.capacity`: non-positive - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_NONPOSITIVE 7 - -/** - * Invalid `libkeccak_generalised_spec_t.capacity`: not a multiple of 8 - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_CAPACITY_MOD_8 8 - -/** - * Invalid `libkeccak_generalised_spec_t.bitrate`: non-positive - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_NONPOSITIVE 9 - -/** - * Invalid `libkeccak_generalised_spec_t.bitrate`: not a multiple of 8 - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_BITRATE_MOD_8 10 - -/** - * Invalid `libkeccak_generalised_spec_t.output`: non-positive - */ -#define LIBKECCAK_GENERALISED_SPEC_ERROR_OUTPUT_NONPOSITIVE 11 - - - -/** - * Generalised datastructure that describes the - * parameters that should be used when hashing - */ -typedef struct libkeccak_generalised_spec -{ - /** - * The bitrate - */ - long bitrate; - - /** - * The capacity - */ - long capacity; - - /** - * The output size - */ - long output; - - /** - * The state size - */ - long state_size; - - /** - * The word size - */ - long word_size; - -} libkeccak_generalised_spec_t; - - - -/** - * Set all specification parameters to automatic - * - * @param spec The specification datastructure to fill in - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused))) -static inline void -libkeccak_generalised_spec_initialise(libkeccak_generalised_spec_t *restrict spec) -{ - spec->bitrate = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; - spec->capacity = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; - spec->output = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; - spec->state_size = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; - spec->word_size = LIBKECCAK_GENERALISED_SPEC_AUTOMATIC; -} - - -/** - * Convert a `libkeccak_generalised_spec_t` to a `libkeccak_spec_t` - * - * @param spec The generalised input specifications, will be update with resolved automatic values - * @param output_spec The specification datastructure to fill in - * @return Zero if `spec` is valid, a `LIBKECCAK_GENERALISED_SPEC_ERROR_*` if an error was found - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) -int libkeccak_degeneralise_spec(libkeccak_generalised_spec_t *restrict spec, - libkeccak_spec_t *restrict output_spec); - - -#endif - diff --git a/src/libkeccak/hex.c b/src/libkeccak/hex.c deleted file mode 100644 index 7531223..0000000 --- a/src/libkeccak/hex.c +++ /dev/null @@ -1,65 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "hex.h" - -#include - - - -/** - * Convert a binary hashsum to lower case hexadecimal representation - * - * @param output Output array, should have an allocation size of at least `2 * n + 1` - * @param hashsum The hashsum to convert - * @param n The size of `hashsum` - */ -void -libkeccak_behex_lower(char *restrict output, const char *restrict hashsum, size_t n) -{ - output[2 * n] = '\0'; - while (n--) { - output[2 * n + 0] = "0123456789abcdef"[(hashsum[n] >> 4) & 15]; - output[2 * n + 1] = "0123456789abcdef"[(hashsum[n] >> 0) & 15]; - } -} - - -/** - * Convert a binary hashsum to upper case hexadecimal representation - * - * @param output Output array, should have an allocation size of at least `2 * n + 1` - * @param hashsum The hashsum to convert - * @param n The size of `hashsum` - */ -void -libkeccak_behex_upper(char *restrict output, const char *restrict hashsum, size_t n) -{ - output[2 * n] = '\0'; - while (n--) { - output[2 * n + 0] = "0123456789ABCDEF"[(hashsum[n] >> 4) & 15]; - output[2 * n + 1] = "0123456789ABCDEF"[(hashsum[n] >> 0) & 15]; - } -} - - -/** - * Convert a hexadecimal hashsum (both lower case, upper - * case and mixed is supported) to binary representation - * - * @param output Output array, should have an allocation size of at least `strlen(hashsum) / 2` - * @param hashsum The hashsum to convert - */ -void -libkeccak_unhex(char *restrict output, const char *restrict hashsum) -{ - size_t n = strlen(hashsum) / 2; - char a, b; - while (n--) { - a = hashsum[2 * n + 0]; - b = hashsum[2 * n + 1]; - - a = (char)((a & 15) + (a > '9' ? 9 : 0)); - b = (char)((b & 15) + (b > '9' ? 9 : 0)); - - output[n] = (char)((a << 4) | b); - } -} diff --git a/src/libkeccak/hex.h b/src/libkeccak/hex.h deleted file mode 100644 index 25375d5..0000000 --- a/src/libkeccak/hex.h +++ /dev/null @@ -1,44 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_HEX_H -#define LIBKECCAK_HEX_H 1 - -#include "internal.h" - -#include - - -/** - * Convert a binary hashsum to lower case hexadecimal representation - * - * @param output Output array, should have an allocation size of at least `2 * n + 1` - * @param hashsum The hashsum to convert - * @param n The size of `hashsum` - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) -void libkeccak_behex_lower(char *restrict output, const char *restrict hashsum, size_t n); - - -/** - * Convert a binary hashsum to upper case hexadecimal representation - * - * @param output Output array, should have an allocation size of at least `2 * n + 1` - * @param hashsum The hashsum to convert - * @param n The size of `hashsum` - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) -void libkeccak_behex_upper(char *restrict output, const char *restrict hashsum, size_t n); - - -/** - * Convert a hexadecimal hashsum (both lower case, upper - * case and mixed is supported) to binary representation - * - * @param output Output array, should have an allocation size of at least `strlen(hashsum) / 2` - * @param hashsum The hashsum to convert - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) -void libkeccak_unhex(char *restrict output, const char *restrict hashsum); - - -#endif - diff --git a/src/libkeccak/internal.h b/src/libkeccak/internal.h deleted file mode 100644 index 466abf9..0000000 --- a/src/libkeccak/internal.h +++ /dev/null @@ -1,26 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_INTERNAL_H -#define LIBKECCAK_INTERNAL_H 1 - - -/** - * Only include some C code (not for CPP directives) - * if compiling with GCC. - */ -#ifdef __GNUC__ -# define LIBKECCAK_GCC_ONLY(x) x -#else -# define LIBKECCAK_GCC_ONLY(x) -#endif - - -/* Use built in functions and branching optimisation if available */ -#ifndef __GNUC__ -# define __builtin_expect(expression, expect) expression -# define __builtin_memset(dest, c, n) memset(dest, c, n) -# define __builtin_memcpy(dest, src, n) memcpy(dest, src, n) -# define __builtin_memmove(dest, src, n) memmove(dest, src, n) -#endif - - -#endif diff --git a/src/libkeccak/mac/hmac.c b/src/libkeccak/mac/hmac.c deleted file mode 100644 index ee3bc6a..0000000 --- a/src/libkeccak/mac/hmac.c +++ /dev/null @@ -1,418 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "hmac.h" - -#include "../digest.h" - - - -/** - * The outer pad pattern - */ -#define OUTER_PAD 0x5C - -/** - * The inner pad pattern - */ -#define INNER_PAD 0x36 - - - -static void *(*volatile my_explicit_memset)(void *, int, size_t) = memset; -static __attribute__((optimize("-O0"))) void -my_explicit_bzero(void *ptr, size_t size) -{ - (*my_explicit_memset)(ptr, 0, size); -} - - -/** - * Change the HMAC-hashing key on the state - * - * @param state The state that should be reset - * @param key The new key - * @param key_length The length of key, in bits - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_set_key(libkeccak_hmac_state_t *restrict state, const char *restrict key, size_t key_length) -{ - size_t i, size, new_key_length, key_bytes; - char *old; - - size = (size_t)(state->sponge.r) > key_length ? (size_t)(state->sponge.r) : key_length; - new_key_length = size; - size = (size + 7) >> 3; - key_bytes = (key_length + 7) >> 3; - - if (size != key_bytes) { - state->key_opad = realloc(old = state->key_opad, 2 * size); - if (!state->key_opad) - return state->key_opad = old, -1; - state->key_ipad = state->key_opad + size / sizeof(char); - } - - memcpy(state->key_opad, key, key_bytes); - if (key_length & 7) - state->key_opad[(key_bytes >> 3) - 1] &= (1 << (key_length & 7)) - 1; - - if ((size_t)(state->sponge.r) > key_length) - __builtin_memset(state->key_opad + key_bytes / sizeof(char), 0, size - key_bytes); - - for (i = 0; i < size; i++) { - state->key_ipad[i] = state->key_opad[i] ^ INNER_PAD; - state->key_opad[i] ^= OUTER_PAD; - } - - state->key_length = new_key_length; - - return 0; -} - - -/** - * Wipe sensitive data wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_hmac_wipe(volatile libkeccak_hmac_state_t *restrict state) -{ - volatile char *restrict key_pads; - size_t i, size; - key_pads = state->key_opad; - size = 2 * ((state->key_length + 7) >> 3); - libkeccak_state_wipe(&state->sponge); - for (i = 0; i < size; i++) - key_pads[i] = 0; - state->leftover = 0; - __builtin_memset(state->buffer, 0, state->buffer_size); -} - - -/** - * Make a copy of an HMAC hashing-state - * - * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) - * @param src The state to duplicate - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_copy(libkeccak_hmac_state_t *restrict dest, const libkeccak_hmac_state_t *restrict src) -{ - size_t size; - - dest->key_opad = NULL; - dest->key_ipad = NULL; - - if (libkeccak_state_copy(&dest->sponge, &src->sponge) < 0) - return -1; - - dest->key_length = src->key_length; - dest->leftover = src->leftover; - - size = (src->key_length + 7) >> 3; - dest->key_opad = malloc(2 * size); - if (dest->key_opad == NULL) - return libkeccak_state_destroy(&dest->sponge), -1; - dest->key_ipad = dest->key_opad + size / sizeof(char); - - memcpy(dest->key_opad, src->key_opad, size); - memcpy(dest->key_ipad, src->key_ipad, size); - - return 0; -} - - -/** - * Unmarshal a `libkeccak_hmac_state_t` from a buffer - * - * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) - * @param data The input buffer - * @return The number of bytes read from `data`, 0 on error - */ -size_t -libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *restrict state, const char *restrict data) -{ - size_t parsed, size, i; - - state->key_opad = NULL; - state->key_ipad = NULL; - - parsed = libkeccak_state_unmarshal(&state->sponge, data); - if (parsed == 0) - return 0; - - data += parsed / sizeof(char); - state->key_length = *(const size_t *)data; - data += sizeof(size_t) / sizeof(char); - size = (state->key_length + 7) >> 3; - - state->key_opad = malloc(2 * size); - if (state->key_opad == NULL) - return libkeccak_state_destroy(&state->sponge), -1; - memcpy(state->key_opad, data, size); - data += size / sizeof(char); - - if (data[0]) { - state->key_ipad = state->key_opad + size / sizeof(char); - memcpy(state->key_ipad, state->key_opad, size); - for (i = 0; i < size / sizeof(char); i++) - state->key_ipad[i] ^= (char)(OUTER_PAD ^ INNER_PAD); - } - - state->leftover = data[1]; - state->buffer = NULL; - state->buffer_size = 0; - - return parsed + sizeof(size_t) + size + 2 * sizeof(char); -} - - -/** - * Absorb more, or the first part, of the message - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message, in bytes - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_fast_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen) -{ - char *old; - size_t i; - int n, cn; - - if (state->key_ipad) { - if (libkeccak_fast_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) - return -1; - if (state->key_length & 7) - state->leftover = state->key_ipad[state->key_length >> 3]; - state->key_ipad = NULL; - } - - if (!msg || !msglen) - return 0; - - if (!(state->key_length & 7)) - return libkeccak_fast_update(&state->sponge, msg, msglen); - - if (msglen != state->buffer_size) { - state->buffer = realloc(old = state->buffer, msglen); - if (!state->buffer) - return state->buffer = old, -1; - state->buffer_size = msglen; - } - - n = (int)(state->key_length & 7); - cn = 8 - n; - for (i = 1; i < msglen; i++) - state->buffer[i] = (((unsigned char)(msg[i - 1])) >> cn) | (msg[i] << n); - state->buffer[0] = (state->leftover & ((1 << n) - 1)) | (msg[0] << n); - state->leftover = ((unsigned char)(msg[msglen - 1])) >> cn; - - return libkeccak_fast_update(&state->sponge, state->buffer, msglen); -} - - -/** - * Absorb more, or the first part, of the message - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message, in bytes - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen) -{ - size_t i; - int n, cn, r; - - if (state->key_ipad) { - if (libkeccak_update(&state->sponge, state->key_ipad, state->key_length >> 3) < 0) - return -1; - if (state->key_length & 7) - state->leftover = state->key_ipad[state->key_length >> 3]; - state->key_ipad = NULL; - } - - if (!msg || !msglen) - return 0; - - if (!(state->key_length & 7)) - return libkeccak_update(&state->sponge, msg, msglen); - - if (msglen != state->buffer_size) { - free(state->buffer); - state->buffer = malloc(state->buffer_size = msglen); - if (!state->buffer) - return -1; - } - - n = (int)(state->key_length & 7); - cn = 8 - n; - for (i = 1; i < msglen; i++) - state->buffer[i] = (((unsigned char)(msg[i - 1])) >> cn) | (msg[i] << n); - state->buffer[0] = (state->leftover & ((1 << n) - 1)) | (msg[0] << n); - state->leftover = ((unsigned char)(msg[msglen - 1])) >> cn; - - r = libkeccak_update(&state->sponge, state->buffer, msglen); - my_explicit_bzero(state->buffer, msglen); - return r; -} - - -/** - * Absorb the last part of the message and fetch the hash - * without wiping sensitive data when possible - * - * You may use `&state->sponge` for continued squeezing - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL`, may be modified - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum) -{ - size_t hashsize = state->sponge.n >> 3; - char *tmp = malloc(((state->sponge.n + 7) >> 3) * sizeof(char)); - char leftover[2]; - size_t newlen; - - if (!tmp) - return -1; - - if (!(state->key_length & 7)) { - if (libkeccak_fast_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) - goto fail; - goto stage_2; - } - - if (libkeccak_hmac_fast_update(state, msg, msglen) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= msg[msglen] >> (state->key_length & 7); - leftover[1] = ((unsigned char)(msg[msglen])) << (8 - (state->key_length & 7)); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_2: - bits = state->sponge.n & 7; - state->key_ipad = state->key_opad; - if (libkeccak_hmac_fast_update(state, NULL, 0) < 0) - goto fail; - - if (!(state->key_length & 7)) { - if (libkeccak_fast_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) - goto fail; - goto stage_3; - } - - if (libkeccak_hmac_fast_update(state, tmp, hashsize) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= tmp[hashsize] >> (state->key_length & 7); - leftover[1] = ((unsigned char)(tmp[hashsize])) << (8 - (state->key_length & 7)); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_fast_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_3: - free(tmp); - return 0; -fail: - free(tmp); - return -1; -} - - -/** - * Absorb the last part of the message and fetch the hash - * and wipe sensitive data when possible - * - * You may use `&state->sponge` for continued squeezing - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL`, may be modified - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -int -libkeccak_hmac_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum) -{ - size_t hashsize = state->sponge.n >> 3; - char *tmp = malloc(((state->sponge.n + 7) >> 3) * sizeof(char)); - char leftover[2]; - size_t newlen; - - if (!tmp) - return -1; - - if (!(state->key_length & 7)) { - if (libkeccak_digest(&state->sponge, msg, msglen, bits, suffix, tmp) < 0) - goto fail; - goto stage_2; - } - - if (libkeccak_hmac_update(state, msg, msglen) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= msg[msglen] >> (state->key_length & 7); - leftover[1] = ((unsigned char)(msg[msglen])) << (8 - (state->key_length & 7)); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_2: - bits = state->sponge.n & 7; - state->key_ipad = state->key_opad; - if (libkeccak_hmac_update(state, NULL, 0) < 0) - goto fail; - - if (!(state->key_length & 7)) { - if (libkeccak_digest(&state->sponge, tmp, hashsize, bits, suffix, hashsum) < 0) - goto fail; - goto stage_3; - } - - if (libkeccak_hmac_update(state, tmp, hashsize) < 0) - goto fail; - leftover[0] = state->leftover; - if (bits) { - leftover[0] |= tmp[hashsize] >> (state->key_length & 7); - leftover[1] = ((unsigned char)(tmp[hashsize])) << (8 - (state->key_length & 7)); - } - newlen = (state->key_length & 7) + bits; - if (libkeccak_digest(&state->sponge, leftover, newlen >> 3, newlen & 7, suffix, tmp) < 0) - goto fail; - -stage_3: - my_explicit_bzero(tmp, ((state->sponge.n + 7) >> 3) * sizeof(char)); - free(tmp); - return 0; - fail: - my_explicit_bzero(tmp, ((state->sponge.n + 7) >> 3) * sizeof(char)); - free(tmp); - return -1; -} - diff --git a/src/libkeccak/mac/hmac.h b/src/libkeccak/mac/hmac.h deleted file mode 100644 index 2681e61..0000000 --- a/src/libkeccak/mac/hmac.h +++ /dev/null @@ -1,393 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_MAC_HMAC_H -#define LIBKECCAK_MAC_HMAC_H 1 - -/* - * The Keccak hash-function, that was selected by NIST as the SHA-3 competition winner, - * doesn't need this nested approach and can be used to generate a MAC by simply prepending - * the key to the message. [http://keccak.noekeon.org] - */ - -#include "../spec.h" -#include "../state.h" -#include "../internal.h" - -#include -#include -#include -#include -#include - - - -/** - * Datastructure that describes the state of an HMAC-hashing process - */ -typedef struct libkeccak_hmac_state -{ - /** - * The key right-padded and XOR:ed with the outer pad - */ - char *restrict key_opad; - - /** - * The key right-padded and XOR:ed with the inner pad - */ - char *restrict key_ipad; - /* Not marshalled, implicitly unmarshalled using `key_opad`. */ - /* Shares allocation with `key_opad`, do not `free`. */ - - /** - * The length of key, but at least the input block size, in bits - */ - size_t key_length; - - /** - * The state of the underlaying hash-algorithm - */ - libkeccak_state_t sponge; - - /** - * Buffer used to temporarily store bit shift message if - * `.key_length` is not zero modulus 8 - */ - char *restrict buffer; - - /** - * The allocation size of `.buffer` - */ - size_t buffer_size; - - /** - * Part of feed key, message or digest that have not been passed yet - */ - char leftover; - - char __pad[sizeof(void*) / sizeof(char) - 1]; - -} libkeccak_hmac_state_t; - - - -/** - * Change the HMAC-hashing key on the state - * - * @param state The state that should be reset - * @param key The new key - * @param key_length The length of key, in bits - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1), unused))) -int libkeccak_hmac_set_key(libkeccak_hmac_state_t *restrict state, const char *restrict key, size_t key_length); - - -/** - * Initialise an HMAC hashing-state according to hashing specifications - * - * @param state The state that should be initialised - * @param spec The specifications for the state - * @param key The key - * @param key_length The length of key, in bits - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) -static inline int -libkeccak_hmac_initialise(libkeccak_hmac_state_t *restrict state, const libkeccak_spec_t *restrict spec, - const char *restrict key, size_t key_length) -{ - if (libkeccak_state_initialise(&state->sponge, spec) < 0) - return -1; - if (libkeccak_hmac_set_key(state, key, key_length) < 0) - return libkeccak_state_destroy(&state->sponge), -1; - state->leftover = 0; - state->buffer = NULL; - state->buffer_size = 0; - return 0; -} - - -/** - * Wrapper for `libkeccak_hmac_initialise` that also allocates the states - * - * @param spec The specifications for the state - * @param key The key - * @param key_length The length of key, in bits - * @return The state, `NULL` on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) -static inline libkeccak_hmac_state_t * -libkeccak_hmac_create(const libkeccak_spec_t *restrict spec, - const char *restrict key, size_t key_length) -{ - libkeccak_hmac_state_t *restrict state = malloc(sizeof(libkeccak_hmac_state_t)); - if (!state || libkeccak_hmac_initialise(state, spec, key, key_length)) - return free(state), NULL; - return state; -} - - -/** - * Reset an HMAC-hashing state according to hashing specifications, - * you can choose whether to change the key - * - * @param state The state that should be reset - * @param key The new key, `NULL` to keep the old key - * @param key_length The length of key, in bits, ignored if `key == NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1), unused))) -static inline int -libkeccak_hmac_reset(libkeccak_hmac_state_t *restrict state, const char *restrict key, size_t key_length) -{ - libkeccak_state_reset(&state->sponge); - return key ? libkeccak_hmac_set_key(state, key, key_length) : 0; -} - - -/** - * Wipe sensitive data wihout freeing any data - * - * @param state The state that should be wipe - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, optimize("-O0")))) -void libkeccak_hmac_wipe(volatile libkeccak_hmac_state_t *restrict state); - - -/** - * Release resources allocation for an HMAC hashing-state without wiping sensitive data - * - * @param state The state that should be destroyed - */ -static inline void -libkeccak_hmac_fast_destroy(libkeccak_hmac_state_t *restrict state) -{ - if (!state) - return; - free(state->key_opad); - state->key_opad = NULL; - state->key_ipad = NULL; - state->key_length = 0; - free(state->buffer); - state->buffer = NULL; - state->buffer_size = 0; -} - - -/** - * Release resources allocation for an HMAC hasing-state and wipe sensitive data - * - * @param state The state that should be destroyed - */ -LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) -static inline void -libkeccak_hmac_destroy(volatile libkeccak_hmac_state_t *restrict state) -{ - if (!state) - return; - libkeccak_hmac_wipe(state); - free(state->key_opad); - state->key_opad = NULL; - state->key_ipad = NULL; - state->key_length = 0; - state->leftover = 0; - free(state->buffer); - state->buffer = NULL; - state->buffer_size = 0; -} - - -/** - * Wrapper for `libkeccak_fast_destroy` that also frees the allocation of the state - * - * @param state The state that should be freed - */ -LIBKECCAK_GCC_ONLY(__attribute__((unused))) -static inline void -libkeccak_hmac_fast_free(libkeccak_hmac_state_t *restrict state) -{ - libkeccak_hmac_fast_destroy(state); - free(state); -} - - -/** - * Wrapper for `libkeccak_hmac_destroy` that also frees the allocation of the state - * - * @param state The state that should be freed - */ -LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) -static inline void -libkeccak_hmac_free(volatile libkeccak_hmac_state_t *restrict state) -{ -#ifdef __GNUC__ -# pragma GCC diagnostic push -# pragma GCC diagnostic ignored "-Wcast-qual" -#endif - libkeccak_hmac_destroy(state); - free((libkeccak_hmac_state_t*)state); -#ifdef __GNUC__ -# pragma GCC diagnostic pop -#endif -} - - -/** - * Make a copy of an HMAC hashing-state - * - * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) - * @param src The state to duplicate - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) -int libkeccak_hmac_copy(libkeccak_hmac_state_t *restrict dest, const libkeccak_hmac_state_t *restrict src); - - -/** - * A wrapper for `libkeccak_hmac_copy` that also allocates the duplicate - * - * @param src The state to duplicate - * @return The duplicate, `NULL` on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) -static inline libkeccak_hmac_state_t * -libkeccak_hmac_duplicate(const libkeccak_hmac_state_t *restrict src) -{ - libkeccak_hmac_state_t* restrict dest = malloc(sizeof(libkeccak_hmac_state_t)); - if (!dest || libkeccak_hmac_copy(dest, src)) - return libkeccak_hmac_free(dest), NULL; - return dest; -} - - -/** - * Calculates the allocation size required for the second argument - * of `libkeccak_hmac_marshal` (`char* restrict data)`) - * - * @param state The state as it will be marshalled by a subsequent call to `libkeccak_hamc_marshal` - * @return The allocation size needed for the buffer to which the state will be marshalled - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused, warn_unused_result, pure))) -static inline size_t -libkeccak_hmac_marshal_size(const libkeccak_hmac_state_t *restrict state) -{ - return libkeccak_state_marshal_size(&state->sponge) + sizeof(size_t) + - ((state->key_length + 7) >> 3) + 2 * sizeof(char); -} - - -/** - * Marshal a `libkeccak_hmac_state_t` into a buffer - * - * @param state The state to marshal - * @param data The output buffer - * @return The number of bytes stored to `data` - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) -static inline size_t -libkeccak_hmac_marshal(const libkeccak_hmac_state_t *restrict state, char *restrict data) -{ - size_t written = libkeccak_state_marshal(&state->sponge, data); - data += written / sizeof(char); - *(size_t *)data = state->key_length; - data += sizeof(size_t) / sizeof(char); - memcpy(data, state->key_opad, (state->key_length + 7) >> 3); - data += ((state->key_length + 7) >> 3) / sizeof(char); - data[0] = (char)!!state->key_ipad; - data[1] = state->leftover; - return written + sizeof(size_t) + ((state->key_length + 7) >> 3) + 2 * sizeof(char); -} - - -/** - * Unmarshal a `libkeccak_hmac_state_t` from a buffer - * - * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) - * @param data The input buffer - * @return The number of bytes read from `data`, 0 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull))) -size_t libkeccak_hmac_unmarshal(libkeccak_hmac_state_t *restrict state, const char *restrict data); - - -/** - * Gets the number of bytes the `libkeccak_hmac_state_t` stored - * at the beginning of `data` occupies - * - * @param data The data buffer - * @return The byte size of the stored state - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, warn_unused_result, pure))) -static inline size_t -libkeccak_hmac_unmarshal_skip(const char *restrict data) -{ - size_t skip = libkeccak_state_unmarshal_skip(data); - data += skip / sizeof(char); - return skip + sizeof(size_t) + *(const size_t *)data + 2 * sizeof(char); -} - - -/** - * Absorb more, or the first part, of the message - * without wiping sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message, in bytes - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) -int libkeccak_hmac_fast_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen); - - -/** - * Absorb more, or the first part, of the message - * and wipe sensitive data when possible - * - * @param state The hashing state - * @param msg The partial message - * @param msglen The length of the partial message, in bytes - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) -int libkeccak_hmac_update(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen); - - -/** - * Absorb the last part of the message and fetch the hash - * without wiping sensitive data when possible - * - * You may use `&state->sponge` for continued squeezing - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL`, may be modified - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) -int libkeccak_hmac_fast_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum); - - -/** - * Absorb the last part of the message and fetch the hash - * and wipe sensitive data when possible - * - * You may use `&state->sponge` for continued squeezing - * - * @param state The hashing state - * @param msg The rest of the message, may be `NULL`, may be modified - * @param msglen The length of the partial message - * @param bits The number of bits at the end of the message not covered by `msglen` - * @param suffix The suffix concatenate to the message, only '1':s and '0':s, and NUL-termination - * @param hashsum Output parameter for the hashsum, may be `NULL` - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull(1)))) -int libkeccak_hmac_digest(libkeccak_hmac_state_t *restrict state, const char *restrict msg, size_t msglen, - size_t bits, const char *restrict suffix, char *restrict hashsum); - - -#endif diff --git a/src/libkeccak/spec.h b/src/libkeccak/spec.h deleted file mode 100644 index 8d73c52..0000000 --- a/src/libkeccak/spec.h +++ /dev/null @@ -1,177 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_SPEC_H -#define LIBKECCAK_SPEC_H 1 - -#include "internal.h" - -#include -#include - - -/** - * Message suffix for SHA3 hashing - */ -#define LIBKECCAK_SHA3_SUFFIX "01" - -/** - * Message suffix for RawSHAKE hashing - */ -#define LIBKECCAK_RAWSHAKE_SUFFIX "11" - -/** - * Message suffix for SHAKE hashing - */ -#define LIBKECCAK_SHAKE_SUFFIX "1111" - - -/** - * Invalid `libkeccak_spec_t.bitrate`: non-positive - */ -#define LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE 1 - -/** - * Invalid `libkeccak_spec_t.bitrate`: not a multiple of 8 - */ -#define LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8 2 - -/** - * Invalid `libkeccak_spec_t.capacity`: non-positive - */ -#define LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE 3 - -/** - * Invalid `libkeccak_spec_t.capacity`: not a multiple of 8 - */ -#define LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8 4 - -/** - * Invalid `libkeccak_spec_t.output`: non-positive - */ -#define LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE 5 - -/** - * Invalid `libkeccak_spec_t` values: `.bitrate + `.capacity` - * is greater 1600 which is the largest supported state size - */ -#define LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE 6 - -/** - * Invalid `libkeccak_spec_t` values: - * `.bitrate + `.capacity` is not a multiple of 25 - */ -#define LIBKECCAK_SPEC_ERROR_STATE_MOD_25 7 - -/** - * Invalid `libkeccak_spec_t` values: `.bitrate + `.capacity` - * is a not a 2-potent multiple of 25 - */ -#define LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT 8 - -/** - * Invalid `libkeccak_spec_t` values: `.bitrate + `.capacity` - * is a not multiple of 100, and thus the word size is not - * a multiple of 8 - */ -#define LIBKECCAK_SPEC_ERROR_WORD_MOD_8 9 - - - -/** - * Datastructure that describes the parameters - * that should be used when hashing - */ -typedef struct libkeccak_spec { - /** - * The bitrate - */ - long bitrate; - - /** - * The capacity - */ - long capacity; - - /** - * The output size - */ - long output; - -} libkeccak_spec_t; - - - -/** - * Fill in a `libkeccak_spec_t` for a SHA3-x hashing - * - * @param spec The specifications datastructure to fill in - * @param x The value of x in `SHA3-x`, the output size - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) -static inline void -libkeccak_spec_sha3(libkeccak_spec_t *restrict spec, long x) -{ - spec->bitrate = 1600 - 2 * x; - spec->capacity = 2 * x; - spec->output = x; -} - - -/** - * Fill in a `libkeccak_spec_t` for a RawSHAKEx hashing - * - * @param spec The specifications datastructure to fill in - * @param x The value of x in `RawSHAKEx`, half the capacity - * @param d The output size - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow))) -static inline void -libkeccak_spec_rawshake(libkeccak_spec_t *restrict spec, long x, long d) -{ - spec->bitrate = 1600 - 2 * x; - spec->capacity = 2 * x; - spec->output = d; -} - - -/** - * Fill in a `libkeccak_spec_t` for a SHAKEx hashing - * - * @param spec:libkeccak_spec_t* The specifications datastructure to fill in - * @param x:long The value of x in `SHAKEx`, half the capacity - * @param d:long The output size - */ -#define libkeccak_spec_shake libkeccak_spec_rawshake - - -/** - * Check for errors in a `libkeccak_spec_t` - * - * @param spec The specifications datastructure to check - * @return Zero if error free, a `LIBKECCAK_SPEC_ERROR_*` if an error was found - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused, warn_unused_result, pure))) -static inline int -libkeccak_spec_check(const libkeccak_spec_t *restrict spec) -{ - long state_size = spec->capacity + spec->bitrate; - int32_t word_size = (int32_t)(state_size / 25); - if (spec->bitrate <= 0) return LIBKECCAK_SPEC_ERROR_BITRATE_NONPOSITIVE; - if (spec->bitrate % 8) return LIBKECCAK_SPEC_ERROR_BITRATE_MOD_8; - if (spec->capacity <= 0) return LIBKECCAK_SPEC_ERROR_CAPACITY_NONPOSITIVE; - if (spec->capacity % 8) return LIBKECCAK_SPEC_ERROR_CAPACITY_MOD_8; - if (spec->output <= 0) return LIBKECCAK_SPEC_ERROR_OUTPUT_NONPOSITIVE; - if (state_size > 1600) return LIBKECCAK_SPEC_ERROR_STATE_TOO_LARGE; - if (state_size % 25) return LIBKECCAK_SPEC_ERROR_STATE_MOD_25; - if (word_size % 8) return LIBKECCAK_SPEC_ERROR_WORD_MOD_8; - - /* `(x & -x) != x` assumes two's complement, which of course is always - * satisfied by GCC, however C99 guarantees that `int32_t` exists, - * and it is basically the same thing as `long int`; with one important - * difference: it is guaranteed to use two's complement. */ - if ((word_size & -word_size) != word_size) - return LIBKECCAK_SPEC_ERROR_WORD_NON_2_POTENT; - - return 0; -} - -#endif diff --git a/src/libkeccak/state.c b/src/libkeccak/state.c deleted file mode 100644 index c6360b7..0000000 --- a/src/libkeccak/state.c +++ /dev/null @@ -1,175 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include "state.h" - -#include - - - -/** - * Initialise a state according to hashing specifications - * - * @param state The state that should be initialised - * @param spec The specifications for the state - * @return Zero on success, -1 on error - */ -int -libkeccak_state_initialise(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec) -{ - long x; - state->r = spec->bitrate; - state->n = spec->output; - state->c = spec->capacity; - state->b = state->r + state->c; - state->w = x = state->b / 25; - state->l = 0; - if (x & 0xF0L) state->l |= 4, x >>= 4; - if (x & 0x0CL) state->l |= 2, x >>= 2; - if (x & 0x02L) state->l |= 1; - state->nr = 12 + (state->l << 1); - state->wmod = (state->w == 64) ? ~0LL : (int64_t)((1ULL << state->w) - 1); - for (x = 0; x < 25; x++) - state->S[x] = 0; - state->mptr = 0; - state->mlen = (size_t)(state->r * state->b) >> 2; - state->M = malloc(state->mlen * sizeof(char)); - return state->M == NULL ? -1 : 0; -} - - -/** - * Wipe data in the state's message wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_state_wipe_message(volatile libkeccak_state_t *restrict state) -{ - volatile char *restrict M = state->M; - size_t i; - for (i = 0; i < state->mptr; i++) - M[i] = 0; -} - -/** - * Wipe data in the state's sponge wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_state_wipe_sponge(volatile libkeccak_state_t *restrict state) -{ - volatile int64_t *restrict S = state->S; - size_t i; - for (i = 0; i < 25; i++) - S[i] = 0; -} - -/** - * Wipe sensitive data wihout freeing any data - * - * @param state The state that should be wipe - */ -void -libkeccak_state_wipe(volatile libkeccak_state_t *restrict state) -{ - libkeccak_state_wipe_message(state); - libkeccak_state_wipe_sponge(state); -} - - -/** - * Make a copy of a state - * - * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) - * @param src The state to duplicate - * @return Zero on success, -1 on error - */ -int -libkeccak_state_copy(libkeccak_state_t *restrict dest, const libkeccak_state_t *restrict src) -{ - memcpy(dest, src, sizeof(libkeccak_state_t)); - dest->M = malloc(src->mlen * sizeof(char)); - if (!dest->M) - return -1; - memcpy(dest->M, src->M, src->mptr * sizeof(char)); - return 0; -} - - -/** - * Marshal a `libkeccak_state_t` into a buffer - * - * @param state The state to marshal - * @param data The output buffer - * @return The number of bytes stored to `data` - */ -size_t -libkeccak_state_marshal(const libkeccak_state_t *restrict state, char *restrict data) -{ -#define set(type, var) *((type *)data) = state->var, data += sizeof(type) / sizeof(char) - set(long, r); - set(long, c); - set(long, n); - set(long, b); - set(long, w); - set(int64_t, wmod); - set(long, l); - set(long, nr); - memcpy(data, state->S, sizeof(state->S)); - data += sizeof(state->S) / sizeof(char); - set(size_t, mptr); - set(size_t, mlen); - memcpy(data, state->M, state->mptr * sizeof(char)); - data += state->mptr; - return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); -#undef set -} - - -/** - * Unmarshal a `libkeccak_state_t` from a buffer - * - * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) - * @param data The input buffer - * @return The number of bytes read from `data`, 0 on error - */ -size_t -libkeccak_state_unmarshal(libkeccak_state_t *restrict state, const char *restrict data) -{ -#define get(type, var) state->var = *((const type *)data), data += sizeof(type) / sizeof(char) - get(long, r); - get(long, c); - get(long, n); - get(long, b); - get(long, w); - get(int64_t, wmod); - get(long, l); - get(long, nr); - memcpy(state->S, data, sizeof(state->S)); - data += sizeof(state->S) / sizeof(char); - get(size_t, mptr); - get(size_t, mlen); - state->M = malloc(state->mptr * sizeof(char)); - if (!state->M) - return 0; - memcpy(state->M, data, state->mptr * sizeof(char)); - data += state->mptr; - return sizeof(libkeccak_state_t) - sizeof(char *) + state->mptr * sizeof(char); -#undef get -} - - -/** - * Gets the number of bytes the `libkeccak_state_t` stored - * at the beginning of `data` occupies - * - * @param data The data buffer - * @return The byte size of the stored state - */ -size_t -libkeccak_state_unmarshal_skip(const char *restrict data) -{ - data += (7 * sizeof(long) + 26 * sizeof(int64_t)) / sizeof(char); - return sizeof(libkeccak_state_t) - sizeof(char *) + *(const size_t *)data * sizeof(char); -} - diff --git a/src/libkeccak/state.h b/src/libkeccak/state.h deleted file mode 100644 index 1c4b24e..0000000 --- a/src/libkeccak/state.h +++ /dev/null @@ -1,295 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#ifndef LIBKECCAK_STATE_H -#define LIBKECCAK_STATE_H 1 - -#include "spec.h" -#include "internal.h" - -#include -#include -#include -#include -#include - - - -/** - * Datastructure that describes the state of a hashing process - * - * The `char`-size of the output hashsum is calculated by `(.n + 7) / 8` - */ -typedef struct libkeccak_state { - /** - * The lanes (state/sponge) - */ - int64_t S[25]; - - /** - * The bitrate - */ - long r; - - /** - * The capacity - */ - long c; - - /** - * The output size - */ - long n; - - /** - * The state size - */ - long b; - - /** - * The word size - */ - long w; - - /** - * The word mask - */ - int64_t wmod; - - /** - * ℓ, the binary logarithm of the word size - */ - long l; - - /** - * 12 + 2ℓ, the number of rounds - */ - long nr; - - /** - * Pointer for `M` - */ - size_t mptr; - - /** - * Size of `M` - */ - size_t mlen; - - /** - * Left over water to fill the sponge with at next update - */ - char *M; - -} libkeccak_state_t; - - - -/** - * Initialise a state according to hashing specifications - * - * @param state The state that should be initialised - * @param spec The specifications for the state - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull))) -int libkeccak_state_initialise(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec); - - -/** - * Reset a state according to hashing specifications - * - * @param state The state that should be reset - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused))) -static inline void -libkeccak_state_reset(libkeccak_state_t *restrict state) -{ - state->mptr = 0; - memset(state->S, 0, sizeof(state->S)); -} - - -/** - * Release resources allocation for a state without wiping sensitive data - * - * @param state The state that should be destroyed - */ -static inline void -libkeccak_state_fast_destroy(libkeccak_state_t *restrict state) -{ - if (state == NULL) - return; - free(state->M); - state->M = NULL; -} - - -/** - * Wipe data in the state's message wihout freeing any data - * - * @param state The state that should be wipe - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow, optimize("-O0")))) -void libkeccak_state_wipe_message(volatile libkeccak_state_t *restrict state); - -/** - * Wipe data in the state's sponge wihout freeing any data - * - * @param state The state that should be wipe - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow, optimize("-O0")))) -void libkeccak_state_wipe_sponge(volatile libkeccak_state_t *restrict state); - -/** - * Wipe sensitive data wihout freeing any data - * - * @param state The state that should be wipe - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, optimize("-O0")))) -void libkeccak_state_wipe(volatile libkeccak_state_t *restrict state); - - -/** - * Release resources allocation for a state and wipe sensitive data - * - * @param state The state that should be destroyed - */ -LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) -static inline void -libkeccak_state_destroy(volatile libkeccak_state_t *restrict state) -{ - if (!state) - return; - libkeccak_state_wipe(state); - free(state->M); - state->M = NULL; -} - - -/** - * Wrapper for `libkeccak_state_initialise` that also allocates the states - * - * @param spec The specifications for the state - * @return The state, `NULL` on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) -static inline libkeccak_state_t * -libkeccak_state_create(const libkeccak_spec_t *restrict spec) -{ - libkeccak_state_t *restrict state = malloc(sizeof(libkeccak_state_t)); - if (!state || libkeccak_state_initialise(state, spec)) - return free(state), NULL; - return state; -} - - -/** - * Wrapper for `libkeccak_state_fast_destroy` that also frees the allocation of the state - * - * @param state The state that should be freed - */ -LIBKECCAK_GCC_ONLY(__attribute__((unused))) -static inline void -libkeccak_state_fast_free(libkeccak_state_t *restrict state) -{ - libkeccak_state_fast_destroy(state); - free(state); -} - - -/** - * Wrapper for `libkeccak_state_destroy` that also frees the allocation of the state - * - * @param state The state that should be freed - */ -LIBKECCAK_GCC_ONLY(__attribute__((unused, optimize("-O0")))) -static inline void -libkeccak_state_free(volatile libkeccak_state_t *restrict state) -{ -#ifdef __GNUC__ -# pragma GCC diagnostic push -# pragma GCC diagnostic ignored "-Wcast-qual" -#endif - libkeccak_state_destroy(state); - free((libkeccak_state_t *)state); -#ifdef __GNUC__ -# pragma GCC diagnostic pop -#endif -} - - -/** - * Make a copy of a state - * - * @param dest The slot for the duplicate, must not be initialised (memory leak otherwise) - * @param src The state to duplicate - * @return Zero on success, -1 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull))) -int libkeccak_state_copy(libkeccak_state_t *restrict dest, const libkeccak_state_t *restrict src); - - -/** - * A wrapper for `libkeccak_state_copy` that also allocates the duplicate - * - * @param src The state to duplicate - * @return The duplicate, `NULL` on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, unused, warn_unused_result, malloc))) -static inline libkeccak_state_t * -libkeccak_state_duplicate(const libkeccak_state_t *restrict src) -{ - libkeccak_state_t *restrict dest = malloc(sizeof(libkeccak_state_t)); - if (!dest || libkeccak_state_copy(dest, src)) - return libkeccak_state_free(dest), NULL; - return dest; -} - - -/** - * Calculates the allocation size required for the second argument - * of `libkeccak_state_marshal` (`char* restrict data)`) - * - * @param state The state as it will be marshalled by a subsequent call to `libkeccak_state_marshal` - * @return The allocation size needed for the buffer to which the state will be marshalled - */ -LIBKECCAK_GCC_ONLY(__attribute__((nonnull, nothrow, unused, warn_unused_result, pure))) -static inline size_t -libkeccak_state_marshal_size(const libkeccak_state_t *restrict state) -{ - return sizeof(libkeccak_state_t) - sizeof(char*) + state->mptr * sizeof(char); -} - - -/** - * Marshal a `libkeccak_state_t` into a buffer - * - * @param state The state to marshal - * @param data The output buffer - * @return The number of bytes stored to `data` - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow))) -size_t libkeccak_state_marshal(const libkeccak_state_t *restrict state, char *restrict data); - - -/** - * Unmarshal a `libkeccak_state_t` from a buffer - * - * @param state The slot for the unmarshalled state, must not be initialised (memory leak otherwise) - * @param data The input buffer - * @return The number of bytes read from `data`, 0 on error - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull))) -size_t libkeccak_state_unmarshal(libkeccak_state_t *restrict state, const char *restrict data); - - -/** - * Gets the number of bytes the `libkeccak_state_t` stored - * at the beginning of `data` occupies - * - * @param data The data buffer - * @return The byte size of the stored state - */ -LIBKECCAK_GCC_ONLY(__attribute__((leaf, nonnull, nothrow, warn_unused_result, pure))) -size_t libkeccak_state_unmarshal_skip(const char *restrict data); - -#endif diff --git a/src/test.c b/src/test.c deleted file mode 100644 index 8394568..0000000 --- a/src/test.c +++ /dev/null @@ -1,662 +0,0 @@ -/* See LICENSE file for copyright and license details. */ -#include - -#include -#include -#include -#include - - -/** - * Test functions in - * - * @return Zero on success, -1 on error - */ -static int -test_hex(void) -{ - const unsigned char bindata[] = {0x04, 0x2F, 0x12, 0x83, 0xFF, 0x80, 0xA3, 0x00}; - const char hexdata_upper[] = "042F1283FF80A300"; - const char hexdata_lower[] = "042f1283ff80a300"; - char hextest[2 * 8 + 1]; - - printf("Testing libkeccak_behex_lower: "); - libkeccak_behex_lower(hextest, (const char*)bindata, 8); - if (!strcmp(hextest, hexdata_lower)) - printf("OK\n"); - else - return printf("Fail\n"), -1; - - printf("Testing libkeccak_behex_upper: "); - libkeccak_behex_upper(hextest, (const char*)bindata, 8); - if (!strcmp(hextest, hexdata_upper)) - printf("OK\n"); - else - return printf("Fail\n"), -1; - - printf("Testing libkeccak_unhex on uppercase: "); - libkeccak_unhex(hextest, hexdata_upper); - if (!memcmp(bindata, hextest, 8 * sizeof(char))) - printf("OK\n"); - else - return printf("Fail\n"), -1; - - printf("Testing libkeccak_unhex on lowercase: "); - libkeccak_unhex(hextest, hexdata_lower); - if (!memcmp(bindata, hextest, 8 * sizeof(char))) - printf("OK\n"); - else - return printf("Fail\n"), -1; - - printf("\n"); - return 0; -} - - -/** - * Test functions in - * - * @param spec The specifications for the state - * @return Zero on success, -1 on error - */ -static int -test_state(libkeccak_spec_t *restrict spec) -{ - libkeccak_state_t *restrict state; - libkeccak_state_t *restrict state2; - size_t marshal_size, marshalled_size, i, n; - char *restrict marshalled_data; - - if (state = libkeccak_state_create(spec), state == NULL) - return perror("libkeccak_state_initialise"), -1; - - n = state->mlen / 2; - for (i = 0; i < n; i++) - state->M[state->mptr++] = (char)(i & 255); - - if (state2 = libkeccak_state_duplicate(state), state2 == NULL) - return perror("libkeccak_state_duplicate"), -1; - - if (state->M[state->mptr - 1] != state2->M[state2->mptr - 1]) - return printf("Inconsistency found between original state and duplicate state.\n"), -1; - - marshal_size = libkeccak_state_marshal_size(state2); - if (marshalled_data = malloc(marshal_size), marshalled_data == NULL) - return perror("malloc"), -1; - - marshalled_size = libkeccak_state_marshal(state2, marshalled_data); - if (marshalled_size != marshal_size) - return printf("libkeccak_state_marshal returned an unexpected value.\n"), -1; - - libkeccak_state_free(state); - - if (state = malloc(sizeof(libkeccak_state_t)), state == NULL) - return perror("malloc"), -1; - marshalled_size = libkeccak_state_unmarshal(state, marshalled_data); - if (marshalled_size == 0) - return perror("libkeccak_state_unmarshal"), -1; - if (marshalled_size != marshal_size) - return printf("libkeccak_state_unmarshal returned an unexpected value.\n"), -1; - - if (libkeccak_state_unmarshal_skip(marshalled_data) != marshal_size) - return printf("libkeccak_state_unmarshal_skip returned an unexpected value.\n"), -1; - - if (state->M[state->mptr - 1] != state2->M[state2->mptr - 1]) - return printf("Inconsistency found between original state and unmarshalled state.\n"), -1; - - free(marshalled_data); - libkeccak_state_free(state); - libkeccak_state_free(state2); - return 0; -} - - -/** - * Run a test case for `libkeccak_digest` - * - * @param spec The specification for the hashing - * @param suffix The message suffix (padding prefix) - * @param msg The message to digest - * @param bits Bits at the end of `message` that does not make up a whole byte - * @param expected_answer The expected answer, must be lowercase - * @return Zero on success, -1 on error - */ -static int -test_digest_case(const libkeccak_spec_t *restrict spec, const char *restrict suffix, - const char *restrict msg, long bits, const char *restrict expected_answer) -{ - libkeccak_state_t state; - char *restrict hashsum; - char *restrict hexsum; - int ok; - - if (libkeccak_state_initialise(&state, spec)) - return perror("libkeccak_state_initialise"), -1; - if (hashsum = malloc((spec->output + 7) / 8), hashsum == NULL) - return perror("malloc"), -1; - if (hexsum = malloc((spec->output + 7) / 8 * 2 + 1), hexsum == NULL) - return perror("malloc"), -1; - - if (libkeccak_digest(&state, msg, strlen(msg) - !!bits, bits, suffix, hashsum)) - return perror("libkeccak_digest"), -1; - libkeccak_state_fast_destroy(&state); - - libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); - ok = !strcmp(hexsum, expected_answer); - printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); - if (!ok) - printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); - - free(hashsum); - free(hexsum); - - return ok - 1; -} - - -/** - * Run test cases for `libkeccak_digest` - * - * @return Zero on success, -1 on error - */ -static int test_digest(void) -{ -#define sha3(output, message)\ - (printf(" Testing SHA3-"#output"(%s): ", #message),\ - libkeccak_spec_sha3(&spec, output),\ - test_digest_case(&spec, LIBKECCAK_SHA3_SUFFIX, message, 0, answer)) - -#define keccak(output, message)\ - (printf(" Testing Keccak-"#output"(%s): ", #message),\ - libkeccak_spec_sha3(&spec, output) /* sic! */,\ - test_digest_case(&spec, "", message, 0, answer)) - -#define keccak_bits(output, message, bits)\ - (printf(" Testing Keccak-"#output"(%s-%i): ", #message, bits),\ - libkeccak_spec_sha3(&spec, output) /* sic! */,\ - test_digest_case(&spec, "", message, bits, answer)) - -#define rawshake(semicapacity, output, message)\ - (printf(" Testing RawSHAKE-"#semicapacity"(%s, %i): ", #message, output),\ - libkeccak_spec_rawshake(&spec, semicapacity, output),\ - test_digest_case(&spec, LIBKECCAK_RAWSHAKE_SUFFIX, message, 0, answer)) - -#define rawshake_bits(semicapacity, output, message, bits)\ - (printf(" Testing RawSHAKE-"#semicapacity"(%s-%i, %i): ", #message, bits, output),\ - libkeccak_spec_rawshake(&spec, semicapacity, output),\ - test_digest_case(&spec, LIBKECCAK_RAWSHAKE_SUFFIX, message, bits, answer)) - -#define shake(semicapacity, output, message)\ - (printf(" Testing SHAKE-"#semicapacity"(%s, %i): ", #message, output),\ - libkeccak_spec_shake(&spec, semicapacity, output),\ - test_digest_case(&spec, LIBKECCAK_SHAKE_SUFFIX, message, 0, answer)) - -#define keccak_g(b, c, o, message)\ - (printf(" Testing Keccak[%i,%i,%i](%s): ", b, c, o, #message),\ - spec.bitrate = b, spec.capacity = c, spec.output = o,\ - test_digest_case(&spec, "", message, 0, answer)) - - - libkeccak_spec_t spec; - const char *answer; - - printf("Testing libkeccak_digest:\n"); - - - answer = "6b4e03423667dbb73b6e15454f0eb1abd4597f9a1b078e3f5b5a6bc7"; - if (sha3(224, "")) return -1; - - answer = "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"; - if (sha3(256, "")) return -1; - - answer = "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004"; - if (sha3(384, "")) return -1; - - answer = "a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a6" - "15b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26"; - if (sha3(512, "")) return -1; - - - answer = "f71837502ba8e10837bdd8d365adb85591895602fc552b48b7390abd"; - if (keccak(224, "")) return -1; - - answer = "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"; - if (keccak(256, "")) return -1; - - answer = "2c23146a63a29acf99e73b88f8c24eaa7dc60aa771780ccc006afbfa8fe2479b2dd2b21362337441ac12b515911957ff"; - if (keccak(384, "")) return -1; - - answer = "0eab42de4c3ceb9235fc91acffe746b29c29a8c366b7c60e4e67c466f36a4304" - "c00fa9caf9d87976ba469bcbe06713b435f091ef2769fb160cdab33d3670680e"; - if (keccak(512, "")) return -1; - - - answer = "22c8017ac8bcf65f59d1b7e92c9d4c6739d25e34ce5cb608b24ff096"; - if (sha3(224, "withdrew hypothesis snakebird qmc2")) return -1; - - answer = "43808dde2662143dc4eed5dac5e98c74b06711829f02a3b121bd74f3"; - if (sha3(224, "intensifierat sturdiness perl-image-exiftool vingla")) return -1; - - answer = "d32b4ac86065774dee5eb5cdd2f67b4e86501086d7373884e8b20a36"; - if (sha3(224, "timjan avogadro uppdriven lib32-llvm-amdgpu-snapshot")) return -1; - - answer = "efbd76d45bfa952485148f8ad46143897f17c27ffdc8eb7287f9353b"; - if (sha3(224, "grilo-plugins auditorium tull dissimilarity's")) return -1; - - answer = "6705aa36ecf58f333e0e6364ac1d0b7931d402e13282127cfd6f876c"; - if (sha3(224, "royalty tt yellowstone deficiencies")) return -1; - - answer = "803a0ff09dda0df306e483a9f91b20a3dbbf9c2ebb8d0a3b28f3b9e0"; - if (sha3(224, "kdegames-kdiamond tunisisk occurrence's outtalad")) return -1; - - answer = "a64779aca943a6aef1d2e7c9a0f4e997f4dabd1f77112a22121d3ed5"; - if (sha3(224, "chevalier slat's spindel representations")) return -1; - - answer = "f0a3e0587af7723f0aa4719059d3f5107115a5b3667cd5209cc4d867"; - if (sha3(224, "archery lexicographical equine veered")) return -1; - - answer = "312e7e3c6403ab1a086155fb9a52b22a3d0d257876afd2b93fb7272e"; - if (sha3(224, "splay washbasin opposing there")) return -1; - - answer = "270ba05b764221ff5b5d94adfb4fdb1f36f07fe7c438904a5f3df071"; - if (sha3(224, "faktum desist thundered klen")) return -1; - - - answer = "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"; - if (keccak_bits(256, "\x02", 2)) return -1; - - answer = "3a1108d4a90a31b85a10bdce77f4bfbdcc5b1d70dd405686f8bbde834aa1a410"; - if (keccak_bits(256, "\x03", 2)) return -1; - - answer = "46b9dd2b0ba88d13233b3feb743eeb243fcd52ea62b81b82b50c27646ed5762f"; - if (keccak_bits(256, "\x0F", 4)) return -1; - - - answer = "3a1108d4a90a31b85a10bdce77f4bfbd"; - if (rawshake(256, 128, "")) return -1; - - answer = "46b9dd2b0ba88d13233b3feb743eeb24"; - if (rawshake_bits(256, 128, "\x03", 2)) return -1; - - answer = "46b9dd2b0ba88d13233b3feb743eeb24"; - if (shake(256, 128, "")) return -1; - - - answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" - "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6"; - if (keccak_g(1024, 1600 - 1024, 576, "capitol's kvistfri broadly raping")) return -1; - - answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" - "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" - "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" - "bb7bea635bcea6331315728fb57866370bf1ad5d"; - if (keccak_g(1024, 1600 - 1024, 1024, "capitol's kvistfri broadly raping")) return -1; - - answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" - "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" - "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" - "bb7bea635bcea6331315728fb57866370bf1ad5decbc56d28d47ce53f18376d9f5531551" - "7a976d52dd3f98b7025e0b3c513c6d17d40462cddb5406d693bbe859a136af5375b5dd6e" - "3478934b00aa6cd44aa7ae2cd0271d83fbab699b"; - if (keccak_g(1024, 1600 - 1024, 1600, "capitol's kvistfri broadly raping")) return -1; - - answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" - "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" - "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" - "bb7bea635bcea6331315728fb57866370bf1ad5decbc56d28d47ce53f18376d9f5531551" - "7a976d52dd3f98b7025e0b3c513c6d17d40462cddb5406d693bbe859a136af5375b5dd6e" - "3478934b00aa6cd44aa7ae2cd0271d83fbab699b9c"; - if (keccak_g(1024, 1600 - 1024, 1608, "capitol's kvistfri broadly raping")) return -1; - - answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" - "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" - "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" - "bb7bea635bcea6331315728fb57866370bf1ad5decbc56d28d47ce53f18376d9f5531551" - "7a976d52dd3f98b7025e0b3c513c6d17d40462cddb5406d693bbe859a136af5375b5dd6e" - "3478934b00aa6cd44aa7ae2cd0271d83fbab699b9c58351bf7d26586b9c32282f1ac6356" - "1981b79791d7ab2b6e01f5b8e6cf0cab8b2076fd82bd99df015a602cdda5684162fea982" - "0f5a441c4620f549fbaf4e818201f292dbf4f6c9f82af8aa80b4124984da6f65b2874e0e" - "f01d042c08e9aedbb6ce4c10526e38c1a4e8b108c4f14b066f9d42640687b55124b081da" - "a9f9ae4232f313740b4fb787545dc19e7778f7082b3fa5824d2400c012be1a6c5ade7149" - "e452d310752fa9ebb964ab36fde0c8f46f47a0e2c9b20f24e3cca904bbedaa7ea176f662" - "33cd2d95"; - if (keccak_g(1024, 1600 - 1024, 3200, "capitol's kvistfri broadly raping")) return -1; - - answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de9225351"; - if (keccak_g(1024, 1600 - 1024, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "e6f86ebc15b962f73f36f36fc8a84c3ae84b1c1023bfd4c5f1829389135aecc3"; - if (keccak_g(512, 1600 - 512, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "420b97fc88962c87ec2adaa8f48d74d9ff4ea7ae7d691f9c33b8713ca1d3d573"; - if (keccak_g(256, 1600 - 256, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "524790afbe4706d938b6f753e14104f556890e2a415e211b0564d60499db0333"; - if (keccak_g(512, 800 - 512, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "04a6b4ad08b3018eefba0fb756272d949ac0f71c26f836d31dd13b28b884aa0f"; - if (keccak_g(256, 800 - 256, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "d56f547791225e54460e6274ed31e57b7085820c11d65f1f322a16a3352c85ed"; - if (keccak_g(256, 400 - 256, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "ceec066a57b9b31a5a0661df7bafec4183a26d0ed81e50bc958471f84fa347a7"; - if (keccak_g(128, 400 - 128, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "b18f679c7105a72a993f70fa5adb3f17ef7ccffaffb4dc0f6fed74aa2f565194"; - if (keccak_g(128, 200 - 128, 256, "capitol's kvistfri broadly raping")) return -1; - - answer = "9b845c1ecc2b1b3a48ba42ef29ccc4b348da8ab15074a870d8e799ca33c15e4b"; - if (keccak_g(64, 200 - 64, 256, "capitol's kvistfri broadly raping")) return -1; - - - printf("\n"); - return 0; - -#undef keccak_g -#undef shake -#undef rawshake_bits -#undef rawshake -#undef keccak_bits -#undef keccak -#undef sha3 -} - - -/** - * Run a test case for `libkeccak_update` - * - * @param spec The specification for the hashing - * @param suffix The message suffix (padding prefix) - * @param msg The message to digest - * @param expected_answer The expected answer, must be lowercase - * @return Zero on success, -1 on error - */ -static int -test_update_case(const libkeccak_spec_t *restrict spec, const char *restrict suffix, - const char *restrict msg, const char *restrict expected_answer) -{ - libkeccak_state_t state; - char *restrict hashsum; - char *restrict hexsum; - int ok; - - if (libkeccak_state_initialise(&state, spec)) - return perror("libkeccak_state_initialise"), -1; - if (hashsum = malloc((spec->output + 7) / 8), hashsum == NULL) - return perror("malloc"), -1; - if (hexsum = malloc((spec->output + 7) / 8 * 2 + 1), hexsum == NULL) - return perror("malloc"), -1; - - if (libkeccak_update(&state, msg, strlen(msg))) - return perror("libkeccak_update"), -1; - if (libkeccak_digest(&state, NULL, 0, 0, suffix, hashsum)) - return perror("libkeccak_digest"), -1; - libkeccak_state_fast_destroy(&state); - - libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); - ok = !strcmp(hexsum, expected_answer); - printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); - if (!ok) - printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); - - free(hashsum); - free(hexsum); - - return ok - 1; -} - - -/** - * Run test cases for `libkeccak_update` - * - * @return Zero on success, -1 on error - */ -static int test_update(void) -{ -#define sha3(output, message)\ - (printf(" Testing SHA3-"#output"(%s): ", #message),\ - libkeccak_spec_sha3(&spec, output),\ - test_update_case(&spec, LIBKECCAK_SHA3_SUFFIX, message, answer)) - - libkeccak_spec_t spec; - const char* answer; - - printf("Testing libkeccak_update:\n"); - - - answer = "22c8017ac8bcf65f59d1b7e92c9d4c6739d25e34ce5cb608b24ff096"; - if (sha3(224, "withdrew hypothesis snakebird qmc2")) return -1; - - answer = "43808dde2662143dc4eed5dac5e98c74b06711829f02a3b121bd74f3"; - if (sha3(224, "intensifierat sturdiness perl-image-exiftool vingla")) return -1; - - answer = "d32b4ac86065774dee5eb5cdd2f67b4e86501086d7373884e8b20a36"; - if (sha3(224, "timjan avogadro uppdriven lib32-llvm-amdgpu-snapshot")) return -1; - - answer = "efbd76d45bfa952485148f8ad46143897f17c27ffdc8eb7287f9353b"; - if (sha3(224, "grilo-plugins auditorium tull dissimilarity's")) return -1; - - answer = "6705aa36ecf58f333e0e6364ac1d0b7931d402e13282127cfd6f876c"; - if (sha3(224, "royalty tt yellowstone deficiencies")) return -1; - - answer = "803a0ff09dda0df306e483a9f91b20a3dbbf9c2ebb8d0a3b28f3b9e0"; - if (sha3(224, "kdegames-kdiamond tunisisk occurrence's outtalad")) return -1; - - answer = "a64779aca943a6aef1d2e7c9a0f4e997f4dabd1f77112a22121d3ed5"; - if (sha3(224, "chevalier slat's spindel representations")) return -1; - - answer = "f0a3e0587af7723f0aa4719059d3f5107115a5b3667cd5209cc4d867"; - if (sha3(224, "archery lexicographical equine veered")) return -1; - - answer = "312e7e3c6403ab1a086155fb9a52b22a3d0d257876afd2b93fb7272e"; - if (sha3(224, "splay washbasin opposing there")) return -1; - - answer = "270ba05b764221ff5b5d94adfb4fdb1f36f07fe7c438904a5f3df071"; - if (sha3(224, "faktum desist thundered klen")) return -1; - - - printf("\n"); - return 0; - -#undef sha3 -} - - -/** - * Run a test for `libkeccak_*squeeze` functions - * - * @param state The state whould should use, we will reset it - * @param spec The specification for the hashing - * @param fast_squeezes The number of fast squeezes to perform - * @param squeezes The number of extra squeezes to perform in total - * @param fast_digest Whether `libkeccak_digest` should do a fast squeeze rather than a slow squeeze - * @param hashsum A buffer in which we can used to store the binary hashsum - * @param hexsum A buffer in which we can used to store the hexadecimal hashsum - * @param expected_answer The hashum we expect, must be in lowercase hexadecimal - * @return Zero on success, -1 on error - */ -static int test_squeeze_case(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec, - long fast_squeezes, long squeezes, int fast_digest, char* restrict hashsum, - char *restrict hexsum, const char *restrict expected_answer) -{ -#define message "withdrew hypothesis snakebird qmc2" - long i; - int ok; - - libkeccak_state_reset(state); - if (libkeccak_digest(state, message, strlen(message), 0, LIBKECCAK_SHA3_SUFFIX, fast_digest ? NULL : hashsum)) - return perror("libkeccak_digest"), -1; - - libkeccak_fast_squeeze(state, fast_squeezes); - for (i = fast_squeezes; i < squeezes; i++) - libkeccak_squeeze(state, hashsum); - - libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); - ok = !strcmp(hexsum, expected_answer); - printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); - if (!ok) - printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); - - return ok - 1; -#undef message -} - - -/** - * Test `libkeccak_*squeeze` functions - * - * @return Zero on success, -1 on error - */ -static int -test_squeeze(void) -{ -#define answer1 "03fe12b4b51d56d96377d927e5cd498fc4bc3aee389b2f2ff8393aa5" -#define answer2 "0b8fb64ee5d8836956f49cbe4577afbc638c855c1d553452fc1eceb8" -#define answer3 "1e03b4cd9eef3892a7b5e865fce393c4bc90120d9aea84d0a0dff3b8" -#define answer4 "aac92fbfd22ce62e83ddaf2e61bd7bf696326e46d1327defa4530e20" - -#define run_test(fast_squeezes, squeezes, fast_digest)\ - test_squeeze_case(&state, &spec, fast_squeezes, squeezes, fast_digest, hashsum, hexsum, answer##squeezes) - - libkeccak_spec_t spec; - libkeccak_state_t state; - char *restrict hashsum; - char *restrict hexsum; - - libkeccak_spec_sha3(&spec, 224); - if (hashsum = malloc((spec.output + 7) / 8), hashsum == NULL) - return perror("malloc"), -1; - if (hexsum = malloc((spec.output + 7) / 8 * 2 + 1), hexsum == NULL) - return perror("malloc"), -1; - if (libkeccak_state_initialise(&state, &spec)) - return perror("libkeccak_state_initialise"), -1; - - printf("Testing squeeze functions with slow initial digest:\n"); - printf(" 1 extra squeeze, including 0 fast squeezes: "), run_test(0, 1, 0); - printf(" 2 extra squeezes, including 0 fast squeezes: "), run_test(0, 2, 0); - printf(" 2 extra squeezes, including 1 fast squeeze: "), run_test(1, 2, 0); - printf(" 3 extra squeezes, including 0 fast squeezes: "), run_test(0, 3, 0); - printf(" 3 extra squeezes, including 1 fast squeeze: "), run_test(1, 3, 0); - printf(" 3 extra squeezes, including 2 fast squeezes: "), run_test(2, 3, 0); - printf(" 4 extra squeezes, including 0 fast squeezes: "), run_test(0, 4, 0); - printf(" 4 extra squeezes, including 1 fast squeeze: "), run_test(1, 4, 0); - printf(" 4 extra squeezes, including 2 fast squeezes: "), run_test(2, 4, 0); - printf(" 4 extra squeezes, including 3 fast squeezes: "), run_test(3, 4, 0); - printf("\n"); - - printf("Testing squeeze functions with fast initial digest:\n"); - printf(" 1 extra squeeze, including 0 fast squeezes: "), run_test(0, 1, 1); - printf(" 2 extra squeezes, including 0 fast squeezes: "), run_test(0, 2, 1); - printf(" 2 extra squeezes, including 1 fast squeeze: "), run_test(1, 2, 1); - printf(" 3 extra squeezes, including 0 fast squeezes: "), run_test(0, 3, 1); - printf(" 3 extra squeezes, including 1 fast squeeze: "), run_test(1, 3, 1); - printf(" 3 extra squeezes, including 2 fast squeezes: "), run_test(2, 3, 1); - printf(" 4 extra squeezes, including 0 fast squeezes: "), run_test(0, 4, 1); - printf(" 4 extra squeezes, including 1 fast squeeze: "), run_test(1, 4, 1); - printf(" 4 extra squeezes, including 2 fast squeezes: "), run_test(2, 4, 1); - printf(" 4 extra squeezes, including 3 fast squeezes: "), run_test(3, 4, 1); - printf("\n"); - - libkeccak_state_fast_destroy(&state); - free(hashsum); - free(hexsum); - return 0; - -#undef run_test -#undef answer4 -#undef answer3 -#undef answer2 -#undef answer1 -} - - - -/** - * Run a test for `libkeccak_generalised_sum_fd` - * - * @param spec The specification for the hashing - * @param suffix The message suffix (padding prefix) - * @param filename The name of the file we should hash - * @param expected_answer The hashum we expect, must be in lowercase hexadecimal - * @return Zero on success, -1 on error - */ -static int -test_file(const libkeccak_spec_t *restrict spec, const char *restrict suffix, - const char *restrict filename, const char *restrict expected_answer) -{ - libkeccak_state_t state; - char *restrict hashsum; - char *restrict hexsum; - int ok, fd; - - printf("Testing libkeccak_generalised_sum_fd on %s: ", filename); - - if (hashsum = malloc((spec->output + 7) / 8), hashsum == NULL) - return perror("malloc"), -1; - if (hexsum = malloc((spec->output + 7) / 8 * 2 + 1), hexsum == NULL) - return perror("malloc"), -1; - - if (fd = open(filename, O_RDONLY), fd < 0) - return perror("open"), -1; - - if (libkeccak_generalised_sum_fd(fd, &state, spec, suffix, hashsum)) - return perror("libkeccak_generalised_sum_fd"), close(fd), -1; - - libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); - ok = !strcmp(hexsum, expected_answer); - printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); - if (!ok) - printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); - - close(fd); - free(hashsum); - free(hexsum); - libkeccak_state_fast_destroy(&state); - return ok - 1; -} - - -/** - * Basically, verify the correctness of the library. - * The current working path must be the root directory - * of the repository (the project directory). - * - * @return Zero on success, 1 on failure or incorrectness - */ -int -main(void) -{ - libkeccak_generalised_spec_t gspec; - libkeccak_spec_t spec; - - libkeccak_generalised_spec_initialise(&gspec); - if (libkeccak_degeneralise_spec(&gspec, &spec)) - return printf("libkeccak_degeneralise_spec failed with all members at automatic.\n"), 1; - - printf("Resolution of default specification:\n"); - printf(" bitrate: %li\n", gspec.bitrate); - printf(" capacity: %li\n", gspec.capacity); - printf(" output: %li\n", gspec.output); - printf(" state size: %li\n", gspec.state_size); - printf(" word size: %li\n", gspec.word_size); - if (gspec.word_size * 25 != gspec.state_size) return printf("Invalid information\n"), 1; - if (gspec.bitrate + gspec.capacity != gspec.state_size) return printf("Invalid information\n"), 1; - if (gspec.state_size != 1600) return printf("Incorrect information\n"), 1; - if (gspec.bitrate != gspec.output * 2) return printf("Incorrect information\n"), 1; - if (gspec.output != 512) return printf("Incorrect information\n"), 1; - printf("\n"); - - if (test_hex()) return 1; - if (test_state(&spec)) return 1; - if (test_digest()) return 1; - if (test_update()) return 1; - if (test_squeeze()) return 1; - - if (test_file(&spec, LIBKECCAK_SHA3_SUFFIX, ".testfile", - "a95484492e9ade0f1d28f872d197ff45d891e85e78f918643f41d524c5d6ab0f" - "17974dc08ec82870b132612dcbeb062213bf594881dc764d6078865a7c694c57")) - return 1; - - return 0; -} diff --git a/test.c b/test.c new file mode 100644 index 0000000..8394568 --- /dev/null +++ b/test.c @@ -0,0 +1,662 @@ +/* See LICENSE file for copyright and license details. */ +#include + +#include +#include +#include +#include + + +/** + * Test functions in + * + * @return Zero on success, -1 on error + */ +static int +test_hex(void) +{ + const unsigned char bindata[] = {0x04, 0x2F, 0x12, 0x83, 0xFF, 0x80, 0xA3, 0x00}; + const char hexdata_upper[] = "042F1283FF80A300"; + const char hexdata_lower[] = "042f1283ff80a300"; + char hextest[2 * 8 + 1]; + + printf("Testing libkeccak_behex_lower: "); + libkeccak_behex_lower(hextest, (const char*)bindata, 8); + if (!strcmp(hextest, hexdata_lower)) + printf("OK\n"); + else + return printf("Fail\n"), -1; + + printf("Testing libkeccak_behex_upper: "); + libkeccak_behex_upper(hextest, (const char*)bindata, 8); + if (!strcmp(hextest, hexdata_upper)) + printf("OK\n"); + else + return printf("Fail\n"), -1; + + printf("Testing libkeccak_unhex on uppercase: "); + libkeccak_unhex(hextest, hexdata_upper); + if (!memcmp(bindata, hextest, 8 * sizeof(char))) + printf("OK\n"); + else + return printf("Fail\n"), -1; + + printf("Testing libkeccak_unhex on lowercase: "); + libkeccak_unhex(hextest, hexdata_lower); + if (!memcmp(bindata, hextest, 8 * sizeof(char))) + printf("OK\n"); + else + return printf("Fail\n"), -1; + + printf("\n"); + return 0; +} + + +/** + * Test functions in + * + * @param spec The specifications for the state + * @return Zero on success, -1 on error + */ +static int +test_state(libkeccak_spec_t *restrict spec) +{ + libkeccak_state_t *restrict state; + libkeccak_state_t *restrict state2; + size_t marshal_size, marshalled_size, i, n; + char *restrict marshalled_data; + + if (state = libkeccak_state_create(spec), state == NULL) + return perror("libkeccak_state_initialise"), -1; + + n = state->mlen / 2; + for (i = 0; i < n; i++) + state->M[state->mptr++] = (char)(i & 255); + + if (state2 = libkeccak_state_duplicate(state), state2 == NULL) + return perror("libkeccak_state_duplicate"), -1; + + if (state->M[state->mptr - 1] != state2->M[state2->mptr - 1]) + return printf("Inconsistency found between original state and duplicate state.\n"), -1; + + marshal_size = libkeccak_state_marshal_size(state2); + if (marshalled_data = malloc(marshal_size), marshalled_data == NULL) + return perror("malloc"), -1; + + marshalled_size = libkeccak_state_marshal(state2, marshalled_data); + if (marshalled_size != marshal_size) + return printf("libkeccak_state_marshal returned an unexpected value.\n"), -1; + + libkeccak_state_free(state); + + if (state = malloc(sizeof(libkeccak_state_t)), state == NULL) + return perror("malloc"), -1; + marshalled_size = libkeccak_state_unmarshal(state, marshalled_data); + if (marshalled_size == 0) + return perror("libkeccak_state_unmarshal"), -1; + if (marshalled_size != marshal_size) + return printf("libkeccak_state_unmarshal returned an unexpected value.\n"), -1; + + if (libkeccak_state_unmarshal_skip(marshalled_data) != marshal_size) + return printf("libkeccak_state_unmarshal_skip returned an unexpected value.\n"), -1; + + if (state->M[state->mptr - 1] != state2->M[state2->mptr - 1]) + return printf("Inconsistency found between original state and unmarshalled state.\n"), -1; + + free(marshalled_data); + libkeccak_state_free(state); + libkeccak_state_free(state2); + return 0; +} + + +/** + * Run a test case for `libkeccak_digest` + * + * @param spec The specification for the hashing + * @param suffix The message suffix (padding prefix) + * @param msg The message to digest + * @param bits Bits at the end of `message` that does not make up a whole byte + * @param expected_answer The expected answer, must be lowercase + * @return Zero on success, -1 on error + */ +static int +test_digest_case(const libkeccak_spec_t *restrict spec, const char *restrict suffix, + const char *restrict msg, long bits, const char *restrict expected_answer) +{ + libkeccak_state_t state; + char *restrict hashsum; + char *restrict hexsum; + int ok; + + if (libkeccak_state_initialise(&state, spec)) + return perror("libkeccak_state_initialise"), -1; + if (hashsum = malloc((spec->output + 7) / 8), hashsum == NULL) + return perror("malloc"), -1; + if (hexsum = malloc((spec->output + 7) / 8 * 2 + 1), hexsum == NULL) + return perror("malloc"), -1; + + if (libkeccak_digest(&state, msg, strlen(msg) - !!bits, bits, suffix, hashsum)) + return perror("libkeccak_digest"), -1; + libkeccak_state_fast_destroy(&state); + + libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); + ok = !strcmp(hexsum, expected_answer); + printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); + if (!ok) + printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); + + free(hashsum); + free(hexsum); + + return ok - 1; +} + + +/** + * Run test cases for `libkeccak_digest` + * + * @return Zero on success, -1 on error + */ +static int test_digest(void) +{ +#define sha3(output, message)\ + (printf(" Testing SHA3-"#output"(%s): ", #message),\ + libkeccak_spec_sha3(&spec, output),\ + test_digest_case(&spec, LIBKECCAK_SHA3_SUFFIX, message, 0, answer)) + +#define keccak(output, message)\ + (printf(" Testing Keccak-"#output"(%s): ", #message),\ + libkeccak_spec_sha3(&spec, output) /* sic! */,\ + test_digest_case(&spec, "", message, 0, answer)) + +#define keccak_bits(output, message, bits)\ + (printf(" Testing Keccak-"#output"(%s-%i): ", #message, bits),\ + libkeccak_spec_sha3(&spec, output) /* sic! */,\ + test_digest_case(&spec, "", message, bits, answer)) + +#define rawshake(semicapacity, output, message)\ + (printf(" Testing RawSHAKE-"#semicapacity"(%s, %i): ", #message, output),\ + libkeccak_spec_rawshake(&spec, semicapacity, output),\ + test_digest_case(&spec, LIBKECCAK_RAWSHAKE_SUFFIX, message, 0, answer)) + +#define rawshake_bits(semicapacity, output, message, bits)\ + (printf(" Testing RawSHAKE-"#semicapacity"(%s-%i, %i): ", #message, bits, output),\ + libkeccak_spec_rawshake(&spec, semicapacity, output),\ + test_digest_case(&spec, LIBKECCAK_RAWSHAKE_SUFFIX, message, bits, answer)) + +#define shake(semicapacity, output, message)\ + (printf(" Testing SHAKE-"#semicapacity"(%s, %i): ", #message, output),\ + libkeccak_spec_shake(&spec, semicapacity, output),\ + test_digest_case(&spec, LIBKECCAK_SHAKE_SUFFIX, message, 0, answer)) + +#define keccak_g(b, c, o, message)\ + (printf(" Testing Keccak[%i,%i,%i](%s): ", b, c, o, #message),\ + spec.bitrate = b, spec.capacity = c, spec.output = o,\ + test_digest_case(&spec, "", message, 0, answer)) + + + libkeccak_spec_t spec; + const char *answer; + + printf("Testing libkeccak_digest:\n"); + + + answer = "6b4e03423667dbb73b6e15454f0eb1abd4597f9a1b078e3f5b5a6bc7"; + if (sha3(224, "")) return -1; + + answer = "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"; + if (sha3(256, "")) return -1; + + answer = "0c63a75b845e4f7d01107d852e4c2485c51a50aaaa94fc61995e71bbee983a2ac3713831264adb47fb6bd1e058d5f004"; + if (sha3(384, "")) return -1; + + answer = "a69f73cca23a9ac5c8b567dc185a756e97c982164fe25859e0d1dcc1475c80a6" + "15b2123af1f5f94c11e3e9402c3ac558f500199d95b6d3e301758586281dcd26"; + if (sha3(512, "")) return -1; + + + answer = "f71837502ba8e10837bdd8d365adb85591895602fc552b48b7390abd"; + if (keccak(224, "")) return -1; + + answer = "c5d2460186f7233c927e7db2dcc703c0e500b653ca82273b7bfad8045d85a470"; + if (keccak(256, "")) return -1; + + answer = "2c23146a63a29acf99e73b88f8c24eaa7dc60aa771780ccc006afbfa8fe2479b2dd2b21362337441ac12b515911957ff"; + if (keccak(384, "")) return -1; + + answer = "0eab42de4c3ceb9235fc91acffe746b29c29a8c366b7c60e4e67c466f36a4304" + "c00fa9caf9d87976ba469bcbe06713b435f091ef2769fb160cdab33d3670680e"; + if (keccak(512, "")) return -1; + + + answer = "22c8017ac8bcf65f59d1b7e92c9d4c6739d25e34ce5cb608b24ff096"; + if (sha3(224, "withdrew hypothesis snakebird qmc2")) return -1; + + answer = "43808dde2662143dc4eed5dac5e98c74b06711829f02a3b121bd74f3"; + if (sha3(224, "intensifierat sturdiness perl-image-exiftool vingla")) return -1; + + answer = "d32b4ac86065774dee5eb5cdd2f67b4e86501086d7373884e8b20a36"; + if (sha3(224, "timjan avogadro uppdriven lib32-llvm-amdgpu-snapshot")) return -1; + + answer = "efbd76d45bfa952485148f8ad46143897f17c27ffdc8eb7287f9353b"; + if (sha3(224, "grilo-plugins auditorium tull dissimilarity's")) return -1; + + answer = "6705aa36ecf58f333e0e6364ac1d0b7931d402e13282127cfd6f876c"; + if (sha3(224, "royalty tt yellowstone deficiencies")) return -1; + + answer = "803a0ff09dda0df306e483a9f91b20a3dbbf9c2ebb8d0a3b28f3b9e0"; + if (sha3(224, "kdegames-kdiamond tunisisk occurrence's outtalad")) return -1; + + answer = "a64779aca943a6aef1d2e7c9a0f4e997f4dabd1f77112a22121d3ed5"; + if (sha3(224, "chevalier slat's spindel representations")) return -1; + + answer = "f0a3e0587af7723f0aa4719059d3f5107115a5b3667cd5209cc4d867"; + if (sha3(224, "archery lexicographical equine veered")) return -1; + + answer = "312e7e3c6403ab1a086155fb9a52b22a3d0d257876afd2b93fb7272e"; + if (sha3(224, "splay washbasin opposing there")) return -1; + + answer = "270ba05b764221ff5b5d94adfb4fdb1f36f07fe7c438904a5f3df071"; + if (sha3(224, "faktum desist thundered klen")) return -1; + + + answer = "a7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a"; + if (keccak_bits(256, "\x02", 2)) return -1; + + answer = "3a1108d4a90a31b85a10bdce77f4bfbdcc5b1d70dd405686f8bbde834aa1a410"; + if (keccak_bits(256, "\x03", 2)) return -1; + + answer = "46b9dd2b0ba88d13233b3feb743eeb243fcd52ea62b81b82b50c27646ed5762f"; + if (keccak_bits(256, "\x0F", 4)) return -1; + + + answer = "3a1108d4a90a31b85a10bdce77f4bfbd"; + if (rawshake(256, 128, "")) return -1; + + answer = "46b9dd2b0ba88d13233b3feb743eeb24"; + if (rawshake_bits(256, 128, "\x03", 2)) return -1; + + answer = "46b9dd2b0ba88d13233b3feb743eeb24"; + if (shake(256, 128, "")) return -1; + + + answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" + "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6"; + if (keccak_g(1024, 1600 - 1024, 576, "capitol's kvistfri broadly raping")) return -1; + + answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" + "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" + "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" + "bb7bea635bcea6331315728fb57866370bf1ad5d"; + if (keccak_g(1024, 1600 - 1024, 1024, "capitol's kvistfri broadly raping")) return -1; + + answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" + "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" + "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" + "bb7bea635bcea6331315728fb57866370bf1ad5decbc56d28d47ce53f18376d9f5531551" + "7a976d52dd3f98b7025e0b3c513c6d17d40462cddb5406d693bbe859a136af5375b5dd6e" + "3478934b00aa6cd44aa7ae2cd0271d83fbab699b"; + if (keccak_g(1024, 1600 - 1024, 1600, "capitol's kvistfri broadly raping")) return -1; + + answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" + "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" + "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" + "bb7bea635bcea6331315728fb57866370bf1ad5decbc56d28d47ce53f18376d9f5531551" + "7a976d52dd3f98b7025e0b3c513c6d17d40462cddb5406d693bbe859a136af5375b5dd6e" + "3478934b00aa6cd44aa7ae2cd0271d83fbab699b9c"; + if (keccak_g(1024, 1600 - 1024, 1608, "capitol's kvistfri broadly raping")) return -1; + + answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de92253515713cce8" + "d2098be1c82df40b40e375549c0eeb655f92d718f01f147ba1c7c67844c7ba8b11492cd6" + "143466958504c110522f772fe746573b1dc905f943ed1ec6ecf858575798596beeca4eb6" + "bb7bea635bcea6331315728fb57866370bf1ad5decbc56d28d47ce53f18376d9f5531551" + "7a976d52dd3f98b7025e0b3c513c6d17d40462cddb5406d693bbe859a136af5375b5dd6e" + "3478934b00aa6cd44aa7ae2cd0271d83fbab699b9c58351bf7d26586b9c32282f1ac6356" + "1981b79791d7ab2b6e01f5b8e6cf0cab8b2076fd82bd99df015a602cdda5684162fea982" + "0f5a441c4620f549fbaf4e818201f292dbf4f6c9f82af8aa80b4124984da6f65b2874e0e" + "f01d042c08e9aedbb6ce4c10526e38c1a4e8b108c4f14b066f9d42640687b55124b081da" + "a9f9ae4232f313740b4fb787545dc19e7778f7082b3fa5824d2400c012be1a6c5ade7149" + "e452d310752fa9ebb964ab36fde0c8f46f47a0e2c9b20f24e3cca904bbedaa7ea176f662" + "33cd2d95"; + if (keccak_g(1024, 1600 - 1024, 3200, "capitol's kvistfri broadly raping")) return -1; + + answer = "65070cdd6f91c0aadcfc470895a2606c828bce7ce3fa723418c9013de9225351"; + if (keccak_g(1024, 1600 - 1024, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "e6f86ebc15b962f73f36f36fc8a84c3ae84b1c1023bfd4c5f1829389135aecc3"; + if (keccak_g(512, 1600 - 512, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "420b97fc88962c87ec2adaa8f48d74d9ff4ea7ae7d691f9c33b8713ca1d3d573"; + if (keccak_g(256, 1600 - 256, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "524790afbe4706d938b6f753e14104f556890e2a415e211b0564d60499db0333"; + if (keccak_g(512, 800 - 512, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "04a6b4ad08b3018eefba0fb756272d949ac0f71c26f836d31dd13b28b884aa0f"; + if (keccak_g(256, 800 - 256, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "d56f547791225e54460e6274ed31e57b7085820c11d65f1f322a16a3352c85ed"; + if (keccak_g(256, 400 - 256, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "ceec066a57b9b31a5a0661df7bafec4183a26d0ed81e50bc958471f84fa347a7"; + if (keccak_g(128, 400 - 128, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "b18f679c7105a72a993f70fa5adb3f17ef7ccffaffb4dc0f6fed74aa2f565194"; + if (keccak_g(128, 200 - 128, 256, "capitol's kvistfri broadly raping")) return -1; + + answer = "9b845c1ecc2b1b3a48ba42ef29ccc4b348da8ab15074a870d8e799ca33c15e4b"; + if (keccak_g(64, 200 - 64, 256, "capitol's kvistfri broadly raping")) return -1; + + + printf("\n"); + return 0; + +#undef keccak_g +#undef shake +#undef rawshake_bits +#undef rawshake +#undef keccak_bits +#undef keccak +#undef sha3 +} + + +/** + * Run a test case for `libkeccak_update` + * + * @param spec The specification for the hashing + * @param suffix The message suffix (padding prefix) + * @param msg The message to digest + * @param expected_answer The expected answer, must be lowercase + * @return Zero on success, -1 on error + */ +static int +test_update_case(const libkeccak_spec_t *restrict spec, const char *restrict suffix, + const char *restrict msg, const char *restrict expected_answer) +{ + libkeccak_state_t state; + char *restrict hashsum; + char *restrict hexsum; + int ok; + + if (libkeccak_state_initialise(&state, spec)) + return perror("libkeccak_state_initialise"), -1; + if (hashsum = malloc((spec->output + 7) / 8), hashsum == NULL) + return perror("malloc"), -1; + if (hexsum = malloc((spec->output + 7) / 8 * 2 + 1), hexsum == NULL) + return perror("malloc"), -1; + + if (libkeccak_update(&state, msg, strlen(msg))) + return perror("libkeccak_update"), -1; + if (libkeccak_digest(&state, NULL, 0, 0, suffix, hashsum)) + return perror("libkeccak_digest"), -1; + libkeccak_state_fast_destroy(&state); + + libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); + ok = !strcmp(hexsum, expected_answer); + printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); + if (!ok) + printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); + + free(hashsum); + free(hexsum); + + return ok - 1; +} + + +/** + * Run test cases for `libkeccak_update` + * + * @return Zero on success, -1 on error + */ +static int test_update(void) +{ +#define sha3(output, message)\ + (printf(" Testing SHA3-"#output"(%s): ", #message),\ + libkeccak_spec_sha3(&spec, output),\ + test_update_case(&spec, LIBKECCAK_SHA3_SUFFIX, message, answer)) + + libkeccak_spec_t spec; + const char* answer; + + printf("Testing libkeccak_update:\n"); + + + answer = "22c8017ac8bcf65f59d1b7e92c9d4c6739d25e34ce5cb608b24ff096"; + if (sha3(224, "withdrew hypothesis snakebird qmc2")) return -1; + + answer = "43808dde2662143dc4eed5dac5e98c74b06711829f02a3b121bd74f3"; + if (sha3(224, "intensifierat sturdiness perl-image-exiftool vingla")) return -1; + + answer = "d32b4ac86065774dee5eb5cdd2f67b4e86501086d7373884e8b20a36"; + if (sha3(224, "timjan avogadro uppdriven lib32-llvm-amdgpu-snapshot")) return -1; + + answer = "efbd76d45bfa952485148f8ad46143897f17c27ffdc8eb7287f9353b"; + if (sha3(224, "grilo-plugins auditorium tull dissimilarity's")) return -1; + + answer = "6705aa36ecf58f333e0e6364ac1d0b7931d402e13282127cfd6f876c"; + if (sha3(224, "royalty tt yellowstone deficiencies")) return -1; + + answer = "803a0ff09dda0df306e483a9f91b20a3dbbf9c2ebb8d0a3b28f3b9e0"; + if (sha3(224, "kdegames-kdiamond tunisisk occurrence's outtalad")) return -1; + + answer = "a64779aca943a6aef1d2e7c9a0f4e997f4dabd1f77112a22121d3ed5"; + if (sha3(224, "chevalier slat's spindel representations")) return -1; + + answer = "f0a3e0587af7723f0aa4719059d3f5107115a5b3667cd5209cc4d867"; + if (sha3(224, "archery lexicographical equine veered")) return -1; + + answer = "312e7e3c6403ab1a086155fb9a52b22a3d0d257876afd2b93fb7272e"; + if (sha3(224, "splay washbasin opposing there")) return -1; + + answer = "270ba05b764221ff5b5d94adfb4fdb1f36f07fe7c438904a5f3df071"; + if (sha3(224, "faktum desist thundered klen")) return -1; + + + printf("\n"); + return 0; + +#undef sha3 +} + + +/** + * Run a test for `libkeccak_*squeeze` functions + * + * @param state The state whould should use, we will reset it + * @param spec The specification for the hashing + * @param fast_squeezes The number of fast squeezes to perform + * @param squeezes The number of extra squeezes to perform in total + * @param fast_digest Whether `libkeccak_digest` should do a fast squeeze rather than a slow squeeze + * @param hashsum A buffer in which we can used to store the binary hashsum + * @param hexsum A buffer in which we can used to store the hexadecimal hashsum + * @param expected_answer The hashum we expect, must be in lowercase hexadecimal + * @return Zero on success, -1 on error + */ +static int test_squeeze_case(libkeccak_state_t *restrict state, const libkeccak_spec_t *restrict spec, + long fast_squeezes, long squeezes, int fast_digest, char* restrict hashsum, + char *restrict hexsum, const char *restrict expected_answer) +{ +#define message "withdrew hypothesis snakebird qmc2" + long i; + int ok; + + libkeccak_state_reset(state); + if (libkeccak_digest(state, message, strlen(message), 0, LIBKECCAK_SHA3_SUFFIX, fast_digest ? NULL : hashsum)) + return perror("libkeccak_digest"), -1; + + libkeccak_fast_squeeze(state, fast_squeezes); + for (i = fast_squeezes; i < squeezes; i++) + libkeccak_squeeze(state, hashsum); + + libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); + ok = !strcmp(hexsum, expected_answer); + printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); + if (!ok) + printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); + + return ok - 1; +#undef message +} + + +/** + * Test `libkeccak_*squeeze` functions + * + * @return Zero on success, -1 on error + */ +static int +test_squeeze(void) +{ +#define answer1 "03fe12b4b51d56d96377d927e5cd498fc4bc3aee389b2f2ff8393aa5" +#define answer2 "0b8fb64ee5d8836956f49cbe4577afbc638c855c1d553452fc1eceb8" +#define answer3 "1e03b4cd9eef3892a7b5e865fce393c4bc90120d9aea84d0a0dff3b8" +#define answer4 "aac92fbfd22ce62e83ddaf2e61bd7bf696326e46d1327defa4530e20" + +#define run_test(fast_squeezes, squeezes, fast_digest)\ + test_squeeze_case(&state, &spec, fast_squeezes, squeezes, fast_digest, hashsum, hexsum, answer##squeezes) + + libkeccak_spec_t spec; + libkeccak_state_t state; + char *restrict hashsum; + char *restrict hexsum; + + libkeccak_spec_sha3(&spec, 224); + if (hashsum = malloc((spec.output + 7) / 8), hashsum == NULL) + return perror("malloc"), -1; + if (hexsum = malloc((spec.output + 7) / 8 * 2 + 1), hexsum == NULL) + return perror("malloc"), -1; + if (libkeccak_state_initialise(&state, &spec)) + return perror("libkeccak_state_initialise"), -1; + + printf("Testing squeeze functions with slow initial digest:\n"); + printf(" 1 extra squeeze, including 0 fast squeezes: "), run_test(0, 1, 0); + printf(" 2 extra squeezes, including 0 fast squeezes: "), run_test(0, 2, 0); + printf(" 2 extra squeezes, including 1 fast squeeze: "), run_test(1, 2, 0); + printf(" 3 extra squeezes, including 0 fast squeezes: "), run_test(0, 3, 0); + printf(" 3 extra squeezes, including 1 fast squeeze: "), run_test(1, 3, 0); + printf(" 3 extra squeezes, including 2 fast squeezes: "), run_test(2, 3, 0); + printf(" 4 extra squeezes, including 0 fast squeezes: "), run_test(0, 4, 0); + printf(" 4 extra squeezes, including 1 fast squeeze: "), run_test(1, 4, 0); + printf(" 4 extra squeezes, including 2 fast squeezes: "), run_test(2, 4, 0); + printf(" 4 extra squeezes, including 3 fast squeezes: "), run_test(3, 4, 0); + printf("\n"); + + printf("Testing squeeze functions with fast initial digest:\n"); + printf(" 1 extra squeeze, including 0 fast squeezes: "), run_test(0, 1, 1); + printf(" 2 extra squeezes, including 0 fast squeezes: "), run_test(0, 2, 1); + printf(" 2 extra squeezes, including 1 fast squeeze: "), run_test(1, 2, 1); + printf(" 3 extra squeezes, including 0 fast squeezes: "), run_test(0, 3, 1); + printf(" 3 extra squeezes, including 1 fast squeeze: "), run_test(1, 3, 1); + printf(" 3 extra squeezes, including 2 fast squeezes: "), run_test(2, 3, 1); + printf(" 4 extra squeezes, including 0 fast squeezes: "), run_test(0, 4, 1); + printf(" 4 extra squeezes, including 1 fast squeeze: "), run_test(1, 4, 1); + printf(" 4 extra squeezes, including 2 fast squeezes: "), run_test(2, 4, 1); + printf(" 4 extra squeezes, including 3 fast squeezes: "), run_test(3, 4, 1); + printf("\n"); + + libkeccak_state_fast_destroy(&state); + free(hashsum); + free(hexsum); + return 0; + +#undef run_test +#undef answer4 +#undef answer3 +#undef answer2 +#undef answer1 +} + + + +/** + * Run a test for `libkeccak_generalised_sum_fd` + * + * @param spec The specification for the hashing + * @param suffix The message suffix (padding prefix) + * @param filename The name of the file we should hash + * @param expected_answer The hashum we expect, must be in lowercase hexadecimal + * @return Zero on success, -1 on error + */ +static int +test_file(const libkeccak_spec_t *restrict spec, const char *restrict suffix, + const char *restrict filename, const char *restrict expected_answer) +{ + libkeccak_state_t state; + char *restrict hashsum; + char *restrict hexsum; + int ok, fd; + + printf("Testing libkeccak_generalised_sum_fd on %s: ", filename); + + if (hashsum = malloc((spec->output + 7) / 8), hashsum == NULL) + return perror("malloc"), -1; + if (hexsum = malloc((spec->output + 7) / 8 * 2 + 1), hexsum == NULL) + return perror("malloc"), -1; + + if (fd = open(filename, O_RDONLY), fd < 0) + return perror("open"), -1; + + if (libkeccak_generalised_sum_fd(fd, &state, spec, suffix, hashsum)) + return perror("libkeccak_generalised_sum_fd"), close(fd), -1; + + libkeccak_behex_lower(hexsum, hashsum, (spec->output + 7) / 8); + ok = !strcmp(hexsum, expected_answer); + printf("%s%s\n", ok ? "OK" : "Fail: ", ok ? "" : hexsum); + if (!ok) + printf(" r, c, n = %li, %li, %li\n", spec->bitrate, spec->capacity, spec->output); + + close(fd); + free(hashsum); + free(hexsum); + libkeccak_state_fast_destroy(&state); + return ok - 1; +} + + +/** + * Basically, verify the correctness of the library. + * The current working path must be the root directory + * of the repository (the project directory). + * + * @return Zero on success, 1 on failure or incorrectness + */ +int +main(void) +{ + libkeccak_generalised_spec_t gspec; + libkeccak_spec_t spec; + + libkeccak_generalised_spec_initialise(&gspec); + if (libkeccak_degeneralise_spec(&gspec, &spec)) + return printf("libkeccak_degeneralise_spec failed with all members at automatic.\n"), 1; + + printf("Resolution of default specification:\n"); + printf(" bitrate: %li\n", gspec.bitrate); + printf(" capacity: %li\n", gspec.capacity); + printf(" output: %li\n", gspec.output); + printf(" state size: %li\n", gspec.state_size); + printf(" word size: %li\n", gspec.word_size); + if (gspec.word_size * 25 != gspec.state_size) return printf("Invalid information\n"), 1; + if (gspec.bitrate + gspec.capacity != gspec.state_size) return printf("Invalid information\n"), 1; + if (gspec.state_size != 1600) return printf("Incorrect information\n"), 1; + if (gspec.bitrate != gspec.output * 2) return printf("Incorrect information\n"), 1; + if (gspec.output != 512) return printf("Incorrect information\n"), 1; + printf("\n"); + + if (test_hex()) return 1; + if (test_state(&spec)) return 1; + if (test_digest()) return 1; + if (test_update()) return 1; + if (test_squeeze()) return 1; + + if (test_file(&spec, LIBKECCAK_SHA3_SUFFIX, ".testfile", + "a95484492e9ade0f1d28f872d197ff45d891e85e78f918643f41d524c5d6ab0f" + "17974dc08ec82870b132612dcbeb062213bf594881dc764d6078865a7c694c57")) + return 1; + + return 0; +} -- cgit v1.2.3-70-g09d2