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)[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.

Service

class aioxmpp.hashes.HashService(client, **kwargs)[source]

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

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)[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.

class aioxmpp.hashes.HashUsed(*args, **kwargs)[source]

Represent a single hash-used algorithm spec.

algo

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

class aioxmpp.hashes.HashesUsedParent[source]

Mix-in class for XSOs which use HashUsed children.

algos

A list of hash algorithms.