/* See LICENSE file for copyright and license details. */ #ifndef LIBHASHSUM_H #define LIBHASHSUM_H #include #if defined(__GNUC__) # define LIBHASHSUM_USERET_ __attribute__((__warn_unused_result__)) # define LIBHASHSUM_1_NONNULL_ __attribute__((__nonnull__(1))) # define LIBHASHSUM_NONNULL_ __attribute__((__nonnull__)) # define LIBHASHSUM_PURE_ __attribute__((__pure__)) #else # define LIBHASHSUM_USERET_ # define LIBHASHSUM_1_NONNULL_ # define LIBHASHSUM_NONNULL_ # define LIBHASHSUM_PURE_ #endif /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_MD2` * * @since 1.0 */ #define LIBHASHSUM_MD2_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_MD4` * * @since 1.0 */ #define LIBHASHSUM_MD4_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_MD5` * * @since 1.0 */ #define LIBHASHSUM_MD5_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_128` * * @since 1.0 */ #define LIBHASHSUM_RIPEMD_128_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_160` * * @since 1.0 */ #define LIBHASHSUM_RIPEMD_160_HASH_SIZE 20 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_256` * * @since 1.0 */ #define LIBHASHSUM_RIPEMD_256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RIPEMD_320` * * @since 1.0 */ #define LIBHASHSUM_RIPEMD_320_HASH_SIZE 40 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA0` * * @since 1.0 */ #define LIBHASHSUM_SHA0_HASH_SIZE 20 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA1` * * @since 1.0 */ #define LIBHASHSUM_SHA1_HASH_SIZE 20 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_224` * * @since 1.0 */ #define LIBHASHSUM_SHA_224_HASH_SIZE 28 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_256` * * @since 1.0 */ #define LIBHASHSUM_SHA_256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_384` * * @since 1.0 */ #define LIBHASHSUM_SHA_384_HASH_SIZE 48 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_512` * * @since 1.0 */ #define LIBHASHSUM_SHA_512_HASH_SIZE 64 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_512_224` * * @since 1.0 */ #define LIBHASHSUM_SHA_512_224_HASH_SIZE 28 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA_512_256` * * @since 1.0 */ #define LIBHASHSUM_SHA_512_256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA3_224` * * @since 1.0 */ #define LIBHASHSUM_KECCAK_224_HASH_SIZE 28 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_KECCAK_256` * * @since 1.0 */ #define LIBHASHSUM_KECCAK_256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_KECCAK_384` * * @since 1.0 */ #define LIBHASHSUM_KECCAK_384_HASH_SIZE 48 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_KECCAK_512` * * @since 1.0 */ #define LIBHASHSUM_KECCAK_512_HASH_SIZE 64 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA3_224` * * @since 1.0 */ #define LIBHASHSUM_SHA3_224_HASH_SIZE 28 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA3_256` * * @since 1.0 */ #define LIBHASHSUM_SHA3_256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA3_384` * * @since 1.0 */ #define LIBHASHSUM_SHA3_384_HASH_SIZE 48 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHA3_512` * * @since 1.0 */ #define LIBHASHSUM_SHA3_512_HASH_SIZE 64 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHAKE128` * * @since 1.0 */ #define LIBHASHSUM_SHAKE128_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHAKE256` * (using default hash size) * * @since 1.0 */ #define LIBHASHSUM_SHAKE256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHAKE512` * (using default hash size) * * @since 1.0 */ #define LIBHASHSUM_SHAKE512_HASH_SIZE 64 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RAWSHAKE128` * (using default hash size) * * @since 1.0 */ #define LIBHASHSUM_RAWSHAKE128_HASH_SIZE 16 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RAWSHAKE256` * (using default hash size) * * @since 1.0 */ #define LIBHASHSUM_RAWSHAKE256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RAWSHAKE512` * (using default hash size) * * @since 1.0 */ #define LIBHASHSUM_RAWSHAKE512_HASH_SIZE 64 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_BLAKE224` * * @since 1.0 */ #define LIBHASHSUM_BLAKE224_HASH_SIZE 28 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_BLAKE256` * * @since 1.0 */ #define LIBHASHSUM_BLAKE256_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_BLAKE384` * * @since 1.0 */ #define LIBHASHSUM_BLAKE384_HASH_SIZE 48 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_BLAKE512` * * @since 1.0 */ #define LIBHASHSUM_BLAKE512_HASH_SIZE 64 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_BLAKE2S` * (using default/maximium hash size) * * @since 1.0 */ #define LIBHASHSUM_BLAKE2S_HASH_SIZE 32 /** * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_BLAKE2B` * (using default/maximium hash size) * * @since 1.0 */ #define LIBHASHSUM_BLAKE2B_HASH_SIZE 64 #if defined(__GNUC__) # pragma GCC diagnostic push # pragma GCC diagnostic ignored "-Wpadded" #endif #include "libhashsum/internal.h" /** * 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) */ LIBHASHSUM_BLAKE2S, /**< BLAKE2s (BLAKE2) */ LIBHASHSUM_BLAKE2B /**< BLAKE2b (BLAKE2) */ }; /** * Which bits in non-whole octets are used * * @since 1.0 */ enum { /* since 1.0 */ LIBHASHSUM_UNSUPPORTED = 0, /**< Non-whole octets are unsupport */ LIBHASHSUM_LEAST_SIGNIFICANT = 1, /**< The least significant bits of a non-whole octet are used */ LIBHASHSUM_MOST_SIGNIFICANT = 2 /**< The most significant bits of a non-whole octet are used */ }; /** * Message hash functions and state * * @since 1.0, 1.1 */ struct libhashsum_hasher { /** * The used hash algorithm * * @since 1.0 */ enum libhashsum_algorithm algorithm; /** * A string describing the used hash * algorithm and parameters * * This may be pointer to a buffer in * `.state` * * @since 1.0 */ const char *algorithm_string; /** * The number of bytes required for each * call to `.process_block` * * @since 1.0 */ size_t input_block_size; /** * The number of bytes in the resulting hash * * @since 1.0 */ size_t hash_size; /** * The hash * * This will be set to `NULL` when the structure * is initialised, but will be set to a pointer * to a buffer inside `.state` once `.finalise_const` * or `.finalise` has been called with successful * completion * * @since 1.0 */ unsigned char *hash_output; /** * Whether the algorithm supports non-whole octet input * * @since 1.0 */ unsigned char supports_non_whole_bytes; /** * libhashsum always uses the least significant bits of * a non-whole octet, however every hash function that * supports non-whole input octets specify their own standard * for how non-whole octet are encoded. This field will be * set to specify the standard used for the hash function. * * If this field is set to `LIBHASHSUM_UNSUPPORTED`, * `.supports_non_whole_bytes` will be 0, and non-whole * input bytes are unsupported. * * If this field is set to `LIBHASHSUM_LEAST_SIGNIFICANT`, * `.supports_non_whole_bytes` will be 1, and the standard * used by the hash function is the same as in libhashsum * (the least significant bits are used), and no conversion * between the hash function's standard and libhashsum's * standard is required for input messages. * * If this field is set to `LIBHASHSUM_MOST_SIGNIFICANT`, * `.supports_non_whole_bytes` will be 1, and the standard * used by the hash function is the opposite of libhashsum's * standard, thus if you have reference input message with * a partial final byte (where the most significant bits are * used, and the least significant bits are discarded), you * have to reverse the bits in the last octet before * inputing it to `*.finalise` or `*.finalise_const`. * * If you are creating your own message, you always store * the used bits, in a non-whole octet, in the least * significant part of the octet, when inputing it to * `*.finalise` or `*.finalise_const`. * * @since 1.0 */ unsigned char standard_partial_byte_input_encoding; /* TODO test */ /** * libhashsum always uses the least significant bits of * a non-while octet, however every hash function that * supports non-whole output octets specify their own standard * for how non-whole octets are encoded. This field will be * set to specify the standard used for the hash function. * * If this field is set to `LIBHASHSUM_UNSUPPORTED`, non-whole * output bytees are unsupported. * * If this field is set to `LIBHASHSUM_LEAST_SIGNIFICANT`, * the standard used by the hash function is the same as in * libhashsum (the least significant bits are used), and no * conversion between the hash function's standard and * libhashsum's standard is required for hashes. * * If this field is set to `LIBHASHSUM_MOST_SIGNIFICANT`, * the standard used by the hash function is the opposite of * libhashsum's standard, thus if you have reference hash * with a partial final byte (where the most significant bits * are used, and the least significant bits are unused), you * have to reverse the bits in the last octet before comparing * the reference hash with the output of `*.finalise` and * `*.finalise_const`. * * The text above assumes that the hash function's standard * is to always clear unused bits; this is also always done * by `*.finalise` and `*.finalise_const`. * * @since 1.0 */ unsigned char standard_partial_byte_output_encoding; /* TODO test */ /** * The size of the hash is rounded up to whole octet in * `.hash_size`, in the case that the hash size is not * a while number of octets, the returned hash will be * padded, on the most significant part of the last byte, * with cleared bits. This fields specifies the number * of pad bits, which is always 0 if for hash functions * that only support whole octet hash sizes (most of them; * when `.standard_partial_byte_output_encoding` is set * to `LIBHASHSUM_UNSUPPORTED`) * * @since 1.1 */ unsigned char hash_excess_bits; /* TODO test */ /** * Update the hash state given additional * input data * * @param this The object containing this function pointer * @param data The new input data * @param bytes The number of bytes available in `data` * @return The number of bytes processed from `data` * * @since 1.0 */ LIBHASHSUM_USERET_ LIBHASHSUM_1_NONNULL_ size_t (*process)(struct libhashsum_hasher *this, const void *data, size_t bytes); /** * Update the hash state given its final * input data * * Regardless of the algorithm's standard, the function * will takes the lower bits from `data[bytes]`, if * `extra_bits > 0` and use the for the additional bits; * the least significant bit will be used as the first * bit and the most significant bit will be used as the * last bit * * `this->hash_output` will be set to point to a buffer * in `this->state` containing the hash * * @param this The object containing this function pointer * @param data The new input data * @param bytes The number of bytes available in `data` for reading * @param extra_bits Additional bits in `data` not covered by `bytes` * @return 0 on success, -1 on failure * * @throws EINVAL `extra_bits` is greater than 7 * @throws EINVAL `extra_bits` is non-zero but `.supports_non_whole_bytes` is 0 * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int (*finalise_const)(struct libhashsum_hasher *this, const void *data, size_t bytes, unsigned extra_bits); /** * Update the hash state given it's final * input data * * Regardless of the algorithm's standard, the function * will takes the lower bits from `data[bytes]`, if * `extra_bits > 0` and use the for the additional bits; * the least significant bit will be used as the first * bit and the most significant bit will be used as the * last bit * * `this->hash_output` will be set to point to a buffer * in `this->state` containing the hash. However if * `this->hash_output` is already non-`NULL`, the function * _may_ choose to immediately output to the buffer that * `this->hash_output` pointers to (the application must * make sure it is sufficiently large). * * @param this The object containing this function pointer * @param data The new input data, the function may rewrite its content * @param bytes The number of bytes available in `data` for reading * @param extra_bits Additional bits in `data` not covered by `bytes` * @param size `bytes` plus any number of additional bytes available * for the function to write additional data block padding * @return 0 on success, -1 on failure * * @throws EINVAL `extra_bits` is greater than 7 * @throws EINVAL `extra_bits` is non-zero but `.supports_non_whole_bytes` is 0 * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int (*finalise)(struct libhashsum_hasher *this, void *data, size_t bytes, unsigned extra_bits, size_t size); /** * Extend the hash with an additional `this->hash_size` bytes * * This pointer will be set to `NULL` when the object initialised, * but once `*.finalise` or `*.finalise_const` is called, it * will be set a point to a function _if_ the algorithm supports * extending the hash indefinitely (if there is a limit, this * pointer will be set to `NULL` once the limit has been reached) * * If the hash function supports generating hashes before the * entire file has been processed, this pointer be non-`NULL` * immediately when the object is initialised, however the * hash function does not support extending the hash, calling * this function, `*.finalise`, or `*.finalise_const` will * reset this pointer to `NULL`. (No currently supported hash * function supports this behaviour.) * * `this->hash_output` will be set to point to a buffer * in `this->state` containing the hash extent. Note that * this overrides any hash previously generated for `this`. * * @param this The object containing this function pointer * @param skip Non-zero if the function need not set * `this->hash_output` and output the hash extent * (note that the function may ignore this argument) * @param buffer If non-`NULL`, the function _may_ choose output the * hash extent to the provided buffer (the application * must ensure it is sufficently large). If the function * does output to the provided buffer, it will reset * `this->hash_output` to `NULL`. * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ void (*stretch)(struct libhashsum_hasher *this, int skip, void *buffer); /** * Unless this pointer its `NULL`, it points to * function that shall be once the object (`this`) * is not needed anymore * * @param this The object containing this function pointer * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ void (*destroy)(struct libhashsum_hasher *this); /** * The hash state * * For internal use * * @since 1.0 */ union libhashsum_state state; }; /** * Keccak hash function parameters * for `libhashsum_init_keccak_hasher2` * * @since 1.1 */ struct libhashsum_keccak_params { /** * The bitrate, 0 for automatic * * This must be a multiple of 8 */ size_t ratebits; /** * The sponge capacity in bits, 0 for automatic * * This must be a multiple of 8 */ size_t capbits; /** * The hash size in bits, 0 for automatic */ size_t hashbits; /** * The state size in bits, 0 for automatic * * This must be 0 or `25 * .wordbits`, it must * also be 0 or `.ratebits + .capbits`, however * if `.ratebits` or `.capbits` is 0, this value * must be less than non-zero value (if both * are 0, only the "0 or `25 * .wordbits`" * restriction apply) */ size_t statebits; /** * The word size in bits, 0 for automatic * * This must be a multiple of 8 and a power of 2, * currently supported value are (apart from 0): '* 8, 16, 32, and 64 */ size_t wordbits; /** * The number of squeezes to performed, * 0 for automatic (which is 1) */ size_t squeezes; }; #if defined(__GNUC__) # pragma GCC diagnostic pop #endif /** * Create an initialised state for a hash algorithm * and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param algorithm The hashing algorithm * @return 0 on success, -1 on failure * * @throws EINVAL `algorithm` is not recognised * @throws EINVAL `algorithm` requires parameters, and is therefore * not supported by this function (use dedicated * initialiser instead). (`algorithm` is `LIBHASHSUM_KECCAK`) * @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 * is however linked to new enough version of the library) * (specifically this means that the application's version * of `union libhashsum_state`, and thus also * `struct libhashsum_hasher`, is too small to store the state) * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algorithm algorithm); /** * Inspect a hashing algorithm string to identify * which algorithm it references * * @param algorithm_out Output parameter for the hashing algorithm * identifier (set if 1 is returned) * @param algorithm The hashing algorithm as a string * @return 1 if the algorithm was recognised, 0 otherwise * * @since 1.0 */ LIBHASHSUM_NONNULL_ int libhashsum_get_algorithm_from_string(enum libhashsum_algorithm *algorithm_out, const char *algorithm); /** * Create an initialised state for a hash algorithm * and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param algorithm The hashing algorithm and parameters * @return 0 on success, -1 on failure * * @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 * is however linked to new enough version of the library) * (specifically this means that the application's version * of `union libhashsum_state`, and thus also * `struct libhashsum_hasher`, is too small to store the state) * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_NONNULL_ int libhashsum_init_hasher_from_string(struct libhashsum_hasher *this, const char *algorithm); /** * Get an estimate, approximate performance relative, * to some unspecified reference point, for a configured * hash function * * Higher is faster * * @param this The hash function details * @return Estimate, approximate performance value, * 0 no estimate is available * * @since 1.1 */ LIBHASHSUM_NONNULL_ LIBHASHSUM_PURE_ uint64_t libhashsum_get_relative_performance(struct libhashsum_hasher *this); /* TODO test */ /** * Create an initialised state for MD2 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_md2_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for MD4 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_md4_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for MD5 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_md5_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for RIPEMD-128 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_ripemd_128_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for RIPEMD-160 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_ripemd_160_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for RIPEMD-256 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_ripemd_256_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for RIPEMD-320 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ 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 * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha0_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA1 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha1_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA-224 (SHA2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha_224_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA-256 (SHA2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha_256_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA-384 (SHA2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha_384_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA-512 (SHA2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha_512_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA-512/224 (SHA2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha_512_224_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA-512/256 (SHA2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha_512_256_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA2 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param algobits 32 for a 32-bit algorithm, 64 for a 64-bit algorithm * @param hashbits Hash output size in bits * @return 0 on success, -1 on failure * * @throws EINVAL `algobits` is invalid (neither 32 nor 64) * @throws EINVAL `hashbits` is invalid (neither 224, 256, 384, nor 512) * @throws EINVAL The combination of `algobits` and `hashbits` is invalid * (`hashbits` is 384 or 512 but `algobits` is 32) * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha2_hasher(struct libhashsum_hasher *this, unsigned algobits, size_t hashbits); /** * Create an initialised state for Keccak-224 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_keccak_224_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for Keccak-256 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_keccak_256_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for Keccak-384 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_keccak_384_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for Keccak-512 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_keccak_512_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for Keccak * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param ratebits Bitrate (in bits), 0 for automatic * @param capbits Capacity in bits, 0 for automatic * @param hashbits Hash output size in bits, 0 for automatic * @param squeezes The number of squeezes to performed, 0 for automatic (which is 1) * @return 0 on success, -1 on failure * * @throws EINVAL (`ratebits`, `capbits`, `hashbits`) is invalid * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_keccak_hasher(struct libhashsum_hasher *this, size_t ratebits, size_t capbits, size_t hashbits, size_t squeezes); /** * Create an initialised state for Keccak * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param param Hash function parameters * @return 0 on success, -1 on failure * * @throws EINVAL `*params` is invalid * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.1 */ LIBHASHSUM_NONNULL_ int libhashsum_init_keccak_hasher2(struct libhashsum_hasher *this, const struct libhashsum_keccak_params *params); /* TODO test */ /** * Create an initialised state for SHA3-224 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha3_224_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA3-256 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha3_256_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA3-384 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha3_384_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA3-512 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha3_512_hasher(struct libhashsum_hasher *this); /** * Create an initialised state for SHA3 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is invalid (neither 224, 256, 384, nor 512) * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_sha3_hasher(struct libhashsum_hasher *this, size_t hashbits); /** * Create an initialised state for SHAKE128 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, if 0, 128 is used * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_shake128_hasher(struct libhashsum_hasher *this, size_t hashbits); /** * Create an initialised state for SHAKE256 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, if 0, 256 is used * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_shake256_hasher(struct libhashsum_hasher *this, size_t hashbits); /** * Create an initialised state for SHAKE512 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, if 0, 512 is used * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_shake512_hasher(struct libhashsum_hasher *this, size_t hashbits); /** * Create an initialised state for SHAKE * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hcapbits Half of the capacity, in bits (this is the * value added behind the function name) * @param hashbits Hash output size in bits, if 0, `hcapbits` is used * @return 0 on success, -1 on failure * * @throws EINVAL `hcapbits` is invalid (neither 128, 256, nor 512) * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_shake_hasher(struct libhashsum_hasher *this, size_t hcapbits, size_t hashbits); /** * Create an initialised state for RawSHAKE128 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, if 0, 128 is used * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_rawshake128_hasher(struct libhashsum_hasher *this, size_t hashbits); /** * Create an initialised state for RawSHAKE256 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, if 0, 256 is used * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_rawshake256_hasher(struct libhashsum_hasher *this, size_t hashbits); /** * Create an initialised state for RawSHAKE512 * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, if 0, 512 is used * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_rawshake512_hasher(struct libhashsum_hasher *this, size_t hashbits); /** * Create an initialised state for RawSHAKE * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hcapbits Half of the capacity, in bits (this is the * value added behind the function name) * @param hashbits Hash output size in bits, if 0, `hcapbits` is used * @return 0 on success, -1 on failure * * @throws EINVAL `hcapbits` is invalid (neither 128, 256, nor 512) * @throws EINVAL `hashbits` is too large * @throws ENOSYS Support was excluded at compile time * @throws ENOMEM Not enough memory available * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_rawshake_hasher(struct libhashsum_hasher *this, size_t hcapbits, size_t hashbits); /** * Create an initialised state for BLAKE224 (BLAKE, BLAKEs) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param salt `NULL` (for all zeroes) or a 16-byte salt * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blake224_hasher(struct libhashsum_hasher *this, const void *salt); /** * Create an initialised state for BLAKE256 (BLAKE, BLAKEs) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param salt `NULL` (for all zeroes) or a 16-byte salt * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blake256_hasher(struct libhashsum_hasher *this, const void *salt); /** * Create an initialised state for BLAKEs (BLAKE) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits * @param salt `NULL` (for all zeroes) or a 16-byte salt * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is invalid (neither 224 nor 256) * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blakes_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt); /** * Create an initialised state for BLAKE384 (BLAKE, BLAKEb) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param salt `NULL` (for all zeroes) or a 32-byte salt * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blake384_hasher(struct libhashsum_hasher *this, const void *salt); /** * Create an initialised state for BLAKE512 (BLAKE, BLAKEb) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param salt `NULL` (for all zeroes) or a 32-byte salt * @return 0 on success, -1 on failure * * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blake512_hasher(struct libhashsum_hasher *this, const void *salt); /** * Create an initialised state for BLAKEb (BLAKE) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits * @param salt `NULL` (for all zeroes) or a 32-byte salt * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is invalid (neither 384 nor 512) * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blakeb_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt); /** * Create an initialised state for BLAKE * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits * @param salt `NULL` (for all zeroes) or a salt * @param saltbytes The number of bytes in `salt` (ignored if `salt` is `NULL`), * shall be 16 for if `hashbits` is 224 or 256, and 32 if * `hashbits` is 384 or 512 * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is invalid (neither 224, 256, 384, nor 512) * @throws EINVAL `salt` is not `NULL` but `saltbytes` does not match * the expected value for the input `hashbits` * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blake_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, size_t saltbytes); /** * Create an initialised state for BLAKE2s (BLAKE2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, must be an multiple of 8 between * 8 and 256 (inclusively), or 0 for the maximum size * @param salt `NULL` (for all zeroes) or a 8-byte salt * @param pepper `NULL` (for all zeroes) or a 8-byte pepper * @param key Key or `NULL` for unkeyed mode, * @param keybits The number of byts in `key` (0 if `key` is `NULL`), * which must be a multiple of 8 no greater than 256 * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is greater than 256 * @throws EINVAL `hashbits` is not a multiple of 8 * @throws EINVAL `keybits` is greater than 256 * @throws EINVAL `keybits` is not a multiple of 8 * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blake2s_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, const void *pepper, const void *key, size_t keybits); /** * Create an initialised state for BLAKE2b (BLAKE2) * hashing and return hash functions and details * * @param this The output parameter for the functions, details, and state * @param hashbits Hash output size in bits, must be an multiple of 8 between * 8 and 512 (inclusively), or 0 for the maximum size * @param salt `NULL` (for all zeroes) or a 16-byte salt * @param pepper `NULL` (for all zeroes) or a 16-byte pepper * @param key Key or `NULL` for unkeyed mode, * @param keybits The number of byts in `key` (0 if `key` is `NULL`), * which must be a multiple of 8 no greater than 512 * @return 0 on success, -1 on failure * * @throws EINVAL `hashbits` is greater than 512 * @throws EINVAL `hashbits` is not a multiple of 8 * @throws EINVAL `keybits` is greater than 512 * @throws EINVAL `keybits` is not a multiple of 8 * @throws ENOSYS Support was excluded at compile time * * @since 1.0 */ LIBHASHSUM_1_NONNULL_ int libhashsum_init_blake2b_hasher(struct libhashsum_hasher *this, size_t hashbits, const void *salt, const void *pepper, const void *key, size_t keybits); #endif