# TupleHash256

TupleHash256 is a variable-lengh hash function for tuples of byte strings, derived from SHA-3, and standardized in NIST SP 800-185.

TupleHash256 provides a robust way to hash a sequence of byte strings, while maintaining the semantics of each single string, and with a security strength of 256 bits.

For example, let’s assume that a banking application combines the following strings to validate a money transfer: `deposit`, amount (e.g., `100`), and username (e.g., `joe`). The application uses SHA256 and naively concatenates the strings to obtain a credential to authorize the operation:

    SHA256("deposit100joe")

A malicious user could register a second user `000joe`, so that the system computes, for the same small transfer:

    SHA256("deposit100000joe")

which is also the same credential that authorizes a much larger transfer to the other user `joe`.

TupleHash256 makes the composition of all strings into a digest more robust by ensuring that the size of each individual byte string is considered. Each byte string is submitted in its entirety via the `update()` method.

This is an example showing how to generate a TupleHash256 for the 3 bytes strings above:

    >>> from Crypto.Hash import TupleHash256
    >>>
    >>> hd = TupleHash256.new(digest_bytes=16)
    >>> hd.update(b'deposit')
    >>> hd.update(b'100')
    >>> hd.update(b'joe')
    >>> print(hd.hexdigest())
    b101225b7e5f1f086fc6d0be01abfa1e

Multiple byte strings can be submitted. Each argument is a separate element in the tuple:

    >>> from Crypto.Hash import TupleHash256
    >>>
    >>> hd = TupleHash128.new(digest_bytes=16)
    >>> hd.update(b'deposit', b'100', b'joe')
    >>> print(hd.hexdigest())
    b101225b7e5f1f086fc6d0be01abfa1e

Any or even all the byte strings in the sequence can be empty. An empty byte string is significant: calling `update(b'')` will still contribute to and modify the final digest.

An application can select the length of the digest by means of the initialization parameters `digest_bytes` or `digest_bits`. For instance, while the traditional SHA256 can only produce 32-byte tags, with TupleHash256 you can produce a 16-byte tag (see the example above) but also a 33-byte tag:

    >>> from Crypto.Hash import TupleHash256
    >>>
    >>> hd = TupleHash256.new(digest_bytes=33)
    >>> hd.update(b'deposit')
    >>> hd.update(b'100')
    >>> hd.update(b'joe')
    >>> print(hd.hexdigest())
    29cbb43b90e19bfebf7ff0acfa651a889f106486dae9f9f42c34a48e1b8a7bfa6f

Note how the 16-byte digest is NOT just the truncated version of the 33-byte digest: they are cryptographically uncorrelated.

Crypto.Hash.TupleHash256.new(**kwargs)

  Create a new TupleHash256 object.

  Parameters:

    - digest_bytes (integer) – Optional. The size of the digest, in bytes. Default is 64. Minimum is 8.

    - digest_bits (integer) – Optional and alternative to `digest_bytes`. The size of the digest, in bits (and in steps of 8). Default is 512. Minimum is 64.

    - custom (bytes) – Optional. A customization bytestring (`S` in SP 800-185).

  Return:

    A `TupleHash` object