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)[source]

Return a hashlib hash given the XEP-0300 algo.

Parameters:

algo (str) – The algorithm identifier as defined in XEP-0300.
Raises:
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)[source]

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)[source]

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[source]

Mix-in class for XSOs which use Hash children.

digests

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