README.md

   1 % ![](img/mhash/MHash-384.jpg)
   2 MHash-384
   3 % Simple fast portable header-only hashing library
   4
   5 # Introduction
   6
   7 **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).
   8
   9 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).
  10
  11 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**.
  12
  13
  14 # Quick Start Guide
  15
  16 In order to use the *MHash-384* library, simply include the header file `mhash_384.h` in your *C* or *C++* source code file.
  17
  18 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.
  19
  20         #include <mhash_384.h>
  21
  22 ## Example for C language
  23
  24 If you source code is written in plain **C**, simply use the provided *global* functions:
  25
  26         /*variables*/
  27         const uint8_t *data_ptr;
  28         uint32_t data_len;
  29         uint8_t result[MHASH_384_LEN];
  30         mhash_384_t context;
  31
  32         /*initialization*/
  33         mhash_384_initialize(&context);
  34
  35         /*input data processing*/
  36         while(have_more_data())
  37         {
  38                 data_ptr = fetch_next_data_chunk(&data_len);
  39                 mhash_384_update(&context, data_ptr, data_len);
  40         }
  41
  42         /*finalization*/
  43         mhash_384_finalize(&context, result);
  44
  45 ## Example for C++ language
  46
  47 And, if you source code is written in **C++**, the *MHash384* class from *mhash* namespace is used:
  48
  49         /*variables*/
  50         std::vector<uint8_t> data;
  51         uint8_t result[MHASH_384_LEN];
  52
  53         /*construction*/
  54         mhash_384::MHash384 instance;
  55
  56         /*input data processing*/
  57         while(source.have_more_data())
  58         {
  59                 data = source.fetch_next_data_chunk();
  60                 instance.update(data);
  61         }
  62
  63         /*finalization*/
  64         instance.finalize(result);
  65
  66
  67 # Command-line Usage
  68
  69 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.
  70
  71 ## Synopsis
  72
  73 The MHash-384 command-line application takes a number of optional options followed by an one or more input files.
  74
  75 If **no** input file is specified, input will be read from standard input (*stdin*).
  76
  77 The digest will be written to the standard output (*stdout*). Diagnostic message are written to the standard error (*stderr*).
  78
  79         mhash_384 [options] [file_1] [file_2] ... [file_n]
  80
  81 ## Options
  82
  83 MHash-384 supports the following options:
  84
  85 * **`-p`**, **`--progress`**
  86   Print the total size of the input file and the percentage processed so far to *stderr* while hash computation is running.
  87   If the total input size can **not** be determined (e.g. using pipe), the number of bytes processed so far is printed.
  88
  89 * **`-u`**, **`--upper`**
  90   Output the final digest (hash) in *upper case* Hex letters. Default mode is *lower case*.
  91
  92 * **`-c`**, **`--curly`**
  93   Output the final digest (hash) using C-style curly brackets. Also each byte will be written as a separate Hex value.
  94
  95 * **`-r`**, **`--raw`**
  96   Output the final digest (hash) as "raw" bytes. Default mode converts the final digest (hash) to a Hex string.
  97   *Note:* This is incompatible with the `-u` (`--upper`) and `-c` (`--curly`) options!
  98
  99 * **`-b`**, **`--bench`**
 100   Compute performance statistics (bytes processed per second) and print them to the *stderr* at the end of the process.
 101
 102 * **`-i`**, **`--ignore`**
 103   Ignore errors. Proceeds with the *next* file when an error is encountered. Default behavior stops immediately on errors.
 104   *Note:* This option only has a noteworthy effect, if *multiple* input files have been given!
 105
 106 * **`-v`**, **`--version`**
 107   Print library version to the *stdout* and exit program. Format is: `mhash-384 version X.Y.Z (built MMM DD YYYY)`
 108
 109 * **`-t`**, **`--test`**
 110   Run *built-in self-test* and exit program. Computes hashes from test vectors and compares results to reference hashes.
 111
 112 * **`-h`**, **`--help`**
 113   Print help screen (man page) and exit program.
 114
 115 ## Output Format
 116
 117 On completion, the computed digest (hash value) will be written to the standard output (*stdout*).
 118
 119 The digest will be printed in lower-case hexadecimal notation, by default. Options `-u` and `-c` can influence the format.
 120
 121 If *multiple* files have been given, the hash value of each files is printed in a separate line, followed by the file name.
 122
 123 With the `-r` option specified, hash values will be written to standard output (*stdout*) as "raw" bytes &ndash; 48 bytes per hash.
 124
 125 ## Exit Code
 126
 127 On success, *zero* is returned. On error or user interruption, a *non-zero* error code is returned.
 128
 129 ## Examples
 130
 131 Compute MHash-384 hash of a single local file:
 132
 133         mhash_384 "C:\Images\debian-8.3.0-amd64-DVD-1.iso"
 134
 135 Compute MHash-384 hash of *two* files:
 136
 137         mhash_384 "C:\Images\debian-8.3.0-amd64-DVD-1.iso" "C:\Images\debian-8.3.0-i386-DVD-1.iso"
 138
 139 Compute MHash-384 hash of *multiple* files, using wildcard expansion ([globbing](https://en.wikipedia.org/wiki/Glob_(programming))):
 140
 141         mhash_384 "C:\Images\*.iso"
 142
 143 Compute MHash-384 hash of a file, with more verbose status outputs:
 144
 145         mhash_384 -p -b "C:\Images\debian-8.3.0-amd64-DVD-1.iso"
 146
 147 Compute MHash-384 from random bytes, passing data directly from [**`dd`**](https://en.wikipedia.org/wiki/Dd_%28Unix%29) via [pipeline](https://en.wikipedia.org/wiki/Pipeline_(Unix)):
 148
 149         dd if=/dev/urandom bs=100 count=1 | mhash_384
 150
 151
 152 # Algoritm Description
 153
 154 This chapter describes the of the MHash-384 algorithm, which is a novel design (from the scratch), in full detail.
 155
 156 ## Informal Description
 157
 158 We start with an informal description of the MHash-384 algorithm, which also explains the design goals:
 159
 160 ### The XOR table
 161
 162 MHash-384 uses a table of *257* pre-computed 384-Bit (48-byte) 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 [Hamming distance](https://en.wikipedia.org/wiki/Hamming_distance) of *at least* 182 bits. This means that every 384-Bit word (row) in the XOR-table differs from *all* other 384-Bit words in that table by about ½ of the bits (columns).
 163
 164 The MHash-384 digest of a given input message is computed in a *stream-like* fashion. This means that we start with the "empty" (all zeros) hash value, we will process the given input 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.
 165
 166 The MHash-384 "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&hellip;
 167
 168 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 subset of its bits. Because all of the 384-Bit words in the XOR-table have a minimum Hamming distance of about ½ of the hash's total length, each possible input byte value is guaranteed to flip a *different* subset of the hash's bits &ndash; a subset that differs from *all* other possible "flip" subsets (i.e. *all* other possible input byte values) at approximately ½ of the bit positions.
 169
 170 This is known as the [avalanche effect](https://en.wikipedia.org/wiki/Avalanche_effect). It means that if we apply a *minimal* change to the current input byte, e.g. we flip *one* of its bits (at random), then a *significant* change to the resulting hash value is induced, i.e. about ½ of the hash bits are flipped.
 171
 172 ### The MIX table
 173
 174 In fact the "update" rule described in the previous section 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 selected (input-dependent) 384-Bit word from the XOR-table.
 175
 176 Be aware that, because of the *associativity* of the XOR function, simply XOR'ing a set of 384-Bit word from the XOR-table would always give the same result, regardless of the *order* in which those 384-Bit words are processed. Hence, input messages that only differ in the order of their message bytes, but besides that contain the same set of message bytes, would result in the same hash value &ndash; which clearly is undesirable! The shuffling of the hash bytes in each update step ensures that processing the *same* set of input bytes in a *different* order will result in a *different* hash value each time &ndash; with very high probability.
 177
 178 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 *256* pre-computed permutations. This table is referred to as the *MIX-table*. Each of its rows, or 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 permutation (MIX-table row) differs as much as possible from all the other permutations (MIX-table rows).
 179
 180 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 *255*) the counter will wrap around to index *zero* again.
 181
 182 ### The RND table
 183
 184 Furthermore, in each update step, to every byte of the hash value a constant byte value will be *added*. There is a distinct constant for each hash byte position, and a different set of constants is employed in subsequent update steps. In any case, the addition is performed modulus 256 &ndash; which means that results greater than or equal to 256 will wrap around to zero.
 185
 186 For this purpose, MHash-384 uses a table of *256* pre-defined 384-Bit (48-byte) words. This table is referred to as the *RND-table*. Each of its rows contains 48 "random" byte values &ndash; one for each hash byte position. The contents of the RND-table are based entirely on "true" **random** numbers. The randomness was collected from atmospheric noise, courtesy of [Random.org](https://www.random.org/).
 187
 188 The rationale is to ensure that there will be enough variation in the hash value bytes, even when there is very few variations in the given input bytes. Note that blending a perfectly uniform byte sequence with a *random* byte sequence yields a "random-looking" byte sequence, whereas blending two random byte sequences still yields a "random-looking" byte sequence. In other words, blending the given input sequence with the random byte sequence can only make the result "look" *more* random.
 189
 190 Of course, even though the RND-table was generated from "true" random numbers, the exactly same table is used in each hash computation, so the hash function remains deterministic. Also, we use the same counter to select the current RND-table row that is used to select the current MIX-table row, i.e. the "active" RND-table row will wrap around after 256 update steps.
 191
 192 ### The SBX table
 193
 194 In addition, after every update step, *all* bytes of the hash value will be subject to a **substitution** operation. For this purpose, MHash-384 uses a table of *256* pre-computed 48-byte (384-Bit) words. This table is referred to as the *SBX-table*. It has been generated in such a way that every *column* represents a permutation of the possible byte values, i.e. each of the byte values `0x00` to `0xFF` appears exactly *once* per column &ndash; in a "randomized" and column-specific order. Also, each of the 48 permutations (columns) stored in the SBX-table differs from all other permutations (columns) in the table as much as possible.
 195
 196 The substitution operation replaces the *i*&#x2011;th byte of the original hash value with a value chosen from the *i*&#x2011;th *column* of the SBX-table. More specifically, each byte is replaced by the value that is stored in the *row* whose index matches the original byte value. If, for example, the original byte value equals `0x00`, then it is replaced by the value from the *first* row of the SBX-table. If the original byte value equals `0x01`, then it is replaced by the value from the *second* row of the SBX-table. And so on&hellip;
 197
 198 The *non-linear* substitution operation improves the "confusion" between the input message and the resulting hash value.
 199
 200 ### Finalization
 201
 202 Last but not least, the computation of the MHash-384 digest is **finalized** by XOR'ing the current hash value, as it appears after the last message byte has been processed, with the very last 384-Bit word of the XOR-table &ndash; that 384-Bit word has index `0x256` and hence can *never* be selected by any input message byte value in a "regular" update step. Apart from this, the MIX, RND and SBX tables will be applied to the current hash value in the same way as in any "regular" update step.
 203
 204 The *unique* finalization step ensures that it will ***not*** be possible to "continue" the computation of a known *final* MHash-384 hash value &ndash; simply by appending further message bytes. Implementations that wish to do so may, of course, retain the current hash value, as it appeared right *before* the finalization step, and later "continue" the computation based on *that* value.
 205
 206 ## Pseudocode
 207
 208 The MHash-384 algorithm can be summed up with the following simple pseudocode:
 209
 210         procedure mhash384
 211         const:
 212           HASH_SIZE = 48
 213           TABLE_INI: matrix[  2 × HASH_SIZE] of byte
 214           TABLE_XOR: matrix[257 × HASH_SIZE] of byte
 215           TABLE_MIX: matrix[256 × HASH_SIZE] of byte
 216           TABLE_RND: matrix[256 × HASH_SIZE] of byte
 217           TABLE_SBX: matrix[256 × HASH_SIZE] of byte
 218         input:
 219           message: array[N] of byte
 220         output:
 221           hash: array[HASH_SIZE] of byte
 222         vars:
 223           ctr: integer
 224           val: byte
 225           tmp_src: array[HASH_SIZE] of byte
 226           tmp_dst: array[HASH_SIZE] of byte
 227         begin
 228           /*initialization*/
 229           ctr ← 0
 230           tmp_src ← TABLE_INI[0]
 231           tmp_dst ← TABLE_INI[1]
 232
 233           /*input message processing*/
 234           for k = 0 to N-1 do
 235             for i = 0 to HASH_SIZE-1 do
 236               val ← ((tmp_src[TABLE_MIX[ctr,i]] ⊕ TABLE_XOR[message[k],i]) + TABLE_RND[ctr,i]) mod 256
 237               tmp_dst[i] ← tmp_dst[i] ⊕ TABLE_SBX[val,i]
 238             done
 239             ctr ← (ctr + 1) mod 256
 240             xchg(tmp_src ⇄ tmp_dst)
 241           done
 242
 243           /*finalization*/
 244           for i = 0 to HASH_SIZE-1 do
 245             val ← ((tmp_src[TABLE_MIX[ctr,i]] ⊕ TABLE_XOR[256,i]) + TABLE_RND[ctr,i]) mod 256
 246             hash[i] ← tmp_dst[i] ⊕ TABLE_SBX[val,i]
 247           done
 248         end.
 249
 250 *Note:* The `⊕` symbol refers to the binary XOR operation, whereas `+` refers to the arithmetic add operation.
 251
 252
 253 # Detailed API Specification
 254
 255 Global definitions for both, C and C++, API's.
 256
 257 ## Global definitions
 258
 259 ### MHASH_384_LEN
 260
 261 This constant specifies the length of a MHash-384 digest (hash value) in bytes/octets. It is equal to `48UL`.
 262
 263 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.
 264
 265 ### MHASH_384_VERSION_MAJOR
 266
 267 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.
 268
 269 ### MHASH_384_VERSION_MINOR
 270
 271 The MHash-384 library *minor* version. Minor releases may add new features, but they do **not** break the API compatibility. Applications may require a certain minimum *minor* version of the library, but will work with higher *minor* versions too.
 272
 273 ### MHASH_384_VERSION_PATCH
 274
 275 The MHash-384 library *patch* level. Patch releases may include bug-fixes 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 for compatibility.
 276
 277 ## API for for C language
 278
 279 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 (or shared between) *different* "concurrent" threads, then the application **must** *serialize* the function calls, e.g. by means of a *mutex lock* (or "critical section").
 280
 281 ### mhash_384_t
 282
 283         typedef struct mhash_384_t;
 284
 285 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 by the calling application!
 286
 287 *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!
 288
 289 ### mhash_384_initialize()
 290
 291         void mhash_384_initialize(mhash_384_t *const ctx);
 292
 293 This function is used to initialize 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! The application may also call this function again in oder to *reset* the hash computation state.
 294
 295 *Parameters:*
 296
 297 * `mhash_384_t *ctx`
 298   Pointer to the hash computation state of type `mhash_384_t` that will be initialized (reset) by this operation. The application must allocate the memory holding the variable of type `mhash_384_t`. The previous state will be lost!
 299
 300 ### mhash_384_update()
 301
 302         void mhash_384_update(mhash_384_t *const ctx, const uint8_t *const input, const size_t len);
 303
 304 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, with *same* context (`mhash_384_t`), until all input has been processed.
 305
 306 *Parameters:*
 307
 308 * `mhash_384_t *ctx`
 309   Pointer to the hash computation state of type `mhash_384_t` that will be updated by this operation.
 310
 311 * `const uint8_t *input`
 312   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*, i.e. the address of the *first* byte (octet) to be processed.
 313   *Note:* Formally, the input data is defined as a sequence of `uint8_t`, i.e. a sequence of bytes (octets). However, *any* suitable *byte*-based (serializable) input data can be processed using the proper *typecast* operator.
 314
 315 * `size_t len`
 316   The *length* of the input data to be processed, in bytes (octets). All memory addresses in the range from `input` up to and including `input+(len-1)` will be processed as input. Applications need to carefully check `len` to avoid buffer overruns!
 317
 318 ### mhash_384_finalize()
 319
 320 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.
 321
 322 *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.
 323
 324         void mhash_384_finalize(const mhash_384_t *const ctx, uint8_t *const output);
 325
 326 * `const mhash_384_t *ctx`
 327   Pointer to the hash computation state of type `mhash_384_t` from which the final digest is computed.
 328
 329 * `uint8_t *output`
 330   Pointer to the memory block where the final digest will be stored. This memory needs to be allocated by the calling application! The digest will be stored to the memory range from `output[0]` to `output[MHASH_384_LEN-1]` (inclusive).
 331
 332 ## API for for C++ language
 333
 334 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 (or shared between) *different* "concurrent" threads, then the application **must** *serialize* the method calls, e.g. by means of a *mutex lock* (or "critical section").
 335
 336 *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; those may be subject to change!
 337
 338 ### Constructor
 339
 340         MHash384::MHash384(void);
 341
 342 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.
 343
 344 ### update() [1]
 345
 346         void MHash384::update(const uint8_t *const input, const size_t len);
 347
 348 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, with *same* context (`mhash_384_t`), until all input has been processed.
 349
 350 *Parameters:*
 351
 352 * `const uint8_t *input`
 353   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*, i.e. the address of the *first* byte (octet) to be processed.
 354   *Note:* Formally, the input data is defined as a sequence of `uint8_t`, i.e. a sequence of bytes (octets). However, *any* suitable *byte*-based (serializable) input data can be processed using the proper *typecast* operator.
 355
 356 * `size_t len`
 357   The *length* of the input data to be processed, in bytes (octets). All memory adresses in the range from `input[0]` to `input[len-1]` (inclusive) will be processed. Applications need to carefully check `len` to avoid buffer overruns!
 358
 359 ### update() [2]
 360
 361         void MHash384::update(const std::vector<uint8_t> &input, const size_t offset = 0, const size_t len = 0);
 362
 363 This method is used to process 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.
 364
 365 *Parameters:*
 366
 367 * `const std::vector<uint8_t> &input`
 368   Reference to the `std::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.
 369
 370 * `size_t offset`
 371   Optional. Specifies the *zero-based* index of the *first* vector element to be processed. By default, processing starts at index **0**.
 372
 373 * `size_t len`
 374   Optional. Specifies the number of vector elements to be processed. All elements from index `offset` up to and including index `offset+(len-1)` will be processed. By default, the *whole* vector is being processed.
 375
 376 ### update() [3]
 377
 378         void MHash384::update(const std::string &input, const size_t offset = 0, const size_t len = 0);
 379
 380 This method is used to process 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.
 381
 382 *Parameters:*
 383
 384 * `const std::vector<uint8_t> &input`
 385   Reference to the `std::string` object to be processed as input. By default, all characters (octets) in the string, excluding the terminating `NULL` character, will be processed. Optionally, a sub-range of the vector can be selected.
 386
 387 * `size_t offset`
 388   Optional. Specifies the *zero-based* index of the *first* character in the string to be processed. By default, processing starts at index **0**.
 389
 390 * `size_t len`
 391   Optional. Specifies the number of character to be processed. All characters from `offset[0]` to `offset[len-1]` (inclusive) will be processed. By default, the whole string, excluding the terminating `NULL` character, is processed.
 392
 393 ### finalize() [1]
 394
 395         void MHash384::finalize(uint8_t *const output) const;
 396
 397 This method is used to finalize the hash computation and output the final digest (hash value). Typically, the application will call this method *once*, and only ***after*** all input data has been processed.
 398
 399 *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.
 400
 401 *Parameters:*
 402
 403 * `uint8_t *output`
 404   Pointer to the memory block where the final digest will be stored. This memory needs to be allocated by the calling application! The digest will be stored to the memory range from `output[0]` to `output[MHASH_384_LEN-1]` (inclusive).
 405
 406 ### finalize() [2]
 407
 408         std::vector<uint8_t> MHash384::finalize(void) const;
 409
 410 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.
 411
 412 *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.
 413
 414 *Return value:*
 415
 416 * Returns a `std::vector<uint8_t>` containing the final digest (hash value). The size of the returned vector object will be exactly `MHASH_384_LEN` elements (octets).
 417
 418 ### reset()
 419
 420         void MHash384::reset(void);
 421
 422 Resets the `MHash384` object to the initial hash computation state, i.e. the object will be in the same state again as a newly constructed object. Use this function to compute multiple *separate* hash values with the same `MHash384` object.
 423
 424 *Note:* In order to do so, call this function *after* the *last* input byte (octet) of the **i**-th message has been processed (and *after* the final digest has been received), but *before* the *first* byte (octet) of the **i+1**-th message is processed.
 425
 426
 427 # Supported Platforms
 428
 429 MHash-384 library should compile on any standard-compliant C/C++ compiler. In particular, the following platforms have been tested successfully:
 430
 431 * Microsoft Windows
 432     - Microsoft C/C++ Compiler, using Visual Studio 2010 or later
 433     - MinGW, using Mingw-w64 from [MSYS2](https://msys2.github.io/) project
 434 * Intel C/C++ Compiler, version Version 15.0 (XE 2015) or later
 435 * GNU/Linux, using GCC/G++, version 4.7 or later
 436
 437 # Language Bindings
 438
 439 While the MHash-384 library is primarily targeted for C/C++ applications, "native" ports of the library *are provided for a variety of programming languages. This allows for using the MHash-384 library in pretty much any scenario/environment.
 440
 441 ## Microsoft.NET
 442
 443 Bindings of the MHash-384 library are provided for **Microsoft.NET**, in the form of the `MHashDotNet384.dll` assembly.
 444
 445 In order to use the MHash-384 library in your Microsoft.NET (e.g. C# or VB.NET) application, simply import and instantiate the provided `MHash384` class from the `MHashDotNet384` namespace:
 446
 447         using MHashDotNet384;
 448
 449         String ComputeHash(FileStream fs)
 450         {
 451                 byte[] buffer = new byte[4096];
 452                 MHash384 digest = new MHash384();
 453                 while (true)
 454                 {
 455                         int count = fs.Read(buffer, 0, buffer.Length);
 456                         if (count > 0)
 457                         {
 458                                 digest.Update(buffer, 0, count);
 459                                 continue;
 460                         }
 461                         break;
 462                 }
 463                 return digest.ToString();
 464         }
 465
 466 ### Prerequisites
 467
 468 In order to use the MHash-384 library in your Microsoft.NET (e.g. C# or VB.NET) application, a reference to the `MHashDotNet384.dll` assembly file **must** be added to the project.
 469
 470 ## Java
 471
 472 Bindings of the MHash-384 library are provided for **Java**, in the form of the `MHashJava384.jar` library.
 473
 474 In order to use the MHash-384 library in your Java-based application, simply import and instantiate the provided `MHash384` class from the `com.muldersoft.mhash384` package:
 475
 476         import com.muldersoft.mhash384.MHash384;
 477
 478         String computeHash(final InputStream inputStream) throws IOException {
 479                 final byte[] buffer = new byte[4096];
 480                 final MHash384 mhash384 = new MHash384()
 481                 int count;
 482                 do {
 483                         count = inputStream.read(buffer);
 484                         if(count > 0) {
 485                                 mhash384.update(buffer, 0, count);
 486                         }
 487                 }
 488                 while(count == buffer.length);
 489                 return mhash384.digest().toString();
 490         }
 491
 492 ### Prerequisites
 493
 494 In order to use the MHash-384 library in your Java project, the `MHashJava384.jar` **must** be added to the Java *build path*.
 495
 496 ## Python
 497
 498 Bindings of the MHash-384 library are provided for **Python** (version 3.x), in the form of the `MHashPy384.py` module.
 499
 500 In order to use the MHash-384 library in your Python-based application, simply import and instantiate the provided `MHash384` class from the `MHashPy384` module:
 501
 502         from MHashPy384 import MHash384
 503
 504         mhash384 = MHash384()
 505         for chunk in read_chunks(fs):
 506                 mhash384.update(chunk)
 507         print(binascii.hexlify(mhash384.digest()))
 508
 509 ### Prerequisites
 510
 511 In order to use the MHash-384 library in your Python project, the `MHashPy384.py` **must** be in your Python *library path*.
 512
 513 *Note:* [CPython](https://www.python.org/), which is the most widely deployed Python interpreter, is known to be **very slow** for computation-intensive workloads, such as hash computations! Greatly improved speed can be achieved by using the [PyPy](http://pypy.org/) instead of CPython.
 514
 515 ## Delphi
 516
 517 Bindings of the MHash-384 library are provided for **Delphi**, in the form of the `MHash384.pas` unit.
 518
 519 In order to use the MHash-384 library in your Delphi application, simply add the `MHash384` unit to the *uses* clause and instantiate the provided `TMHash384` class:
 520
 521         uses
 522                 {...}, MHash384;
 523
 524         function ComputeHash(var inputFile: File): TByteArray;
 525         var
 526                 digest: TMHash384;
 527                 buffer: TByteArray;
 528                 count: Integer;
 529         begin
 530                 SetLength(buffer, 4096);
 531                 digest := TMHash384.Create();
 532                 try
 533                         while not Eof(inputFile) do
 534                         begin
 535                                 BlockRead(inputFile, buffer[0], Length(buffer), count);
 536                                 if count > 0 then
 537                                 begin
 538                                         digest.Update(buffer, 0, count);
 539                                 end;
 540                         end;
 541                         digest.Result(Result);
 542                 finally
 543                         digest.Destroy();
 544                 end;
 545         end;
 546
 547 ### Prerequisites
 548
 549 In order to use the MHash-384 library in your Delphi application, the Unit file 'MHash384.pas' must be added to the project. This unit contains the `TMHash384` convenience class and associated data types.
 550
 551
 552 # Source Code
 553
 554 The MHash-384 source is available from the official [**git**](https://git-scm.com/) mirrors:
 555
 556 * `git clone https://github.com/lordmulder/mhash-384.git` [[Browse](https://github.com/lordmulder/mhash-384)]
 557
 558 * `git clone https://bitbucket.org/muldersoft/mhash-384.git` [[Browse](https://bitbucket.org/muldersoft/mhash-384)]
 559
 560 * `git clone https://git.assembla.com/mhash-384.git` [[Browse](https://www.assembla.com/spaces/mhash-384/git/source)]
 561
 562 * `git clone https://gitlab.com/lord_mulder/mhash-384.git` [[Browse](https://gitlab.com/lord_mulder/mhash-384)]
 563
 564
 565 # Build Instructions
 566
 567 This section describes how to build the MHash-384 sample application. Please note that you do **not** need to "build" the library in order to use it in your own application.
 568
 569 * For supported versions of *Microsoft Visual Studio*, MHash-384 library ships with project/solution files, which will compile "out of the box".
 570
 571 * The *Intel C/C++ Compiler* integrates into Visual Studio, so simply select "Use Intel C++" from the project/solution menu.
 572
 573 * Optionally, the build script `Make.cmd` may be used to create ready-to-use deployment packages. Note, however, that it may be necessary to adjust the paths in the header section of the script!
 574
 575 * 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.
 576
 577 ## Influential Environment Variables
 578
 579 The following environment variables may effect the build process and need to be set carefully:
 580
 581 * **Java:**
 582     - `JAVA_HOME`: The *Java* "home" directory, should be pointing to JDK (*not* JRE) root directory
 583     - `ANT_HOME`: The *Apache Ant* "home" directory, should be pointing to root directory
 584
 585 * **Python:**
 586     - `PYTHON_INC`: Directory to look for Python *include* files (typically `<PYTHON_INSTALL_PATH>/include`)
 587     - `PYTHON_LIB32`: Directory to look for 32-Bit (x86) Python *library* files (typically `<PYTHON_X86_PATH>/libs`)
 588     - `PYTHON_LIB64`: Directory to look for 64-Bit (x64) Python *library* files (typically `<PYTHON_X64_PATH>/libs`)
 589
 590 * **Delphi:**
 591     - `DELPHI_PATH`: The *Borland Delphi* installation directory (for Windows only)
 592
 593 * **Makefile:**
 594     - `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!
 595     - `CPLUSPLUS`:  If set to `1`, build CLI front-end from *C++* sources, otherwise from *plain C* sources (defaults to `0`)
 596     - `NO_JAVA`: If set to `1`, the *Java* bindings are **not** built (defaults to `0`, i.e. *do* build)
 597     - `NO_PYTHON`: If set to `1`, the *Python* bindings are **not** built (defaults to `0`, i.e. *do* build)
 598
 599 * **Windows:**
 600     - `MSVC_PATH`: *Microsoft Visual C++* installation directory
 601     - `PDOC_PATH`: *Pandoc v2.x* installation directory
 602     - `GIT2_PATH`: *Git for Windows* (formerly *MSYS Git*) installation directory
 603
 604
 605 # License
 606
 607 **Copyright(c) 2016-2018 LoRd_MuldeR &lt;mulder2@gmx.de&gt;, released under the MIT License.**
 608 **Check <http://muldersoft.com/> or <http://muldersoft.sourceforge.net/> for updates!**
 609
 610         Permission is hereby granted, free of charge, to any person obtaining a copy of this software
 611         and associated documentation files (the "Software"), to deal in the Software without
 612         restriction, including without limitation the rights to use, copy, modify, merge, publish,
 613         distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
 614         Software is furnished to do so, subject to the following conditions:
 615
 616         The above copyright notice and this permission notice shall be included in all copies or
 617         substantial portions of the Software.
 618
 619         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
 620         BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 621         NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 622         DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 623         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 624
 625 <https://opensource.org/licenses/MIT>
 626
 627
 628 # Version History
 629
 630 ## Version 1.2.0 [2018-01-20]
 631
 632 * Implemented the new INI-, RND- and SBX-tables for a further increased hash quality
 633
 634 *  ***Note:*** This change, unfortunately, breaks compatibility with v1.1 hashes!
 635
 636 * Many improvements to the C and C++ command-line front-ensd have been implemented
 637
 638 * Various improvements and fixes for the Java, Microsoft.NET, Python and Delphi ports
 639
 640 ## Version 1.1.0 [2017-12-22]
 641
 642 * Re-generated the XOR- and MIX-tables with higher hamming distance for increased hash quality
 643
 644 * ***Note:*** This change, unfortunately, breaks compatibility with v1.0 hashes!
 645
 646 * All language bindings have been *replaced* by full ports of the library to the respective language
 647
 648 ## Version 1.0.1 [2016-03-31]
 649
 650 * Added language bindings for *Java*.
 651
 652 * Added language bindings for *Microsoft.NET*.
 653
 654 * Added language bindings for *Python*.
 655
 656 * Added language bindings for *Delphi*.
 657
 658 ## Version 1.0.0 [2016-03-03]
 659
 660 * First public release.
 661
 662 &nbsp;
 663
 664 [■](https://www.youtube.com/watch?v=dng06ZqI4Ss)