# Hash Library

The hash library can be used to compute hash values and HMACs. The following algorithms are supported:

- MD4
- MD5
- SHA1
- SHA224
- SHA256
- SHA384
- SHA512
- SHA512/224
- SHA512/256

## File information

File | common/ilib/hash.h
Classes | hash hmac
Data types | hash_t
Examples | Calculating a SHA256 hash Calculating HMAC-SHA1

# Classes

## hash

    class hash {
        ulong64 context[27];
        hash_t type;
    public:
        hash();
        void init(hash_t type);
        void update(const void * in, size_t len);
        void final(void * out);
        void copy(class hash * from);
        size_t size();
    };

### Overview

The hash class defines a uniform interface for calculating hashes using different algorithms.

Hash functions process an arbitrary number of bytes, possibly devided into chunks, and produce a fixed number of output bytes. The output is called a "hash" or "digest". The same input data always produces the same digest. So hashes can be used for integrity protection of messages. Cryptographically strong hash functions like SHA256 make it very hard (aka impossible) to gain any information about the input from the produced digest. So they are often used for digital signatures and login protocols.

### Public functions

init
  Initializes the internal state of the object and sets the algorithm to be used.

  #### Parameters

  hash_t type | The hash algorithm to be used.

  #### Remarks

  The init function has to be called before using any other functions of the object.
update
  Processes a chunk of input data.

  #### Parameters

  const void * in | The input buffer.
  size_t len | The number of bytes to be processed.

  #### Remarks

  This function can be called mupltiple times.
final
  Calculates the hash and copies the value to the given out buffer.

  #### Parameters

  void * out | The output buffer to write the hash value in binary form. The buffer size must match the hash size defined by the algorithm.

  #### Remarks

  The size function can be used to determine the needed output buffer size.
copy
  Copies the internal state from the given other hash.

  #### Parameters

  class hash * from | A pointer to another hash object that shall be duplicated.

size

  #### Return value

  size_t | The size of the hash value for the current algorithm. This is the number of bytes that is written by function final to the out buffer.

# Data types

## Defines / Statics

HASH_SIZE_MD4 | MD4 hashes use 16 bytes
HASH_SIZE_MD5 | MD5 hashes use 16 bytes
HASH_SIZE_SHA1 | SHA1 hashes use 20 bytes
HASH_SIZE_SHA224 | SHA224 hashes use 28 bytes
HASH_SIZE_SHA256 | SHA256 hashes use 32 bytes
HASH_SIZE_SHA384 | SHA384 hashes use 48 bytes
HASH_SIZE_SHA512 | SHA512 hashes use 64 bytes
HASH_SIZE_SHA512_224 | SHA512/224 hashes use 28 bytes
HASH_SIZE_SHA512_256 | SHA512/256 hashes use 32 bytes
HASH_SIZE_MAX | The maximum hash size produced by the library.

## hash_t

    enum hash_t {
        HASH_UNDEFINED,
        HASH_MD4,
        HASH_MD5,
        HASH_SHA1,
        HASH_SHA224,
        HASH_SHA256,
        HASH_SHA384,
        HASH_SHA512,
        HASH_SHA512_224,
        HASH_SHA512_256
    };

### Overview

The hash_t enum defines all hash algorithms supported by the library.

### Values

HASH_UNDEFINED | Used internally to identify uninitialized objects.
HASH_MD4 | Considered as cryptographically weak.
HASH_MD5 | Considered as cryptographically weak.
HASH_SHA1 | Considered as cryptographically weak.
HASH_SHA224 |
HASH_SHA256 |
HASH_SHA384 |
HASH_SHA512 |
HASH_SHA512_224 |
HASH_SHA512_256 |

### Remarks

The old algorithms MD4, MD5 and SHA1 are insecure. They should not be used for new projects. Please use the algorithms of the SHA2 family (SHA224, SHA256, SHA384 or SHA512).

# Code Example

## Calculating a SHA256 hash

    hash h;
    byte out[32];
    h.init(HASH_SHA256);
    h.update(data1, 16);
    h.update(data2, 5);
    h.final(out);

## Calculating HMAC-SHA1

    hmac h;
    byte out[HASH_SIZE_SHA1];
    h.init(HASH_SHA1, key, key_len);
    h.update(data1, 16);
    h.update(data2, 5);
    h.final(out);