-% MHash-384
+% 
+MHash-384
% Simple fast portable header-only hashing library
# Introduction
-**MHash-384** is a fast portable header-only hashing library, released under the *MIT license*. It provides a very simple "stream processing" API and produces hash values with a length of 384 bits (48 bytes).
+**MHash-384** is a fast, portable and secure *header-only* hash library, released under the *MIT license*. It provides a very simple "stream processing" API and produces hash values with a length of 384 bits (48 bytes).
-The MHash-384 library is primarily targeted for **C** and **C++** applications. It provides a "plain C" API as well as an *object-oriented* API for C++. Also, it supports many compilers (MSVC, GCC, MinGW, Intel C++, etc.) on various platforms (Windows, Linux/Unix, etc).
+The MHash-384 library has originally been written for **C** and **C++**. It provides a "plain C" API as well as an *object-oriented* C++ wrapper. It also supports many compilers (MSVC, GCC, MinGW, etc.) on various platforms (Windows, Linux, etc).
-Furthermore, **language bindings** for the MHash-384 library are provided in variety of other programming languages, including *Microsoft.NET* (C#, VB.NET, etc.), *Java*, *Python* and *Delphi*.
+Furthermore, the MHash-384 library has already been *ported* to various other programming languages. This currently includes the **Microsoft.NET** platform (C#, VB.NET, etc.), **Java**, **Delphi** (Pascal) as well as **Python**.
# Quick Start Guide
In order to use the *MHash-384* library, simply include the header file `mhash_384.h` in your *C* or *C++* source code file.
-This is the *only* file you are going to need. Being a [*header-only*](https://en.wikipedia.org/wiki/Header-only) library, MHash-384 does **not** require any additional library files to be linked to your program. **No** additional DLL files (or *shared objects*) are required at runtime.
+This is the *only* file you are going to need. Being a [*header-only*](https://en.wikipedia.org/wiki/Header-only) library, MHash-384 does **not** require any additional library files to be linked to your program. Also, **no** additional DLL files (or *shared objects*) are required at runtime.
#include <mhash_384.h>
uint8_t result[MHASH_384_LEN];
/*construction*/
- mhash::MHash384 instance;
+ mhash_384::MHash384 instance;
/*input data processing*/
- while(have_more_data())
+ while(source.have_more_data())
{
- data = fetch_next_data_chunk();
+ data = source.fetch_next_data_chunk();
instance.update(data);
}
# Command-line Usage
-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 comes with a simple "standalone" command-line application. This program primarily serves as an example on how to use the library. However, the command-line application may also come in handy to quickly compute checksums (hashes) of local files. Furthermore, the MHash-384 program integrates nicely into the "pipes and filters" design pattern, by consuming arbitrary inputs from the standard input stream and writing hash values (as Hex string) to the standard output stream.
## Synopsis
-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*).
+The MHash-384 command-line application 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`
+* **`-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`
+* **`-u`**, **`--upper`**
Output the final digest (hash) in *upper case* Hex letters. Default mode is *lower case*.
-* `-b`, `--bench`
+* **`-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`
+* **`-v`**, **`--version`**
Print library version to the *stdout* and exit program.
-* `-t`, `--test`
+* **`-t`**, **`--test`**
Run *built-in self-test* and exit program. Computes hashes from test vectors and compares results to reference hashes.
-* `-h`, `--help`
+* **`-h`**, **`--help`**
Print help screen (man page) and exit program.
## Examples
dd if=/dev/urandom bs=100 count=1 | mhash_384
+# Algoritm Description
+
+This chapter describes the MHash-384 algorithm, as designed – from the scratch – by LoRd_MuldeR <mulder2@gmx.de>.
+
+## Informal Description
+
+MHash-384 uses a table of *257* pre-computed 384-Bit words. This table is referred to as the *XOR-table*. It has been generated in such a way that each possible pair of 384-Bit words has a binary [Hamming distance](https://en.wikipedia.org/wiki/Hamming_distance) of *at least* 180 bits.
+
+The MHash-384 digest of a given input message is computed in a *stream-like* fashion. This means that we start with the "empty" (zero) hash value, we will process the given message *byte by byte*, and we will "update" the hash value for each input byte. The final hash value of a message is the hash value that results after all of its bytes have been processed.
+
+The "update" rule is defined as follows: We select the 384-Bit word from the XOR-table whose index matches the current input byte value, and we *combine* the selected 384-Bit word with the previous hash value in order to form the new (updated) hash value. If, for example, the current input byte equals `0x00`, then we select the *first* 384-Bit word from the XOR-table. If the current input byte equals `0x01`, then we select the *second* 384-Bit word from the XOR-table. And so on…
+
+In any case, the selected 384-Bit word (from the XOR-table) will be combined with the previous hash value using the binary [XOR](https://en.wikipedia.org/wiki/Exclusive_or) (exclusive OR) function. XOR'ing the previous hash value with the selected 384-Bit word will effectively *flip* a certain sub-set of its bits – depending on the current input byte value. Because the 384-Bit words in the XOR-table have a guaranteed minimum Hamming distance to each other, each possible input byte value is also guaranteed to flip a *different* subset of bits.
+
+In fact the "update" rule is slightly more complex. That's because, in each update step, the previous hash value bytes additionally will be *shuffled* (permuted). The shuffling of the hash bytes will be performed immediately *before* XOR'ing the previous hash value with the select 384-Bit word from the XOR-table. Be aware that the shuffling ensures that the *same* input bytes are going results in a *different* hash value – with very high probability – when they are processed in a different order.
+
+The shuffling procedure is implemented using the [Fisher-Yates](https://en.wikipedia.org/wiki/Fisher%E2%80%93Yates_shuffle) "in-place" shuffle algorithm. For this purpose, MHash-384 uses a table of *997* pre-computed permutations. This table is referred to as the *MIX-table*. Each of its rows (permutations) contains 48 Fisher-Yates shuffling indices, as required to shuffle the 48 hash bytes. The MIX-table has been generated in such a way, that each of the *997* permutations "moves" the elements (hash bytes) to different positions than all other permutations.
+
+We use a counter that keeps track of the MIX-table row (permutation). The counter's value equals the zero-based index of the MIX-table row which is to be applied in the *next* update step. It is initialized to *zero* at the beginning, and it will be increased by one after each update step. After the *last* MIX-table row (i.e. index *996*) the counter will wrap around to index *zero* again.
+
+Last but not least, the computation of the MHash-384 digest is *finalized* by XOR'ing the current hash value with the very last 384-Bit word of the XOR-table. This 384-Bit word has index 256 and therefore can *never* be selected by any input byte value.
+
+## Pseudocode
+
+The MHash-384 algorithm can be summed up with the following simple pseudocode:
+
+ procedure mhash384
+ const:
+ HASH_SIZE = 48
+ TABLE_XOR: array[257 × HASH_SIZE] of byte
+ TABLE_MIX: array[997 × HASH_SIZE] of byte
+ input:
+ message: array[N] of byte
+ output:
+ hash: array[HASH_SIZE] of byte
+ vars:
+ round: integer
+ begin
+ /*initialization*/
+ round ← 0
+ for i = 0 to HASH_SIZE-1 do
+ hash[i] ← 0x00
+ done
+
+ /*input message processing*/
+ for k = 0 to N-1 do
+ for i = 0 to HASH_SIZE-1 do
+ exchange hash[i] ⇄ hash[TABLE_MIX[round][i]]
+ hash[i] ← hash[i] ⊕ TABLE_XOR[message[k]][i]
+ done
+ round ← (round + 1) mod 997
+ done
+
+ /*finalization*/
+ for i = 0 to HASH_SIZE-1 do
+ hash[i] ← hash[i] ⊕ TABLE_XOR[256][i]
+ done
+ end.
+
+
# Detailed API Specification
Global definitions for both, C and C++, API's.
### Prerequisites
-It is highly recommended to install the MHash-384 library into Python's [`site-packages`](https://docs.python.org/3.5/install/#how-installation-works) directory. For this purpose, create a new sub-directory `mhash` inside the `site-packages` directory. Then copy `mhash.pth` directly to the `site-packages` directory, so *site* will include the new sub-directory. Also, copy both modules, `MHashPy384_Wrapper.py` *and* `MHashPy384_Native.pyd`, to the `site-packages\mhash` sub-directory. The former module contains the `MHash384` convenience class, the latter module contains the "native" MHash-384 functions.
+It is highly recommended to install the MHash-384 library into Python's [`site-packages`](https://docs.python.org/3.5/install/#how-installation-works) directory. For this purpose, create a new sub-directory `mhash` inside the `site-packages` directory. Then copy `mhash.pth` directly to the `site-packages` directory, so *site* will include the new sub-directory. Also, copy both modules, `MHashPy384_Wrapper.py` *and* `MHashPy384_Native.{pyd,so}`, to the `site-packages\mhash` sub-directory. The former module contains the `MHash384` convenience class, the latter module contains the "native" MHash-384 functions.
-***Note:*** The *32-Bit* (x86) version of Python can only work with the `MHashPy384_Native.x86.pyd` module, and the *64-Bit* (x64) version of Python can only work with the `MHashPy384_Native.x64.pyd` module. In any case, the file **must** be renamed to just `MHashPy384_Native.pyd`!
+***Note #1:*** The *32-Bit* (x86) version of Python can only work with the `MHashPy384_Native.x86` module, and the *64-Bit* (x64) version of Python can only work with the `MHashPy384_Native.x64` module.
+
+***Note #2:*** In any case, the "native" module **must** be renamed to just `MHashPy384_Native.pyd` or `MHashPy384_Native.so` when running on the Windows or Linux platform, respectively. Otherwise Python will *not* be able to locate the module!
## Delphi
* `git clone https://github.com/lordmulder/mhash-384.git` [[Browse](https://github.com/lordmulder/mhash-384)]
-* `git clone https://bitbucket.org/lord_mulder/mhash-384.git` [[Browse](https://bitbucket.org/lord_mulder/mhash-384)]
+* `git clone https://bitbucket.org/muldersoft/mhash-384.git` [[Browse](https://bitbucket.org/muldersoft/mhash-384)]
* `git clone https://git.assembla.com/mhash-384.git` [[Browse](https://www.assembla.com/spaces/mhash-384/git/source)]
* Finally, for the *GNU/Linux* and *MinGW/MSYS2* platforms, the MHash-384 library provides a Makefile (tested with GNU Make). Just run `make` from the MHash-384 directory.
+## Influential Environment Variables
+
+The following environment variables may effect the build process and need to be set carefully:
+
+* **Java:**
+ - `JAVA_HOME`: The *Java* "home" directory, should be pointing to JDK (*not* JRE) root directory
+ - `ANT_HOME`: The *Apache Ant* "home" directory, should be pointing to root directory
+
+* **Python:**
+ - `PYTHON_INC`: Directory to look for Python *include* files (typically `<PYTHON_INSTALL_PATH>/include`)
+ - `PYTHON_LIB32`: Directory to look for 32-Bit (x86) Python *library* files (typically `<PYTHON_X86_PATH>/libs`)
+ - `PYTHON_LIB64`: Directory to look for 64-Bit (x64) Python *library* files (typically `<PYTHON_X64_PATH>/libs`)
+
+* **Delphi:**
+ - `DELPHI_PATH`: The *Borland Delphi* installation directory (for Windows only)
+
+* **Makefile:**
+ - `CPU_TYPE`: Optimize binaries for the specified CPU type (defaults to "native"), see [`-march`](https://gcc.gnu.org/onlinedocs/gcc/x86-Options.html#x86-Options) for details!
+ - `CPLUSPLUS`: If set to `1`, build CLI front-end from *C++* sources, otherwise from *plain C* sources (defaults to `0`)
+ - `NO_JAVA`: If set to `1`, the *Java* bindings are **not** built (defaults to `0`, i.e. *do* build)
+ - `NO_PYTHON`: If set to `1`, the *Python* bindings are **not** built (defaults to `0`, i.e. *do* build)
+
+* **Windows:**
+ - `MSVC_PATH`: *Microsoft Visual C++* installation directory
+ - `PDOC_PATH`: *Pandoc v2.x* installation directory
+ - `GIT2_PATH`: *Git for Windows* (formerly *MSYS Git*) installation directory
+
# License
-**Copyright(c) 2016 LoRd_MuldeR <mulder2@gmx.de>, released under the MIT License.**
+**Copyright(c) 2016-2017 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
<https://opensource.org/licenses/MIT>
+
+# Version History
+
+## Version 1.1.0 [2017-07-??]
+
+* Re-generated the XOR- and MIX-tables with higher hamming distance for increased hash quality
+
+* ***Note:*** This change, unfortunately, breaks compatibility with v1.0 hashes!
+
+* All language bindings have been *replaced* by full ports of the library to the respective language
+
+## Version 1.0.1 [2016-03-31]
+
+* Added language bindings for *Java*.
+
+* Added language bindings for *Microsoft.NET*.
+
+* Added language bindings for *Python*.
+
+* Added language bindings for *Delphi*.
+
+## Version 1.0.0 [2016-03-03]
+
+* First public release.
+
[■](https://www.youtube.com/watch?v=dng06ZqI4Ss)
OSDN Git Service
