README.md

   1 % MHash-384
   2 % Simple fast portable header-only hashing library
   3
   4
   5 # Quick Start Guide
   6
   7 In order to use the *MHash-384* library, simply include the header file in your *C* or *C++* source code file. This is the *only* file you are ever going to need; linking any additional library files to your program is **not** required.
   8
   9         #include "mhash_384.h"
  10
  11 ## Example for C language
  12
  13 If you source code is written in plain **C**, simply use the provided *global* functions:
  14
  15         /*variables*/
  16         const uint8_t *data_ptr;
  17         uint32_t data_len;
  18         uint8_t result[MHASH_384_LEN];
  19         mhash_384_t context;
  20
  21         /*initialization*/
  22         mhash_384_initialize(&context);
  23
  24         /*input data processing*/
  25         while(have_more_data())
  26         {
  27                 data_ptr = fetch_next_data_chunk(&data_len);
  28                 mhash_384_update(&context, data_ptr, data_len);
  29         }
  30
  31         /*finalization*/
  32         mhash_384_finalize(&context, result);
  33
  34 ## Example for C++ language
  35
  36 And, if you source code is written in **C++**, the *MHash384* class from *mhash* namespace is used:
  37
  38         /*variables*/
  39         std::vector<uint8_t> data;
  40         uint8_t result[MHASH_384_LEN];
  41
  42         /*construction*/
  43         mhash::MHash384 instance;
  44
  45         /*input data processing*/
  46         while(have_more_data())
  47         {
  48                 data = fetch_next_data_chunk();
  49                 instance.update(data);
  50         }
  51
  52         /*finalization*/
  53         instance.finalize(result);
  54
  55
  56 # Command-line Usage
  57
  58 MHash-384 comes with a simple "standalone" command-line application. This program primarily serves as an example on how to use the MHash-384 library. However, the command-line application may also come in handy to quickly compute MHash-384 checksums (hashes) of local files. Furthermore, the MHash-384 program integrates nicely into the "pipes and filters" design pattern, by processing arbitrary inputs from the standard input stream. Computed checksums (hashes) will be written to the standard output stream, as a Hex string.
  59
  60 ## Synopsis
  61
  62 MHash-384 takes a number of optional options followed by an optional input file. If **no** input file is specified, or if input file is "-", input will be read from standard input stream (*stdin*).
  63
  64         mhash_384 [options] [input_file]
  65
  66 ## Options
  67
  68 MHash-384 supports the following options:
  69
  70 * `-p`, `--progress`
  71   Print the total size of the input file and the percentage processed so far to *stderr* while hash computation is running.
  72   If the total input size can **not** be determined (e.g. using pipe), the number of bytes processed so far is printed.
  73
  74 * `-u`, `--upper`
  75   Output the final digest (hash) in *upper case* Hex letters. Default mode is *lower case*.
  76
  77 * `-b`, `--bench`
  78   Compute performance statistics (e.g. bytes processed per second) and print them to the *stderr* at the end of the process.
  79
  80 * `-v`, `--version`
  81   Print library version to the *stdout* and exit program.
  82
  83 * `-t`, `--test`
  84   Run *built-in self-test* and exit program. Computes hashes from test vectors and compares results to reference hashes.
  85
  86 * `-h`, `--help`
  87   Print help screen (man page) and exit program.
  88
  89 ## Examples
  90
  91 Compute MHash-384 hash of a local file:
  92
  93         mhash_384 C:\Images\debian-8.3.0-amd64-DVD-1.iso"
  94
  95 Compute MHash-384 hash of a local file, with more verbose status outputs:
  96
  97         mhash_384 -p -b C:\Images\debian-8.3.0-amd64-DVD-1.iso"
  98
  99 Compute MHash-384 from random bytes, passing data directly from [`dd`](https://en.wikipedia.org/wiki/Dd_%28Unix%29) via pipe:
 100
 101         dd if=/dev/urandom bs=100 count=1 | mhash_384
 102
 103
 104 # Detailed API Specification
 105
 106 Global definitions for both, C and C++, API's.
 107
 108 ## Global definitions
 109
 110 ### MHASH_384_LEN
 111
 112 This constant specifies the length of a MHash-384 digest (hash value) in bytes/octets. It is equal to `48UL`.
 113
 114 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.
 115
 116 ### MHASH_384_VERSION_MAJOR
 117
 118 The MHash-384 library *major* version. Major release may change the API, so backwards compatibility is **not** guaranteed between different *major* versions.
 119
 120 Applications generally are written for a specific *major* version of the library.
 121
 122 ### MHASH_384_VERSION_MINOR
 123
 124 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.
 125
 126 Applications may require a certain minimum *minor* version of the library, but will work with higher *minor* versions too.
 127
 128 ### MHASH_384_VERSION_PATCH
 129
 130 The MHash-384 library *patch* level. Patch releases may include bugfixes and optimizations, but they do **not** add new features or change the API.
 131
 132 Application code does **not** need to care about the *patch* level of the library.
 133
 134 ## API for for C language
 135
 136 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*.
 137
 138 ### mhash_384_t
 139
 140         typedef struct mhash_384_t;
 141
 142 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.
 143
 144 *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!
 145
 146 ### mhash_384_initialize()
 147
 148         void mhash_384_initialize(mhash_384_t *const ctx);
 149
 150 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!
 151
 152 *Parameters:*
 153
 154 * `mhash_384_t *ctx`
 155   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!
 156
 157 ### mhash_384_update()
 158
 159         void mhash_384_update(mhash_384_t *const ctx, const uint8_t *const input, const size_t len);
 160
 161 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.
 162
 163 *Parameters:*
 164
 165 * `mhash_384_t *ctx`
 166   Pointer to the hash computation state of type `mhash_384_t` that will be updated by this operation.
 167
 168 * `const uint8_t *input`
 169   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.
 170   *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.
 171
 172 * `size_t len`
 173   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!
 174
 175 ### mhash_384_finalize()
 176
 177 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.
 178
 179 *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).
 180
 181         void mhash_384_finalize(const mhash_384_t *const ctx, uint8_t *const output);
 182
 183 * `const mhash_384_t *ctx`
 184   Pointer to the hash computation state of type `mhash_384_t` from which the final digest is computed.
 185
 186 * `uint8_t *output`
 187   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)`.
 188
 189 ## API for for C++ language
 190
 191 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*.
 192
 193 *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!
 194
 195 ### Constructor
 196
 197         MHash384::MHash384(void);
 198
 199 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.
 200
 201 ### update() [1]
 202
 203         void MHash384::update(const uint8_t *const input, const size_t len);
 204
 205 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.
 206
 207 *Parameters:*
 208
 209 * `const uint8_t *input`
 210   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.
 211   *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.
 212
 213 * `size_t len`
 214   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!
 215
 216 ### update() [2]
 217
 218         void MHash384::update(const std::vector<uint8_t> &input, const size_t offset = 0, const size_t len = 0);
 219
 220 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.
 221
 222 *Parameters:*
 223
 224 * `const std::vector<uint8_t> &input`
 225   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.
 226
 227 * `size_t offset`
 228   Optional. Specifies the *zero-based* index of the *first* vector element to be processed. By default, processing starts at index **0**.
 229
 230 * `size_t len`
 231   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.
 232
 233 ### update() [3]
 234
 235         void MHash384::update(const std::string &input, const size_t offset = 0, const size_t len = 0);
 236
 237 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.
 238
 239 *Parameters:*
 240
 241 * `const std::vector<uint8_t> &input`
 242   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.
 243
 244 * `size_t offset`
 245   Optional. Specifies the *zero-based* index of the *first* character in the string to be processed. By default, processing starts at index **0**.
 246
 247 * `size_t len`
 248   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.
 249
 250 ### finalize() [1]
 251
 252         void MHash384::finalize(uint8_t *const output) const;
 253
 254 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.
 255
 256 *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).
 257
 258 *Parameters:*
 259
 260 * `uint8_t *output`
 261   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)`.
 262
 263 ### finalize() [2]
 264
 265         std::vector<uint8_t> MHash384::finalize(void) const;
 266
 267 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.
 268
 269 *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).
 270
 271 *Return value:*
 272
 273 * 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).
 274
 275
 276 # Supported Platforms
 277
 278 MHash-384 library should compile on any standard-compliant C/C++ compiler. In particular, the following platforms have been tested successfully:
 279
 280 * Microsoft Windows
 281     - Microsoft C/C++ Compiler, using Visual Studio 2010 or later
 282     - MinGW, using Mingw-w64 from [MSYS2](https://msys2.github.io/) project
 283 * Intel C/C++ Compiler, version Version 15.0 (XE 2015) or later
 284 * GNU/Linux, using GCC/G++, version 4.7 or later
 285
 286 # Language Bindings
 287
 288 While the MHash-384 library is primarily targeted for C/C++ applications, *language bindings* are provided for a variety of programming languages. This allows for using the MHash-384 library in pretty much any scenario/environment.
 289
 290 ## Microsoft.NET
 291
 292 ## Java
 293
 294 ## Python
 295
 296 Bindings of the MHash-384 library are provided for [*CPython*](https://en.wikipedia.org/wiki/CPython), in the form of an *extension module* (Python C/C++ API).
 297
 298 In order to use the MHash-384 library in your Python application, simply import the `MHash384` convenience class from the `MHashPy384_Wrapper` module:
 299
 300         from MHashPy384_Wrapper import MHash384
 301
 302         with MHash384() as digest:
 303                 for chunk in read_chunks():
 304                         digest.update(chunk)
 305                 print(binascii.hexlify(digest.result()))
 306
 307 ***Note:*** The `MHash384` class is designed to be used via Python's [`with`](http://effbot.org/zone/python-with-statement.htm) statement. This will ensure that "native" resources are *always* cleaned up!
 308
 309 ### Installation
 310
 311 It is highly recommended to install the MHash-384 library into Python's [`site-packages`](https://docs.python.org/3.5/install/#how-installation-works) directory. For this purpose, create a new sub-directory `mhash` inside the `site-packages` directory. Then copy `mhash.pth` directly to the `site-packages` directory, so *site* will include the new sub-directory. Also, copy both modules, `MHashPy384_Wrapper.py` *and* `MHashPy384_Native.pyd`, to the `site-packages\mhash` sub-directory. The former module contains the `MHash384` convenience class, the latter module contains the "native" MHash-384 functions.
 312
 313 ***Note:*** The *32-Bit* (x86) version of Python can only work with the `MHashPy384_Native.x86.pyd` module, and the *64-Bit* (x64) version of Python can only work with the `MHashPy384_Native.x64.pyd` module. In any case, the file **must** be renamed to just `MHashPy384_Native.pyd`!
 314
 315
 316 # Source Code
 317
 318 The MHash-384 source is available from the official [**git**](https://git-scm.com/) mirrors:
 319
 320 * `git clone https://github.com/lordmulder/mhash-384.git` [[Browse](https://github.com/lordmulder/mhash-384)]
 321
 322 * `git clone https://bitbucket.org/lord_mulder/mhash-384.git` [[Browse](https://bitbucket.org/lord_mulder/mhash-384)]
 323
 324 * `git clone https://git.assembla.com/mhash-384.git` [[Browse](https://www.assembla.com/spaces/mhash-384/git/source)]
 325
 326 * `git clone https://gitlab.com/lord_mulder/mhash-384.git` [[Browse](https://gitlab.com/lord_mulder/mhash-384)]
 327
 328
 329 # Build Instructions
 330
 331 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.
 332
 333 * For supported versions of *Microsoft Visual Studio*, MHash-384 library ships with project/solution files, which will compile "out of the box".
 334
 335 * The *Intel C/C++ Compiler* integrates into Visual Studio, so simply select "Use Intel C++" from the project/solution menu.
 336
 337 * 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!
 338
 339 * 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.
 340
 341
 342 # License
 343
 344 **Copyright(c) 2016 LoRd_MuldeR &lt;mulder2@gmx.de&gt;, released under the MIT License.**
 345 **Check <http://muldersoft.com/> or <http://muldersoft.sourceforge.net/> for updates!**
 346
 347         Permission is hereby granted, free of charge, to any person obtaining a copy of this software
 348         and associated documentation files (the "Software"), to deal in the Software without
 349         restriction, including without limitation the rights to use, copy, modify, merge, publish,
 350         distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
 351         Software is furnished to do so, subject to the following conditions:
 352
 353         The above copyright notice and this permission notice shall be included in all copies or
 354         substantial portions of the Software.
 355
 356         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
 357         BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
 358         NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
 359         DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 360         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 361
 362 <https://opensource.org/licenses/MIT>
 363
 364 &nbsp;
 365
 366 [■](https://www.youtube.com/watch?v=dng06ZqI4Ss)