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