diff options
| -rw-r--r-- | libhashsum.h | 93 |
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); |