diff options
53 files changed, 9915 insertions, 233 deletions
@@ -21,8 +21,12 @@ LIB_NAME = hashsum OBJ =\ + $(OBJ_PUBLIC)\ + $(OBJ_HIDDEN) + +OBJ_PUBLIC =\ libhashsum_init_hasher.o\ - libhashsum_get_algorithm_string.o\ + libhashsum_get_algorithm_from_string.o\ libhashsum_init_hasher_from_string.o\ libhashsum_init_md2_hasher.o\ libhashsum_init_md4_hasher.o\ @@ -64,13 +68,19 @@ OBJ =\ libhashsum_init_blake384_hasher.o\ libhashsum_init_blake512_hasher.o\ libhashsum_init_blakeb_hasher.o\ - libhashsum_init_blake_hasher.o\ + libhashsum_init_blake_hasher.o + +OBJ_HIDDEN =\ libhashsum_reverse_byte__.o\ libhashsum_init_keccak__.o HDR =\ libhashsum.h\ - common.h + common.h\ + $(SUBHDR) + +SUBHDR =\ + libhashsum/internal.h TEST =\ md2.t\ @@ -104,6 +114,9 @@ TEST =\ LOBJ = $(OBJ:.o=.lo) TOBJ = $(TEST:.t=.o) +MAN3 = $(OBJ_PUBLIC:.o=.3) +MAN7 = libhashsum.7 + all: libhashsum.a libhashsum.$(LIBEXT) $(TEST) $(OBJ): $(HDR) @@ -140,13 +153,18 @@ check: $(TEST) install: libhashsum.a libhashsum.$(LIBEXT) mkdir -p -- "$(DESTDIR)$(PREFIX)/lib" - mkdir -p -- "$(DESTDIR)$(PREFIX)/include" + mkdir -p -- "$(DESTDIR)$(PREFIX)/include/libhashsum" + mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man3" + mkdir -p -- "$(DESTDIR)$(MANPREFIX)/man7" cp -- libhashsum.a "$(DESTDIR)$(PREFIX)/lib/" cp -- libhashsum.$(LIBEXT) "$(DESTDIR)$(PREFIX)/lib/libhashsum.$(LIBMINOREXT)" $(FIX_INSTALL_NAME) "$(DESTDIR)$(PREFIX)/lib/libhashsum.$(LIBMINOREXT)" ln -sf -- libhashsum.$(LIBMINOREXT) "$(DESTDIR)$(PREFIX)/lib/libhashsum.$(LIBMAJOREXT)" ln -sf -- libhashsum.$(LIBMAJOREXT) "$(DESTDIR)$(PREFIX)/lib/libhashsum.$(LIBEXT)" cp -- libhashsum.h "$(DESTDIR)$(PREFIX)/include/" + cp -- $(SUBHDR) "$(DESTDIR)$(PREFIX)/include/libhashsum/" + cp -- $(MAN3) "$(DESTDIR)$(MANPREFIX)/man3/" + cp -- $(MAN7) "$(DESTDIR)$(MANPREFIX)/man7/" uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libhashsum.a" @@ -154,6 +172,10 @@ uninstall: -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libhashsum.$(LIBMINOREXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/lib/libhashsum.$(LIBEXT)" -rm -f -- "$(DESTDIR)$(PREFIX)/include/libhashsum.h" + -cd -- "$(DESTDIR)$(PREFIX)/include/libhashsum/" && rm -f -- $(SUBHDR) + -rmdir -- "$(DESTDIR)$(PREFIX)/include/libhashsum" + -cd -- "$(DESTDIR)$(MANPREFIX)/man3/" && rm -f -- $(MAN3) + -cd -- "$(DESTDIR)$(MANPREFIX)/man7/" && rm -f -- $(MAN7) clean: -rm -f -- *.o *.a *.lo *.su *.so *.so.* *.dll *.dylib *.t @@ -1,9 +1,9 @@ NAME - libhashsum - Library for calculating the cryptographic hashes + libhashsum - library for calculating the cryptographic hashes DESCRIPTION - libhashsum provides a unified interface for several - cryptographic hash functions. Currently supported + The libhashsum library provides a unified interface for + several cryptographic hash functions. Currently supported hash functions are: Built in @@ -11,17 +11,17 @@ DESCRIPTION RIPEMD-320 Via libsha1 - SHA0, SHA1 + SHA-0, SHA-1 Via libsha2 SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256 Via libkeccak>=1.3 - Keccak[], Keccak-224, Keccak-256, Keccak-384, - Keccak-512, SHA3-224, SHA3-256, SHA3-384, SHA3-512, - SHAKE128, SHAKE256, SHAKE512, RawSHAKE128, - RawSHAKE256, RawSHAKE512 + Keccak, Keccak-224, Keccak-256, Keccak-384, + Keccak-512, SHA-3-224, SHA-3-256, SHA-3-384, + SHA-3-512, SHAKE128, SHAKE256, SHAKE512, + RawSHAKE128, RawSHAKE256, RawSHAKE512 Via libblake>=1.1 BLAKE224, BLAKE256, BLAKE384, BLAKE512 @@ -34,6 +34,7 @@ DESCRIPTION hash function. It also have a function that can parse a string describing any support function with its parameters. For hash function that do not require - any parameters, it has a function that can select - the appropriate initialiser based on an enum value - that specifies the algorithm. + any parameters, or only have optional parameters with + obvious default values, it has a function that can + select the appropriate initialiser based on an enum + value that specifies the algorithm. @@ -39,11 +39,14 @@ #if defined(__GNUC__) -__attribute__((__const__)) +__attribute__((__const__, __visibility__("hidden"))) #endif uint8_t libhashsum_reverse_byte__(uint8_t); #ifdef LIBHASHSUM_INCLUDE_LIBKECCAK_STATE +#if defined(__GNUC__) +__attribute__((__visibility__("hidden"))) +#endif int libhashsum_init_keccak__(struct libhashsum_hasher *this, size_t hashbits, void *spec, size_t squeezes, const char *suffix); #endif diff --git a/libhashsum.7 b/libhashsum.7 new file mode 100644 index 0000000..1945b99 --- /dev/null +++ b/libhashsum.7 @@ -0,0 +1,62 @@ +.TH LIBHASHSUM 7 libhashsum +.SH NAME +libhashsum - library for calculating the cryptographic hashes + +.SH SYNOPSIS +.nf +#include <libhashsum.h> +.fi +.PP +Link with +.I -lhashsum +.br +.I -lsha1 +(unless support for SHA-0 and SHA-1 was excluded) +.br +.I -lsha2 +(unless support for SHA-2 was excluded) +.br +.I -lkeccak +(unless support for Keccak, SHA-3, SHAKE, and RawSHAKE was excluded) +.br +.I -lblake +(unless support for BLAKE was excluded). + +.SH DESCRIPTION +The +.B libhashsum +library provides a unified interface for +several cryptographic hash functions. Currently supported +hash functions are: +.TP +Built in +MD2, MD4, MD5, RIPEMD-128, RIPEMD-160, RIPEMD-256, RIPEMD-320 +.TP +Via libsha1 +SHA-0, SHA-1 +.TP +Via libsha2 +SHA-224, SHA-256, SHA-384, SHA-512, SHA-512/224, SHA-512/256 +.TP +Via libkeccak>=1.3 +Keccak, Keccak-224, Keccak-256, Keccak-384, Keccak-512, +SHA-3-224, SHA-3-256, SHA-3-384, SHA-3-512, +SHAKE128, SHAKE256, SHAKE512, +RawSHAKE128, RawSHAKE256, RawSHAKE512 +.TP +Via libblake>=1.1 +BLAKE224, BLAKE256, BLAKE384, BLAKE512 +.PP +For each hash function, +.B libhashsum +has a dedicated initialiser that may take required +parameters for the hash function. It also have a +function that can parse a string describing any support +function with its parameters. For hash function that do +not require any parameters, or only have optional +parameters with obvious default values, it has a +function that can select the appropriate initialiser +based on an enum value that specifies the algorithm. +.SH SEE ALSO +.BR libhashsum_init_hasher (3), +.BR libhashsum_init_hasher_from_string (3) diff --git a/libhashsum.h b/libhashsum.h index 65c3a66..d1a9f64 100644 --- a/libhashsum.h +++ b/libhashsum.h @@ -3,20 +3,6 @@ #define LIBHASHSUM_H #include <stddef.h> -#include <stdint.h> - -#ifdef LIBHASHSUM_INCLUDE_LIBSHA1_STATE -# include <libsha1.h> -#endif -#ifdef LIBHASHSUM_INCLUDE_LIBSHA2_STATE -# include <libsha2.h> -#endif -#ifdef LIBHASHSUM_INCLUDE_LIBKECCAK_STATE -# include <libkeccak.h> -#endif -#ifdef LIBHASHSUM_INCLUDE_LIBBLAKE_STATE -# include <libblake.h> -#endif #if defined(__GNUC__) @@ -31,50 +17,6 @@ /** - * Hashing algorithm - * - * @since 1.0 - */ -enum libhashsum_algorithm { - /* since 1.0 */ - LIBHASHSUM_MD2, /**< MD2; this algorithm has been theoretically compromised */ - LIBHASHSUM_MD4, /**< MD4; this algorithm has been compromised */ - LIBHASHSUM_MD5, /**< MD5; this algorithm has been compromised */ - LIBHASHSUM_RIPEMD_128, /**< RIPEMD-128 */ - LIBHASHSUM_RIPEMD_160, /**< RIPEMD-160 */ - LIBHASHSUM_RIPEMD_256, /**< RIPEMD-256 */ - LIBHASHSUM_RIPEMD_320, /**< RIPEMD-320 */ - LIBHASHSUM_SHA0, /**< SHA0; this algorithm has been compromised */ - LIBHASHSUM_SHA1, /**< SHA1; this algorithm has been compromised */ - LIBHASHSUM_SHA_224, /**< SHA-224 (SHA2) */ - LIBHASHSUM_SHA_256, /**< SHA-256 (SHA2) */ - LIBHASHSUM_SHA_384, /**< SHA-384 (SHA2) */ - LIBHASHSUM_SHA_512, /**< SHA-512 (SHA2) */ - LIBHASHSUM_SHA_512_224, /**< SHA-512/224 (SHA2) */ - LIBHASHSUM_SHA_512_256, /**< SHA-512/256 (SHA2) */ - LIBHASHSUM_KECCAK, /**< Keccak[] */ - LIBHASHSUM_KECCAK_224, /**< Keccak-224 */ - LIBHASHSUM_KECCAK_256, /**< Keccak-256 */ - LIBHASHSUM_KECCAK_384, /**< Keccak-384 */ - LIBHASHSUM_KECCAK_512, /**< Keccak-512 */ - LIBHASHSUM_SHA3_224, /**< SHA3-224 */ - LIBHASHSUM_SHA3_256, /**< SHA3-256 */ - LIBHASHSUM_SHA3_384, /**< SHA3-384 */ - LIBHASHSUM_SHA3_512, /**< SHA3-512 */ - LIBHASHSUM_SHAKE128, /**< SHAKE128 */ - LIBHASHSUM_SHAKE256, /**< SHAKE256 */ - LIBHASHSUM_SHAKE512, /**< SHAKE512 */ - LIBHASHSUM_RAWSHAKE128, /**< RawSHAKE128 */ - LIBHASHSUM_RAWSHAKE256, /**< RawSHAKE256 */ - LIBHASHSUM_RAWSHAKE512, /**< RawSHAKE512 */ - LIBHASHSUM_BLAKE224, /**< BLAKE224 (BLAKE, BLAKEs) */ - LIBHASHSUM_BLAKE256, /**< BLAKE256 (BLAKE, BLAKEs) */ - LIBHASHSUM_BLAKE384, /**< BLAKE384 (BLAKE, BLAKEb) */ - LIBHASHSUM_BLAKE512 /**< BLAKE512 (BLAKE, BLAKEb) */ -}; - - -/** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_MD2` * * @since 1.0 @@ -240,7 +182,7 @@ enum libhashsum_algorithm { * * @since 1.0 */ -#define LIBHASHSUM_SHAKE_128_HASH_SIZE 28 +#define LIBHASHSUM_SHAKE_128_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHAKE_256` @@ -261,7 +203,7 @@ enum libhashsum_algorithm { * * @since 1.0 */ -#define LIBHASHSUM_RAWSHAKE_128_HASH_SIZE 28 +#define LIBHASHSUM_RAWSHAKE_128_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RAWSHAKE_256` @@ -312,152 +254,50 @@ enum libhashsum_algorithm { #endif -/** - * Hash state - * - * For internal use - */ -union libhashsum_state { - struct { - unsigned char x[32]; - unsigned char mp[16]; - unsigned char mz[16]; - unsigned char sum[16]; - unsigned t; - } md2; /* size = [82, 88] */ - - struct { - union { - uint32_t h32[4]; - uint8_t sum[16]; - } h; - union { - uint32_t m32[16]; - uint8_t m8[64]; - } m; - uint64_t count; - } md4; /* size = 70 */ - - struct { - union { - uint32_t h32[4]; - uint8_t sum[16]; - } h; - uint8_t m[64]; - uint32_t w[16]; - uint64_t count; - } md5; /* size = 152 */ - - struct { - union { - uint32_t h32[4]; - uint8_t sum[16]; - } h; - union { - uint32_t m32[16]; - uint8_t m8[64]; - } m; - uint64_t count; - } ripemd_128; /* size = 88 */ - - struct { - union { - uint32_t h32[5]; - uint8_t sum[20]; - } h; - union { - uint32_t m32[16]; - uint8_t m8[64]; - } m; - uint32_t w1[5]; - uint32_t w2[5]; - uint64_t count; - } ripemd_160; /* size = 132 */ - - struct { - union { - uint32_t h32[8]; - uint8_t sum[32]; - } h; - union { - uint32_t m32[16]; - uint8_t m8[64]; - } m; - uint64_t count; - } ripemd_256; /* size = 104 */ - - struct { - union { - uint32_t h32[10]; - uint8_t sum[40]; - } h; - union { - uint32_t m32[16]; - uint8_t m8[64]; - } m; - uint32_t w1[5]; - uint32_t w2[5]; - uint64_t count; - } ripemd_320; /* size = 152 */ - -#ifdef LIBHASHSUM_INCLUDE_LIBSHA1_STATE - struct { - struct libsha1_state s; - uint8_t sum[20]; - } sha0, sha1; /* size = [432, 440] */ -#endif - -#ifdef LIBHASHSUM_INCLUDE_LIBSHA2_STATE - struct { - struct libsha2_state s; - uint8_t sum[64]; - } sha2; /* size = [1612, 1624] */ -#endif - -#ifdef LIBHASHSUM_INCLUDE_LIBKECCAK_STATE - struct { - struct libkeccak_state s; - union { - uint8_t buf[512]; - uint8_t *dyn; - } sum; - const char *suffix; - size_t squeezes; - char algostr[256]; - } keccak; /* size = [1024, 1072] */ -#endif - -#ifdef LIBHASHSUM_INCLUDE_LIBBLAKE_STATE - struct { - struct libblake_blake224_state s; - uint8_t buf[128]; - char algostr[49]; - } blake224; /* size = 233 */ - - struct { - struct libblake_blake256_state s; - uint8_t buf[128]; - char algostr[49]; - } blake256; /* size = 233 */ - - struct { - struct libblake_blake384_state s; - uint8_t buf[256]; - char algostr[81]; - } blake384; /* size = 449 */ - - struct { - struct libblake_blake512_state s; - uint8_t buf[256]; - char algostr[81]; - } blake512; /* size = 449 */ -#endif +#include "libhashsum/internal.h" - /* libblake: 48(2s), 96(2b), 144(2Xs), 276(2Xb) */ - char max_size[1648]; -#define libhashsum_init_hasher libhashsum_init_hasher__1648 -#define libhashsum_init_hasher_from_string libhashsum_init_hasher_from_string__1648 +/** + * Hashing algorithm + * + * @since 1.0 + */ +enum libhashsum_algorithm { + /* since 1.0 */ + LIBHASHSUM_MD2, /**< MD2; this algorithm has been theoretically compromised */ + LIBHASHSUM_MD4, /**< MD4; this algorithm has been compromised */ + LIBHASHSUM_MD5, /**< MD5; this algorithm has been compromised */ + LIBHASHSUM_RIPEMD_128, /**< RIPEMD-128 */ + LIBHASHSUM_RIPEMD_160, /**< RIPEMD-160 */ + LIBHASHSUM_RIPEMD_256, /**< RIPEMD-256 */ + LIBHASHSUM_RIPEMD_320, /**< RIPEMD-320 */ + LIBHASHSUM_SHA0, /**< SHA0; this algorithm has been compromised */ + LIBHASHSUM_SHA1, /**< SHA1; this algorithm has been compromised */ + LIBHASHSUM_SHA_224, /**< SHA-224 (SHA2) */ + LIBHASHSUM_SHA_256, /**< SHA-256 (SHA2) */ + LIBHASHSUM_SHA_384, /**< SHA-384 (SHA2) */ + LIBHASHSUM_SHA_512, /**< SHA-512 (SHA2) */ + LIBHASHSUM_SHA_512_224, /**< SHA-512/224 (SHA2) */ + LIBHASHSUM_SHA_512_256, /**< SHA-512/256 (SHA2) */ + LIBHASHSUM_KECCAK, /**< Keccak[] */ + LIBHASHSUM_KECCAK_224, /**< Keccak-224 */ + LIBHASHSUM_KECCAK_256, /**< Keccak-256 */ + LIBHASHSUM_KECCAK_384, /**< Keccak-384 */ + LIBHASHSUM_KECCAK_512, /**< Keccak-512 */ + LIBHASHSUM_SHA3_224, /**< SHA3-224 */ + LIBHASHSUM_SHA3_256, /**< SHA3-256 */ + LIBHASHSUM_SHA3_384, /**< SHA3-384 */ + LIBHASHSUM_SHA3_512, /**< SHA3-512 */ + LIBHASHSUM_SHAKE128, /**< SHAKE128 */ + LIBHASHSUM_SHAKE256, /**< SHAKE256 */ + LIBHASHSUM_SHAKE512, /**< SHAKE512 */ + LIBHASHSUM_RAWSHAKE128, /**< RawSHAKE128 */ + LIBHASHSUM_RAWSHAKE256, /**< RawSHAKE256 */ + LIBHASHSUM_RAWSHAKE512, /**< RawSHAKE512 */ + LIBHASHSUM_BLAKE224, /**< BLAKE224 (BLAKE, BLAKEs) */ + LIBHASHSUM_BLAKE256, /**< BLAKE256 (BLAKE, BLAKEs) */ + LIBHASHSUM_BLAKE384, /**< BLAKE384 (BLAKE, BLAKEb) */ + LIBHASHSUM_BLAKE512 /**< BLAKE512 (BLAKE, BLAKEb) */ }; @@ -638,7 +478,7 @@ struct libhashsum_hasher { * @since 1.0 */ LIBHASHSUM_1_NONNULL_ -int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algorithm algorithm); +int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algorithm algorithm); /* TODO test */ /** * Inspect a hashing algorithm string to identify @@ -652,7 +492,7 @@ int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algor * @since 1.0 */ LIBHASHSUM_NONNULL_ -int libhashsum_get_algorithm_string(enum libhashsum_algorithm *algorithm_out, const char *algorithm); +int libhashsum_get_algorithm_from_string(enum libhashsum_algorithm *algorithm_out, const char *algorithm); /* TODO test */ /** * Create an initialised state for a hash algorithm @@ -662,7 +502,8 @@ int libhashsum_get_algorithm_string(enum libhashsum_algorithm *algorithm_out, co * @param algorithm The hashing algorithm and parameters * @return 0 on success, -1 on failure * - * @throws EINVAL `algorithm` is not recognised or contains an invalid value + * @throws EINVAL `algorithm` is not recognised or contains an invalid + * parameter or an invalid combination of parameters * @throws ENOSYS Support for `algorithm` was excluded at compile time * @throws ENOSYS The `algorithm` requires a newer version of the library * that application was compiled for (the application @@ -675,7 +516,7 @@ int libhashsum_get_algorithm_string(enum libhashsum_algorithm *algorithm_out, co * @since 1.0 */ LIBHASHSUM_NONNULL_ -int libhashsum_init_hasher_from_string(struct libhashsum_hasher *this, const char *algorithm); +int libhashsum_init_hasher_from_string(struct libhashsum_hasher *this, const char *algorithm); /* TODO test */ /** * Create an initialised state for MD2 @@ -775,6 +616,10 @@ int libhashsum_init_ripemd_256_hasher(struct libhashsum_hasher *this); LIBHASHSUM_1_NONNULL_ int libhashsum_init_ripemd_320_hasher(struct libhashsum_hasher *this); +/* there is no `libhashsum_init_ripemd_hasher` because this can + * be confused with the proprietary hash function RIPEMD, which + * is the predecessor to RIPEMD-{128,160,256,320} */ + /** * Create an initialised state for SHA0 * hashing and return hash functions and details @@ -1252,7 +1097,7 @@ int libhashsum_init_blake256_hasher(struct libhashsum_hasher *this, const void * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ -int libhashsum_init_blakes_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt); +int libhashsum_init_blakes_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt); /* TODO test */ /** * Create an initialised state for BLAKE384 (BLAKE, BLAKEb) @@ -1299,7 +1144,7 @@ int libhashsum_init_blake512_hasher(struct libhashsum_hasher *this, const void * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ -int libhashsum_init_blakeb_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt); +int libhashsum_init_blakeb_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt); /* TODO test */ /** * Create an initialised state for BLAKE @@ -1321,7 +1166,7 @@ int libhashsum_init_blakeb_hasher(struct libhashsum_hasher *this, size_t hashbit * @since 1.0 */ LIBHASHSUM_1_NONNULL_ -int libhashsum_init_blake_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, size_t saltbytes); +int libhashsum_init_blake_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, size_t saltbytes); /* TODO test */ #endif diff --git a/libhashsum/internal.h b/libhashsum/internal.h new file mode 100644 index 0000000..b75cdd9 --- /dev/null +++ b/libhashsum/internal.h @@ -0,0 +1,165 @@ +/* See LICENSE file for copyright and license details. */ +#include <stdint.h> + + +#ifdef LIBHASHSUM_INCLUDE_LIBSHA1_STATE +# include <libsha1.h> +#endif +#ifdef LIBHASHSUM_INCLUDE_LIBSHA2_STATE +# include <libsha2.h> +#endif +#ifdef LIBHASHSUM_INCLUDE_LIBKECCAK_STATE +# include <libkeccak.h> +#endif +#ifdef LIBHASHSUM_INCLUDE_LIBBLAKE_STATE +# include <libblake.h> +#endif + + +/** + * Hash state + * + * For internal use + */ +union libhashsum_state { + struct { + unsigned char x[32]; + unsigned char mp[16]; + unsigned char mz[16]; + unsigned char sum[16]; + unsigned t; + } md2; /* size = [82, 88] */ + + struct { + union { + uint32_t h32[4]; + uint8_t sum[16]; + } h; + union { + uint32_t m32[16]; + uint8_t m8[64]; + } m; + uint64_t count; + } md4; /* size = 70 */ + + struct { + union { + uint32_t h32[4]; + uint8_t sum[16]; + } h; + uint8_t m[64]; + uint32_t w[16]; + uint64_t count; + } md5; /* size = 152 */ + + struct { + union { + uint32_t h32[4]; + uint8_t sum[16]; + } h; + union { + uint32_t m32[16]; + uint8_t m8[64]; + } m; + uint64_t count; + } ripemd_128; /* size = 88 */ + + struct { + union { + uint32_t h32[5]; + uint8_t sum[20]; + } h; + union { + uint32_t m32[16]; + uint8_t m8[64]; + } m; + uint32_t w1[5]; + uint32_t w2[5]; + uint64_t count; + } ripemd_160; /* size = 132 */ + + struct { + union { + uint32_t h32[8]; + uint8_t sum[32]; + } h; + union { + uint32_t m32[16]; + uint8_t m8[64]; + } m; + uint64_t count; + } ripemd_256; /* size = 104 */ + + struct { + union { + uint32_t h32[10]; + uint8_t sum[40]; + } h; + union { + uint32_t m32[16]; + uint8_t m8[64]; + } m; + uint32_t w1[5]; + uint32_t w2[5]; + uint64_t count; + } ripemd_320; /* size = 152 */ + +#ifdef LIBHASHSUM_INCLUDE_LIBSHA1_STATE + struct { + struct libsha1_state s; + uint8_t sum[20]; + } sha0, sha1; /* size = [432, 440] */ +#endif + +#ifdef LIBHASHSUM_INCLUDE_LIBSHA2_STATE + struct { + struct libsha2_state s; + uint8_t sum[64]; + } sha2; /* size = [1612, 1624] */ +#endif + +#ifdef LIBHASHSUM_INCLUDE_LIBKECCAK_STATE + struct { + struct libkeccak_state s; + union { + uint8_t buf[512]; + uint8_t *dyn; + } sum; + const char *suffix; + size_t squeezes; + char algostr[256]; + } keccak; /* size = [1024, 1072] */ +#endif + +#ifdef LIBHASHSUM_INCLUDE_LIBBLAKE_STATE + struct { + struct libblake_blake224_state s; + uint8_t buf[128]; + char algostr[49]; + } blake224; /* size = 233 */ + + struct { + struct libblake_blake256_state s; + uint8_t buf[128]; + char algostr[49]; + } blake256; /* size = 233 */ + + struct { + struct libblake_blake384_state s; + uint8_t buf[256]; + char algostr[81]; + } blake384; /* size = 449 */ + + struct { + struct libblake_blake512_state s; + uint8_t buf[256]; + char algostr[81]; + } blake512; /* size = 449 */ +#endif + + /* libblake: 48(2s), 96(2b), 144(2Xs), 276(2Xb) */ + + char max_size[1648]; +#define libhashsum_init_hasher libhashsum_init_hasher__1648 +#define libhashsum_init_hasher_from_string libhashsum_init_hasher_from_string__1648 +}; diff --git a/libhashsum_get_algorithm_from_string.3 b/libhashsum_get_algorithm_from_string.3 new file mode 100644 index 0000000..d7f338f --- /dev/null +++ b/libhashsum_get_algorithm_from_string.3 @@ -0,0 +1,347 @@ +.TH LIBHASHSUM_GET_ALGORITHM_FROM_STRING 3 libhashsum +.SH NAME +libhashsum_get_algorithm_from_string - identify named hash function + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBenum libhashsum_algorithm\fP { /* see the section DESCRIPTION for a listing of values */ }; + +int \fBlibhashsum_get_algorithm_from_string\fP(enum libhashsum_algorithm \fIalgorithm_out\fP, const char *\fIalgorithm\fP); +.fi +.PP +Link with +.IR -lhashsum . + +.SH DESCRIPTION +The +.B libhashsum_get_algorithm_from_string +functions parses the string +.I algorithm +to identify the hash function it specifies, +and stores one of the following values in +.I *algorithm_out +to indicate the specified hash function: +.TP +.B LIBHASHSUM_MD2 +MD2 + +.I algorithm +is +.RB \(dq MD2 \(dq. +.TP +.B LIBHASHSUM_MD4 +MD4 + +.I algorithm +is +.RB \(dq MD4 \(dq. +.TP +.B LIBHASHSUM_MD5 +MD5 + +.I algorithm +is +.RB \(dq MD5 \(dq. +.TP +.B LIBHASHSUM_RIPEMD_128 +RIPEMD-128 + +.I algorithm +is +.RB \(dq RIPEMD-128 \(dq +or +.RB \(dq RMD-128 \(dq. +.TP +.B LIBHASHSUM_RIPEMD_160 +RIPEMD-160 + +.I algorithm +is +.RB \(dq RIPEMD-160 \(dq +or +.RB \(dq RMD-160 \(dq. +.TP +.B LIBHASHSUM_RIPEMD_256 +RIPEMD-256 + +.I algorithm +is +.RB \(dq RIPEMD-256 \(dq +or +.RB \(dq RMD-256 \(dq. +.TP +.B LIBHASHSUM_RIPEMD_512 +RIPEMD-512 + +.I algorithm +is +.RB \(dq RIPEMD-512 \(dq +or +.RB \(dq RMD-512 \(dq. +.TP +.B LIBHASHSUM_SHA0 +SHA-0 + +.I algorithm +is +.RB \(dq SHA-0 \(dq. +.TP +.B LIBHASHSUM_SHA1 +SHA-1 + +.I algorithm +is +.RB \(dq SHA-1 \(dq. +.TP +.B LIBHASHSUM_SHA_224 +SHA-224 (32-bit SHA-2 with 224 bit output) + +.I algorithm +is +.RB \(dq SHA-224 \(dq +or +.RB \(dq SHA-2-224 \(dq. +.TP +.B LIBHASHSUM_SHA_256 +SHA-256 (32-bit SHA-2 with 356 bit output) + +.I algorithm +is +.RB \(dq SHA-256 \(dq +or +.RB \(dq SHA-2-256 \(dq. +.TP +.B LIBHASHSUM_SHA_384 +SHA-384 (64-bit SHA-2 with 384 bit output) + +.I algorithm +is +.RB \(dq SHA-384 \(dq +or +.RB \(dq SHA-2-384 \(dq. +.TP +.B LIBHASHSUM_SHA_512 +SHA-512 (64-bit SHA-2 with 512 bit output) + +.I algorithm +is +.RB \(dq SHA-512 \(dq +or +.RB \(dq SHA-2-512 \(dq. +.TP +.B LIBHASHSUM_SHA_512_224 +SHA-512/224 (64-bit SHA-2 with 224 bit output) + +.I algorithm +is +.RB \(dq SHA-512/224 \(dq +or +.RB \(dq SHA-2-512/224 \(dq, +where the slash +.RB (' / ') +may be replaces with a dash +.RB (' - ') +or underscore +.RB (' _ '). +.TP +.B LIBHASHSUM_SHA_512_256 +SHA-512/256 (64-bit SHA-2 with 256 bit output) + +.I algorithm +is +.RB \(dq SHA-512/256 \(dq +or +.RB \(dq SHA-2-512/256 \(dq, +where the slash +.RB (' / ') +may be replaces with a dash +.RB (' - ') +or underscore +.RB (' _ '). +.TP +.B LIBHASHSUM_KECCAK +Keccak + +.I algorithm +is +.RB \(dq Keccak \(dq. +.TP +.B LIBHASHSUM_KECCAK_224 +Keccak-224 (Keccak[n=224]) + +.I algorithm +is +.RB \(dq Keccak-224 \(dq. +.TP +.B LIBHASHSUM_KECCAK_256 +Keccak-256 (Keccak[n=256]) + +.I algorithm +is +.RB \(dq Keccak-256 \(dq. +.TP +.B LIBHASHSUM_KECCAK_384 +Keccak-384 (Keccak[n=384]) + +.I algorithm +is +.RB \(dq Keccak-384 \(dq. +.TP +.B LIBHASHSUM_KECCAK_512 +Keccak-512 (Keccak[n=512]) + +.I algorithm +is +.RB \(dq Keccak-512 \(dq. +.TP +.B LIBHASHSUM_SHA3_224 +SHA-3-224 (SHA-3 with 224 bit output) + +.I algorithm +is +.RB \(dq SHA-3-224 \(dq. +.TP +.B LIBHASHSUM_SHA3_256 +SHA-3-256 (SHA-3 with 256 bit output) + +.I algorithm +is +.RB \(dq SHA-3-256 \(dq. +.TP +.B LIBHASHSUM_SHA3_384 +SHA-3-384 (SHA-3 with 384 bit output) + +.I algorithm +is +.RB \(dq SHA-3-384 \(dq. +.TP +.B LIBHASHSUM_SHA3_512 +SHA-3-512 (SHA-3 with 512 bit output) + +.I algorithm +is +.RB \(dq SHA-3-512 \(dq. +.TP +.B LIBHASHSUM_SHAKE128 +SHAKE128 (SHAKE with 256 bit capacity, and default output of 128 bits) + +.I algorithm +is +.RB \(dq SHAKE-128 \(dq. +.TP +.B LIBHASHSUM_SHAKE256 +SHAKE128 (SHAKE with 512 bit capacity, and default output of 256 bits) + +.I algorithm +is +.RB \(dq SHAKE-256 \(dq. +.TP +.B LIBHASHSUM_SHAKE512 +SHAKE128 (SHAKE with 1024 bit capacity, and default output of 512 bits) + +.I algorithm +is +.RB \(dq SHAKE-512 \(dq. +.TP +.B LIBHASHSUM_RAWSHAKE128 +RawSHAKE128 (RawSHAKE with 256 bit capacity, and default output of 128 bits) + +.I algorithm +is +.RB \(dq RawSHAKE-128 \(dq. +.TP +.B LIBHASHSUM_RAWSHAKE256 +RawSHAKE128 (RawSHAKE with 512 bit capacity, and default output of 256 bits) + +.I algorithm +is +.RB \(dq RawSHAKE-256 \(dq. +.TP +.B LIBHASHSUM_RAWSHAKE512 +RawSHAKE128 (RawSHAKE with 1024 bit capacity, and default output of 512 bits) + +.I algorithm +is +.RB \(dq RawSHAKE-512 \(dq. +.TP +.B LIBHASHSUM_BLAKE224 +BLAKE224 (BLAKEs (BLAKE) with 224 bit output) + +.I algorithm +is +.RB \(dq BLAKE-224 \(dq +or +.RB \(dq B224 \(dq. +.TP +.B LIBHASHSUM_BLAKE256 +BLAKE256 (BLAKEs (BLAKE) with 256 bit output) + +.I algorithm +is +.RB \(dq BLAKE-256 \(dq +or +.RB \(dq B256 \(dq. +.TP +.B LIBHASHSUM_BLAKE384 +BLAKE384 (BLAKEb (BLAKE) with 384 bit output) + +.I algorithm +is +.RB \(dq BLAKE-384 \(dq +or +.RB \(dq B384 \(dq. +.TP +.B LIBHASHSUM_BLAKE512 +BLAKE512 (BLAKEb (BLAKE) with 512 bit output) + +.I algorithm +is +.RB \(dq BLAKE-512 \(dq +or +.RB \(dq B512 \(dq. +.PP +The function is case-insensitive, and tolerates +skipping dashes +.RB (' - ') +that are not immediately after a digit. Additionally, +it will ignore the substring +.RB \(dq sum \(dq +if it is added to the end of the function name. +.PP +The function +.I does not +validate the parameters for the hash function +that may be places inside square brackets at +the end of +.IR algorithm . +.PP +.I algorithm_out +and +.I algorithm +must not be +.IR NULL . + +.SH RETURN VALUE +The +.B libhashsum_get_algorithm_from_string +returns 1 if the hash function was identified. +Otherwise the function returns 0. +If 1 is returned, the +.I *algoritm_out +is set, otherwise +.I *algoritm_out +is unmodified. + +.SH ERRORS +The +.B libhashsum_get_algorithm_from_string +function cannot fail. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_hasher_from_string (3) diff --git a/libhashsum_get_algorithm_string.c b/libhashsum_get_algorithm_from_string.c index 5f910be..96892e1 100644 --- a/libhashsum_get_algorithm_string.c +++ b/libhashsum_get_algorithm_from_string.c @@ -25,7 +25,7 @@ equiv(const char *a, const char *b) int -libhashsum_get_algorithm_string(enum libhashsum_algorithm *algorithm_out, const char *algorithm) +libhashsum_get_algorithm_from_string(enum libhashsum_algorithm *algorithm_out, const char *algorithm) { if (equiv(algorithm, "MD2")) *algorithm_out = LIBHASHSUM_MD2; diff --git a/libhashsum_init_blake224_hasher.3 b/libhashsum_init_blake224_hasher.3 new file mode 100644 index 0000000..1dd1655 --- /dev/null +++ b/libhashsum_init_blake224_hasher.3 @@ -0,0 +1,208 @@ +.TH LIBHASHSUM_INIT_BLAKE224_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blake224_hasher - initialise state for BLAKE224 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_blake224_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, const void *\fIsalt\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blake224_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKE224 +(a version of BLAKEs, which is a version of BLAKE), and +stores hash function information and hashing functions for +BLAKE224 in +.IR *hasher . +.PP +.I salt +shall be +.I NULL +or a buffer of 16 bytes that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_BLAKE224 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE224 \(dq, +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE224[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKE224 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of BLAKE224 hashes, in bytes +.RI ( LIBHASHSUM_BLAKE224_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_blake224_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_blake224_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blakes_hasher (3), +.BR libhashsum_init_blake_hasher (3) diff --git a/libhashsum_init_blake256_hasher.3 b/libhashsum_init_blake256_hasher.3 new file mode 100644 index 0000000..c427f51 --- /dev/null +++ b/libhashsum_init_blake256_hasher.3 @@ -0,0 +1,208 @@ +.TH LIBHASHSUM_INIT_BLAKE256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blake256_hasher - initialise state for BLAKE256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_blake256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, const void *\fIsalt\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blake256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKE256 +(a version of BLAKEs, which is a version of BLAKE), and +stores hash function information and hashing functions for +BLAKE256 in +.IR *hasher . +.PP +.I salt +shall be +.I NULL +or a buffer of 16 bytes that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_BLAKE256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE256 \(dq, +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE256[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKE256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of BLAKE256 hashes, in bytes +.RI ( LIBHASHSUM_BLAKE256_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_blake256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_blake256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blakes_hasher (3), +.BR libhashsum_init_blake_hasher (3) diff --git a/libhashsum_init_blake384_hasher.3 b/libhashsum_init_blake384_hasher.3 new file mode 100644 index 0000000..29b31b5 --- /dev/null +++ b/libhashsum_init_blake384_hasher.3 @@ -0,0 +1,208 @@ +.TH LIBHASHSUM_INIT_BLAKE384_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blake384_hasher - initialise state for BLAKE384 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_blake384_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, const void *\fIsalt\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blake384_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKE384 +(a version of BLAKEb, which is a version of BLAKE), and +stores hash function information and hashing functions for +BLAKE384 in +.IR *hasher . +.PP +.I salt +shall be +.I NULL +or a buffer of 32 bytes that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_BLAKE384 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE384 \(dq, +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE384[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKE384 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of BLAKE384 hashes, in bytes +.RI ( LIBHASHSUM_BLAKE384_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_blake384_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_blake384_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blakeb_hasher (3), +.BR libhashsum_init_blake_hasher (3) diff --git a/libhashsum_init_blake512_hasher.3 b/libhashsum_init_blake512_hasher.3 new file mode 100644 index 0000000..a2d690d --- /dev/null +++ b/libhashsum_init_blake512_hasher.3 @@ -0,0 +1,208 @@ +.TH LIBHASHSUM_INIT_BLAKE512_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blake512_hasher - initialise state for BLAKE512 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_blake512_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, const void *\fIsalt\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blake512_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKE512 +(a version of BLAKEb, which is a version of BLAKE), and +stores hash function information and hashing functions for +BLAKE512 in +.IR *hasher . +.PP +.I salt +shall be +.I NULL +or a buffer of 32 bytes that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_BLAKE512 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE512 \(dq, +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE512[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKE512 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of BLAKE512 hashes, in bytes +.RI ( LIBHASHSUM_BLAKE512_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_blake512_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_blake512_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blakeb_hasher (3), +.BR libhashsum_init_blake_hasher (3) diff --git a/libhashsum_init_blake_hasher.3 b/libhashsum_init_blake_hasher.3 new file mode 100644 index 0000000..f6f77bb --- /dev/null +++ b/libhashsum_init_blake_hasher.3 @@ -0,0 +1,295 @@ +.TH LIBHASHSUM_INIT_BLAKE_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blake_hasher - initialise state for BLAKE hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_blake_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP, const void *\fIsalt\fP, size_t \fIsaltbytes\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blake_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKE +(a version of BLAKE), and stores hash function information +and hashing functions for BLAKE in +.IR *hasher . +.PP +.I hashbits +shall be the hash size in bits, which shall be either +224, 256, 384, or 512. +.PP +.I salt +shall be +.I NULL +or a buffer that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I saltbytes +shall be the number bytes in +.IR salt , +which must be 16 if +.I hashbits +is 224 or 256, and 32 if +.I hashbits +is 384 or 512; however +.I saltbytes +is ignored if +.I salt +is +.IR NULL . +.PP +.I hasher->algorithm +will be set to either +.I LIBHASHSUM_BLAKE224 +(if +.I hashbits +is 224), +.I LIBHASHSUM_BLAKE256 +(if +.I hashbits +is 256), +.I LIBHASHSUM_BLAKE384 +(if +.I hashbits +is 384), or +.I LIBHASHSUM_BLAKE512 +if +.I hashbits +is 512). +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE \fIhashbits\fP\(dq +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE \fIhashbits\fP[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKE uses, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( hashbits/8 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_blake_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_blake_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B EINVAL +.I hashbits +is either 224, 256, 384, nor 384. +.TP +.B EINVAL +.I hashbits +is either 224 or 256 and +.I salt +is +.RI non- NULL +but +.I saltbytes +is not 16. +.TP +.B EINVAL +.I hashbits +is either 384 or 512 and +.I salt +is +.RI non- NULL +but +.I saltbytes +is not 32. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.I libhashsum_init_blake_hasher(hasher, 224, salt, 16) +and +.I libhashsum_init_blake_hasher(hasher, 256, salt, 16) +are equivalent to +.I libhashsum_init_blake224_hasher(hasher, salt) +and +.I libhashsum_init_blake256_hasher(hasher, salt) +respectively as well as to +.I libhashsum_init_blakes_hasher(hasher, 224, salt) +and +.I libhashsum_init_blakes_hasher(hasher, 256, salt) +respectively. +.PP +.I libhashsum_init_blake_hasher(hasher, 384, salt, 32) +and +.I libhashsum_init_blake_hasher(hasher, 512, salt, 32) +are equivalent to +.I libhashsum_init_blake384_hasher(hasher, salt) +and +.I libhashsum_init_blake512_hasher(hasher, salt) +respectively as well as to +.I libhashsum_init_blakeb_hasher(hasher, 384, salt) +and +.I libhashsum_init_blakeb_hasher(hasher, 512, salt) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blake224_hasher (3), +.BR libhashsum_init_blake256_hasher (3), +.BR libhashsum_init_blake384_hasher (3), +.BR libhashsum_init_blake512_hasher (3), +.BR libhashsum_init_blakes_hasher (3), +.BR libhashsum_init_blakeb_hasher (3) diff --git a/libhashsum_init_blake_hasher.c b/libhashsum_init_blake_hasher.c index 7b6d78e..2fc5ae4 100644 --- a/libhashsum_init_blake_hasher.c +++ b/libhashsum_init_blake_hasher.c @@ -4,14 +4,14 @@ int -libhashsum_init_blake_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, size_t salybytes) +libhashsum_init_blake_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, size_t saltbytes) { if (salt) { if (hashbits == 224U || hashbits == 256U) { - if (salybytes != 16U) + if (saltbytes != 16U) goto einval; } else if (hashbits == 384U || hashbits == 512U) { - if (salybytes != 32U) + if (saltbytes != 32U) goto einval; } } @@ -33,7 +33,7 @@ einval: #else int -libhashsum_init_blake_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, size_t salybytes) +libhashsum_init_blake_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, size_t saltbytes) { (void) this; (void) hashbits; diff --git a/libhashsum_init_blakeb_hasher.3 b/libhashsum_init_blakeb_hasher.3 new file mode 100644 index 0000000..3d1230e --- /dev/null +++ b/libhashsum_init_blakeb_hasher.3 @@ -0,0 +1,232 @@ +.TH LIBHASHSUM_INIT_BLAKEB_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blakeb_hasher - initialise state for BLAKEb hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_blakeb_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP, const void *\fIsalt\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blakeb_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKEb +(a version of BLAKE), and stores hash function information +and hashing functions for BLAKEb in +.IR *hasher . +.PP +.I hashbits +shall be the hash size in bits, which shall be either 384 or 512. +.PP +.I salt +shall be +.I NULL +or a buffer of 32 bytes that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I hasher->algorithm +will be set to either +.I LIBHASHSUM_BLAKE384 +(if +.I hashbits +is 384) or +.I LIBHASHSUM_BLAKE512 +if +.I hashbits +is 512). +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE \fIhashbits\fP\(dq +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE \fIhashbits\fP[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKEb uses, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( hashbits/8 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_blakeb_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_blakeb_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B EINVAL +.I hashbits +is either 384 nor 512. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.I libhashsum_init_blakeb_hasher(hasher, 384, salt) +and +.I libhashsum_init_blakeb_hasher(hasher, 512, salt) +are equivalent to +.I libhashsum_init_blake384_hasher(hasher, salt) +and +.I libhashsum_init_blake512_hasher(hasher, salt) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blake384_hasher (3), +.BR libhashsum_init_blake512_hasher (3), +.BR libhashsum_init_blake_hasher (3) diff --git a/libhashsum_init_blakes_hasher.3 b/libhashsum_init_blakes_hasher.3 new file mode 100644 index 0000000..23ce54f --- /dev/null +++ b/libhashsum_init_blakes_hasher.3 @@ -0,0 +1,232 @@ +.TH LIBHASHSUM_INIT_BLAKES_HASHER 3 libhashsum +.SH NAME +libhashsum_init_blakes_hasher - initialise state for BLAKEs hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_blakes_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP, const void *\fIsalt\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lblake" . + +.SH DESCRIPTION +The +.B libhashsum_init_blakes_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function BLAKEs +(a version of BLAKE), and stores hash function information +and hashing functions for BLAKEs in +.IR *hasher . +.PP +.I hashbits +shall be the hash size in bits, which shall be either 224 or 256. +.PP +.I salt +shall be +.I NULL +or a buffer of 16 bytes that shall be used as a salt +.RI ( NULL +is equivalent to all zeroes). +.PP +.I hasher->algorithm +will be set to either +.I LIBHASHSUM_BLAKE224 +(if +.I hashbits +is 224) or +.I LIBHASHSUM_BLAKE256 +if +.I hashbits +is 256). +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq BLAKE \fIhashbits\fP\(dq +or (if +.I salt +is neither +.I NULL +nor all zeroes) +.RB \(dq BLAKE \fIhashbits\fP[salt= \fIlowercase_hexadecimal(salt)\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size BLAKEs uses, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( hashbits/8 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_blakes_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_blakes_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B EINVAL +.I hashbits +is either 224 nor 256. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.I libhashsum_init_blakes_hasher(hasher, 224, salt) +and +.I libhashsum_init_blakes_hasher(hasher, 256, salt) +are equivalent to +.I libhashsum_init_blake224_hasher(hasher, salt) +and +.I libhashsum_init_blake256_hasher(hasher, salt) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_blake224_hasher (3), +.BR libhashsum_init_blake256_hasher (3), +.BR libhashsum_init_blake_hasher (3) diff --git a/libhashsum_init_hasher.3 b/libhashsum_init_hasher.3 new file mode 100644 index 0000000..df8c382 --- /dev/null +++ b/libhashsum_init_hasher.3 @@ -0,0 +1,414 @@ +.TH LIBHASHSUM_INIT_HASHER 3 libhashsum +.SH NAME +libhashsum_init_hasher - initialise state for hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBenum libhashsum_algorithm\fP { /* see the section DESCRIPTION for a listing of values */ }; + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, enum libhashsum_algorithm \fIalgorithm\fP); +.fi +.PP +Link with +.I -lhashsum +.br +.I -lsha1 +(unless support for SHA-0 and SHA-1 was excluded) +.br +.I -lsha2 +(unless support for SHA-2 was excluded) +.br +.I -lkeccak +(unless support for Keccak, SHA-3, SHAKE, and RawSHAKE was excluded) +.br +.I -lblake +(unless support for BLAKE was excluded). + +.SH DESCRIPTION +The +.B libhashsum_init_hasher +function initialises +.I *hasher +for hashing using a cryptographic hash function selected +using the parameter +.IR algorithm , +and stores hash function information and +hashing functions in +.IR *hasher . +.PP +.I algorithm +shall be one of the following values to select hash function: +.TP +.B LIBHASHSUM_MD2 +Selects MD2. See +.BR libhashsum_init_md2_hasher (3) +for more information. +.TP +.B LIBHASHSUM_MD4 +Selects MD4. See +.BR libhashsum_init_md4_hasher (3) +for more information. +.TP +.B LIBHASHSUM_MD5 +Selects MD5. See +.BR libhashsum_init_md5_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_128 +Selects RIPEMD-128. See +.BR libhashsum_init_ripemd_128_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_160 +Selects RIPEMD-160. See +.BR libhashsum_init_ripemd_160_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_256 +Selects RIPEMD-256. See +.BR libhashsum_init_ripemd_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RIPEMD_512 +Selects RIPEMD-512. See +.BR libhashsum_init_ripemd_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA0 +Selects SHA-0. See +.BR libhashsum_init_sha0_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA1 +Selects SHA-1. See +.BR libhashsum_init_sha0_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_224 +Selects SHA-224 (SHA-2). See +.BR libhashsum_init_sha_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_256 +Selects SHA-256 (SHA-2). See +.BR libhashsum_init_sha_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_384 +Selects SHA-384 (SHA-2). See +.BR libhashsum_init_sha_384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_512 +Selects SHA-512 (SHA-2). See +.BR libhashsum_init_sha_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_512_224 +Selects SHA-512/224 (SHA-2). See +.BR libhashsum_init_sha_512_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA_512_256 +Selects SHA-512/256 (SHA-2). See +.BR libhashsum_init_sha_512_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK +Selects Keccak. However, this value is +unsupported, as parameters are expected +(even though they are technically optional), +so the function will return -1 and set +.I errno +to +.IR EINVAL . +See +.BR libhashsum_init_keccak_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_224 +Selects Keccak-224 (Keccak[n=224]). See +.BR libhashsum_init_keccak_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_256 +Selects Keccak-256 (Keccak[n=256]). See +.BR libhashsum_init_keccak_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_384 +Selects Keccak-384 (Keccak[n=384]). See +.BR libhashsum_init_keccak_384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_KECCAK_512 +Selects Keccak-512 (Keccak[n=512]). See +.BR libhashsum_init_keccak_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_224 +Selects SHA-3-224. See +.BR libhashsum_init_sha3_224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_256 +Selects SHA-3-256. See +.BR libhashsum_init_sha3_256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_384 +Selects SHA-3-384. See +.BR libhashsum_init_sha3_384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHA3_512 +Selects SHA-3-512. See +.BR libhashsum_init_sha3_512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHAKE128 +Selects SHAKE128 (SHAKE). See +.BR libhashsum_init_shake128_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHAKE256 +Selects SHAKE256 (SHAKE). See +.BR libhashsum_init_shake256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_SHAKE512 +Selects SHAKE512 (SHAKE). See +.BR libhashsum_init_shake512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RAWSHAKE128 +Selects RawSHAKE128 (RawSHAKE). See +.BR libhashsum_init_rawshake128_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RAWSHAKE256 +Selects RawSHAKE256 (RawSHAKE). See +.BR libhashsum_init_rawshake256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_RAWSHAKE512 +Selects RawSHAKE512 (RawSHAKE). See +.BR libhashsum_init_rawshake512_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE224 +Selects BLAKE224 (BLAKE, BLAKEs). See +.BR libhashsum_init_blake224_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE256 +Selects BLAKE256 (BLAKE, BLAKEs). See +.BR libhashsum_init_blake256_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE384 +Selects BLAKE384 (BLAKE, BLAKEb). See +.BR libhashsum_init_blake384_hasher (3) +for more information. +.TP +.B LIBHASHSUM_BLAKE512 +Selects BLAKE512 (BLAKE, BLAKEb). See +.BR libhashsum_init_blake512_hasher (3) +for more information. +.PP +.I hasher->algorithm +will be set to +.IR algorithm . +.PP +.I hasher->algorithm_string +will be set to a string representing the hash +function selected using the parameter +.IR algorithm . +.PP +.I hasher->input_block_size +will be set to the block size, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes. +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 if +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter, or to 0 otherwise. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.TP +.B EINVAL +.I extra_bits +is not 0 but +.I hasher->supports_non_whole_bytes +was set to 0 by +.BR libhashsum_init_hasher . +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will either be set to +.I NULL +or to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOSYS +The selected algorithm requires a larger +(newer) version +.B union libhashsum_state +(and thus a larger version of +.BR "struct libhashsum_hasher" ) +than the application is compiled with. +.TP +.B EINVAL +The value of +.I algorithm +is unrecognised or unsupported. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_hasher_from_string (3), +.BR libhashsum_init_keccak_hasher (3) diff --git a/libhashsum_init_hasher_from_string.3 b/libhashsum_init_hasher_from_string.3 new file mode 100644 index 0000000..00f7723 --- /dev/null +++ b/libhashsum_init_hasher_from_string.3 @@ -0,0 +1,250 @@ +.TH LIBHASHSUM_INIT_HASHER_FROM_STRING 3 libhashsum +.SH NAME +libhashsum_init_hasher_from_string - initialise state for hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_hasher_from_string\fP(struct libhashsum_hasher *\fIhasher\fP, const char *\fIalgorithm\fP); +.fi +.PP +Link with +.I -lhashsum +.br +.I -lsha1 +(unless support for SHA-0 and SHA-1 was excluded) +.br +.I -lsha2 +(unless support for SHA-2 was excluded) +.br +.I -lkeccak +(unless support for Keccak, SHA-3, SHAKE, and RawSHAKE was excluded) +.br +.I -lblake +(unless support for BLAKE was excluded). + +.SH DESCRIPTION +The +.B libhashsum_init_hasher_from_string +function initialises +.I *hasher +for hashing using a cryptographic hash function +and parameters selected +using the parameter +.I algorithm +(see +.BR libhashsum_get_algorithm_from_string (3) +for more information; for the list of valid parameters, +see the output to +.I hasher->algorithm_string +for the dedicated initialiser function for the +selected hash function), and stores hash function +information and hashing functions in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to the algorithm selected by +.I algorithm +(which will be +.I a +after running +.IR "libhashsum_get_algorithm_from_string(&a, algorithm)" ). +.PP +.I hasher->algorithm_string +will be set to a string representing the hash +function selected using the parameter +.IR algorithm . +.PP +.I hasher->input_block_size +will be set to the block size, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes. +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 if +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter, or to 0 otherwise. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.TP +.B EINVAL +.I extra_bits +is not 0 but +.I hasher->supports_non_whole_bytes +was set to 0 by +.BR libhashsum_init_hasher . +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will either be set to +.I NULL +or to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +and +.I algorithm +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_hasher_from_string +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_hasher_from_string +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOSYS +The selected algorithm requires a larger +(newer) version +.B union libhashsum_state +(and thus a larger version of +.BR "struct libhashsum_hasher" ) +than the application is compiled with. +.TP +.B EINVAL +The value of +.I algorithm +is unrecognised or unsupported. +.TP +.B EINVAL +.I algorithm +contains an invalid parameter or +an invalid combination of parameters. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_hasher (3), +.BR libhashsum_get_algorithm_from_string (3) diff --git a/libhashsum_init_hasher_from_string.c b/libhashsum_init_hasher_from_string.c index 0eaa12e..c4bf441 100644 --- a/libhashsum_init_hasher_from_string.c +++ b/libhashsum_init_hasher_from_string.c @@ -158,7 +158,7 @@ int libhashsum_init_hasher_from_string(struct libhashsum_hasher *this, const char *algorithm) { enum libhashsum_algorithm algo; - if (!libhashsum_get_algorithm_string(&algo, algorithm)) { + if (!libhashsum_get_algorithm_from_string(&algo, algorithm)) { errno = EINVAL; return -1; } diff --git a/libhashsum_init_keccak_224_hasher.3 b/libhashsum_init_keccak_224_hasher.3 new file mode 100644 index 0000000..9852f68 --- /dev/null +++ b/libhashsum_init_keccak_224_hasher.3 @@ -0,0 +1,198 @@ +.TH LIBHASHSUM_INIT_KECCAK_224_HASHER 3 libhashsum +.SH NAME +libhashsum_init_keccak_224_hasher - initialise state for Keccak-224 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_keccak_224_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_keccak_224_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function Keccak-224 +(Keccak[s=1600,n=224], which is Keccak[r=1152,c=448,n=224]), +and stores hash function information and hashing functions +for Keccak-224 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_KECCAK_224 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq Keccak-224 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size Keccak-224 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of Keccak-224 hashes, in bytes +.RI ( LIBHASHSUM_KECCAK_224_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_keccak_224_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_keccak_224_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_keccak_hasher (3) diff --git a/libhashsum_init_keccak_256_hasher.3 b/libhashsum_init_keccak_256_hasher.3 new file mode 100644 index 0000000..6492401 --- /dev/null +++ b/libhashsum_init_keccak_256_hasher.3 @@ -0,0 +1,198 @@ +.TH LIBHASHSUM_INIT_KECCAK_256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_keccak_256_hasher - initialise state for Keccak-256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_keccak_256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_keccak_256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function Keccak-256 +(Keccak[s=1600,n=256], which is Keccak[r=1088,c=512,n=256]), +and stores hash function information and hashing functions +for Keccak-256 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_KECCAK_256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq Keccak-256 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size Keccak-256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of Keccak-256 hashes, in bytes +.RI ( LIBHASHSUM_KECCAK_256_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_keccak_256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_keccak_256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_keccak_hasher (3) diff --git a/libhashsum_init_keccak_384_hasher.3 b/libhashsum_init_keccak_384_hasher.3 new file mode 100644 index 0000000..1527ad0 --- /dev/null +++ b/libhashsum_init_keccak_384_hasher.3 @@ -0,0 +1,198 @@ +.TH LIBHASHSUM_INIT_KECCAK_384_HASHER 3 libhashsum +.SH NAME +libhashsum_init_keccak_384_hasher - initialise state for Keccak-384 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_keccak_384_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_keccak_384_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function Keccak-384 +(Keccak[s=1600,n=384], which is Keccak[r=832,c=768,n=384]), +and stores hash function information and hashing functions +for Keccak-384 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_KECCAK_384 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq Keccak-384 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size Keccak-384 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of Keccak-384 hashes, in bytes +.RI ( LIBHASHSUM_KECCAK_384_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_keccak_384_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_keccak_384_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_keccak_hasher (3) diff --git a/libhashsum_init_keccak_512_hasher.3 b/libhashsum_init_keccak_512_hasher.3 new file mode 100644 index 0000000..d59f0ba --- /dev/null +++ b/libhashsum_init_keccak_512_hasher.3 @@ -0,0 +1,198 @@ +.TH LIBHASHSUM_INIT_KECCAK_512_HASHER 3 libhashsum +.SH NAME +libhashsum_init_keccak_512_hasher - initialise state for Keccak-512 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_keccak_512_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_keccak_512_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function Keccak-512 +(Keccak[s=1600,n=512], which is Keccak[r=576,c=1024,n=512]), +and stores hash function information and hashing functions +for Keccak-512 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_KECCAK_512 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq Keccak-512 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size Keccak-512 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of Keccak-512 hashes, in bytes +.RI ( LIBHASHSUM_KECCAK_512_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_keccak_512_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_keccak_512_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_keccak_hasher (3) diff --git a/libhashsum_init_keccak_hasher.3 b/libhashsum_init_keccak_hasher.3 new file mode 100644 index 0000000..3b2def5 --- /dev/null +++ b/libhashsum_init_keccak_hasher.3 @@ -0,0 +1,290 @@ +.TH LIBHASHSUM_INIT_KECCAK_HASHER 3 libhashsum +.SH NAME +libhashsum_init_keccak_hasher - initialise state for Keccak hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_keccak_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIratebits\fP, + size_t \fIcapbits\fP, size_t \fIhashbits\fP, size_t \fIsqueezes\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_keccak_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function Keccak, +and stores hash function information and hashing functions +for Keccak in +.IR *hasher . +.PP +.I ratebit +shall be the rate, in bits per \(dqabsorption\(dq, of the hash function, +or 0 if it shall be resolved to an automatically determined value. +.PP +.I capbits +shall be the capacity, in bits, of the hash function's \(dqsponge\(dq, +or 0 if it shall be resolved to an automatically determined value. +.PP +.I hashbits +shall be the hash size, in bits or 0 if it shall be resolved to +an automatically determined value. +.PP +.I squeezes +shall be the number of \(dqsponge squeezes\(dq to perform at the +end phase when producing the hash, or 0 if it shall be resolved +to an automatically determined value (which will always be 1). +.PP +.I hasher->algorithm +will be set to +.I LIBHASHSUM_KECCAK_224 +(if +.I (ratebits, capbits, hashbits, squeezes) +have the values (1152, 448, 224, 1) +after zeroes have been resolved), +.I LIBHASHSUM_KECCAK_256 +(if +.I (ratebits, capbits, hashbits, squeezes) +have the values (1088, 512, 256, 1) +after zeroes have been resolved), +.I LIBHASHSUM_KECCAK_384 +(if +.I (ratebits, capbits, hashbits, squeezes) +have the values (832, 768, 384, 1) +after zeroes have been resolved), +.I LIBHASHSUM_KECCAK_512 +(if +.I (ratebits, capbits, hashbits, squeezes) +have the values (576, 1024, 512, 1) +after zeroes have been resolved), or +.I LIBHASHSUM_KECCAK +(otherwise). +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq Keccak-224 \(dq +if +.I hasher->algorithm +was set to +.IR LIBHASHSUM_KECCAK_224 , +.RB \(dq Keccak-256 \(dq +if +.I hasher->algorithm +was set to +.IR LIBHASHSUM_KECCAK_256 , +.RB \(dq Keccak-384 \(dq +if +.I hasher->algorithm +was set to +.IR LIBHASHSUM_KECCAK_384 , +.RB \(dq Keccak-512 \(dq +if +.I hasher->algorithm +was set to +.IR LIBHASHSUM_KECCAK_512 , +and otherwise to +.RB \(dq Keccak[r= \fIratebits\fP ,c= \fIcapbits\fP ,n= \fIhashbits\fP ] \(dq +if +.I squeezes<2 +or +.RB \(dq Keccak[r= \fIratebits\fP ,c= \fIcapbits\fP ,n= \fIhashbits\fP z= \fIsqueezes\fP ] \(dq +(if +.IR squeezes>1 ), +where +.IR ratebits , +.IR capbits , +and +.I hashbits +have their resolved non-zero values. +For the later two cases, +.I hasher->algorithm_string +will be a pointer to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size, in bytes +.RI ( ratebits/8 +unless +.IR ratebits==0 ). +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( (hashbits+7)/8 +unless +.IR hashbits==0 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_keccak_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_keccak_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +The combination of the values +.IR ratebits , +.IR capbits , +and +.I hashbits +is invalid (possibly any single value +is invalid). + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_keccak_224_hasher (3), +.BR libhashsum_init_keccak_256_hasher (3), +.BR libhashsum_init_keccak_384_hasher (3), +.BR libhashsum_init_keccak_512_hasher (3) diff --git a/libhashsum_init_md2_hasher.3 b/libhashsum_init_md2_hasher.3 new file mode 100644 index 0000000..5ec44b4 --- /dev/null +++ b/libhashsum_init_md2_hasher.3 @@ -0,0 +1,191 @@ +.TH LIBHASHSUM_INIT_MD2_HASHER 3 libhashsum +.SH NAME +libhashsum_init_md2_hasher - initialise state for MD2 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_md2_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.IR "-lhashsum" . + +.SH DESCRIPTION +The +.B libhashsum_init_md2_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function MD2, and stores +hash function information and hashing functions for MD2 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_MD2 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq MD2 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size MD2 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of MD2 hashes, in bytes +.RI ( LIBHASHSUM_MD2_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 0 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions will fail unless their +.I extra_bits +parameter for is 0. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] , +however because MD2 can only process whole bytes, +.I extra_bits +must be 0. The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is not 0. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_md2_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_md2_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +MD2 has been compromised with a theoretical attack. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_md4_hasher.3 b/libhashsum_init_md4_hasher.3 new file mode 100644 index 0000000..fba261d --- /dev/null +++ b/libhashsum_init_md4_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_MD4_HASHER 3 libhashsum +.SH NAME +libhashsum_init_md4_hasher - initialise state for MD4 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_md4_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.IR "-lhashsum" . + +.SH DESCRIPTION +The +.B libhashsum_init_md4_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function MD4, and stores +hash function information and hashing functions for MD4 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_MD4 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq MD4 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size MD4 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of MD4 hashes, in bytes +.RI ( LIBHASHSUM_MD4_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_md4_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_md4_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +MD4 has been compromised with a practical attack. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_md5_hasher.3 b/libhashsum_init_md5_hasher.3 new file mode 100644 index 0000000..be887fc --- /dev/null +++ b/libhashsum_init_md5_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_MD5_HASHER 3 libhashsum +.SH NAME +libhashsum_init_md5_hasher - initialise state for MD5 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_md5_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.IR "-lhashsum" . + +.SH DESCRIPTION +The +.B libhashsum_init_md5_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function MD5, and stores +hash function information and hashing functions for MD5 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_MD5 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq MD5 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size MD5 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of MD5 hashes, in bytes +.RI ( LIBHASHSUM_MD5_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_md5_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_md5_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +MD5 has been compromised with a practical attack. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_rawshake128_hasher.3 b/libhashsum_init_rawshake128_hasher.3 new file mode 100644 index 0000000..fdc0f1d --- /dev/null +++ b/libhashsum_init_rawshake128_hasher.3 @@ -0,0 +1,217 @@ +.TH LIBHASHSUM_INIT_RAWSHAKE128_HASHER 3 libhashsum +.SH NAME +libhashsum_init_rawshake128_hasher - initialise state for RawSHAKE128 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_rawshake128_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_rawshake128_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +RawSHAKE128 (a version of RawSHAKE), and stores hash +function information and hashing functions for +RawSHAKE128 in +.IR *hasher . +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (128 bits). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_RAWSHAKE128 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RawSHAKE128 \(dq, +or (if +.I hashbits +is neither 0 nor 128) +.RB \(dq RawSHAKE128[n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size RawSHAKE128 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of RawSHAKE128 hashes, in bytes +.RI ( LIBHASHSUM_RAWSHAKE128_HASH_SIZE +if +.I hashbits +is 0 or 128). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_rawshake128_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_rawshake128_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_rawshake_hasher (3) diff --git a/libhashsum_init_rawshake256_hasher.3 b/libhashsum_init_rawshake256_hasher.3 new file mode 100644 index 0000000..e0b1e69 --- /dev/null +++ b/libhashsum_init_rawshake256_hasher.3 @@ -0,0 +1,217 @@ +.TH LIBHASHSUM_INIT_RAWSHAKE256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_rawshake256_hasher - initialise state for RawSHAKE256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_rawshake256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_rawshake256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +RawSHAKE256 (a version of RawSHAKE), and stores hash +function information and hashing functions for +RawSHAKE256 in +.IR *hasher . +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (256 bits). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_RAWSHAKE256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RawSHAKE256 \(dq, +or (if +.I hashbits +is neither 0 nor 256) +.RB \(dq RawSHAKE256[n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size RawSHAKE256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of RawSHAKE256 hashes, in bytes +.RI ( LIBHASHSUM_RAWSHAKE256_HASH_SIZE +if +.I hashbits +is 0 or 256). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_rawshake256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_rawshake256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_rawshake_hasher (3) diff --git a/libhashsum_init_rawshake512_hasher.3 b/libhashsum_init_rawshake512_hasher.3 new file mode 100644 index 0000000..3ee9aa6 --- /dev/null +++ b/libhashsum_init_rawshake512_hasher.3 @@ -0,0 +1,217 @@ +.TH LIBHASHSUM_INIT_RAWSHAKE512_HASHER 3 libhashsum +.SH NAME +libhashsum_init_rawshake512_hasher - initialise state for RawSHAKE512 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_rawshake512_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_rawshake512_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +RawSHAKE512 (a version of RawSHAKE), and stores hash +function information and hashing functions for +RawSHAKE512 in +.IR *hasher . +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (512 bits). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_RAWSHAKE512 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RawSHAKE512 \(dq, +or (if +.I hashbits +is neither 0 nor 512) +.RB \(dq RawSHAKE512[n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size RawSHAKE512 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of RawSHAKE512 hashes, in bytes +.RI ( LIBHASHSUM_RAWSHAKE512_HASH_SIZE +if +.I hashbits +is 0 or 512). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_rawshake512_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_rawshake512_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_rawshake_hasher (3) diff --git a/libhashsum_init_rawshake_hasher.3 b/libhashsum_init_rawshake_hasher.3 new file mode 100644 index 0000000..cd2b9a0 --- /dev/null +++ b/libhashsum_init_rawshake_hasher.3 @@ -0,0 +1,249 @@ +.TH LIBHASHSUM_INIT_RAWSHAKE_HASHER 3 libhashsum +.SH NAME +libhashsum_init_rawshake_hasher - initialise state for RawSHAKE hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_rawshake_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhcapbits\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_rawshake_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +RawSHAKE, and stores hash function information and +hashing functions for RawSHAKE in +.IR *hasher . +.PP +.I hcapbits +shall be the hash functions's (the Keccak sponge's) +capacity, in bits, divided by 2, which shall be +either 128, 256, or 512. +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (which is +.IR hcapbits ). +.PP +.I hasher->algorithm +will be set to +.I LIBHASHSUM_RAWSHAKE128 +(if +.I hcapbits +is 128), +.I LIBHASHSUM_RAWSHAKE256 +(if +.I hcapbits +is 256), or +.I LIBHASHSUM_RAWSHAKE512 +(if +.I hcapbits +is 512). +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RawSHAKE \fIhcapbits\fP\(dq, +or (if +.I hashbits +is neither 0 nor +.IR hcapbits ) +.RB \(dq RawSHAKE \fIhcapbits\fP [n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( (hashbits?hashbits:hcapbits)/8 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_rawshake_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_rawshake_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hcapbits +is neither 128, 256, nor 512. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.IR "libhashsum_init_rawshake_hasher(hasher, 128, hashbits)" , +.IR "libhashsum_init_rawshake_hasher(hasher, 256, hashbits)" , +and +.I libhashsum_init_rawshake_hasher(hasher, 512, hashbits) +are equivalent to +.IR "libhashsum_init_rawshake128_hasher(hasher, hashbits)" , +.IR "libhashsum_init_rawshake256_hasher(hasher, hashbits)" , +and +.I libhashsum_init_rawshake512_hasher(hasher, hashbits) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_rawshake128_hasher (3), +.BR libhashsum_init_rawshake256_hasher (3), +.BR libhashsum_init_rawshake512_hasher (3) diff --git a/libhashsum_init_ripemd_128_hasher.3 b/libhashsum_init_ripemd_128_hasher.3 new file mode 100644 index 0000000..856fedf --- /dev/null +++ b/libhashsum_init_ripemd_128_hasher.3 @@ -0,0 +1,186 @@ +.TH LIBHASHSUM_INIT_RIPEMD_128_HASHER 3 libhashsum +.SH NAME +libhashsum_init_ripemd_128_hasher - initialise state for RIPEMD-128 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_ripemd_128_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.IR "-lhashsum" . + +.SH DESCRIPTION +The +.B libhashsum_init_ripemd_128_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function RIPEMD-128, and stores +hash function information and hashing functions for RIPEMD-128 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_RIPEMD_128 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RIPEMD-128 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size RIPEMD-128 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of RIPEMD-128 hashes, in bytes +.RI ( LIBHASHSUM_RIPEMD_128_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_ripemd_128_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_ripemd_128_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_ripemd_160_hasher.3 b/libhashsum_init_ripemd_160_hasher.3 new file mode 100644 index 0000000..94de83d --- /dev/null +++ b/libhashsum_init_ripemd_160_hasher.3 @@ -0,0 +1,186 @@ +.TH LIBHASHSUM_INIT_RIPEMD_160_HASHER 3 libhashsum +.SH NAME +libhashsum_init_ripemd_160_hasher - initialise state for RIPEMD-160 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_ripemd_160_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.IR "-lhashsum" . + +.SH DESCRIPTION +The +.B libhashsum_init_ripemd_160_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function RIPEMD-160, and stores +hash function information and hashing functions for RIPEMD-160 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_RIPEMD_160 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RIPEMD-160 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size RIPEMD-160 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of RIPEMD-160 hashes, in bytes +.RI ( LIBHASHSUM_RIPEMD_160_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_ripemd_160_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_ripemd_160_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_ripemd_256_hasher.3 b/libhashsum_init_ripemd_256_hasher.3 new file mode 100644 index 0000000..12638d8 --- /dev/null +++ b/libhashsum_init_ripemd_256_hasher.3 @@ -0,0 +1,186 @@ +.TH LIBHASHSUM_INIT_RIPEMD_256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_ripemd_256_hasher - initialise state for RIPEMD-256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_ripemd_256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.IR "-lhashsum" . + +.SH DESCRIPTION +The +.B libhashsum_init_ripemd_256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function RIPEMD-256, and stores +hash function information and hashing functions for RIPEMD-256 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_RIPEMD_256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RIPEMD-256 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size RIPEMD-256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of RIPEMD-256 hashes, in bytes +.RI ( LIBHASHSUM_RIPEMD_256_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_ripemd_256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_ripemd_256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_ripemd_320_hasher.3 b/libhashsum_init_ripemd_320_hasher.3 new file mode 100644 index 0000000..bcaf00a --- /dev/null +++ b/libhashsum_init_ripemd_320_hasher.3 @@ -0,0 +1,186 @@ +.TH LIBHASHSUM_INIT_RIPEMD_320_HASHER 3 libhashsum +.SH NAME +libhashsum_init_ripemd_320_hasher - initialise state for RIPEMD-320 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_ripemd_320_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.IR "-lhashsum" . + +.SH DESCRIPTION +The +.B libhashsum_init_ripemd_320_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function RIPEMD-320, and stores +hash function information and hashing functions for RIPEMD-320 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_RIPEMD_320 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq RIPEMD-320 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size RIPEMD-320 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of RIPEMD-320 hashes, in bytes +.RI ( LIBHASHSUM_RIPEMD_320_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_ripemd_320_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_ripemd_320_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_sha0_hasher.3 b/libhashsum_init_sha0_hasher.3 new file mode 100644 index 0000000..521f0cb --- /dev/null +++ b/libhashsum_init_sha0_hasher.3 @@ -0,0 +1,190 @@ +.TH LIBHASHSUM_INIT_SHA0_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha0_hasher - initialise state for SHA-0 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha0_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha1" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha0_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-0, and stores +hash function information and hashing functions for SHA-0 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA0 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA0 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-0 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-0 hashes, in bytes +.RI ( LIBHASHSUM_SHA0_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha0_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha0_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +SHA-0 has been compromised with a practical attack. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_sha1_hasher.3 b/libhashsum_init_sha1_hasher.3 new file mode 100644 index 0000000..4669f81 --- /dev/null +++ b/libhashsum_init_sha1_hasher.3 @@ -0,0 +1,190 @@ +.TH LIBHASHSUM_INIT_SHA1_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha1_hasher - initialise state for SHA-1 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha1_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha1" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha1_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-1, and stores +hash function information and hashing functions for SHA-1 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA1 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA1 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-1 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-1 hashes, in bytes +.RI ( LIBHASHSUM_SHA1_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha1_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha1_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +SHA-1 has been compromised with a practical attack. + +.SH SEE ALSO +.BR libhashsum (7) diff --git a/libhashsum_init_sha2_hasher.3 b/libhashsum_init_sha2_hasher.3 new file mode 100644 index 0000000..618dafc --- /dev/null +++ b/libhashsum_init_sha2_hasher.3 @@ -0,0 +1,263 @@ +.TH LIBHASHSUM_INIT_SHA2_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha2_hasher - initialise state for SHA-2 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha2_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, unsigned \fIalgobits\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha2" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha2_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-2 +and stores hash function information and hashing functions +for SHA-2 in +.IR *hasher . +.PP +.I algobits +shall be either 32 (for 32-bit family; the SHA-256 family; +which contains SHA-224 and SHA-256) or 64 (for 64-bit family; +the SHA-512 family; which contains SHA-384, SHA-512, +SHA-512/224, and SHA-512/256). +.PP +.I hashbits +shall be the hash size in bits, which shall be either +224 (for SHA-224) or 256 (for SHA-256) if +.I algobits +is 32, or +224 (for SHA-512/224), 256 (for SHA-512/256), +384 (for SHA-384), or 512 (for SHA-512) if +.I algobits +is 64. +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA_224 , +.IR LIBHASHSUM_SHA_256 , +.IR LIBHASHSUM_SHA_384 , +.IR LIBHASHSUM_SHA_512 , +.IR LIBHASHSUM_SHA_512_224 , +or +.IR LIBHASHSUM_SHA_512_256 , +depending on the values of +.I algobits +and +.IR hashbits . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA-224 \(dq, +.RB \(dq SHA-256 \(dq, +.RB \(dq SHA-384 \(dq, +.RB \(dq SHA-512 \(dq, +.RB \(dq SHA-512/224 \(dq, +or +.RB \(dq SHA-512/256 \(dq, +depending on the values of +.I algobits +and +.IR hashbits . +.PP +.I hasher->input_block_size +will be set to the block size, in bytes +.RI ( algobits*2 ). +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( hashbits/8 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha2_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha2_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B EINVAL +.I algobits +was neither 32 nor 64. +.TP +.B EINVAL +.I hashbits +was neither 224, 256, 384, nor 512. +.TP +.B EINVAL +.I algobits +was 32 but +.I hashbits +was 384 or 512. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.IR "libhashsum_init_sha2_hasher(hasher, 32, 224)" , +.IR "libhashsum_init_sha2_hasher(hasher, 32, 256)" , +.IR "libhashsum_init_sha2_hasher(hasher, 64, 384)" , +.IR "libhashsum_init_sha2_hasher(hasher, 64, 512)" , +.IR "libhashsum_init_sha2_hasher(hasher, 64, 224)" , +and +.I libhashsum_init_sha2_hasher(hasher, 64, 256) +are equivalent to +.IR libhashsum_init_sha_224_hasher(hasher) , +.IR libhashsum_init_sha_256_hasher(hasher) , +.IR libhashsum_init_sha_384_hasher(hasher) , +.IR libhashsum_init_sha_512_hasher(hasher) , +.IR libhashsum_init_sha_512_224_hasher(hasher) , +and +.I libhashsum_init_sha_512_256_hasher(hasher) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha_224_hasher (3), +.BR libhashsum_init_sha_256_hasher (3), +.BR libhashsum_init_sha_384_hasher (3), +.BR libhashsum_init_sha_512_hasher (3), +.BR libhashsum_init_sha_512_224_hasher (3), +.BR libhashsum_init_sha_512_256_hasher (3) diff --git a/libhashsum_init_sha3_224_hasher.3 b/libhashsum_init_sha3_224_hasher.3 new file mode 100644 index 0000000..b6af8cd --- /dev/null +++ b/libhashsum_init_sha3_224_hasher.3 @@ -0,0 +1,197 @@ +.TH LIBHASHSUM_INIT_SHA3_224_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha3_224_hasher - initialise state for SHA-3-224 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha3_224_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha3_224_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-3-224, +and stores hash function information and hashing functions +for SHA-3-224 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA3_224 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA3-224 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-3-224 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-3-224 hashes, in bytes +.RI ( LIBHASHSUM_SHA3_224_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha3_224_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha3_224_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha3_hasher (3) diff --git a/libhashsum_init_sha3_256_hasher.3 b/libhashsum_init_sha3_256_hasher.3 new file mode 100644 index 0000000..f26de4d --- /dev/null +++ b/libhashsum_init_sha3_256_hasher.3 @@ -0,0 +1,197 @@ +.TH LIBHASHSUM_INIT_SHA3_256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha3_256_hasher - initialise state for SHA-3-256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha3_256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha3_256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-3-256, +and stores hash function information and hashing functions +for SHA-3-256 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA3_256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA3-256 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-3-256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-3-256 hashes, in bytes +.RI ( LIBHASHSUM_SHA3_256_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha3_256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha3_256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha3_hasher (3) diff --git a/libhashsum_init_sha3_384_hasher.3 b/libhashsum_init_sha3_384_hasher.3 new file mode 100644 index 0000000..ba82490 --- /dev/null +++ b/libhashsum_init_sha3_384_hasher.3 @@ -0,0 +1,197 @@ +.TH LIBHASHSUM_INIT_SHA3_384_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha3_384_hasher - initialise state for SHA-3-384 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha3_384_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha3_384_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-3-384, +and stores hash function information and hashing functions +for SHA-3-384 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA3_384 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA3-384 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-3-384 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-3-384 hashes, in bytes +.RI ( LIBHASHSUM_SHA3_384_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha3_384_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha3_384_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha3_hasher (3) diff --git a/libhashsum_init_sha3_512_hasher.3 b/libhashsum_init_sha3_512_hasher.3 new file mode 100644 index 0000000..5155ae1 --- /dev/null +++ b/libhashsum_init_sha3_512_hasher.3 @@ -0,0 +1,197 @@ +.TH LIBHASHSUM_INIT_SHA3_512_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha3_512_hasher - initialise state for SHA-3-512 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha3_512_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha3_512_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-3-512, +and stores hash function information and hashing functions +for SHA-3-512 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA3_512 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA3-512 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-3-512 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-3-512 hashes, in bytes +.RI ( LIBHASHSUM_SHA3_512_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha3_512_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha3_512_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha3_hasher (3) diff --git a/libhashsum_init_sha3_hasher.3 b/libhashsum_init_sha3_hasher.3 new file mode 100644 index 0000000..3aa3612 --- /dev/null +++ b/libhashsum_init_sha3_hasher.3 @@ -0,0 +1,222 @@ +.TH LIBHASHSUM_INIT_SHA3_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha3_hasher - initialise state for SHA-3 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha3_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha3_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-3, +and stores hash function information and hashing functions +for SHA-3 in +.IR *hasher . +.PP +.I hashbits +shall be the hash size, in bits, which shall be either +224, 256, 384, or 512. +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA3 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA3- \fIhashbits\fP\(dq. +.PP +.I hasher->input_block_size +will be set to the block size, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( hashbits/8 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha3_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha3_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hashbits +is neither 224, 245, 384, nor 512. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.IR "libhashsum_init_sha3_hasher(hasher, 224)" , +.IR "libhashsum_init_sha3_hasher(hasher, 256)" , +.IR "libhashsum_init_sha3_hasher(hasher, 384)" , +and +.I libhashsum_init_sha3_hasher(hasher, 512) +are equivalent to +.IR libhashsum_init_sha3_224_hasher(hasher) , +.IR libhashsum_init_sha3_256_hasher(hasher) , +.IR libhashsum_init_sha3_384_hasher(hasher) , +and +.I libhashsum_init_sha3_512_hasher(hasher) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha3_224_hasher (3), +.BR libhashsum_init_sha3_256_hasher (3), +.BR libhashsum_init_sha3_384_hasher (3), +.BR libhashsum_init_sha3_512_hasher (3) diff --git a/libhashsum_init_sha_224_hasher.3 b/libhashsum_init_sha_224_hasher.3 new file mode 100644 index 0000000..6ce3e23 --- /dev/null +++ b/libhashsum_init_sha_224_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_SHA_224_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha_224_hasher - initialise state for SHA-224 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha_224_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha2" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha_224_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-224 +(a version of SHA-2), and stores hash function information +and hashing functions for SHA-224 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA_224 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA-224 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-224 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-224 hashes, in bytes +.RI ( LIBHASHSUM_SHA_224_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha_224_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha_224_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha2_hasher (3) diff --git a/libhashsum_init_sha_256_hasher.3 b/libhashsum_init_sha_256_hasher.3 new file mode 100644 index 0000000..6d8ee51 --- /dev/null +++ b/libhashsum_init_sha_256_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_SHA_256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha_256_hasher - initialise state for SHA-256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha_256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha2" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha_256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-256 +(a version of SHA-2), and stores hash function information +and hashing functions for SHA-256 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA_256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA-256 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-256 hashes, in bytes +.RI ( LIBHASHSUM_SHA_256_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha_256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha_256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha2_hasher (3) diff --git a/libhashsum_init_sha_384_hasher.3 b/libhashsum_init_sha_384_hasher.3 new file mode 100644 index 0000000..6f31e8c --- /dev/null +++ b/libhashsum_init_sha_384_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_SHA_384_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha_384_hasher - initialise state for SHA-384 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha_384_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha2" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha_384_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-384 +(a version of SHA-2), and stores hash function information +and hashing functions for SHA-384 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA_384 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA-384 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-384 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-384 hashes, in bytes +.RI ( LIBHASHSUM_SHA_384_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha_384_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha_384_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha2_hasher (3) diff --git a/libhashsum_init_sha_512_224_hasher.3 b/libhashsum_init_sha_512_224_hasher.3 new file mode 100644 index 0000000..c06d4b1 --- /dev/null +++ b/libhashsum_init_sha_512_224_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_SHA_512_224_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha_512_224_hasher - initialise state for SHA-512/224 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha_512_224_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha2" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha_512_224_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-512/224 +(a version of SHA-2), and stores hash function information +and hashing functions for SHA-512/224 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA_512_224 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA-512/224 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-512/224 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-512/224 hashes, in bytes +.RI ( LIBHASHSUM_SHA_512_224_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha_512_224_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha_512_224_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha2_hasher (3) diff --git a/libhashsum_init_sha_512_256_hasher.3 b/libhashsum_init_sha_512_256_hasher.3 new file mode 100644 index 0000000..c162484 --- /dev/null +++ b/libhashsum_init_sha_512_256_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_SHA_512_256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha_512_256_hasher - initialise state for SHA-512/256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha_512_256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha2" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha_512_256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-512/256 +(a version of SHA-2), and stores hash function information +and hashing functions for SHA-512/256 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA_512_256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA-512/256 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-512/256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-512/256 hashes, in bytes +.RI ( LIBHASHSUM_SHA_512_256_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha_512_256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha_512_256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha2_hasher (3) diff --git a/libhashsum_init_sha_512_hasher.3 b/libhashsum_init_sha_512_hasher.3 new file mode 100644 index 0000000..3c8541d --- /dev/null +++ b/libhashsum_init_sha_512_hasher.3 @@ -0,0 +1,189 @@ +.TH LIBHASHSUM_INIT_SHA_512_HASHER 3 libhashsum +.SH NAME +libhashsum_init_sha_512_hasher - initialise state for SHA-512 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_sha_512_hasher\fP(struct libhashsum_hasher *\fIhasher\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lsha2" . + +.SH DESCRIPTION +The +.B libhashsum_init_sha_512_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function SHA-512 +(a version of SHA-2), and stores hash function information +and hashing functions for SHA-512 in +.IR *hasher . +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHA_512 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHA-512 \(dq. +.PP +.I hasher->input_block_size +will be set to the block size SHA-512 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHA-512 hashes, in bytes +.RI ( LIBHASHSUM_SHA_512_HASH_SIZE ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to +.IR NULL . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_sha_512_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_sha_512_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_sha2_hasher (3) diff --git a/libhashsum_init_shake128_hasher.3 b/libhashsum_init_shake128_hasher.3 new file mode 100644 index 0000000..e69fabe --- /dev/null +++ b/libhashsum_init_shake128_hasher.3 @@ -0,0 +1,217 @@ +.TH LIBHASHSUM_INIT_SHAKE128_HASHER 3 libhashsum +.SH NAME +libhashsum_init_shake128_hasher - initialise state for SHAKE128 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_shake128_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_shake128_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +SHAKE128 (a version of SHAKE), and stores hash +function information and hashing functions for +SHAKE128 in +.IR *hasher . +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (128 bits). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHAKE128 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHAKE128 \(dq, +or (if +.I hashbits +is neither 0 nor 128) +.RB \(dq SHAKE128[n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size SHAKE128 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHAKE128 hashes, in bytes +.RI ( LIBHASHSUM_SHAKE128_HASH_SIZE +if +.I hashbits +is 0 or 128). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_shake128_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_shake128_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_shake_hasher (3) diff --git a/libhashsum_init_shake256_hasher.3 b/libhashsum_init_shake256_hasher.3 new file mode 100644 index 0000000..d9f407e --- /dev/null +++ b/libhashsum_init_shake256_hasher.3 @@ -0,0 +1,217 @@ +.TH LIBHASHSUM_INIT_SHAKE256_HASHER 3 libhashsum +.SH NAME +libhashsum_init_shake256_hasher - initialise state for SHAKE256 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_shake256_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_shake256_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +SHAKE256 (a version of SHAKE), and stores hash +function information and hashing functions for +SHAKE256 in +.IR *hasher . +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (256 bits). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHAKE256 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHAKE256 \(dq, +or (if +.I hashbits +is neither 0 nor 256) +.RB \(dq SHAKE256[n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size SHAKE256 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHAKE256 hashes, in bytes +.RI ( LIBHASHSUM_SHAKE256_HASH_SIZE +if +.I hashbits +is 0 or 256). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_shake256_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_shake256_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_shake_hasher (3) diff --git a/libhashsum_init_shake512_hasher.3 b/libhashsum_init_shake512_hasher.3 new file mode 100644 index 0000000..ba3d5b6 --- /dev/null +++ b/libhashsum_init_shake512_hasher.3 @@ -0,0 +1,217 @@ +.TH LIBHASHSUM_INIT_SHAKE512_HASHER 3 libhashsum +.SH NAME +libhashsum_init_shake512_hasher - initialise state for SHAKE512 hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_shake512_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_shake512_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +SHAKE512 (a version of SHAKE), and stores hash +function information and hashing functions for +SHAKE512 in +.IR *hasher . +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (512 bits). +.PP +.I hasher->algorithm +will be set to +.IR LIBHASHSUM_SHAKE512 . +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHAKE512 \(dq, +or (if +.I hashbits +is neither 0 nor 512) +.RB \(dq SHAKE512[n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size SHAKE512 uses, in bytes. +.PP +.I hasher->hash_size +will be set to the size of SHAKE512 hashes, in bytes +.RI ( LIBHASHSUM_SHAKE512_HASH_SIZE +if +.I hashbits +is 0 or 512). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_shake512_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_shake512_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_shake_hasher (3) diff --git a/libhashsum_init_shake_hasher.3 b/libhashsum_init_shake_hasher.3 new file mode 100644 index 0000000..e04429f --- /dev/null +++ b/libhashsum_init_shake_hasher.3 @@ -0,0 +1,249 @@ +.TH LIBHASHSUM_INIT_SHAKE_HASHER 3 libhashsum +.SH NAME +libhashsum_init_shake_hasher - initialise state for SHAKE hashing + +.SH SYNOPSIS +.nf +#include <libhashsum.h> + +\fBstruct libhashsum_hasher\fP { + enum libhashsum_algorithm \fIalgorithm\fP; + const char *\fIalgorithm_string\fP; + size_t \fIinput_block_size\fP; + size_t \fIhash_size\fP; + unsigned char *\fIhash_output\fP; + unsigned char \fIsupports_non_whole_bytes\fP; + size_t (*\fIprocess\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP); + int (*\fIfinalise_const\fP)(struct libhashsum_hasher *\fPthis\fP, const void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP); + int (*\fIfinalise\fP)(struct libhashsum_hasher *\fPthis\fP, void *\fPdata\fP, size_t \fPbytes\fP, unsigned \fPextra_bits\fP, size_t \fPsize\fP); + void (*\fIdestroy\fP)(struct libhashsum_hasher *\fPthis\fP); + union libhashsum_state { /* definition omitted */ } \fIstate\fP; +}; + +int \fBlibhashsum_init_shake_hasher\fP(struct libhashsum_hasher *\fIhasher\fP, size_t \fIhcapbits\fP, size_t \fIhashbits\fP); +.fi +.PP +Link with +.I -lhashsum +.IR "-lkeccak" . + +.SH DESCRIPTION +The +.B libhashsum_init_shake_hasher +function initialises +.I *hasher +for hashing using the cryptographic hash function +SHAKE, and stores hash function information and +hashing functions for SHAKE in +.IR *hasher . +.PP +.I hcapbits +shall be the hash functions's (the Keccak sponge's) +capacity, in bits, divided by 2, which shall be +either 128, 256, or 512. +.PP +.I hashbits +shall the hash size in bits or 0, for the default +hash size (which is +.IR hcapbits ). +.PP +.I hasher->algorithm +will be set to +.I LIBHASHSUM_SHAKE128 +(if +.I hcapbits +is 128), +.I LIBHASHSUM_SHAKE256 +(if +.I hcapbits +is 256), or +.I LIBHASHSUM_SHAKE512 +(if +.I hcapbits +is 512). +.PP +.I hasher->algorithm_string +will be set to +.RB \(dq SHAKE \fIhcapbits\fP\(dq, +or (if +.I hashbits +is neither 0 nor +.IR hcapbits ) +.RB \(dq SHAKE \fIhcapbits\fP [n= \fIhashbits\fP ] \(dq, +in which case +.I hasher->algorithm_string +will point to a buffer in +.IR hasher->state . +.PP +.I hasher->input_block_size +will be set to the block size, in bytes. +.PP +.I hasher->hash_size +will be set to the hash size, in bytes +.RI ( (hashbits?hashbits:hcapbits)/8 ). +.PP +.I hasher->hash_output +will be set to +.IR NULL . +.PP +.I hasher->supports_non_whole_bytes +will be set to 1 +to indicate that the +.I *hasher->finalise +and +.I *hasher->finalise_const +functions support non-zero values in their +.I extra_bits +parameter. +.PP +.I hasher->process +will be set to a pointer to the function to call +to feed, and process, data into the hash function. +Its parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +parameter shall be set to the buffer of data to +process, and its parameter +.I bytes +shall set to the number of bytes to process from +.IR data . +.I *hasher->process +will return the number of bytes processed, which +will be a multiple of +.IR hasher->input_block_size +no greater than +.IR bytes . +.PP +.I hasher->finalise_const +will be set to a pointer to the function to call +once the entire text being hashed has been loaded, +and to get the hash of the text. It's parameter +.I this +shall be set to +.IR hasher . +Its parameter +.I data +shall be set to the beginning of any yet unprocessed +data, and its parameter +.I bytes +shall be set to the number of bytes to process from +.IR data . +Its parameter +.I extra_bits +shall be set to the number of bits to process from +the lower bits of the incomplete byte +.IR data[bytes] . +The +.I *hasher->finalise_const +function will return 0 upon successful completion, +and set +.I hasher->hash_output +to a pointer to a buffer in +.I hasher->state +containing the binary hash of the processed data. +Otherwise, the function will return -1, and set +.I errno +to indicate the error. The function will failure +if: +.RS +.TP +.B EINVAL +.I extra_bits +is 8 or greater. +.RE +.PP +.I hasher->finalise +will be set to the pointer to a function that +is an alternative to +.I *hasher->finalise_const +that can support zero-copy provided that the +buffer input as the argument +.I data +is sufficiently large. The +.I *hasher->finalise +function may rewrite +.I data +and shall is does not safe to use for multiple +hashers (if the same text is hashed using multiple +hashers, +.I *hasher->finalise_const +must be used). The +function's parameter +.I size +shall be set to the size of the buffer +.IR data . +.I *hasher->finalise +is otherwise identical to +.IR *hasher->finalise_const . +.PP +.I hasher->destroy +will be set to a pointer to a function to to +call, with +.I hasher +as the argument, deallocate dynamically +allocated data, which may invalidate any +pointer in +.IR *hasher . +.PP +.I hasher->state +will be initialised, it shall be treated as +internal to the library's implementation, and +may change between versions. +.PP +.I hasher +must not be +.IR NULL . + +.SH RETURN VALUE +Upon successful completion, the +.B libhashsum_init_shake_hasher +function returns 0. Otherwise, +the function returns -1 and sets +.I errno +to indicate the error. If -1 +is returned, the state of +.I *hasher +is undefined. + +.SH ERRORS +The +.B libhashsum_init_shake_hasher +function fails if: +.TP +.B ENOSYS +Support was excluded at compile time. +.TP +.B ENOMEM +Insufficient memory available. +.TP +.B EINVAL +.I hcapbits +is neither 128, 256, nor 512. +.TP +.B EINVAL +.I hashbits +is too large. + +.SH HISTORY +libhashsum 1.0. + +.SH NOTES +.IR "libhashsum_init_shake_hasher(hasher, 128, hashbits)" , +.IR "libhashsum_init_shake_hasher(hasher, 256, hashbits)" , +and +.I libhashsum_init_shake_hasher(hasher, 512, hashbits) +are equivalent to +.IR "libhashsum_init_shake128_hasher(hasher, hashbits)" , +.IR "libhashsum_init_shake256_hasher(hasher, hashbits)" , +and +.I libhashsum_init_shake512_hasher(hasher, hashbits) +respectively. + +.SH SEE ALSO +.BR libhashsum (7), +.BR libhashsum_init_shake128_hasher (3), +.BR libhashsum_init_shake256_hasher (3), +.BR libhashsum_init_shake512_hasher (3) |