include/MUtils/Hash.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // MuldeR's Utilities for Qt
   3 // Copyright (C) 2004-2023 LoRd_MuldeR <MuldeR2@GMX.de>
   4 //
   5 // This library is free software; you can redistribute it and/or
   6 // modify it under the terms of the GNU Lesser General Public
   7 // License as published by the Free Software Foundation; either
   8 // version 2.1 of the License, or (at your option) any later version.
   9 //
  10 // This library is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  13 // Lesser General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU Lesser General Public
  16 // License along with this library; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  18 //
  19 // http://www.gnu.org/licenses/lgpl-2.1.txt
  20 //////////////////////////////////////////////////////////////////////////////////
  21
  22 /**
  23 * @file
  24 * @brief This file contains function for cryptographic hash computation
  25 *
  26 * Call the MUtils::Hash::create() function to create an instance of the desired hash function. All Hash functions implement the MUtils::Hash::Hash interface.
  27 */
  28
  29 #pragma once
  30
  31 //MUtils
  32 #include <MUtils/Global.h>
  33
  34 //Qt
  35 #include <QByteArray>
  36 #include <QFile>
  37
  38 namespace MUtils
  39 {
  40         namespace Hash
  41         {
  42                 static const quint16 HASH_BLAKE2_512 = 0x0000U; ///< \brief Hash algorithm identifier \details Use [BLAKE2](https://blake2.net/) hash algorithm, with a length of 512-Bit.
  43                 static const quint16 HASH_KECCAK_224 = 0x0100U; ///< \brief Hash algorithm identifier \details Use [Keccak](http://keccak.noekeon.org/) (SHA-3) hash algorithm, with a length of 224-Bit.
  44                 static const quint16 HASH_KECCAK_256 = 0x0101U; ///< \brief Hash algorithm identifier \details Use [Keccak](http://keccak.noekeon.org/) (SHA-3) hash algorithm, with a length of 256-Bit.
  45                 static const quint16 HASH_KECCAK_384 = 0x0102U; ///< \brief Hash algorithm identifier \details Use [Keccak](http://keccak.noekeon.org/) (SHA-3) hash algorithm, with a length of 384-Bit.
  46                 static const quint16 HASH_KECCAK_512 = 0x0103U; ///< \brief Hash algorithm identifier \details Use [Keccak](http://keccak.noekeon.org/) (SHA-3) hash algorithm, with a length of 512-Bit.
  47
  48                 /**
  49                 * \brief This abstract class specifies the generic interface for all support hash algorithms.
  50                 *
  51                 * In order to compute a hash value (digest) call the the Hash::update() function repeatedly until all input data (i.e. the complete "message") has been processed. Then call the Hash::digest() function to retrieve the final hash value.
  52                 *
  53                 * All overloads of the Hash::update() function may be called in an interleaved fashion as needed.
  54                 *
  55                 * This class is **not** thread-safe, i.e. do **not** call the *same* Hash instance from difference threads, unless serialization is ensured (e.g. by means of a Mutex). It is safe, however, to call different *different* Hash instances from difference threads concurrently.
  56                 */
  57                 class MUTILS_API Hash
  58                 {
  59                 public:
  60                         virtual ~Hash(void) {};
  61
  62                         /**
  63                         * \brief Process the next chunk of input data
  64                         *
  65                         * Updates the internal state of the hash function by processing the next chunk of input that. Can be called repeatedly, until until all input data has been processed.
  66                         *
  67                         * \param data A read-only pointer to the memory buffer holding the input data to be processed.
  68                         *
  69                         * \param len The length of the input data, in bytes. The `data` parameter must be pointing to a memory buffer that is at least `len` bytes in size.
  70                         *
  71                         * \return The function returns `true`, if the input data was processed successfully; otherwise it returns `false`.
  72                         */
  73                         bool update(const quint8 *const data, const quint32 len) { return process(data, len); }
  74
  75                         /**
  76                         * \brief Process the next chunk of input data
  77                         *
  78                         * Updates the internal state of the hash function by processing the next chunk of input that. Can be called repeatedly, until until all input data has been processed.
  79                         *
  80                         * \param data A read-only reference to a QByteArray object holding the input data to be processed. All bytes in the QByteArray object will be processed.
  81                         *
  82                         * \return The function returns `true`, if the input data was processed successfully; otherwise it returns `false`.
  83                         */
  84                         bool update(const QByteArray &data) { return process(((const quint8*)data.constData()), ((quint32)data.length())); }
  85
  86                         /**
  87                         * \brief Process the next chunk of input data
  88                         *
  89                         * Updates the internal state of the hash function by processing the next chunk of input that. Can be called repeatedly, until until all input data has been processed.
  90                         *
  91                         * \param data A reference to a QFile object. The QFile object must be open and readable. All data from the current file position to the end of the file will be processed.
  92                         *
  93                         * \return The function returns `true`, if all data in the file was processed successfully; otherwise (e.g. in case of file read errors) it returns `false`.
  94                         */
  95                         bool update(QFile &file);
  96
  97                         /**
  98                         * \brief Retrieve the hash value
  99                         *
 100                         * This function is used to retrieve the final hash value (digest), after all input data has been processed successfully.
 101                         *
 102                         * \param bAsHex If set to `true`, the function returns the hash value as a Hexadecimal-encoded ASCII string; if set to `false`, the function returns the hash value as "raw" bytes.
 103                         *
 104                         * \return The function returns a QByteArray object holding the final hash value (digest). The format depends on the `bAsHex` parameter.
 105                         */
 106                         QByteArray digest(const bool bAsHex = true) { return bAsHex ? finalize().toHex() : finalize(); }
 107
 108                 protected:
 109                         Hash(const char* /*key*/ = NULL) {/*nothing to do*/};
 110                         virtual bool process(const quint8 *const data, const quint32 len) = 0;
 111                         virtual QByteArray finalize(void) = 0;
 112
 113                 private:
 114                         MUTILS_NO_COPY(Hash);
 115                 };
 116
 117                 /**
 118                 * \brief Create instance of a hash function
 119                 *
 120                 * This function is used to create a new instance of the desired hash function. All Hash functions implement the MUtils::Hash::Hash interface. The caller is responsible for destroying the returned MUtils::Hash::Hash object.
 121                 *
 122                 * \param hashId Specifies the desired hash function. This must be a valid hash algorithm identifier, as defined in the `Hash.h` header file.
 123                 *
 124                 * \param key Specifies on optional key that is used to "seed" the hash function. If a key is given, it must be a NULL-terminated string of appropriate length. If set to `NULL`, the optional seeding is skipped.
 125                 *
 126                 * \return Returns a pointer to a new MUtils::Hash::Hash object that implements the desired hash function. The function throws if an invalid algorithm identifier was specified!
 127                 */
 128                 MUTILS_API Hash *create(const quint16 &hashId, const char *const key = NULL);
 129         }
 130 }