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 optional input file. If **no** input file is specified, or if input file is "-", input will be read from standard input stream (*stdin*).
  74
  75         mhash_384 [options] [input_file]
  76
  77 ## Options
  78
  79 MHash-384 supports the following options:
  80
  81 * **`-p`**, **`--progress`**
  82   Print the total size of the input file and the percentage processed so far to *stderr* while hash computation is running.
  83   If the total input size can **not** be determined (e.g. using pipe), the number of bytes processed so far is printed.
  84
  85 * **`-u`**, **`--upper`**
  86   Output the final digest (hash) in *upper case* Hex letters. Default mode is *lower case*.
  87
  88 * **`-b`**, **`--bench`**
  89   Compute performance statistics (e.g. bytes processed per second) and print them to the *stderr* at the end of the process.
  90
  91 * **`-v`**, **`--version`**
  92   Print library version to the *stdout* and exit program.
  93
  94 * **`-t`**, **`--test`**
  95   Run *built-in self-test* and exit program. Computes hashes from test vectors and compares results to reference hashes.
  96
  97 * **`-h`**, **`--help`**
  98   Print help screen (man page) and exit program.
  99
 100 ## Examples
 101
 102 Compute MHash-384 hash of a local file:
 103
 104         mhash_384 C:\Images\debian-8.3.0-amd64-DVD-1.iso"
 105
 106 Compute MHash-384 hash of a local file, with more verbose status outputs:
 107
 108         mhash_384 -p -b C:\Images\debian-8.3.0-amd64-DVD-1.iso"
 109
 110 Compute MHash-384 from random bytes, passing data directly from [`dd`](https://en.wikipedia.org/wiki/Dd_%28Unix%29) via pipe:
 111
 112         dd if=/dev/urandom bs=100 count=1 | mhash_384
 113
 114
 115 # Algoritm Description
 116
 117 This chapter describes the MHash-384 algorithm, as designed &ndash; from the scratch &ndash; by LoRd_MuldeR &lt;mulder2@gmx.de&gt;.
 118
 119 ## Informal Description
 120
 121 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.
 122
 123 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.
 124
 125 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&hellip;
 126
 127 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 &ndash; 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.
 128
 129 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 &ndash; with very high probability &ndash; when they are processed in a different order.
 130
 131 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.
 132
 133 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.
 134
 135 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.
 136
 137 ## Pseudocode
 138
 139 The MHash-384 algorithm can be summed up with the following simple pseudocode:
 140
 141         procedure mhash384
 142         const:
 143           HASH_SIZE = 48
 144           TABLE_XOR: array[257 × HASH_SIZE] of byte
 145           TABLE_MIX: array[997 × HASH_SIZE] of byte
 146         input:
 147           message: array[N] of byte
 148         output:
 149           hash: array[HASH_SIZE] of byte
 150         vars:
 151           round: integer
 152         begin
 153           /*initialization*/
 154           round ← 0
 155           for i = 0 to HASH_SIZE-1 do
 156             hash[i] ← 0x00
 157           done
 158
 159           /*input message processing*/
 160           for k = 0 to N-1 do
 161             for i = 0 to HASH_SIZE-1 do
 162               exchange hash[i] ⇄ hash[TABLE_MIX[round][i]]
 163               hash[i] ← hash[i] ⊕ TABLE_XOR[message[k]][i]
 164             done
 165             round ← (round + 1) mod 997
 166           done
 167
 168           /*finalization*/
 169           for i = 0 to HASH_SIZE-1 do
 170             hash[i] ← hash[i] ⊕ TABLE_XOR[256][i]
 171           done
 172         end.
 173
 174
 175 # Detailed API Specification
 176
 177 Global definitions for both, C and C++, API's.
 178
 179 ## Global definitions
 180
 181 ### MHASH_384_LEN
 182
 183 This constant specifies the length of a MHash-384 digest (hash value) in bytes/octets. It is equal to `48UL`.
 184
 185 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.
 186
 187 ### MHASH_384_VERSION_MAJOR
 188
 189 The MHash-384 library *major* version. Major release may change the API, so backwards compatibility is **not** guaranteed between different *major* versions.
 190
 191 Applications generally are written for a specific *major* version of the library.
 192
 193 ### MHASH_384_VERSION_MINOR
 194
 195 The MHash-384 library *minor* version. Minor releases may add new features, but they do **not** change the API in a way that would break backwards compatibility.
 196
 197 Applications may require a certain minimum *minor* version of the library, but will work with higher *minor* versions too.
 198
 199 ### MHASH_384_VERSION_PATCH
 200
 201 The MHash-384 library *patch* level. Patch releases may include bugfixes and optimizations, but they do **not** add new features or change the API.
 202
 203 Application code does **not** need to care about the *patch* level of the library.
 204
 205 ## API for for C language
 206
 207 All functions described in the following are *reentrant*, but **not** *thread-safe*. This means that *multiple* hash computation *can* be performed safely in an "interleaved" fashion, as long as each hash computation uses its own separate state variable. Also, multiple hash computation *can* be performed safely in "concurrent" threads, as long as each thread uses its own separate state variable. If, however, the *same* state variable needs to be accessed from *different* "concurrent" threads, then the application **must** *serialize* the function calls, e.g. by means of a *mutex lock*.
 208
 209 ### mhash_384_t
 210
 211         typedef struct mhash_384_t;
 212
 213 The `mhash_384_t` data-type is used to maintain the hash computation state. Use one instance (variable) of `mhash_384_t` for each ongoing hash computation. The memory for the `mhash_384_t` instance must be allocated/maintained by the calling application.
 214
 215 *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!
 216
 217 ### mhash_384_initialize()
 218
 219         void mhash_384_initialize(mhash_384_t *const ctx);
 220
 221 This function is used to initialize (or to reset) the hash computation, i.e. it will set up the initial hash computation state. The application is required to call this function *once* for each hash computation. The function has to be called **before** any input data is processed!
 222
 223 *Parameters:*
 224
 225 * `mhash_384_t *ctx`
 226   Pointer to the hash computation state of type `mhash_384_t` that will be initialized (reset) by this operation. The previous state will be lost!
 227
 228 ### mhash_384_update()
 229
 230         void mhash_384_update(mhash_384_t *const ctx, const uint8_t *const input, const size_t len);
 231
 232 This function is used to process the next **N** bytes (octets) of input data. It will update the hash computation state accordingly. The application needs to call this function repeatedly, on the *same* state variable (`mhash_384_t`), until all input data has been processed.
 233
 234 *Parameters:*
 235
 236 * `mhash_384_t *ctx`
 237   Pointer to the hash computation state of type `mhash_384_t` that will be updated by this operation.
 238
 239 * `const uint8_t *input`
 240   Pointer to the input data to be processed by this operation. The input data needs to be located in one continuous block of memory. The given pointer specifies the *base address* of the input data, i.e. the address of the *first* byte (octet) to be processed.
 241   *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 input data can be processed using the proper *typecast* operator.
 242
 243 * `size_t len`
 244   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!
 245
 246 ### mhash_384_finalize()
 247
 248 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.
 249
 250 *Note:* The hash computation state is treated *read-only* by this function. This means that the application *may* call the function at any time to get an "intermediate" hash of all input bytes (octets) process *so far* and then continue to process more input bytes (octets).
 251
 252         void mhash_384_finalize(const mhash_384_t *const ctx, uint8_t *const output);
 253
 254 * `const mhash_384_t *ctx`
 255   Pointer to the hash computation state of type `mhash_384_t` from which the final digest is computed.
 256
 257 * `uint8_t *output`
 258   Pointer to the memory block where the final digest (hash value) will be stored. This memory needs to be allocated by the calling application! The digest will be written to the memory addresses from `output` up to and including `output+(MHASH_384_LEN-1)`.
 259
 260 ## API for for C++ language
 261
 262 All classes described in the following are *reentrant*, but **not** *thread-safe*. This means that *multiple* hash computation *can* be performed safely in an "interleaved" fashion, as long as each hash computation uses its own separate object (instance). Also, multiple hash computation *can* be performed safely in "concurrent" threads, as long as each thread uses its own separate object (instance). If, however, the *same* object (instance) needs to be accessed from *different* "concurrent" threads, then the application **must** *serialize* the method calls, e.g. by means of a *mutex lock*.
 263
 264 *Note:* The classes described in the following live in the `mhash` namespace. Any functions, data-types or constants in the `mhash::internals` namespace should be regarded *opaque* by the application, as those may be subject to change in future library versions!
 265
 266 ### Constructor
 267
 268         MHash384::MHash384(void);
 269
 270 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.
 271
 272 ### update() [1]
 273
 274         void MHash384::update(const uint8_t *const input, const size_t len);
 275
 276 This method is used to process the next **N** bytes (octets) of input data. It will update the hash computation state accordingly. The application needs to call this method repeatedly, on the *same* `MHash364` instance, until all input data has been processed.
 277
 278 *Parameters:*
 279
 280 * `const uint8_t *input`
 281   Pointer to the input data to be processed by this operation. The input data needs to be located in one continuous block of memory. The given pointer specifies the *base address* of the input data, i.e. the address of the *first* byte (octet) to be processed.
 282   *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 input data can be processed using the proper *typecast* operator.
 283
 284 * `size_t len`
 285   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!
 286
 287 ### update() [2]
 288
 289         void MHash384::update(const std::vector<uint8_t> &input, const size_t offset = 0, const size_t len = 0);
 290
 291 This method is used to process input a `std::vector<uint8_t>` as input. It will update the hash computation state accordingly. The application needs to call this method repeatedly, on the *same* `MHash364` instance, until all input data has been processed.
 292
 293 *Parameters:*
 294
 295 * `const std::vector<uint8_t> &input`
 296   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.
 297
 298 * `size_t offset`
 299   Optional. Specifies the *zero-based* index of the *first* vector element to be processed. By default, processing starts at index **0**.
 300
 301 * `size_t len`
 302   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 processed.
 303
 304 ### update() [3]
 305
 306         void MHash384::update(const std::string &input, const size_t offset = 0, const size_t len = 0);
 307
 308 This method is used to process input a `std::string` as input. It will update the hash computation state accordingly. The application needs to call this method repeatedly, on the *same* `MHash364` instance, until all input data has been processed.
 309
 310 *Parameters:*
 311
 312 * `const std::vector<uint8_t> &input`
 313   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.
 314
 315 * `size_t offset`
 316   Optional. Specifies the *zero-based* index of the *first* character in the string to be processed. By default, processing starts at index **0**.
 317
 318 * `size_t len`
 319   Optional. Specifies the number of character to be processed. All characters from index `offset` up to and including index `offset+(len-1)` will be processed. By default, the whole string, excluding the terminating `NULL` character, is processed.
 320
 321 ### finalize() [1]
 322
 323         void MHash384::finalize(uint8_t *const output) const;
 324
 325 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.
 326
 327 *Note:* The hash computation state is treated *read-only* by this method. This means that the application *may* call the method at any time to get an "intermediate" hash of all input bytes (octets) process *so far* and then continue to process more input bytes (octets).
 328
 329 *Parameters:*
 330
 331 * `uint8_t *output`
 332   Pointer to the memory block where the final digest (hash value) will be stored. This memory needs to be allocated by the calling application! The digest will be written to the memory addresses from `output` up to and including `output+(MHASH_384_LEN-1)`.
 333
 334 ### finalize() [2]
 335
 336         std::vector<uint8_t> MHash384::finalize(void) const;
 337
 338 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.
 339
 340 *Note:* The hash computation state is treated *read-only* by this method. This means that the application *may* call the method at any time to get an "intermediate" hash of all input bytes (octets) process *so far* and then continue to process more input bytes (octets).
 341
 342 *Return value:*
 343
 344 * 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).
 345
 346
 347 # Supported Platforms
 348
 349 MHash-384 library should compile on any standard-compliant C/C++ compiler. In particular, the following platforms have been tested successfully:
 350
 351 * Microsoft Windows
 352     - Microsoft C/C++ Compiler, using Visual Studio 2010 or later
 353     - MinGW, using Mingw-w64 from [MSYS2](https://msys2.github.io/) project
 354 * Intel C/C++ Compiler, version Version 15.0 (XE 2015) or later
 355 * GNU/Linux, using GCC/G++, version 4.7 or later
 356
 357 # Language Bindings
 358
 359 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.
 360
 361 ## Microsoft.NET
 362
 363 Bindings of the MHash-384 library are provided for **Microsoft.NET**, in the form of the `MHashDotNet384.dll` assembly.
 364
 365 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:
 366
 367         using MHashDotNet384;
 368
 369         String ComputeHash(FileStream fs)
 370         {
 371                 byte[] buffer = new byte[4096];
 372                 MHash384 digest = new MHash384();
 373                 while (true)
 374                 {
 375                         int count = fs.Read(buffer, 0, buffer.Length);
 376                         if (count > 0)
 377                         {
 378                                 digest.Update(buffer, 0, count);
 379                                 continue;
 380                         }
 381                         break;
 382                 }
 383                 return digest.ToString();
 384         }
 385
 386 ### Prerequisites
 387
 388 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.
 389
 390 ## Java
 391
 392 Bindings of the MHash-384 library are provided for **Java**, in the form of the `MHashJava384.jar` library.
 393
 394 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:
 395
 396         import com.muldersoft.mhash384.MHash384;
 397
 398         String computeHash(final InputStream inputStream) throws IOException {
 399                 final byte[] buffer = new byte[4096];
 400                 final MHash384 mhash384 = new MHash384()
 401                 int count;
 402                 do {
 403                         count = inputStream.read(buffer);
 404                         if(count > 0) {
 405                                 mhash384.update(buffer, 0, count);
 406                         }
 407                 }
 408                 while(count == buffer.length);
 409                 return mhash384.digest().toString();
 410         }
 411
 412 ### Prerequisites
 413
 414 In order to use the MHash-384 library in your Java project, the `MHashJava384.jar` **must** be added to the Java *build path*.
 415
 416 ## Python
 417
 418 Bindings of the MHash-384 library are provided for **Python**, in the form of the `MHashPy384.py` module.
 419
 420 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:
 421
 422         from MHashPy384 import MHash384
 423
 424         mhash384 = MHash384()
 425         for chunk in read_chunks(fs):
 426                 mhash384.update(chunk)
 427         print(binascii.hexlify(mhash384.digest()))
 428
 429 ### Prerequisites
 430
 431 In order to use the MHash-384 library in your Python project, the `MHashPy384.py` **must** be in your Python *library path*.
 432
 433 The `MHashPy384.py` module requires the [***NumPy***](http://www.numpy.org/) package to be installed. See [*here*](https://scipy.org/install.html) for install instructions!
 434
 435 ## Delphi
 436
 437 Bindings of the MHash-384 library are provided for **Delphi**, in the form of the `MHash384.pas` unit.
 438
 439 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:
 440
 441         uses
 442                 {...}, MHash384;
 443
 444         function ComputeHash(var inputFile: File): TByteArray;
 445         var
 446                 digest: TMHash384;
 447                 buffer: TByteArray;
 448                 count: Integer;
 449         begin
 450                 SetLength(buffer, 4096);
 451                 digest := TMHash384.Create();
 452                 try
 453                         while not Eof(inputFile) do
 454                         begin
 455                                 BlockRead(inputFile, buffer[0], Length(buffer), count);
 456                                 if count > 0 then
 457                                 begin
 458                                         digest.Update(buffer, 0, count);
 459                                 end;
 460                         end;
 461                         digest.Result(Result);
 462                 finally
 463                         digest.Destroy();
 464                 end;
 465         end;
 466
 467 ### Prerequisites
 468
 469 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.
 470
 471
 472 # Source Code
 473
 474 The MHash-384 source is available from the official [**git**](https://git-scm.com/) mirrors:
 475
 476 * `git clone https://github.com/lordmulder/mhash-384.git` [[Browse](https://github.com/lordmulder/mhash-384)]
 477
 478 * `git clone https://bitbucket.org/muldersoft/mhash-384.git` [[Browse](https://bitbucket.org/muldersoft/mhash-384)]
 479
 480 * `git clone https://git.assembla.com/mhash-384.git` [[Browse](https://www.assembla.com/spaces/mhash-384/git/source)]
 481
 482 * `git clone https://gitlab.com/lord_mulder/mhash-384.git` [[Browse](https://gitlab.com/lord_mulder/mhash-384)]
 483
 484
 485 # Build Instructions
 486
 487 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.
 488
 489 * For supported versions of *Microsoft Visual Studio*, MHash-384 library ships with project/solution files, which will compile "out of the box".
 490
 491 * The *Intel C/C++ Compiler* integrates into Visual Studio, so simply select "Use Intel C++" from the project/solution menu.
 492
 493 * 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!
 494
 495 * 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.
 496
 497 ## Influential Environment Variables
 498
 499 The following environment variables may effect the build process and need to be set carefully:
 500
 501 * **Java:**
 502     - `JAVA_HOME`: The *Java* "home" directory, should be pointing to JDK (*not* JRE) root directory
 503     - `ANT_HOME`: The *Apache Ant* "home" directory, should be pointing to root directory
 504
 505 * **Python:**
 506     - `PYTHON_INC`: Directory to look for Python *include* files (typically `<PYTHON_INSTALL_PATH>/include`)
 507     - `PYTHON_LIB32`: Directory to look for 32-Bit (x86) Python *library* files (typically `<PYTHON_X86_PATH>/libs`)
 508     - `PYTHON_LIB64`: Directory to look for 64-Bit (x64) Python *library* files (typically `<PYTHON_X64_PATH>/libs`)
 509
 510 * **Delphi:**
 511     - `DELPHI_PATH`: The *Borland Delphi* installation directory (for Windows only)
 512
 513 * **Makefile:**
 514     - `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!
 515     - `CPLUSPLUS`:  If set to `1`, build CLI front-end from *C++* sources, otherwise from *plain C* sources (defaults to `0`)
 516     - `NO_JAVA`: If set to `1`, the *Java* bindings are **not** built (defaults to `0`, i.e. *do* build)
 517     - `NO_PYTHON`: If set to `1`, the *Python* bindings are **not** built (defaults to `0`, i.e. *do* build)
 518
 519 * **Windows:**
 520     - `MSVC_PATH`: *Microsoft Visual C++* installation directory
 521     - `PDOC_PATH`: *Pandoc v2.x* installation directory
 522     - `GIT2_PATH`: *Git for Windows* (formerly *MSYS Git*) installation directory
 523
 524
 525 # License
 526
 527 **Copyright(c) 2016-2017 LoRd_MuldeR &lt;mulder2@gmx.de&gt;, released under the MIT License.**
 528 **Check <http://muldersoft.com/> or <http://muldersoft.sourceforge.net/> for updates!**
 529
 530         Permission is hereby granted, free of charge, to any person obtaining a copy of this software
 531         and associated documentation files (the "Software"), to deal in the Software without
 532         restriction, including without limitation the rights to use, copy, modify, merge, publish,
 533         distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
 534         Software is furnished to do so, subject to the following conditions:
 535
 536         The above copyright notice and this permission notice shall be included in all copies or
 537         substantial portions of the Software.
 538
 539         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
 540         BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 541         NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 542         DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 543         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 544
 545 <https://opensource.org/licenses/MIT>
 546
 547
 548 # Version History
 549
 550 ## Version 1.1.0 [2017-12-22]
 551
 552 * Re-generated the XOR- and MIX-tables with higher hamming distance for increased hash quality
 553
 554 *  ***Note:*** This change, unfortunately, breaks compatibility with v1.0 hashes!
 555
 556 * All language bindings have been *replaced* by full ports of the library to the respective language
 557
 558 ## Version 1.0.1 [2016-03-31]
 559
 560 * Added language bindings for *Java*.
 561
 562 * Added language bindings for *Microsoft.NET*.
 563
 564 * Added language bindings for *Python*.
 565
 566 * Added language bindings for *Delphi*.
 567
 568 ## Version 1.0.0 [2016-03-03]
 569
 570 * First public release.
 571
 572 &nbsp;
 573
 574 [■](https://www.youtube.com/watch?v=dng06ZqI4Ss)