README.md

   1 ---
   2 title: "![MHash-384](img/mhash384/MHash-384.jpg)"
   3 subtitle: "**Yet another simple fast portable secure hashing library**"
   4 ---
   5
   6
   7 # Introduction
   8
   9 **MHash-384** is a fast, portable and secure hashing library, released under the *MIT license*.
  10
  11 The MHash-384 core library has been written in plain **C**, and the CLI front-end has been written in **C++**. The core library provides a simple "stream processing" API, that is available in two flavors: a plain C99 version and an *object-oriented* C++ wrapper. Either way, the MHash-384 library produces hash values with a fixed length of 384 bits (48 bytes).
  12
  13 MHash-384 supports a wide range of compilers, including MSVC++, GCC, MinGW/Cygwin, Clang/LLVM and Intel C++. It also runs on many platforms, including Windows, Linux, BSD and Solaris. Furthermore, the MHash-384 library has already been *ported* to various other programming languages, including **Java**, **Microsoft.NET**, **Python** as well as **Delphi**.
  14
  15
  16 # Quick Start Guide
  17
  18 In order to use the *MHash-384* library, simply include the header file `mhash384.h` in your code:
  19
  20         #include <mhash384.h>
  21
  22 ## Example for C language
  23
  24 If you source code is written in **C**, use the **`mhash384_t`** struct and the **`mhash384_XYZ()`** functions:
  25
  26         /*variables*/
  27         uint8_t buffer[BUFFSIZE];
  28         size_t len;
  29         uint8_t result[MHASH384_SIZE];
  30         mhash384_t mhash384;
  31
  32         /*initialization*/
  33         mhash384_init(&mhash384);
  34
  35         /*input data processing*/
  36         while(more_data())
  37         {
  38                 len = read_data(buffer, BUFFSIZE);
  39                 mhash384_update(&mhash384, buffer, len);
  40         }
  41
  42         /*finalization*/
  43         mhash384_final(&mhash384, result);
  44
  45 ## Example for C++ language
  46
  47 Or, if you source code is written in **C++**, use the provided **`MHash384`** wrapper class:
  48
  49         /*instance*/
  50         MHash384 mhash384;
  51
  52         /*input data processing*/
  53         while(more_data())
  54         {
  55                 const std::vector<uint8_t> buffer = read_data();
  56                 mhash384.update(buffer);
  57         }
  58
  59         /*finalization*/
  60         const uint8_t *result = mhash384.finish();
  61
  62
  63 # Command-line Usage
  64
  65 MHash-384 comes with a simple "standalone" command-line application, similar to the `sha1sum` or`sha256sum` utilities.
  66
  67 ## Synopsis
  68
  69 The MHash-384 command-line application takes a number of optional options followed by an one or more input files.
  70
  71 If **no** input file is specified, input will be read from standard input (*stdin*).
  72
  73 The digest will be written to the standard output (*stdout*). Diagnostic message are written to the standard error (*stderr*).
  74
  75         mhash384 [OPTIONS] [<FILE_1> <FILE_2> ... <FILE_N>]
  76
  77 ## Options
  78
  79 MHash-384 supports the following options:
  80
  81 * **`--keep-going`**
  82   Try to proceed with the remaining files, if a file has failed (e.g. access denied or file not found).
  83   Only applicable, if *multiple* files have been specified. Default behavior is to abort immediately when a file has failed.
  84
  85 * **`--short`**
  86   Print the digest in *short* format (**no** file names). Default format prints the digest followed by the file name.
  87
  88 * **`--lower-case`**
  89   Print the digest in *lower-case* letters. Default format prints the digest in *upper-case* letters.
  90   This option can **only** be used with the default *Hex* (hexadecimal) output format.
  91
  92 * **`--base64`**
  93   Print the digest in [**Base64**](https://en.wikipedia.org/wiki/Base64) (RFC-4648) format. Default prints the digest in [**Hex**](https://en.wikipedia.org/wiki/Hexadecimal) (hexadecimal) output format.
  94   This option **must not** be combined with the `--base85` option, for obvious reasons.
  95
  96 * **`--base85`**
  97   Print the digest in [**Base85**](https://en.wikipedia.org/wiki/Ascii85) (Ascii85) format. Default prints the digest in [**Hex**](https://en.wikipedia.org/wiki/Hexadecimal) (hexadecimal) output format.
  98   This option **must not** be combined with the `--base64` option, for obvious reasons.
  99
 100 * **`--help`**
 101   Print the help screen (manpage) and exit program.
 102
 103 * **`--version`**
 104   Print the program version (plus some build information) and exit program.
 105
 106 * **`--self-test`**
 107   Run self-test and exit program. This will process various standard test vectors and validate the resulting hashes.
 108   *Note:* Some test vectors contain very long inputs, therefore the computation can take a while to complete!
 109
 110 * **`--stress`**
 111   Enable stress test mode. This will process all test strings from the specified input file, expecting one string *per line*.
 112   All computed hash values are added to an `std::unordered_set`, thus checking for possible collisions.
 113
 114 * **`--benchmark`**
 115   Measure the overall time required for the operation. If specified, output the total amount of time elapsed, in seconds.
 116
 117 ## Output Format
 118
 119 In default operation mode, MHash-384 writes one line per input file to the standard output:
 120
 121         <HASH_VALUE> [SPACE SPACE <FILE_NAME>]
 122
 123 The format of the hash value is either [**Hex**](https://en.wikipedia.org/wiki/Hexadecimal) (hexadecimal) or [**Base64**](https://en.wikipedia.org/wiki/Base64) (RFC-4648), depending on the specified options.
 124
 125 Also, the file name will be printed, unless "short" format was requested. File names *may* contain a path!
 126
 127 #### Sample output {-}
 128
 129         BD41A203A61FE74178A8D507...33E553FD1569ED733C52BE8B  debian-7.9.0-amd64-DVD-1.iso
 130         EE328DDD4E116165252F1FF8...11729801097C51FB61D20184  debian-7.9.0-i386-DVD-1.iso
 131         A8B2007537867BDA0C18A264...45A1379AB8B4A77F9D8C8B24  debian-10.0.0-amd64-DVD-1.iso
 132
 133 ## Exit Code
 134
 135 On success, *zero* is returned. On error or user interruption, a *non-zero* error code is returned.
 136
 137 Note that, with "keep going" mode enabled, the exit code reflects whether *at least* one file was processed successfully.
 138
 139 ## Examples
 140
 141 Compute MHash-384 hash of a single file:
 142
 143         mhash384 "C:\Images\debian-8.3.0-amd64-DVD-1.iso"
 144
 145 Compute MHash-384 hash of *two* files:
 146
 147         mhash384 "C:\Images\debian-8.3.0-amd64-DVD-1.iso" "C:\Images\debian-8.3.0-i386-DVD-1.iso"
 148
 149 Compute MHash-384 hash of *multiple* files, using wildcard expansion ([globbing](https://en.wikipedia.org/wiki/Glob_(programming))):
 150
 151         mhash384 "C:\Images\*.iso"
 152
 153 Compute MHash-384 hash from data passed directly via [pipeline](https://en.wikipedia.org/wiki/Pipeline_(Unix)):
 154
 155         dd if=/dev/urandom bs=100 count=1 | mhash384
 156
 157
 158 # API Specification
 159
 160 ## Global definitions
 161
 162 Global definitions for both, the C and C++, API's.
 163
 164 ### MHASH384_SIZE
 165
 166 The size of the final MHash-384 hash value (digest), in bytes. This value is qual to `48U`.
 167
 168 ### MHASH384_WORDS
 169
 170 The number of words per MHash-384 hash. Each word has a size of 64 bits (`uint64_t`). This value is qual to `6U`.
 171
 172 ## API for C language
 173
 174 All functions described in the following are *reentrant* and *thread-safe*. A single thread may compute multiple MHash-384 hashes in an "interleaved" fashion, provided that a separate MHash-384 context is used for each ongoing hash computation. Multiple threads may compute multiple MHash-384 hashes in parallel, provided that each thread uses its own separate MHash-384 context; *no* synchronization is required. However, sharing the same MHash-384 context between multiple threads is **not** safe in the general case. If the same MHash-384 context needs to be accessed from multiple threads, then the threads need to be synchronized explicitly (e.g. via Mutex lock), ensuring that all access to the shared context is rigorously serialized!
 175
 176 ### mhash384_t
 177
 178         typedef struct mhash384_t;
 179
 180 The MHash-384 context. It represents all state of an ongoing MHash-384 hash computation. Each MHash-384 hash computation needs a corresponding MHash-384 context. It is possible to re-use an MHash-384 context for multiple MHash-384 hash computations, provided that those hash computations are strictly serialized. If multiple MHash-384 hash computations need to be performed in an "interleaved" fashion, each ongoing hash computation needs to use its own separate MHash-384 context. In any case, the memory for the `mhash384_t` instance(s) must be allocated by the calling application. If the MHash-384 context was allocated on the heap space, the calling application also is responsible for freeing up that memory.
 181
 182 *Note:* Applications should treat this data-type as *opaque*, i.e. the application **must not** access the fields of the struct directly!
 183
 184 ### mhash384_init()
 185
 186         void mhash384_init(mhash384_t *const ctx);
 187
 188 Set up the MHash-384 hash computation. This function initializes the MHash-384 context; it prepares the state for the upcoming hash computation. The application is required to call this function *once* for each MHash-384 hash computation. The function must to be called ***before*** any input data can be processed in a specific MHash-384 context! The application may call this function again, on the same MHash-384 context, which will *reset* that context and start a new hash computation.
 189
 190 *Parameters:*
 191
 192 * `mhash384_t *ctx`
 193   Pointer to the MHash-384 context of type `mhash384_t` that will be initialized (reset) by this operation.
 194   *Note:* The MHash-384 library does **not** allocate the required memory; it must be allocated by the calling application!
 195
 196 ### mhash384_update()
 197
 198         void mhash384_update(mhash384_t *const ctx, const uint8_t *const data_in, const size_t len);
 199
 200 Process next chunk of input data. This function performs the actual MHash-384 hash computation, in an incremental way. The function processes the next **N** bytes of input data and updates the MHash-384 context (`mhash384_t`) accordingly. The application is supposed to call this function in a loop, with the *same* MHash-384 context, until all input has been processed.
 201
 202 *Parameters:*
 203
 204 * `mhash384_t *ctx`
 205   Pointer to the hash computation state of type `mhash384_t` that will be updated by this operation.
 206
 207 * `const uint8_t *data_in`
 208   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 to be processed.
 209   *Note:* Formally, the input data is defined as an array of byte (`uint8_t`). Nonetheless, *any* kind of input data can be processed, by applying the proper *typecast* operator. For numeric values, the platform's [endianness](https://en.wikipedia.org/wiki/Endianness) applies!
 210
 211 * `size_t len`
 212   The *length* of the input data to be processed, *in bytes*. Specify `sizeof(T) * count` for data types **T** other than byte.
 213   *Note:* All *bytes* in the range from `data_in[0]` up to and including `data_in[len-1]` will be processed as input.
 214
 215 ### mhash384_final()
 216
 217         void mhash384_final(mhash384_t *const ctx, uint8_t *const digest_out);
 218
 219 Retrieve final hash value. This function completes the MHash-384 hash computation and returns the computed hash value. The function finalizes the MHash-384 context (`mhash384_t`) and writes the resulting hash value to the output buffer. Once this function has been called, the corresponding MHash-384 context will be in an ***undefined*** state, until it is [reset](#mhash384_init)!
 220
 221 *Parameters:*
 222
 223 * `mhash384_t *ctx`
 224   Pointer to the hash computation state of type `mhash384_t` that will be finalized by this operation.
 225   *Note:* The MHash-384 library does **not** free this memory; it may need to be freed up by the calling application!
 226
 227 * `uint8_t *digest_out`
 228   Pointer to the memory block where the final MHash-384 hash (digest) is to be stored. This memory needs to be allocated by the calling application! The size of the MHash-384 hash value, in bytes, is equal to `MHASH384_SIZE`.
 229   *Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten!
 230
 231 ### mhash384_compute()
 232
 233         void mhash384_compute(uint8_t *const digest_out, const uint8_t *const data_in, const size_t len);
 234
 235 Compute hash value at once. This is a convenience function that can be used to compute an MHash-384 hash value with just a single invocation. The function processes a block of **N** input bytes and writes the resulting hash value to the output buffer. This function does *not* required the caller to provide an MHash-384 context; it internally uses a "transient" context. Anyway, this function is fully thread-safe. Naturally, this function is *only* applicable where *all* input data is available at once.
 236
 237 *Parameters:*
 238
 239 * `uint8_t *digest_out`
 240   Pointer to the memory block where the final MHash-384 hash (digest) is to be stored. This memory needs to be allocated by the calling application! This size of the MHash-384 hash value, in bytes, is equal to `MHASH384_SIZE`.
 241   *Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten!
 242
 243 * `const uint8_t *data_in`
 244   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 to be processed.
 245   *Note:* Formally, the input data is defined as an array of byte (`uint8_t`). Nonetheless, *any* kind of input data can be processed, by applying the proper *typecast* operator. For numeric values, the platform's [endianness](https://en.wikipedia.org/wiki/Endianness) applies!
 246
 247 * `size_t len`
 248   The *length* of the input data to be processed, *in bytes*. Specify `sizeof(T) * count` for data types **T** other than byte.
 249   *Note:* All *bytes* in the range from `data_in[0]` up to and including `data_in[len-1]` will be processed as input.
 250
 251 ### mhash384_version()
 252
 253         void mhash384_version (uint16_t *const major, uint16_t *const minor, uint16_t *const patch);
 254
 255 Retrieve version information. This function returns the current version of the MHash-384 library.
 256
 257 *Parameters:*
 258
 259 * `uint16_t *major`
 260   Pointer to a variable of type `uint16_t` where the *major* version of the MHash-384 library will be stored.
 261
 262 * `uint16_t *minor`
 263   Pointer to a variable of type `uint16_t` where the *minor* version of the MHash-384 library will be stored.
 264
 265 * `uint16_t *patch`
 266   Pointer to a variable of type `uint16_t` where the *patch* level of the MHash-384 library will be stored.
 267
 268 ### mhash384_selftest()
 269
 270         bool mhash384_selftest(void);
 271
 272 Self-test routine. This function runs the built-in self-test of the MHash-384 library; intended for debugging purposes.
 273
 274 *Return value:*
 275
 276 * Returns `true`, if the self-test completed successfully; returns `false`, if any problems have been detected.
 277
 278 ## API for C++ language
 279
 280 For the C++ langauge, the **`MHash384`** class is provided, as a convenience wrapper around the C-API. All functions of the `MHash384` class are *reentrant* and *thread-safe*. A single thread may compute multiple MHash-384 hashes in an "interleaved" fashion, provided that a separate `MHash384` instance (object) is used for each ongoing hash computation. Multiple threads may compute multiple MHash-384 hashes in parallel, provided that each thread uses its own separate `MHash384` instance; *no* synchronization is required. However, sharing the same `MHash384` instance between multiple threads is **not** safe in the general case. If the same `MHash384` instance needs to be accessed from multiple threads, then the threads need to be synchronized explicitly (e.g. via Mutex lock), ensuring that all access to the shared instance is rigorously serialized!
 281
 282 ### MHash384()
 283
 284         MHash384(void)
 285
 286 Constructor. Creates a new `MHash384` instance (object) and prepares the state for the upcoming hash computation. Each instance *internally* maintains the corresponding MHash-384 context. The application is required to create a separate `MHash384` instance for each ongoing MHash-384 hash computation; it is possible to re-use an `MHash384` instance for multiple MHash-384 hash computations, provided that those hash computations are strictly serialized.
 287 *Note:* The application is required to allocate the memory for the `MHash384` instance. If the instance was allocated on the heap (*dynamic* storage duration), the application is also required to explicitly destroy the instance, when no longer needed.
 288
 289 ### MHash384::update() [1]
 290
 291         void MHash384::update(const std::uint8_t *const data, const size_t len)
 292
 293 Process next chunk of input data. This function performs the actual MHash-384 hash computation, in an incremental way. The function processes the next **N** bytes of input data and updates the internal MHash-384 context accordingly. The application is supposed to call this function in a loop, on the *same* `MHash384` instance, until all input has been processed.
 294
 295 *Parameters:*
 296
 297 * `const uint8_t *data_in`
 298   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 to be processed.
 299   *Note:* Formally, the input data is defined as an array of byte (`uint8_t`). Nonetheless, *any* kind of input data can be processed, by applying the proper *typecast* operator. For numeric values, the platform's [endianness](https://en.wikipedia.org/wiki/Endianness) applies!
 300
 301 * `size_t len`
 302   The *length* of the input data to be processed, *in bytes*. Specify `sizeof(T) * count` for data types **T** other than byte.
 303   *Note:* All *bytes* in the range from `data_in[0]` up to and including `data_in[len-1]` will be processed as input.
 304
 305 ### MHash384::update() [2]
 306
 307         template<size_t size>
 308         void MHash384::update(const std::array<std::uint8_t, size> &data)
 309
 310 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::array<uint8_t, N>` as input.
 311
 312 *Parameters:*
 313
 314 * `const std::array<uint8_t, N> &data`
 315   Read-only reference to the `std::array<uint8_t, N>` containing the input data to be processed.
 316   *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input.
 317
 318 ### MHash384::update() [3]
 319
 320         void MHash384::update(const std::vector<std::uint8_t> &data)
 321
 322 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::vector<uint8_t>` as input.
 323
 324 *Parameters:*
 325
 326 * `const std::vector<std::uint8_t> &data`
 327   Read-only reference to the `std::vector<uint8_t>` containing the input data to be processed.
 328   *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input.
 329
 330 ### MHash384::update() [4]
 331
 332         void MHash384::update(const std::string &text)
 333
 334 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::string` as input.
 335
 336 *Parameters:*
 337
 338 * `const std::string &text`
 339   Read-only reference to the `std::string` containing the input data to be processed.
 340   *Note:* All characters in the range from `text[0]` up to and including `text[text.length()-1]` will be processed as input. Each character in the `std::string` is processed as a *byte* value, disregarding any specific character encoding.
 341
 342 ### MHash384::update() [5]
 343
 344         void MHash384::update(const char *const text)
 345
 346 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a NULL-terminated C string as input.
 347
 348 *Parameters:*
 349
 350 * `const char *const text`
 351   Read-only pointer to the first character of the NULL-terminated string to be processed.
 352   *Note:* All characters in the range from `text[0]` up to and including `text[strlen(text)-1]` will be processed as input. Each character in the C string is processed as a *byte* value, disregarding any specific character encoding.
 353
 354 ### MHash384::update() [6]
 355
 356         template<typename element_type>
 357         void MHash384::update(const element_type *const address);
 358
 359 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a pointer.
 360
 361 *Parameters:*
 362
 363 * `const element_type *const address`
 364   Read-only pointer to the target object to be processed.
 365   *Note:* The given object is processed as a byte-sequence, like a POD; all bytes in the range from `address[0]` up to and including `address[sizeof(element_type)-1]` will be processed as input.
 366
 367 ### MHash384::update() [7]
 368
 369         template<typename element_type>
 370         void MHash384::update(const element_type &element);
 371
 372 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a reference.
 373
 374 *Parameters:*
 375
 376 * `const element_type &element`
 377   Read-only reference to the target object to be processed.
 378   *Note:* The given object is processed as a byte-sequence, like a POD; all bytes in the range from `addr[0]` up to and including `addr[sizeof(element_type)-1]` with `addr = std::addressof(element)` will be processed as input.
 379
 380 ### MHash384::update() [8]
 381
 382         template<typename iterator_type>
 383         void MHash384::update(const iterator_type &first, const iterator_type &last)
 384
 385 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a sequence of elements via iterators.
 386
 387 *Parameters:*
 388
 389 * `const iterator_type &first`
 390   Read-only reference to the iterator designating the *first* element to be processed.
 391   *Note:* All elements in the range from `*first` up to but excluding `*last` will be processed as input. Each element in this range is processed as a byte-sequence, like a POD, assuming a size of `sizeof(iterator_type::value_type)`.
 392
 393 * `const iterator_type &last`
 394   Read-only reference to the iterator designating the element just after the *last* element to be processed.
 395   *Note:* All elements in the range from `*first` up to but excluding `*last` will be processed as input. Each element in this range is processed as a byte-sequence, like a POD, assuming a size of `sizeof(iterator_type::value_type)`.
 396
 397 ### MHash384::finish()
 398
 399         const std::uint8_t *MHash384::finish(void)
 400
 401 Retrieve final hash value. This function completes the MHash-384 hash computation. The function finalizes the internal MHash-384 context, if it was not finalized yet, and returns a pointer to the buffer containing the resulting hash value. Once this function has been called, the `MHash384` instance remains in the *finalized* state, until it is [reset](#mhash384reset).
 402
 403 ***Warning:*** Trying to process more input data while the `MHash384` instance is in *finalized* state will throw an exception!
 404
 405 *Return value:*
 406
 407 * Returns a read-only pointer to the internal buffer containing the final hash value; this buffer is owned by the `MHash384` instance. The size of the MHash-384 hash value, in bytes, is equal to `MHASH384_SIZE`.
 408   *Note:* This pointer remains valid only until the `MHash384` instance is [reset](#mhash384reset) or destroyed. If the hash value needs to be retained after the instance was reset/destroyed, the application must copy the hash value to a separate buffer!
 409
 410 ### MHash384::reset()
 411
 412         void MHash384::reset(void)
 413
 414 Reset the MHash-384 hash computation. This function re-initializes the internal MHash-384 context, thus starting a new MHash-384 hash computation. It is **not** necessary to explicitly call this function on a new `MHash384` instance; it is called implicitly by the constructor. However, it is possible to re-use an existing `MHash384` instance for multiple (strictly serialized) MHash-384 hash computations, by calling this function in between each pair of consecutive hash computations.
 415
 416
 417 # Supported platforms
 418
 419 MHash-384 has been tested to successfully build and run on (at least) the following platforms:
 420
 421 ## C/C++ library and CLI front-end
 422
 423 * **Microsoft Windows (x84/x64)**
 424     - Microsoft Visual C++, version 16.00 (Visual Studio 2010) or newer
 425     - Mingw-w64 (from MSYS2), tested with version 8.0.0, using GCC 9.2.0 or Clang 9.0.0
 426     - MinGW (mingw.org), tested with version 5.3.2, using GCC 8.2.0
 427     - Cygwin, tested with version 3.1.2 (x64), using GCC 7.4.0 or Clang 8.0.1
 428
 429 * **Linux/GNU (x86/x64)**
 430     - Ubuntu, tested with version 16.04 (Xenial), using GCC 5.4.0 or Clang 3.8.0
 431     - CentOS/Red Hat Enterprise Linux, tested with version 8.1, using GCC 8.3.1 or Clang 8.0.1
 432     - Manjaro, tested with version 18.1.5, using GCC 9.2.0 or Clang 9.0.1
 433     - openSUSE (Leap), tested with version 15.1, using GCC 7.5.0 or Clang 7.0.1
 434
 435 * **BSD-Family (x86/x64)**
 436     - FreeBSD, tested with TrueOS version 18.12, using GCC 7.4.0 or Clang 7.0.1
 437     - OpenBSD, tested with version 6.6, using GCC 8.2.0 or Clang 8.0.1
 438
 439 * **Solaris (x86/x64)**
 440     - OpenSolaris/Illumos, tested with OpenIndiana version 2019.10, using GCC 9.2.0
 441
 442 ## Ports to other lanuguages
 443
 444 * **Java**
 445     - Java SE 8, tested with OpenJDK Runtime Environment 1.8.0_242
 446     - Java SE 11, tested with OpenJDK Runtime Environment 11.0.5
 447
 448 * **.NET Framework**
 449     - Microsoft.NET Framework 4.5 (or newer), tested with Visual Studio 2019 (version 15.9.20)
 450     - Mono, tested with Mono C# Compiler version 5.18.0 (Ubuntu 19.10)
 451
 452 * **Python**
 453     - CPython 3.x, tested with version 3.8.1
 454     - PyPy (Python 3.6 compatible), tested with version 7.3.0, highly recommended for improved performance!
 455
 456 * **Delphi (Object Pascal)**
 457     - Bordland Delphi, tested with Delphi 7.1 (DCC 15.00)
 458     - Lazarus/Free Pascal, tested with Lazarus 2.06 (Free Pascal Compiler 3.04)
 459
 460
 461 # Build instructions
 462
 463 The MHash-384 C/C++ library and CLI front-end can be built using (at least) one of the following build systems:
 464
 465 ## Microsoft Visual C++
 466
 467 MHash-384 can be built for the Windows platform using the **Microsoft Visual C++** compiler, version 16.00 or later.
 468
 469 The provided project/solution files should build successfully with *Visual Studio 2010* or later. However, be aware that it may be necessary to adjust the "Platform Toolset" to your specific version of Visual Studio in all projects! Build configurations are available for both, *32-Bit* (`Win32`) and *64-Bit* (`x64`) Windows, but the 64-Bit flavor is recommended for best performance.
 470
 471 Note: You can download the latest version of the Visual Studio "Community" edition for free from the [official web-site](https://visualstudio.microsoft.com/).
 472
 473 ### Command-line usage
 474
 475 Building MHash-384 from the developer command prompt is supported via the MSBuild tool:
 476
 477     MSBuild.exe /property:Configuration=Release /property:Platform=x64 /target:Rebuild "MHash384.sln"
 478
 479 ## GNU  C/C++ compiler
 480
 481 MHash-384 can be built using the **GNU  C/C++ compiler (GCC)**, version 4.8 or later, or any GCC-compatible compiler, such as Clang/LLVM, on a wide range of platforms; supported platforms include Linux, the BSD family, Solaris and Windows.
 482
 483 The provided makefiles should build successfully with GNUmake on any supported platform. GNUmake is the default `make` implementation on Linux/GNU, but may need to be installed separately and invoked as `gmake` on BSD and Solaris. GCC or a GCC-compatible compiler (e.g. Clang/LLVM) is available out-of-the-box on most supported platforms; otherwise it can usually be installed from the system's package manager. Please see the documentation of your specific distribution for details!
 484
 485 ### Command-line usage
 486
 487 In order to build MHash-384, simply run **`make`** from the MHash-384 base directory, for example:
 488
 489     $ make -B MARCH=x86-64 MTUNE=intel STATIC=1
 490
 491 ### Make file parameters
 492
 493 The following options can be used to tweak the behavior of the provided makefiles:
 494
 495 * **`MARCH`**: Generate machine code for the specified CPU type, see [*-march*](https://gcc.gnu.org/onlinedocs/gcc-9.2.0/gcc/x86-Options.html#index-march-14) for details (default is `native`)
 496 * **`MTUNE`**: Tune the generated machine code for the specified CPU type, see [*-mtune*](https://gcc.gnu.org/onlinedocs/gcc-9.2.0/gcc/x86-Options.html#index-mtune-16) for details (default is `native`)
 497 * **`STATIC`**: If set to `1`, link with *static* CRT libraries; otherwise link with *shared* CRT libraries (default is `0`)
 498 * **`DEBUG`**: If set to `1`, generate a binary suitable for debugging; otherwise generate an optimized binary (default is `0`)
 499 * **`NODOCS`**: If set to `1`, the HTML documents are **no** generated; useful where pandoc is unavailable (default is `0`)
 500 * **`SANITIZE`**: Instrument the binary with the specified sanitizer, e.g. `address` to enable the [*AddressSanitizer*](https://gcc.gnu.org/onlinedocs/gcc-9.2.0/gcc/Instrumentation-Options.html#index-fsanitize_003daddress) (*no* default)
 501
 502 The following options can be used to override the default tools used by the makefiles:
 503
 504 * **`CXX`**: The C++ compiler to be used (default is *system-specific*, e.g. `g++` or `clang++`)
 505 * **`AR`**: The archiver to be used (default is *system-specific*, usually `ar`)
 506 * **`STRIP`**: The strip program to be used (default is `strip`)
 507 * **`PNDC`**: The document converter to be used (default is `pandoc`)
 508 * **`TAR`**: The tarball program to be used (default is `tar`)
 509 * **`WNDRS`**: The Windows resource compiler to be used, used on Cygwin and MinGW only (default is `windres`)
 510 * **`ZIP`**: The zip program to be used, used on Cygwin and MinGW only (default is `zip`)
 511
 512 ### Windows support
 513
 514 It is possible to build MHash-384 with GCC or Clang/LLVM on the Windows platform thanks to [Cygwin](https://www.cygwin.com/) or [MinGW/MSYS](http://www.mingw.org/wiki/msys). However, if you want to build with GCC or Clang/LLVM on Windows nowadays, then it is *highly recommended* to use [**MSYS2**](https://www.msys2.org/) in conjunction with [**Mingw-w64**](http://mingw-w64.org/) – even for 32-Bit targets! The “old” Mingw.org (Mingw32) project is considered *deprecated*.
 515
 516 Just follow the basic **MSYS2** setup procedure, as described on the [official web-site](https://github.com/msys2/msys2/wiki/MSYS2-installation), then install Mingw-w64:
 517
 518     pacman -S base-devel mingw-w64-i686-toolchain mingw-w64-x86_64-toolchain
 519
 520 # Algorithm Description
 521
 522 This section contains a *pseudo-code* description of the **MHash-384** algorithm:
 523
 524 ## Constants
 525
 526 Pre-defined constants for MHash-384 computation:
 527
 528     const
 529       MHASH384_SIZE := 48                                         /*size of the hash, in bytes*/
 530       MHASH384_WORDS := 6                                         /*size of the hash, in 64-Bit words*/
 531       MHASH384_INI: array[0..MHASH384_WORDS-1] of UInt64          /*the initial state vector*/
 532       MHASH384_FIN: array[0..MHASH384_SIZE-1] of Byte             /*byte indices for the finalization routine*/
 533       MHASH384_XOR: array[0..256, 0..MHASH384_WORDS-1] of UInt64  /*LUT for XOR (exclusive or) constants*/
 534       MHASH384_ADD: array[0..256, 0..MHASH384_WORDS-1] of UInt64  /*LUT for ADD (arithmetic addition) constants*/
 535       MHASH384_MIX: array[0..255, 0..MHASH384_WORDS-1] of Byte    /*LUT containing the "mixing" indices*/
 536
 537 ***Note:*** The lookup tables **`MHASH384_XOR`** and **`MHASH384_ADD`** have been pre-computed in such a way that each of the 257 rows (each with a size of 48 Bytes) has a [hamming distance](https://en.wikipedia.org/wiki/Hamming_distance) of *at least* 182 bits to *any* other row. This ensures that, for each possible value an input byte can take, a *different* set of state bits will be "flipped" by the XOR (exclusive or) operation.
 538
 539 ## State
 540
 541 The state of an ongoing MHash-384 computation:
 542
 543     type MHash384State = record
 544       rnd: UInt8
 545       hash: array[0..MHASH384_WORDS-1] of UInt64
 546
 547 ## Initialization
 548
 549 Set up the MHash-384 state for a new hash computation:
 550
 551     procedure MHash384_Initialize
 552       state.rnd ← 0
 553       state.hash ← MHASH384_INI
 554
 555 ## Update Routine
 556
 557 Update the MHash-384 state with the next *N* input (message) bytes:
 558
 559     procedure MHash384_Update
 560       input:
 561         message: array[0..N-1] of Byte
 562       for each Byte b in message do
 563         _MHash364_Iterate(MHASH384_XOR[b], MHASH384_ADD[b],  MHASH384_MIX[rnd])
 564         state.rnd ← (state.rnd + 1) mod 256
 565
 566 ***Note:*** This routine can be invoked multiple times in order to process in the input message in "chunks" of arbitrary size.
 567
 568 ## Finalization Routine
 569
 570 Compute the final hash value (digest), once all input has been processed:
 571
 572     procedure MHash384_Update
 573       var:
 574         previous: UInt16
 575       output:
 576         digest: array[0..MHASH384_SIZE-1] of Byte
 577       previous ← 256;
 578       for i = 0 to HASH384_SIZE-1 do
 579         _MHash364_Iterate(MHASH384_XOR[previous], MHASH384_ADD[previous],  MHASH384_MIX[rnd])
 580         state.rnd ← (state.rnd + 1) mod 256
 581         previous ← (digest[i] ← _MHash384_GetByte(MHASH384_FIN[i]))
 582
 583 ## Iteration Routine
 584
 585 Internal processing routine, used by the "update" and "finalization" routines:
 586
 587     procedure _MHash364_Iterate
 588       var:
 589         temp: array[0..MHASH384_WORDS-1] of UInt64
 590       input:
 591         xor_row: array[0..MHASH384_WORDS-1] of UInt64
 592         add_row: array[0..MHASH384_WORDS-1] of UInt64
 593         mix_row: array[0..MHASH384_WORDS-1] of Byte
 594       for i = 0 to HASH384_WORDS-1 do
 595         temp[i] ← Hash128to64(state.hash[i] + add_row[i], state.hash[mix_row[i]]) ⊻ xor_row[i]
 596       state.hash ← temp
 597
 598 ***Note:*** Here the **`⊻`** symbol denotes the bit-wise *XOR* (exclusive or) operator. Furthermore, the **`Hash128to64()`** routine is adopted from the function of the same name that appears in Google's *CityHash*. Please see [here](https://github.com/google/cityhash/blob/master/src/city.h) for details!
 599
 600 ## Extract Byte
 601
 602 Internal routine to extract a specific byte from the current state:
 603
 604     procedure _MHash384_GetByte
 605       input:
 606         index: Byte
 607       output:
 608         value: Byte
 609       value ← (state.hash[index ÷ 8] ≫ ((index mod 8) × 8)) mod 256
 610
 611 ***Note:*** Here the **`÷`** symbol denotes *integer division*, i.e. an arithmetic division in which the fractional part (remainder) is discarded. Furthermore, the **`≫`** symbol denotes the bit-wise *"right shift"* operator (shift bits to the right by **n** places).
 612
 613 # License
 614
 615 **MHash-384 - Simple fast portable secure hashing library**
 616 **&copy; 2016-2020 LoRd_MuldeR [&lt;mulder2@gmx.de&gt;](mailto:mulder2@gmx.de)**
 617
 618         Permission is hereby granted, free of charge, to any person obtaining a copy of this software
 619         and associated documentation files (the "Software"), to deal in the Software without
 620         restriction, including without limitation the rights to use, copy, modify, merge, publish,
 621         distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
 622         Software is furnished to do so, subject to the following conditions:
 623
 624         The above copyright notice and this permission notice shall be included in all copies or
 625         substantial portions of the Software.
 626
 627         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
 628         BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 629         NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 630         DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 631         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 632
 633 <https://opensource.org/licenses/MIT>
 634
 635
 636 # Version History
 637
 638 ## Version 2.0.0 [????-??-??]
 639
 640 * Initial release of the 2.x development cycle
 641
 642 &nbsp;
 643
 644 [■](https://www.youtube.com/watch?v=dng06ZqI4Ss)