Add support for Keccak, SHA3, SHAKE, and RawSHAKE via libkeccak>=1.3 (this version introduced zerocopy)

Signed-off-by: Mattias Andrée <maandree@kth.se>

1 files changed, 466 insertions, 19 deletions

diff --git a/libhashsum.h b/libhashsum.h
index 67f27b4..e7050c1 100644
--- a/libhashsum.h
+++ b/libhashsum.h
@@ -5,8 +5,15 @@
 #include <stddef.h>
 #include <stdint.h>
 
-#include <libsha1.h>
-#include <libsha2.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
 
 
 #if defined(__GNUC__)
@@ -27,21 +34,36 @@
  */
 enum libhashsum_algorithm {
 	/* since 1.0 */
-	LIBHASHSUM_MD2,         /**< MD2 */
-	LIBHASHSUM_MD4,         /**< MD4 */
-	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_MD2,          /**< MD2 */
+	LIBHASHSUM_MD4,          /**< MD4 */
+	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 */
 };
 
 
@@ -150,6 +172,104 @@ enum libhashsum_algorithm {
  */
 #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_SHAKE_128`
+ * 
+ * @since  1.0
+ */
+#define LIBHASHSUM_SHAKE_128_HASH_SIZE 28
+
+/**
+ * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHAKE_256`
+ * 
+ * @since  1.0
+ */
+#define LIBHASHSUM_SHAKE_256_HASH_SIZE 32
+
+/**
+ * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_SHAKE_512`
+ * 
+ * @since  1.0
+ */
+#define LIBHASHSUM_SHAKE_512_HASH_SIZE 64
+
+/**
+ * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RAWSHAKE_128`
+ * 
+ * @since  1.0
+ */
+#define LIBHASHSUM_RAWSHAKE_128_HASH_SIZE 28
+
+/**
+ * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RAWSHAKE_256`
+ * 
+ * @since  1.0
+ */
+#define LIBHASHSUM_RAWSHAKE_256_HASH_SIZE 32
+
+/**
+ * The value of `struct libhashsum_hasher.hash_size` for `LIBHASHSUM_RAWSHAKE_512`
+ * 
+ * @since  1.0
+ */
+#define LIBHASHSUM_RAWSHAKE_512_HASH_SIZE 64
+
 
 /**
  * Hash state
@@ -239,17 +359,32 @@ union libhashsum_state {
 		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;
+		char algostr[256];
+	} keccak; /* size = [1020, 1065] */
+#endif
 
-	/* libkeccak: size = [248, 288] */
 	/* libblake: size = 56(s), 112(b), 48(2s), 96(2b), 144(2Xs), 276(2Xb) */
 
 	char max_size[1648];
@@ -384,6 +519,18 @@ struct libhashsum_hasher {
 	int (*finalise)(struct libhashsum_hasher *this, void *data, size_t bytes, unsigned extra_bits, size_t size);
 
 	/**
+	 * 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
@@ -405,7 +552,7 @@ struct libhashsum_hasher {
  * @throws  EINVAL  `algorithm` is not recognised
  * @throws  EINVAL  `algorithm` requires parameters, and is therefore
  *                  not supported by this function (use dedicated
- *                  initialiser instead)
+ *                  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
@@ -413,6 +560,7 @@ struct libhashsum_hasher {
  *                  (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
  */
@@ -435,6 +583,7 @@ int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algor
  *                  (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
  */
@@ -671,5 +820,303 @@ int libhashsum_init_sha_512_256_hasher(struct libhashsum_hasher *this);
 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
+ * @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);
+
+/**
+ * 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);
+
 
 #endif