README.md

   1 % ![](img/mhash384/MHash-384.jpg)
   2 MHash-384
   3 % Simple fast portable secure hashing library
   4
   5 # Introduction
   6
   7 **MHash-384** is a fast, portable and secure hashing library, released under the *MIT license*.
   8
   9 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).
  10
  11 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 and Linux. Furthermore, the MHash-384 library has already been *ported* to various other programming languages, including **Java**, **Microsoft.NET**, **Python** as well as **Delphi** and **Free Pascal**.
  12
  13
  14 # Quick Start Guide
  15
  16 In order to use the *MHash-384* library, simply include the header file `mhash384.h` in your code:
  17
  18         #include <mhash384.h>
  19
  20 ## Example for C language
  21
  22 If you source code is written in **C**, use the **`mhash384_t`** struct and the **`mhash384_XYZ()`** functions:
  23
  24         /*variables*/
  25         uint8_t buffer[BUFFSIZE];
  26         size_t len;
  27         uint8_t result[MHASH384_SIZE];
  28         mhash384_t mhash384;
  29
  30         /*initialization*/
  31         mhash384_init(&mhash384);
  32
  33         /*input data processing*/
  34         while(more_data())
  35         {
  36                 len = read_data(buffer, BUFFSIZE);
  37                 mhash384_update(&mhash384, buffer, len);
  38         }
  39
  40         /*finalization*/
  41         mhash384_final(&mhash384, result);
  42
  43 ## Example for C++ language
  44
  45 Or, if you source code is written in **C++**, use the provided **`MHash384`** wrapper class:
  46
  47         /*instance*/
  48         MHash384 mhash384;
  49
  50         /*input data processing*/
  51         while(more_data())
  52         {
  53                 const std::vector<uint8_t> buffer = read_data();
  54                 mhash384.update(buffer);
  55         }
  56
  57         /*finalization*/
  58         const uint8_t *result = mhash384.finish();
  59
  60
  61 # Command-line Usage
  62
  63 MHash-384 comes with a simple "standalone" command-line application, similar to the `sha1sum` or`sha256sum` utilities.
  64
  65 ## Synopsis
  66
  67 The MHash-384 command-line application takes a number of optional options followed by an one or more input files.
  68
  69 If **no** input file is specified, input will be read from standard input (*stdin*).
  70
  71 The digest will be written to the standard output (*stdout*). Diagnostic message are written to the standard error (*stderr*).
  72
  73         mhash384 [OPTIONS] [<FILE_1> <FILE_2> ... <FILE_N>]
  74
  75 ## Options
  76
  77 MHash-384 supports the following options:
  78
  79 * **`--keep-going`**
  80   Try to proceed with the remaining files, if a file has failed (e.g. access denied or file not found).
  81   Only applicable, if *multiple* files have been specified. Default behavior is to abort immediately when a file has failed.
  82
  83 * **`--short`**
  84   Print the digest in *short* format (**no** file names). Default format prints the digest followed by the file name.
  85
  86 * **`--lower-case`**
  87   Print the digest in *lower-case* letters. Default format prints the digest in *upper-case* letters.
  88   This option can only be used with the default *Hex* (hexadecimal) output format; it is **not** supported for Base64 format!
  89
  90 * **`--base64`**
  91   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.
  92
  93 * **`--help`**
  94   Print the help screen (manpage) and exit program.
  95
  96 * **`--version`**
  97   Print the program version (plus some build information) and exit program.
  98
  99 * **`--self-test`**
 100   Run self-test and exit program. This will process various standard test vectors and validate the resulting hashes.
 101   *Note:* Some test vectors contain very long inputs, therefore the computation can take a while to complete!
 102
 103 * **`--stress`**
 104   Enable stress test mode. This will process all test strings from the specified input file, expecting one string *per line*.
 105   All computed hash values are added to an `std::unordered_set`, thus checking for possible collisions.
 106
 107 * **`--benchmark`**
 108   Measure the overall time required for the operation. If specified, output the total amount of time elapsed, in seconds.
 109
 110 ## Output Format
 111
 112 In default operation mode, MHash-384 writes one line per input file to the standard output:
 113
 114         <HASH_VALUE> [SPACE SPACE <FILE_NAME>]
 115
 116 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.
 117
 118 Also, the file name will be printed, unless "short" format was requested. File names *may* contain a path!
 119
 120 #### Sample output {-}
 121
 122         BD41A203A61FE74178A8D507...33E553FD1569ED733C52BE8B  debian-7.9.0-amd64-DVD-1.iso
 123         EE328DDD4E116165252F1FF8...11729801097C51FB61D20184  debian-7.9.0-i386-DVD-1.iso
 124         A8B2007537867BDA0C18A264...45A1379AB8B4A77F9D8C8B24  debian-10.0.0-amd64-DVD-1.iso
 125
 126 ## Exit Code
 127
 128 On success, *zero* is returned. On error or user interruption, a *non-zero* error code is returned.
 129
 130 Note that, with "keep going" mode enabled, the exit code reflects whether *at least* one file was processed successfully.
 131
 132 ## Examples
 133
 134 Compute MHash-384 hash of a single file:
 135
 136         mhash384 "C:\Images\debian-8.3.0-amd64-DVD-1.iso"
 137
 138 Compute MHash-384 hash of *two* files:
 139
 140         mhash384 "C:\Images\debian-8.3.0-amd64-DVD-1.iso" "C:\Images\debian-8.3.0-i386-DVD-1.iso"
 141
 142 Compute MHash-384 hash of *multiple* files, using wildcard expansion ([globbing](https://en.wikipedia.org/wiki/Glob_(programming))):
 143
 144         mhash384 "C:\Images\*.iso"
 145
 146 Compute MHash-384 hash from data passed directly via [pipeline](https://en.wikipedia.org/wiki/Pipeline_(Unix)):
 147
 148         dd if=/dev/urandom bs=100 count=1 | mhash384
 149
 150
 151 # API Specification
 152
 153 ## Global definitions
 154
 155 Global definitions for both, the C and C++, API's.
 156
 157 ### MHASH384_SIZE
 158
 159 The size of the final MHash-384 hash value (digest), in bytes. This value is qual to `48U`.
 160
 161 ### MHASH384_WORDS
 162
 163 The number of words per MHash-384 hash. Each word has a size of 64 bits (`uint64_t`). This value is qual to `6U`.
 164
 165 ## API for C language
 166
 167 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!
 168
 169 ### mhash384_t
 170
 171         typedef struct mhash384_t;
 172
 173 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.
 174
 175 *Note:* Applications should treat this data-type as *opaque*, i.e. the application **must not** access the fields of the struct directly!
 176
 177 ### mhash384_init()
 178
 179         void mhash384_init(mhash384_t *const ctx);
 180
 181 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.
 182
 183 *Parameters:*
 184
 185 * `mhash384_t *ctx`
 186   Pointer to the MHash-384 context of type `mhash384_t` that will be initialized (reset) by this operation.
 187   *Note:* The MHash-384 library does **not** allocate the required memory; it must be allocated by the calling application!
 188
 189 ### mhash384_update()
 190
 191         void mhash384_update(mhash384_t *const ctx, const uint8_t *const data_in, const size_t len);
 192
 193 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.
 194
 195 *Parameters:*
 196
 197 * `mhash384_t *ctx`
 198   Pointer to the hash computation state of type `mhash384_t` that will be updated by this operation.
 199
 200 * `const uint8_t *data_in`
 201   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.
 202   *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!
 203
 204 * `size_t len`
 205   The *length* of the input data to be processed, *in bytes*. Specify `sizeof(T) * count` for data types **T** other than byte.
 206   *Note:* All *bytes* in the range from `data_in[0]` up to and including `data_in[len-1]` will be processed as input.
 207
 208 ### mhash384_final()
 209
 210         void mhash384_final(mhash384_t *const ctx, uint8_t *const digest_out);
 211
 212 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)!
 213
 214 *Parameters:*
 215
 216 * `mhash384_t *ctx`
 217   Pointer to the hash computation state of type `mhash384_t` that will be finalized by this operation.
 218   *Note:* The MHash-384 library does **not** free this memory; it may need to be freed up by the calling application!
 219
 220 * `uint8_t *digest_out`
 221   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`.
 222   *Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten!
 223
 224 ### mhash384_compute()
 225
 226         void mhash384_compute(uint8_t *const digest_out, const uint8_t *const data_in, const size_t len);
 227
 228 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.
 229
 230 *Parameters:*
 231
 232 * `uint8_t *digest_out`
 233   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`.
 234   *Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten!
 235
 236 * `const uint8_t *data_in`
 237   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.
 238   *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!
 239
 240 * `size_t len`
 241   The *length* of the input data to be processed, *in bytes*. Specify `sizeof(T) * count` for data types **T** other than byte.
 242   *Note:* All *bytes* in the range from `data_in[0]` up to and including `data_in[len-1]` will be processed as input.
 243
 244 ### mhash384_version()
 245
 246         void mhash384_version (uint16_t *const major, uint16_t *const minor, uint16_t *const patch);
 247
 248 Retrieve version information. This function returns the current version of the MHash-384 library.
 249
 250 *Parameters:*
 251
 252 * `uint16_t *major`
 253   Pointer to a variable of type `uint16_t` where the *major* version of the MHash-384 library will be stored.
 254
 255 * `uint16_t *minor`
 256   Pointer to a variable of type `uint16_t` where the *minor* version of the MHash-384 library will be stored.
 257
 258 * `uint16_t *patch`
 259   Pointer to a variable of type `uint16_t` where the *patch* level of the MHash-384 library will be stored.
 260
 261 ### mhash384_selftest()
 262
 263         bool mhash384_selftest(void);
 264
 265 Self-test routine. This function runs the built-in self-test of the MHash-384 library; intended for debugging purposes.
 266
 267 *Return value:*
 268
 269 * Returns `true`, if the self-test completed successfully; returns `false`, if any problems have been detected.
 270
 271 ## API for C++ language
 272
 273 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!
 274
 275 ### MHash384()
 276
 277         MHash384(void)
 278
 279 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.
 280 *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.
 281
 282 ### MHash384::update() [1]
 283
 284         void MHash384::update(const std::uint8_t *const data, const size_t len)
 285
 286 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.
 287
 288 *Parameters:*
 289
 290 * `const uint8_t *data_in`
 291   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.
 292   *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!
 293
 294 * `size_t len`
 295   The *length* of the input data to be processed, *in bytes*. Specify `sizeof(T) * count` for data types **T** other than byte.
 296   *Note:* All *bytes* in the range from `data_in[0]` up to and including `data_in[len-1]` will be processed as input.
 297
 298 ### MHash384::update() [2]
 299
 300         template<size_t size>
 301         void MHash384::update(const std::array<std::uint8_t, size> &data)
 302
 303 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::array<uint8_t, N>` as input.
 304
 305 *Parameters:*
 306
 307 * `const std::array<uint8_t, N> &data`
 308   Read-only reference to the `std::array<uint8_t, N>` containing the input data to be processed.
 309   *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input.
 310
 311 ### MHash384::update() [3]
 312
 313         void MHash384::update(const std::vector<std::uint8_t> &data)
 314
 315 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::vector<uint8_t>` as input.
 316
 317 *Parameters:*
 318
 319 * `const std::vector<std::uint8_t> &data`
 320   Read-only reference to the `std::vector<uint8_t>` containing the input data to be processed.
 321   *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input.
 322
 323 ### MHash384::update() [4]
 324
 325         void MHash384::update(const std::string &text)
 326
 327 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::string` as input.
 328
 329 *Parameters:*
 330
 331 * `const std::string &text`
 332   Read-only reference to the `std::string` containing the input data to be processed.
 333   *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.
 334
 335 ### MHash384::update() [5]
 336
 337         void MHash384::update(const char *const text)
 338
 339 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a NULL-terminated C string as input.
 340
 341 *Parameters:*
 342
 343 * `const char *const text`
 344   Read-only pointer to the first character of the NULL-terminated string to be processed.
 345   *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.
 346
 347 ### MHash384::update() [6]
 348
 349         template<typename element_type>
 350         void MHash384::update(const element_type *const address);
 351
 352 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a pointer.
 353
 354 *Parameters:*
 355
 356 * `const element_type *const address`
 357   Read-only pointer to the target object to be processed.
 358   *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.
 359
 360 ### MHash384::update() [7]
 361
 362         template<typename element_type>
 363         void MHash384::update(const element_type &element);
 364
 365 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a reference.
 366
 367 *Parameters:*
 368
 369 * `const element_type &element`
 370   Read-only reference to the target object to be processed.
 371   *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.
 372
 373 ### MHash384::update() [8]
 374
 375         template<typename iterator_type>
 376         void MHash384::update(const iterator_type &first, const iterator_type &last)
 377
 378 A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a sequence of elements via iterators.
 379
 380 *Parameters:*
 381
 382 * `const iterator_type &first`
 383   Read-only reference to the iterator designating the *first* element to be processed.
 384   *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)`.
 385
 386 * `const iterator_type &last`
 387   Read-only reference to the iterator designating the element just after the *last* element to be processed.
 388   *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)`.
 389
 390 ### MHash384::finish()
 391
 392         const std::uint8_t *MHash384::finish(void)
 393
 394 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).
 395
 396 ***Warning:*** Trying to process more input data while the `MHash384` instance is in *finalized* state will throw an exception!
 397
 398 *Return value:*
 399
 400 * 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`.
 401   *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!
 402
 403 ### MHash384::reset()
 404
 405         void MHash384::reset(void)
 406
 407 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.
 408
 409
 410 # License
 411
 412 **MHash-384 - Simple fast portable secure hashing library**
 413 **Copyright(c) 2016-2020 LoRd_MuldeR <mulder2@gmx.de>**
 414
 415         Permission is hereby granted, free of charge, to any person obtaining a copy of this software
 416         and associated documentation files (the "Software"), to deal in the Software without
 417         restriction, including without limitation the rights to use, copy, modify, merge, publish,
 418         distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
 419         Software is furnished to do so, subject to the following conditions:
 420
 421         The above copyright notice and this permission notice shall be included in all copies or
 422         substantial portions of the Software.
 423
 424         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
 425         BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 426         NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 427         DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 428         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 429
 430 <https://opensource.org/licenses/MIT>
 431
 432
 433 # Version History
 434
 435 ## Version 2.0.0 [????-??-??]
 436
 437 * Initial release of the 2.x development cycle
 438
 439 &nbsp;
 440
 441 [■](https://www.youtube.com/watch?v=dng06ZqI4Ss)