m + add man pages

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

1 files changed, 56 insertions, 211 deletions

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