# `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`) and hash algorithms to be used (`HashUsed`).

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

The service `HashService` registers the disco features for the supported hash functions and allows querying hash functions supported by you and another entity on the Jabber network supporting XEP-0300.

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 algorithm 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`.

## Service

class aioxmpp.hashes.HashService(client, **kwargs)

  The service component of the XEP-0300 support. This service registers the features and allows to query the hash functions supported by us and a remote entity:

  async select_common_hashes(other_entity)

    Return the list of algos supported by us and other_entity. The algorithms are represented by their XEP-0300 URNs (urn:xmpp:hash-function-text-names:…).

    Parameters

      other_entity (`aioxmpp.JID`) – the address of another entity

    Returns

      the identifiers of the hash algorithms supported by both us and the other entity

    Return type

      `set`

    Raises

      RuntimeError – if the other entity does not support the XEP-0300 feature nor does not publish hash functions URNs we support.

    Note: This assumes the protocol is supported if valid hash function features are detected, even if urn:xmpp:hashes:2 is not listed as a feature.

## XSOs

class aioxmpp.hashes.Hash(*args, **kwargs)

  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`.

class aioxmpp.hashes.HashUsed(*args, **kwargs)

  Represent a single hash-used algorithm spec.

  algo

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

class aioxmpp.hashes.HashesUsedParent

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

  algos

    A list of hash algorithms.