aboutsummaryrefslogtreecommitdiffstats
path: root/libhashsum.h
diff options
context:
space:
mode:
authorMattias Andrée <maandree@kth.se>2024-08-24 00:16:14 +0200
committerMattias Andrée <maandree@kth.se>2024-08-24 00:19:57 +0200
commitc0c939c21cece2f7ddf7e9310a3fe1d80bd8e7cf (patch)
tree390b864208354b6476e49a4c2828062eedc36f03 /libhashsum.h
parentSilence some clang warnings (diff)
downloadlibhashsum-c0c939c21cece2f7ddf7e9310a3fe1d80bd8e7cf.tar.gz
libhashsum-c0c939c21cece2f7ddf7e9310a3fe1d80bd8e7cf.tar.bz2
libhashsum-c0c939c21cece2f7ddf7e9310a3fe1d80bd8e7cf.tar.xz
Document when things were introduced
Also mention when an algorithm has been compromised Signed-off-by: Mattias Andrée <maandree@kth.se>
Diffstat (limited to '')
-rw-r--r--libhashsum.h93
1 files changed, 90 insertions, 3 deletions
diff --git a/libhashsum.h b/libhashsum.h
index 8bf38c7..5fb71cf 100644
--- a/libhashsum.h
+++ b/libhashsum.h
@@ -20,17 +20,20 @@
/**
* Hashing algorithm
+ *
+ * @since 1.0
*/
enum libhashsum_algorithm {
+ /* since 1.0 */
LIBHASHSUM_MD2, /**< MD2 */
LIBHASHSUM_MD4, /**< MD4 */
- LIBHASHSUM_MD5, /**< MD5 */
+ 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 */
- LIBHASHSUM_SHA1, /**< SHA1 */
+ 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) */
@@ -42,76 +45,106 @@ enum libhashsum_algorithm {
/**
* 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
@@ -218,21 +251,29 @@ union libhashsum_state {
/**
* Message hash functions and state
+ *
+ * @since 1.0
*/
struct libhashsum_hasher {
/**
* The used hash algorithm
+ *
+ * @since 1.0
*/
enum libhashsum_algorithm algorithm;
/**
* 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;
@@ -244,11 +285,15 @@ struct libhashsum_hasher {
* 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;
@@ -260,6 +305,8 @@ struct libhashsum_hasher {
* @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);
@@ -276,6 +323,8 @@ struct libhashsum_hasher {
*
* @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);
@@ -294,6 +343,8 @@ struct libhashsum_hasher {
*
* @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);
@@ -302,6 +353,8 @@ struct libhashsum_hasher {
* The hash state
*
* For internal use
+ *
+ * @since 1.0
*/
union libhashsum_state state;
};
@@ -316,6 +369,8 @@ struct libhashsum_hasher {
* @return 0 on success, -1 on failure
*
* @throws EINVAL `algorithm` is unsupported
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algorithm algorithm);
@@ -328,6 +383,8 @@ int libhashsum_init_hasher(struct libhashsum_hasher *this, enum libhashsum_algor
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_md2_hasher(struct libhashsum_hasher *this);
@@ -340,6 +397,8 @@ int libhashsum_init_md2_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_md4_hasher(struct libhashsum_hasher *this);
@@ -352,6 +411,8 @@ int libhashsum_init_md4_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_md5_hasher(struct libhashsum_hasher *this);
@@ -364,6 +425,8 @@ int libhashsum_init_md5_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_ripemd_128_hasher(struct libhashsum_hasher *this);
@@ -376,6 +439,8 @@ int libhashsum_init_ripemd_128_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_ripemd_160_hasher(struct libhashsum_hasher *this);
@@ -388,6 +453,8 @@ int libhashsum_init_ripemd_160_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_ripemd_256_hasher(struct libhashsum_hasher *this);
@@ -400,6 +467,8 @@ int libhashsum_init_ripemd_256_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_ripemd_320_hasher(struct libhashsum_hasher *this);
@@ -412,6 +481,8 @@ int libhashsum_init_ripemd_320_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha0_hasher(struct libhashsum_hasher *this);
@@ -424,6 +495,8 @@ int libhashsum_init_sha0_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha1_hasher(struct libhashsum_hasher *this);
@@ -436,6 +509,8 @@ int libhashsum_init_sha1_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha_224_hasher(struct libhashsum_hasher *this);
@@ -448,6 +523,8 @@ int libhashsum_init_sha_224_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha_256_hasher(struct libhashsum_hasher *this);
@@ -460,6 +537,8 @@ int libhashsum_init_sha_256_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha_384_hasher(struct libhashsum_hasher *this);
@@ -472,6 +551,8 @@ int libhashsum_init_sha_384_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha_512_hasher(struct libhashsum_hasher *this);
@@ -484,6 +565,8 @@ int libhashsum_init_sha_512_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha_512_224_hasher(struct libhashsum_hasher *this);
@@ -496,6 +579,8 @@ int libhashsum_init_sha_512_224_hasher(struct libhashsum_hasher *this);
* @return 0 on success, -1 on failure
*
* Failure isn't actually possible, so this function always return 0
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha_512_256_hasher(struct libhashsum_hasher *this);
@@ -513,6 +598,8 @@ int libhashsum_init_sha_512_256_hasher(struct libhashsum_hasher *this);
* @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)
+ *
+ * @since 1.0
*/
LIBHASHSUM_1_NONNULL_
int libhashsum_init_sha2_hasher(struct libhashsum_hasher *this, unsigned algobits, size_t hashbits);