% MHash-384 % Simple fast portable header-only hashing library
In order to use the MHash-384 library, simply include the header file in your C or C++ source code file; linking any additional library files to your program is not required.
#include "mhash_384.h"
If you source code is written in plain C, simply use the provided global functions:
/*variables*/
const uint8_t *data_ptr;
uint32_t data_len;
uint8_t result[MHASH_384_LEN];
mhash_384_t context;
/*initialization*/
mhash_384_initialize(&context);
/*input data processing*/
while(have_more_data())
{
data_ptr = fetch_next_data_chunk(&data_len);
mhash_384_update(&context, data_ptr, data_len);
}
/*finalization*/
mhash_384_finalize(&context, result);
And, if you source code is written in C++, the MHash384 class from mhash namespace is used:
/*variables*/
std::vector<uint8_t> data;
uint8_t result[MHASH_384_LEN];
/*construction*/
mhash::MHash384 instance;
/*input data processing*/
while(have_more_data())
{
data = fetch_next_data_chunk();
instance.update(data);
}
/*finalization*/
instance.finalize(result);
MHash-384 comes with a simple "standalone" command-line application. This program primarily serves as an example on how to use the MHash-384 library. However, the command-line application may also come in handy to quickly compute MHash-384 checksums (hashes) of local files. Furthermore, the MHash-384 program integrates nicely into the "pipes and filters" design pattern, by processing arbitrary inputs from the standard input stream. Computed checksums (hashes) will be written to the standard output stream, as a Hex string.
MHash-384 takes a number of optional options followed by an optional input file. If no input file is specified, or if input file is "-", input will be read from standard input stream (stdin).
mhash_384 [options] [input_file]
MHash-384 supports the following options:
-
-p,--progress
Print the total size of the input file and the percentage processed so far to stderr while hash computation is running.
If the total input size can not be determined (e.g. using pipe), the number of bytes processed so far is printed. -
-u,--upper
Output the final digest (hash) in upper case Hex letters. Default mode is lower case. -
-b,--bench
Compute performance statistics (e.g. bytes processed per second) and print them to the stderr at the end of the process. -
-v,--version
Print library version to the stdout and exit program. -
-t,--test
Run built-in self-test and exit program. Computes hashes from test vectors and compares results to reference hashes. -
-h,--help
Print help screen (man page) and exit program.
Compute MHash-384 hash of a local file:
mhash_384 C:\Images\debian-8.3.0-amd64-DVD-1.iso"
Compute MHash-384 from random bytes, passing data directly from dd via pipe:
dd if=/dev/urandom bs=100 count=1 | mhash_384
Global definitions for both, C and C++, API's.
This constant specifies the length of a MHash-384 digest (hash value) in bytes/octets. It is equal to 48UL.
A memory block (array) that is intended to hold a MHash-384 digest, e.g. the final result of the hash computation, needs to be at least MHASH_384_LEN bytes in size.
The MHash-384 library major version. Major release may change the API, so backwards compatibility is not guaranteed between different major versions.
Applications generally are written for a specific major version of the library.
The MHash-384 library minor version. Minor releases may add new features, but they do not change the API in a way that would break backwards compatibility.
Applications may require a certain minimum minor version of the library, but will work with higher minor versions too.
The MHash-384 library patch level. Patch releases may include bugfixes and optimizations, but they do not add new features or change the API.
Application code does not need to care about the patch level of the library.
All functions described in the following are reentrant, but not thread-safe. This means that multiple hash computation can be performed safely in an "interleaved" fashion, as long as each hash computation uses its own separate state variable. Also, multiple hash computation can be performed safely in "concurrent" threads, as long as each thread uses its own separate state variable. If, however, the same state variable needs to be accessed from different "concurrent" threads, then the application must serialize the function calls, e.g. by means of a mutex lock.
typedef struct mhash_384_t;
The mhash_384_t data-type is used to maintain the hash computation state. Use one instance (variable) of mhash_384_t for each ongoing hash computation. The memory for the mhash_384_t instance must be allocated/maintained by the calling application.
Note: Applications should treat this data-type as opaque, i.e. the application must not access the fields of the struct directly, because mhash_384_t may be subject to change in future library versions!
void mhash_384_initialize(mhash_384_t *const ctx);
This function is used to initialize (or to reset) the hash computation, i.e. it will set up the initial hash computation state. The application is required to call this function once for each hash computation. The function has to be called before any input data is processed!
Parameters:
mhash_384_t *ctx
Pointer to the hash computation state of typemhash_384_tthat will be initialized (reset) by this operation. The previous state will be lost!
void mhash_384_update(mhash_384_t *const ctx, const uint8_t *const input, const size_t len);
This function is used to process the next N bytes (octets) of input data. It will update the hash computation state accordingly. The application needs to call this function repeatedly, on the same state variable (mhash_384_t), until all input data has been processed.
Parameters:
-
mhash_384_t *ctx
Pointer to the hash computation state of typemhash_384_tthat will be updated by this operation. -
const uint8_t *input
Pointer to the input data to be processed by this operation. The input data needs to be located in one continuous block of memory. The given pointer specifies the base address of the input data, i.e. the address of the first byte (octet) to be processed.
Note: Formally, the input data is defined as a sequence ofuint8_t, i.e. a sequence of bytes (octets). However, any suitable byte-based input data can be processed using the proper typecast operator. -
size_t len
The length of the input data to be processed, in bytes (octets). All memory addresses in the range frominputup to and includinginput+(len-1)will be processed as input. Applications need to carefully checklento avoid buffer overruns!
This function is used to finalize the hash computation and output the final digest (hash value). Typically, the application will call this function once, after all input data has been processed.
Note: The hash computation state is treated read-only by this function. This means that the application may call the function at any time to get an "intermediate" hash of all input bytes (octets) process so far and then continue to process more input bytes (octets).
void mhash_384_finalize(const mhash_384_t *const ctx, uint8_t *const output);
-
const mhash_384_t *ctx
Pointer to the hash computation state of typemhash_384_tfrom which the final digest is computed. -
uint8_t *outputPointer to the memory block where the final digest (hash value) will be stored. This memory needs to be allocated by the calling application! The digest will be written to the memory addresses fromoutputup to and includingoutput+(MHASH_384_LEN-1).
All classes described in the following are reentrant, but not thread-safe. This means that multiple hash computation can be performed safely in an "interleaved" fashion, as long as each hash computation uses its own separate object (instance). Also, multiple hash computation can be performed safely in "concurrent" threads, as long as each thread uses its own separate object (instance). If, however, the same object (instance) needs to be accessed from different "concurrent" threads, then the application must serialize the method calls, e.g. by means of a mutex lock.
Note: The classes described in the following live in the mhash namespace. Any functions, data-types or constants in the mhash::internals namespace should be regarded opaque by the application, as those may be subject to change in future library versions!
MHash384::MHash384(void);
Constructs a new MHash384 object sets up the initial hash computation state. The application is required to use the same MHash384 object for the entire hash computation.
void MHash384::update(const uint8_t *const input, const size_t len);
This method is used to process the next N bytes (octets) of input data. It will update the hash computation state accordingly. The application needs to call this method repeatedly, on the same MHash364 instance, until all input data has been processed.
Parameters:
-
const uint8_t *input
Pointer to the input data to be processed by this operation. The input data needs to be located in one continuous block of memory. The given pointer specifies the base address of the input data, i.e. the address of the first byte (octet) to be processed.
Note: Formally, the input data is defined as a sequence ofuint8_t, i.e. a sequence of bytes (octets). However, any suitable byte-based input data can be processed using the proper typecast operator. -
size_t len
The length of the input data to be processed, in bytes (octets). All memory addresses in the range frominputup to and includinginput+(len-1)will be processed as input. Applications need to carefully checklento avoid buffer overruns!
void MHash384::update(const std::vector<uint8_t> &input, const size_t offset = 0, const size_t len = 0);
This method is used to process input a std::vector<uint8_t> as input. It will update the hash computation state accordingly. The application needs to call this method repeatedly, on the same MHash364 instance, until all input data has been processed.
Parameters:
-
const std::vector<uint8_t> &input
Reference to thestd::vector<uint8_t>object to be processed as input. By default, all bytes (octets) in the vector will be processed. Optionally, a sub-range of the vector can be selected. -
size_t offset
Optional. Specifies the zero-based index of the first vector element to be processed. By default, processing starts at index 0. -
size_t len
Optional. Specifies the number of vector elements to be processed. All elements from indexoffsetup to and including indexoffset+(len-1)will be processed. By default, the whole vector is processed.
void MHash384::update(const std::string &input, const size_t offset = 0, const size_t len = 0);
This method is used to process input a std::string as input. It will update the hash computation state accordingly. The application needs to call this method repeatedly, on the same MHash364 instance, until all input data has been processed.
Parameters:
-
const std::vector<uint8_t> &input
Reference to thestd::stringobject to be processed as input. By default, all characters (octets) in the string, excluding the terminatingNULLcharacter, will be processed. Optionally, a sub-range of the vector can be selected. -
size_t offset
Optional. Specifies the zero-based index of the first character in the string to be processed. By default, processing starts at index 0. -
size_t len
Optional. Specifies the number of character to be processed. All characters from indexoffsetup to and including indexoffset+(len-1)will be processed. By default, the whole string, excluding the terminatingNULLcharacter, is processed.
void MHash384::finalize(uint8_t *const output) const;
This method is used to finalize the hash computation and output the final digest (hash value). Typically, the application will call this method once, after all input data has been processed.
Note: The hash computation state is treated read-only by this method. This means that the application may call the method at any time to get an "intermediate" hash of all input bytes (octets) process so far and then continue to process more input bytes (octets).
Parameters:
uint8_t *outputPointer to the memory block where the final digest (hash value) will be stored. This memory needs to be allocated by the calling application! The digest will be written to the memory addresses fromoutputup to and includingoutput+(MHASH_384_LEN-1).
std::vector<uint8_t> MHash384::finalize(void) const;
This method is used to finalize the hash computation and output the final digest (hash value). Typically, the application will call this method once, after all input data has been processed.
Note: The hash computation state is treated read-only by this method. This means that the application may call the method at any time to get an "intermediate" hash of all input bytes (octets) process so far and then continue to process more input bytes (octets).
Return value:
- Returns a
std::vector<uint8_t>containing the final digest (hash value). The size of the returned vector object will be exactlyMHASH_384_LENelements (octets).
MHash-384 library should compile on any standard-compliant C/C++ compiler. In particular, the following platforms have been tested successfully:
- GNU/Linux, using GCC/G++, version 4.7 or later
- Microsoft Windows
- Microsoft C/C++ Compiler, Visual Studio 2010 or later
- MinGW, using Mingw-w64 from MSYS2 project
- Intel C/C++ Compiler, version Version 15.0 (XE 2015) or later
Copyright(c) 2016 LoRd_MuldeR <mulder2@gmx.de>, released under the MIT License.
Check http://muldersoft.com/ or http://muldersoft.sourceforge.net/ for updates!
Permission is hereby granted, free of charge, to any person obtaining a copy of this software
and associated documentation files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or
substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
https://opensource.org/licenses/MIT