multiformats.multihash.raw

Implementation of raw hash functions used by multihash multicodecs.

Hash functions are implemented using the following modules:

hashlib, for the sha/shake hash functions and the blake2 hash functions.
blake3, for the blake3 hash function.
pyskein, for the skein hash functions.
mmh3, for the murmur3 hash functions.
pycryptodomex, for the ripemd-160 hash function, the kangarootwelve hash function, the keccak hash functions and the sha2-512-224/sha2-512-256 hash functions.

All modules other than hashlib are optional dependencies. The get function attempts to dynamically import any optional dependencies required by desired multihash implementation, raising ImportError if the dependency is not installed.

Core functionality is provided by the exists and get functions, which can be used to check whether an implementatino with given name is known, and if so to get the corresponding pair of hash function and max digest size:

>>> multihash.hashfun.exists("sha2-256")
True
>>> multihash.hashfun.get("sha2-256")
(<function _hashlib_sha.<locals>.hashfun at 0x0000013F4A3C6160>, 32)

The hash functions take a single bytes input (the data) and return a bytes output (the hash digest). The max digest sizes (if not None) are used to sense-check hash digests passed to wrap and/or obtained from unwrap: telling whether a digest has been generated by a hash function is deemed to be computationally unfeasible in general, but hash digests of length greater than the max digest size can always be discounted as invalid.

Hashfun

class Hashfun(*args, **kwargs)[source]

Bases: Protocol

Protocol for raw hash functions.

@runtime_checkable
class Hashfun(Protocol):
    def __call__(self, data: BytesLike, size: Optional[int] = None) -> bytes:
        ...

MultihashImpl

MultihashImpl

Type alias for multihash implementations.

alias of Tuple[Hashfun, Optional[int]]

exists

exists(name)[source]

Checks whether the multihash multicodec with given name has an implementation.

>>> multihash.hashfun.exists("sha2-256")
True

Parameters:: name (str) – the name of the multihash
Return type:: bool

get

get(name)[source]

Given a multihash multicodec name, returns its implementation as a pair of a hash function and a max digest size (possibly None).

>>> multihash.hashfun.get("sha2-256")
(<function _hashlib_sha.<locals>.hashfun at 0x0000013F4A3C6160>, 32)

Parameters:: name (str) – the name of the multihash
Raises:: KeyError – if no implementation is available for this name
Return type:: MultihashImpl

register

register(name, hashfun, digest_size, *, overwrite=False)[source]

Registers a hash function and hash digest size implementing the multihash multicodec with given name, which must already exist.

Example usage (from the source code of this module):

register("sha1", _hashlib_sha(1), 20) # max digest size is 20 bytes, i.e. 160 bits
register(f"sha2-256", _hashlib_sha(2, 256), 256//8)

Parameters:

name (str) – the name of the multihash
hashfun (Hashfun) – the raw hash function
digest_size (int or None) – the max size for digests, or None if not max size
overwrite (bool, optional) – whether an existing implementation with the same name should be overwritten

Raises:

ValueError – if overwrite is False and an implementation the same name already exists

Return type:

None

unregister

unregister(name)[source]

Unregisters a raw encoding by multihash name.

Parameters:: name (str) – the name of the multihash
Raises:: KeyError – if no such raw encoding exists
Return type:: None