# `hashes` — Hash Functions for use with XMPP (XEP-0300)

XEP-0300 consolidates the use of hash functions and their digests in XMPP. Identifiers (usually called algo) are defined to refer to specific implementations and parametrisations of hashes (`hash_from_algo()`, `algo_of_hash()`) and there is a defined XML format for carrying hash digests (`Hash`).

This allows other extensions to easily embed hash digests in their protocols (`HashesParent`).

Note

Compliance with XEP-0300 depends on your build of Python and possibly OpenSSL. Version 0.5.1 of XEP-0300 requires support of SHA3 and BLAKE2b, which was only introduced in Python 3.6.

## Utilities for Working with Hash Algorithm Identifiers

`aioxmpp.hashes.``hash_from_algo`(algo)

  Return a `hashlib` hash given the XEP-0300 algo.

  Parameters: | algo (`str`) – The algorithm identifier as defined in XEP-0300.

  Raises:

  - NotImplementedError – if the hash algortihm is not supported by `hashlib`.
  - ValueError – if the hash algorithm MUST NOT be supported.

  Returns: | A hash object from `hashlib` or compatible.

  If the algo is not supported by the `hashlib` module, `NotImplementedError` is raised.

`aioxmpp.hashes.``algo_of_hash`(h)

  Return a XEP-0300 algo from a given `hashlib` hash.

  Parameters: | h – Hash object from `hashlib`.

  Raises:

  - ValueError – if h does not have a defined algo value.
  - ValueError – if the hash function MUST NOT be supported.

  Returns: | The algo value for the given hash.
  Return type: | `str`

  Warning

  Use with caution for `hashlib.blake2b()` hashes. `algo_of_hash()` cannot safely determine whether blake2b was initialised with a salt, personality, key or other non-default XEP-0300 mode.

  In such a case, the return value will be the matching `blake2b-*` algo, but the digest will not be compatible with the results of other implementations.

`aioxmpp.hashes.``default_hash_algorithms`

  A set of algo values which consists of hash functions matching the following criteria:

  - They are specified as `MUST` or `SHOULD` in the supported version of XEP-0300.
  - They are supported by `hashlib`.
  - Only one function from each matching family is selected. If multiple functions apply, `MUST` is preferred over `SHOULD`.

  The set thus varies based on the build of Python and possibly OpenSSL. The algorithms in the set are guaranteed to return a valid hash implementation when passed to `hash_from_algo()`.

  In a fully compliant build, this set consists of `sha-256`, `sha3-256` and `blake2b-256`.

## XSOs

class `aioxmpp.hashes.``Hash`(algo, digest)

  Represent a single hash digest.

  `algo`

    The hash algorithm used. The name is as specified in XEP-0300.

  `digest`

    The digest as `bytes`.

class `aioxmpp.hashes.``HashesParent`

  Mix-in class for XSOs which use `Hash` children.

  `digests`

    A mapping which maps from the `Hash.algo` to the `Hash.digest`.