diff options
Diffstat (limited to 'Utilities/cmlibrhash/librhash/rhash.h')
| -rw-r--r-- | Utilities/cmlibrhash/librhash/rhash.h | 393 |
1 files changed, 312 insertions, 81 deletions
diff --git a/Utilities/cmlibrhash/librhash/rhash.h b/Utilities/cmlibrhash/librhash/rhash.h index cee0e253e4..f596509705 100644 --- a/Utilities/cmlibrhash/librhash/rhash.h +++ b/Utilities/cmlibrhash/librhash/rhash.h @@ -9,7 +9,9 @@ extern "C" { #endif #ifndef RHASH_API -/* modifier for LibRHash functions */ +/** + * Modifier for LibRHash functions + */ # define RHASH_API #endif @@ -32,11 +34,11 @@ enum rhash_ids RHASH_AICH = 0x100, RHASH_WHIRLPOOL = 0x200, RHASH_RIPEMD160 = 0x400, - RHASH_GOST = 0x800, - RHASH_GOST_CRYPTOPRO = 0x1000, - RHASH_HAS160 = 0x2000, - RHASH_SNEFRU128 = 0x4000, - RHASH_SNEFRU256 = 0x8000, + RHASH_GOST94 = 0x800, + RHASH_GOST94_CRYPTOPRO = 0x1000, + RHASH_HAS160 = 0x2000, + RHASH_GOST12_256 = 0x4000, + RHASH_GOST12_512 = 0x8000, RHASH_SHA224 = 0x10000, RHASH_SHA256 = 0x20000, RHASH_SHA384 = 0x40000, @@ -47,18 +49,28 @@ enum rhash_ids RHASH_SHA3_256 = 0x0800000, RHASH_SHA3_384 = 0x1000000, RHASH_SHA3_512 = 0x2000000, + RHASH_CRC32C = 0x4000000, + RHASH_SNEFRU128 = 0x8000000, + RHASH_SNEFRU256 = 0x10000000, - /** The bit-mask containing all supported hashe functions */ - RHASH_ALL_HASHES = RHASH_CRC32 | RHASH_MD4 | RHASH_MD5 | RHASH_ED2K | RHASH_SHA1 | - RHASH_TIGER | RHASH_TTH | RHASH_GOST | RHASH_GOST_CRYPTOPRO | + /** + * The bit-mask containing all supported hashe functions. + */ + RHASH_ALL_HASHES = RHASH_CRC32 | RHASH_CRC32C | RHASH_MD4 | RHASH_MD5 | + RHASH_ED2K | RHASH_SHA1 |RHASH_TIGER | RHASH_TTH | + RHASH_GOST94 | RHASH_GOST94_CRYPTOPRO | RHASH_GOST12_256 | RHASH_GOST12_512 | RHASH_BTIH | RHASH_AICH | RHASH_WHIRLPOOL | RHASH_RIPEMD160 | RHASH_HAS160 | RHASH_SNEFRU128 | RHASH_SNEFRU256 | RHASH_SHA224 | RHASH_SHA256 | RHASH_SHA384 | RHASH_SHA512 | RHASH_SHA3_224 | RHASH_SHA3_256 | RHASH_SHA3_384 | RHASH_SHA3_512 | RHASH_EDONR256 | RHASH_EDONR512, - /** The number of supported hash functions */ - RHASH_HASH_COUNT = 26 + RHASH_GOST = RHASH_GOST94, /* deprecated constant name */ + RHASH_GOST_CRYPTOPRO = RHASH_GOST94_CRYPTOPRO, /* deprecated constant name */ + /** + * The number of supported hash functions. + */ + RHASH_HASH_COUNT = 29 #else RHASH_MD5 = 0x01, RHASH_SHA1 = 0x02, @@ -86,15 +98,17 @@ enum rhash_ids }; /** - * The rhash context structure contains contexts for several hash functions + * The rhash context structure contains contexts for several hash functions. */ typedef struct rhash_context { - /** The size of the hashed message */ + /** + * The size of the hashed message. + */ unsigned long long msg_size; /** - * The bit-mask containing identifiers of the hashes being calculated + * The bit-mask containing identifiers of the hashes being calculated. */ unsigned hash_id; } rhash_context; @@ -107,109 +121,285 @@ typedef struct rhash_context typedef struct rhash_context* rhash; #endif /* LIBRHASH_RHASH_CTX_DEFINED */ -/** type of a callback to be called periodically while hashing a file */ +/** + * Type of a callback to be called periodically while hashing a file. + */ typedef void (*rhash_callback_t)(void* data, unsigned long long offset); -RHASH_API void rhash_library_init(void); /* initialize static data */ +/** + * Initialize static data of rhash algorithms + */ +RHASH_API void rhash_library_init(void); -/* hi-level hashing functions */ + +/* HIGH-LEVEL LIBRHASH INTERFACE */ + +/** + * Compute a hash of the given message. + * + * @param hash_id id of hash sum to compute + * @param message the message to process + * @param length message length + * @param result buffer to receive binary hash string + * @return 0 on success, -1 on error + */ RHASH_API int rhash_msg(unsigned hash_id, const void* message, size_t length, unsigned char* result); + +/** + * Compute a single hash for given file. + * + * @param hash_id id of hash sum to compute + * @param filepath path to the file to hash + * @param result buffer to receive hash value with the lowest requested id + * @return 0 on success, -1 on error and errno is set + */ RHASH_API int rhash_file(unsigned hash_id, const char* filepath, unsigned char* result); -RHASH_API int rhash_file_update(rhash ctx, FILE* fd); -#ifdef _WIN32 /* windows only function */ +#ifdef _WIN32 +/** + * Compute a single hash for given file (Windows-specific function). + * + * @param hash_id id of hash sum to compute + * @param filepath path to the file to hash + * @param result buffer to receive hash value with the lowest requested id + * @return 0 on success, -1 on error, -1 on error and errno is set + */ RHASH_API int rhash_wfile(unsigned hash_id, const wchar_t* filepath, unsigned char* result); #endif -/* lo-level interface */ + +/* LOW-LEVEL LIBRHASH INTERFACE */ + +/** + * Allocate and initialize RHash context for calculating hash(es). + * After initializing rhash_update()/rhash_final() functions should be used. + * Then the context must be freed by calling rhash_free(). + * + * @param hash_id union of bit flags, containing ids of hashes to calculate. + * @return initialized rhash context, NULL on error and errno is set + */ RHASH_API rhash rhash_init(unsigned hash_id); -/*RHASH_API rhash rhash_init_by_ids(unsigned hash_ids[], unsigned count);*/ -RHASH_API int rhash_update(rhash ctx, const void* message, size_t length); -RHASH_API int rhash_final(rhash ctx, unsigned char* first_result); -RHASH_API void rhash_reset(rhash ctx); /* reinitialize the context */ + +/** + * Calculate hashes of message. + * Can be called repeatedly with chunks of the message to be hashed. + * + * @param ctx the rhash context + * @param message message chunk + * @param length length of the message chunk + * @return 0 on success; On fail return -1 and set errno + */ +RHASH_API int rhash_update(rhash ctx, const void* message, size_t length); + +/** + * Hash a file or stream. Multiple hashes can be computed. + * First, inintialize ctx parameter with rhash_init() before calling + * rhash_file_update(). Then use rhash_final() and rhash_print() + * to retrive hash values. Finaly call rhash_free() on ctx + * to free allocated memory or call rhash_reset() to reuse ctx. + * + * @param ctx rhash context + * @param fd descriptor of the file to hash + * @return 0 on success, -1 on error and errno is set + */ +RHASH_API int rhash_file_update(rhash ctx, FILE* fd); + +/** + * Finalize hash calculation and optionally store the first hash. + * + * @param ctx the rhash context + * @param first_result optional buffer to store a calculated hash with the lowest available id + * @return 0 on success; On fail return -1 and set errno + */ +RHASH_API int rhash_final(rhash ctx, unsigned char* first_result); + +/** + * Re-initialize RHash context to reuse it. + * Useful to speed up processing of many small messages. + * + * @param ctx context to reinitialize + */ +RHASH_API void rhash_reset(rhash ctx); + +/** + * Free RHash context memory. + * + * @param ctx the context to free. + */ RHASH_API void rhash_free(rhash ctx); -/* additional lo-level functions */ +/** + * Set the callback function to be called from the + * rhash_file() and rhash_file_update() functions + * on processing every file block. The file block + * size is set internally by rhash and now is 8 KiB. + * + * @param ctx rhash context + * @param callback pointer to the callback function + * @param callback_data pointer to data passed to the callback + */ RHASH_API void rhash_set_callback(rhash ctx, rhash_callback_t callback, void* callback_data); -/** bit-flag: default hash output format is base32 */ -#define RHASH_INFO_BASE32 1 + +/* INFORMATION FUNCTIONS */ /** - * Information about a hash function. + * Returns the number of supported hash algorithms. + * + * @return the number of supported hash functions */ -typedef struct rhash_info -{ - /** hash function indentifier */ - unsigned hash_id; - /** flags bit-mask, including RHASH_INFO_BASE32 bit */ - unsigned flags; - /** size of binary message digest in bytes */ - size_t digest_size; - const char* name; - const char* magnet_name; -} rhash_info; - -/* information functions */ RHASH_API int rhash_count(void); /* number of supported hashes */ + +/** + * Returns size of binary digest for given hash algorithm. + * + * @param hash_id the id of hash algorithm + * @return digest size in bytes + */ RHASH_API int rhash_get_digest_size(unsigned hash_id); /* size of binary message digest */ + +/** + * Returns length of digest hash string in default output format. + * + * @param hash_id the id of hash algorithm + * @return the length of hash string + */ RHASH_API int rhash_get_hash_length(unsigned hash_id); /* length of formatted hash string */ + +/** + * Detect default digest output format for given hash algorithm. + * + * @param hash_id the id of hash algorithm + * @return 1 for base32 format, 0 for hexadecimal + */ RHASH_API int rhash_is_base32(unsigned hash_id); /* default digest output format */ + +/** + * Returns a name of given hash algorithm. + * + * @param hash_id the id of hash algorithm + * @return algorithm name + */ RHASH_API const char* rhash_get_name(unsigned hash_id); /* get hash function name */ + +/** + * Returns a name part of magnet urn of the given hash algorithm. + * Such magnet_name is used to generate a magnet link of the form + * urn:<magnet_name>=<hash_value>. + * + * @param hash_id the id of hash algorithm + * @return name + */ RHASH_API const char* rhash_get_magnet_name(unsigned hash_id); /* get name part of magnet urn */ -/* note, that rhash_info_by_id() is not exported to a shared library or DLL */ -const rhash_info* rhash_info_by_id(unsigned hash_id); /* get hash sum info by hash id */ +/* HASH SUM OUTPUT INTERFACE */ #if 0 /** - * Flags for printing a hash sum + * Flags for printing a hash sum. */ enum rhash_print_sum_flags { - /** print in a default format */ + /* + * Print in a default format + */ RHPR_DEFAULT = 0x0, - /** output as binary message digest */ + /* + * Output as binary message digest + */ RHPR_RAW = 0x1, - /** print as a hexadecimal string */ + /* + * Print as a hexadecimal string + */ RHPR_HEX = 0x2, - /** print as a base32-encoded string */ + /* + * Print as a base32-encoded string + */ RHPR_BASE32 = 0x3, - /** print as a base64-encoded string */ + /* + * Print as a base64-encoded string + */ RHPR_BASE64 = 0x4, - - /** + /* * Print as an uppercase string. Can be used * for base32 or hexadecimal format only. */ RHPR_UPPERCASE = 0x8, - - /** + /* * Reverse hash bytes. Can be used for GOST hash. */ RHPR_REVERSE = 0x10, - - /** don't print 'magnet:?' prefix in rhash_print_magnet */ + /* + * Don't print 'magnet:?' prefix in rhash_print_magnet + */ RHPR_NO_MAGNET = 0x20, - /** print file size in rhash_print_magnet */ + /* + * Print file size in rhash_print_magnet + */ RHPR_FILESIZE = 0x40, + /* + * Print as URL-encoded string + */ + RHPR_URLENCODE = 0x80 }; #endif -/* output hash into the given buffer */ + +/** + * Print a text presentation of a given hash sum to the specified buffer. + * + * @param output a buffer to print the hash to + * @param bytes a hash sum to print + * @param size a size of hash sum in bytes + * @param flags a bit-mask controlling how to format the hash sum, + * can be a mix of the flags: RHPR_RAW, RHPR_HEX, RHPR_BASE32, + * RHPR_BASE64, RHPR_URLENCODE, RHPR_UPPERCASE, RHPR_REVERSE + * @return the number of written characters + */ RHASH_API size_t rhash_print_bytes(char* output, const unsigned char* bytes, size_t size, int flags); +/** + * Print text presentation of a hash sum with given hash_id to the specified + * output buffer. If the hash_id is zero, then print the hash sum with + * the lowest id stored in the hash context. + * The function call fails if the context doesn't include a hash with the + * given hash_id. + * + * @param output a buffer to print the hash to + * @param context algorithms state + * @param hash_id id of the hash sum to print or 0 to print the first hash + * saved in the context. + * @param flags a bitmask controlling how to print the hash. Can contain flags + * RHPR_UPPERCASE, RHPR_HEX, RHPR_BASE32, RHPR_BASE64, etc. + * @return the number of written characters on success or 0 on fail + */ RHASH_API size_t rhash_print(char* output, rhash ctx, unsigned hash_id, int flags); -/* output magnet URL into the given buffer */ +/** + * Print magnet link with given filepath and calculated hash sums into the + * output buffer. The hash_mask can limit which hash values will be printed. + * The function returns the size of the required buffer. + * If output is NULL the . + * + * @param output a string buffer to receive the magnet link or NULL + * @param filepath the file path to be printed or NULL + * @param context algorithms state + * @param hash_mask bit mask of the hash sums to add to the link + * @param flags can be combination of bits RHPR_UPPERCASE, RHPR_NO_MAGNET, + * RHPR_FILESIZE + * @return number of written characters, including terminating '\0' on success, 0 on fail + */ RHASH_API size_t rhash_print_magnet(char* output, const char* filepath, rhash context, unsigned hash_mask, int flags); -/* macros for message API */ -/** The type of an unsigned integer large enough to hold a pointer */ +/* MESSAGE API */ + +/** + * The type of an unsigned integer large enough to hold a pointer. + */ #if defined(UINTPTR_MAX) typedef uintptr_t rhash_uptr_t; #elif defined(_LP64) || defined(__LP64__) || defined(__x86_64) || \ @@ -219,14 +409,28 @@ typedef unsigned long long rhash_uptr_t; typedef unsigned long rhash_uptr_t; #endif -/** The value returned by rhash_transmit on error */ +/** + * The value returned by rhash_transmit on error. + */ #define RHASH_ERROR ((rhash_uptr_t)-1) -/** Convert a pointer to rhash_uptr_t */ +/** + * Convert a pointer to rhash_uptr_t. + */ #define RHASH_STR2UPTR(str) ((rhash_uptr_t)(char*)(str)) -/** Convert a rhash_uptr_t to a void* pointer */ -#define RHASH_UPTR2PVOID(u) ((void*)((char*)0 + (u))) +/** + * Convert a rhash_uptr_t to a void* pointer. + */ +#define RHASH_UPTR2PVOID(u) ((void*)((u) + 0)) -/* rhash API to set/get data via messages */ +/** + * Process a rhash message. + * + * @param msg_id message identifier + * @param dst message destination (can be NULL for generic messages) + * @param ldata data depending on message + * @param rdata data depending on message + * @return message-specific data + */ RHASH_API rhash_uptr_t rhash_transmit( unsigned msg_id, void* dst, rhash_uptr_t ldata, rhash_uptr_t rdata); @@ -239,22 +443,32 @@ RHASH_API rhash_uptr_t rhash_transmit( #define RMSG_SET_AUTOFINAL 5 #define RMSG_SET_OPENSSL_MASK 10 #define RMSG_GET_OPENSSL_MASK 11 +#define RMSG_GET_OPENSSL_SUPPORTED_MASK 12 +#define RMSG_GET_OPENSSL_AVAILABLE_MASK 13 -/* helper macros */ +/* HELPER MACROS */ -/** Get a pointer to context of the specified hash function */ +/** + * Get a pointer to context of the specified hash function. + */ #define rhash_get_context_ptr(ctx, hash_id) RHASH_UPTR2PVOID(rhash_transmit(RMSG_GET_CONTEXT, ctx, hash_id, 0)) -/** Cancel hash calculation of a file */ +/** + * Cancel hash calculation of a file. + */ #define rhash_cancel(ctx) rhash_transmit(RMSG_CANCEL, ctx, 0, 0) -/** Return non-zero if hash calculation was canceled, zero otherwise */ +/** + * Return non-zero if hash calculation was canceled, zero otherwise. + */ #define rhash_is_canceled(ctx) rhash_transmit(RMSG_IS_CANCELED, ctx, 0, 0) -/** Return non-zero if rhash_final was called for rhash_context */ +/** + * Return non-zero if rhash_final was called for rhash_context. + */ #define rhash_get_finalized(ctx) rhash_transmit(RMSG_GET_FINALIZED, ctx, 0, 0) /** * Turn on/off the auto-final flag for the given rhash_context. By default * auto-final is on, which means rhash_final is called automatically, if - * needed when a hash value is retrived by rhash_print call. + * needed when a hash value is retrieved by rhash_print call. */ #define rhash_set_autofinal(ctx, on) rhash_transmit(RMSG_SET_AUTOFINAL, ctx, on, 0) @@ -267,19 +481,36 @@ RHASH_API rhash_uptr_t rhash_transmit( #define rhash_set_openssl_mask(mask) rhash_transmit(RMSG_SET_OPENSSL_MASK, NULL, mask, 0) /** - * Return current bit-mask of hash algorithms selected to be calculated - * by OpenSSL library. + * Return current bit-mask of hash algorithms selected to be calculated by OpenSSL + * library. Return RHASH_ERROR if LibRHash is compiled without OpenSSL support. */ #define rhash_get_openssl_mask() rhash_transmit(RMSG_GET_OPENSSL_MASK, NULL, 0, 0) -/** The bit mask of hash algorithms implemented by OpenSSL */ -#if defined(USE_OPENSSL) || defined(OPENSSL_RUNTIME) -# define RHASH_OPENSSL_SUPPORTED_HASHES (RHASH_MD4 | RHASH_MD5 | \ - RHASH_SHA1 | RHASH_SHA224 | RHASH_SHA256 | RHASH_SHA384 | \ - RHASH_SHA512 | RHASH_RIPEMD160 | RHASH_WHIRLPOOL) -#else -# define RHASH_OPENSSL_SUPPORTED_HASHES 0 -#endif +/** + * Return the bit-mask of algorithms that can be provided by the OpenSSL plugin, + * if the library is compiled with OpenSSL support, 0 otherwise. This bit-mask is + * a constant value computed at compile-time. + */ +#define rhash_get_openssl_supported_mask() rhash_transmit(RMSG_GET_OPENSSL_SUPPORTED_MASK, NULL, 0, 0) + +/** + * Return the bit-mask of algorithms that are successfully loaded from + * OpenSSL library. If the library is not loaded or not supported by LibRHash, + * then return 0. + */ +#define rhash_get_openssl_available_mask() rhash_transmit(RMSG_GET_OPENSSL_AVAILABLE_MASK, NULL, 0, 0) + + +/** + * Return non-zero if LibRHash hash been compiled with OpenSSL support, + * and zero otherwise. + */ +#define rhash_is_openssl_supported() (rhash_get_openssl_mask() != RHASH_ERROR) + +/** + * Legacy macro. The bit mask of hash algorithms implemented by OpenSSL. + */ +# define RHASH_OPENSSL_SUPPORTED_HASHES (rhash_get_openssl_supported_mask()) #ifdef __cplusplus } /* extern "C" */ |