passlib.crypto.digest - Hash & Related Helpers

Added in version 1.7.

This module provides various cryptographic support functions used by Passlib to implement the various password hashes it provides, as well as paper over some VM & version incompatibilities.

Hash Functions

passlib.crypto.digest.norm_hash_name(name, format='hashlib')

Normalize hash function name (convenience wrapper for lookup_hash()).

Parameters:

  • name –

    Original hash function name.

    This name can be a Python hashlib digest name, a SCRAM mechanism name, IANA assigned hash name, etc. Case is ignored, and underscores are converted to hyphens.

  • format –

    Naming convention to normalize to. Possible values are:

    • "hashlib" (the default) - normalizes name to be compatible with Python’s hashlib.

    • "iana" - normalizes name to IANA-assigned hash function name. For hashes which IANA hasn’t assigned a name for, this issues a warning, and then uses a heuristic to return a “best guess” name.

Returns:

Hash name, returned as native str.

passlib.crypto.digest.lookup_hash(digest, return_unknown=False, required=True)

Returns a HashInfo record containing information about a given hash function. Can be used to look up a hash constructor by name, normalize hash name representation, etc.

Parameters:

  • digest –

    This can be any of:

    • A string containing a hashlib digest name (e.g. "sha256"),

    • A string containing an IANA-assigned hash name,

    • A digest constructor function (e.g. hashlib.sha256).

    Case is ignored, underscores are converted to hyphens, and various other cleanups are made.

  • required –

    By default (True), this function will throw an UnknownHashError if no hash constructor can be found, or if the hash is not actually available.

    If this flag is False, it will instead return a dummy HashInfo record which will defer throwing the error until it’s constructor function is called. This is mainly used by norm_hash_name().

  • return_unknown –

    Deprecated since version 1.7.3: deprecated, and will be removed in passlib 2.0. this acts like inverse of required.

Returns HashInfo:

HashInfo instance containing information about specified digest.

Multiple calls resolving to the same hash should always return the same HashInfo instance.

Note

lookup_hash() supports all hashes available directly in hashlib, as well as offered through hashlib.new(). It will also fallback to passlib’s builtin MD4 implementation if one is not natively available.

class passlib.crypto.digest.HashInfo

Record containing information about a given hash algorithm, as returned lookup_hash().

This class exposes the following attributes:

const = None

Hash constructor function (e.g. hashlib.sha256())

digest_size = None

Hash’s digest size

block_size = None

Hash’s block size

name = None

Canonical / hashlib-compatible name (e.g. "sha256").

iana_name = None

IANA assigned name (e.g. "sha-256"), may be None if unknown.

aliases = ()

Tuple of other known aliases (may be empty)

supported

whether hash is available for use (if False, constructor will throw UnknownHashError if called)

This object can also be treated a 3-element sequence containing (const, digest_size, block_size).

PKCS#5 Key Derivation Functions

passlib.crypto.digest.pbkdf1(digest, secret, salt, rounds, keylen=None)

pkcs#5 password-based key derivation v1.5

Parameters:

  • digest – digest name or constructor.

  • secret – secret to use when generating the key. may be bytes or str (encoded using UTF-8).

  • salt – salt string to use when generating key. may be bytes or str (encoded using UTF-8).

  • rounds – number of rounds to use to generate key.

  • keylen – number of bytes to generate (if omitted / None, uses digest’s native size)

Returns:

raw bytes of generated key

Note

This algorithm has been deprecated, new code should use PBKDF2. Among other limitations, keylen cannot be larger than the digest size of the specified hash.

passlib.crypto.digest.pbkdf2_hmac(digest: bytes, secret: bytes, salt: bytes, rounds: int, keylen=None)

pkcs#5 password-based key derivation v2.0 using HMAC + arbitrary digest.

Parameters:

  • digest – digest name or constructor.

  • secret – passphrase to use to generate key. may be bytes or str (encoded using UTF-8).

  • salt – salt string to use when generating key. may be bytes or str (encoded using UTF-8).

  • rounds – number of rounds to use to generate key.

  • keylen – number of bytes to generate. if omitted / None, will use digest’s native output size.

Returns:

raw bytes of generated key

Changed in version 1.7: This function will use the first available of the following backends:

  • hashlib.pbkdf2_hmac() (only available in py2 >= 2.7.8, and py3 >= 3.4)

See passlib.crypto.digest.PBKDF2_BACKENDS to determine which backend(s) are in use.

passlib.crypto.digest.PBKDF2_BACKENDS

List of the pbkdf2 backends in use (listed in order of priority).

Added in version 1.7.

Note

The details of PBKDF1 and PBKDF2 are specified in RFC 2898.