X-Git-Url: http://git.osdn.net/view?a=blobdiff_plain;f=README.md;h=cf24b42304032e95b99bece4f8e51899c49688f3;hb=1dfdae5cdfc52259d30144f0b731e86815dffa47;hp=7c96925343d5c96735512fced639b819200bcbae;hpb=539ea422f8c6db5962437e636d2720a242946b3d;p=mhash384%2Fmhash384.git diff --git a/README.md b/README.md index 7c96925..cf24b42 100644 --- a/README.md +++ b/README.md @@ -8,7 +8,7 @@ MHash-384 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). -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**. +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**. # Quick Start Guide @@ -217,7 +217,7 @@ Retrieve final hash value. This function completes the MHash-384 hash computatio Pointer to the hash computation state of type `mhash384_t` that will be finalized by this operation. *Note:* The MHash-384 library does **not** free this memory; it may need to be freed up by the calling application! -* `uint8_t *digest_out` +* `uint8_t *digest_out` 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`. *Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten! @@ -229,7 +229,7 @@ Compute hash value at once. This is a convenience function that can be used to c *Parameters:* -* `uint8_t *digest_out` +* `uint8_t *digest_out` 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`. *Note:* All *bytes* ranging from `digest_out[0]` up to and including `digest_out[MHASH384_SIZE-1]` will be overwritten! @@ -249,13 +249,13 @@ Retrieve version information. This function returns the current version of the M *Parameters:* -* `uint16_t *major` +* `uint16_t *major` Pointer to a variable of type `uint16_t` where the *major* version of the MHash-384 library will be stored. -* `uint16_t *minor` +* `uint16_t *minor` Pointer to a variable of type `uint16_t` where the *minor* version of the MHash-384 library will be stored. -* `uint16_t *patch` +* `uint16_t *patch` Pointer to a variable of type `uint16_t` where the *patch* level of the MHash-384 library will be stored. ### mhash384_selftest() @@ -297,17 +297,30 @@ Process next chunk of input data. This function performs the actual MHash-384 ha ### MHash384::update() [2] + template + void MHash384::update(const std::array &data) + +A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::array` as input. + +*Parameters:* + +* `const std::array &data` + Read-only reference to the `std::array` containing the input data to be processed. + *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input. + +### MHash384::update() [3] + void MHash384::update(const std::vector &data) A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an `std::vector` as input. *Parameters:* -* `const std::vector &data` +* `const std::vector &data` Read-only reference to the `std::vector` containing the input data to be processed. - *Note:* All bytes in the range from `vector[0]` up to and including `vector[vector.size()-1]` will be processed as input. + *Note:* All bytes in the range from `data[0]` up to and including `data[data.size()-1]` will be processed as input. -### MHash384::update() [3] +### MHash384::update() [4] void MHash384::update(const std::string &text) @@ -315,26 +328,64 @@ A convenience overload of the [`MHash384::update()`](#mhash384update-1) function *Parameters:* -* `const std::vector &data` +* `const std::string &text` Read-only reference to the `std::string` containing the input data to be processed. - *Note:* All characters in the range from `str[0]` up to and including `str[str.length()-1]` will be processed as input. Each character in the `std::string` is processed as a *byte* value, disregarding any specific character encoding. + *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. -### MHash384::update() [4] +### MHash384::update() [5] + + void MHash384::update(const char *const text) + +A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a NULL-terminated C string as input. + +*Parameters:* + +* `const char *const text` + Read-only pointer to the first character of the NULL-terminated string to be processed. + *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. + +### MHash384::update() [6] + + template + void MHash384::update(const element_type *const address); + +A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a pointer. + +*Parameters:* + +* `const element_type *const address` + Read-only pointer to the target object to be processed. + *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. + +### MHash384::update() [7] + + template + void MHash384::update(const element_type &element); + +A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes an object designated by a reference. + +*Parameters:* + +* `const element_type &element` + Read-only reference to the target object to be processed. + *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. + +### MHash384::update() [8] template - void update(const iterator_type &first, const iterator_type &last) + void MHash384::update(const iterator_type &first, const iterator_type &last) A convenience overload of the [`MHash384::update()`](#mhash384update-1) function, which processes a sequence of elements via iterators. *Parameters:* -* `const iterator_type &first` +* `const iterator_type &first` Read-only reference to the iterator designating the *first* element to be processed. - *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; the size of an element is `sizeof(iterator_type::value_type)`. + *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)`. -* `const iterator_type &last` - Read-only reference to the iterator designating the *last* element to be processed. - *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; the size of an element is `sizeof(iterator_type::value_type)`. +* `const iterator_type &last` + Read-only reference to the iterator designating the element just after the *last* element to be processed. + *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)`. ### MHash384::finish() @@ -356,6 +407,50 @@ Retrieve final hash value. This function completes the MHash-384 hash computatio 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. +# Supported platforms + +MHash-384 has been tested to successfully build and run on (at least) the following platforms: + +## C/C++ library and CLI front-end + +* **Microsoft Windows (x84/x64)** + - Microsoft Visual C++, version 16.00 (Visual Studio 2010) or newer + - Mingw-w64 (from MSYS2), tested with version 8.0.0, using GCC 9.2.0 or Clang 9.0.0 + - MinGW (mingw.org), tested with version 5.3.2, using GCC 8.2.0 + - Cygwin, tested with version 3.1.2 (x64), using GCC 7.4.0 or Clang 8.0.1 + +* **Linux/GNU (x86/x64)** + - Ubuntu, tested with version 16.04 (Xenial), using GCC 5.4.0 or Clang 3.8.0 + - CentOS/Red Hat Enterprise Linux, tested with version 8.1, using GCC 8.3.1 or Clang 8.0.1 + - Manjaro, tested with version 18.1.5, using GCC 9.2.0 or Clang 9.0.1 + - openSUSE (Leap), tested with version 15.1, using GCC 7.5.0 or Clang 7.0.1 + +* **BSD-Family (x86/x64)** + - FreeBSD, tested with TrueOS version 18.12, using GCC 7.4.0 or Clang 7.0.1 + - OpenBSD, tested with version 6.6, using GCC 8.2.0 or Clang 8.0.1 + +* **Solaris (x86/x64)** + - OpenSolaris/Illumos, tested with OpenIndiana version 2019.10, using GCC 9.2.0 + +## Ports to other lanuguages + +* **Java** + - Java SE 8, tested with OpenJDK Runtime Environment 1.8.0_242 + - Java SE 11, tested with OpenJDK Runtime Environment 11.0.5 + +* **.NET Framework** + - Microsoft.NET Framework 4.5 (or newer), tested with Visual Studio 2019 (version 15.9.20) + - Mono, tested with Mono C# Compiler version 5.18.0 (Ubuntu 19.10) + +* **Python** + - CPython 3.x, tested with version 3.8.1 + - PyPy (Python 3.6 compatible), tested with version 7.3.0, highly recommended for improved performance! + +* **Delphi (Object Pascal)** + - Bordland Delphi, tested with Delphi 7.1 (DCC 15.00) + - Lazarus/Free Pascal, tested with Lazarus 2.06 (Free Pascal Compiler 3.04) + + # License **MHash-384 - Simple fast portable secure hashing library**