passlib.crypto.digest - Hash & Related Helpers

Internal cryptographic helpers.

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

norm_hash_name

norm_hash_name(name, format='hashlib')

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

Parameters:

• name –

  Original hash function name.

  This name can be a Python :mod:~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 :mod:!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 :class:!str.

lookup_hash

lookup_hash(
    digest, return_unknown=False, required=True
)

Returns a :class: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 :mod:!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 :exc:~passlib.exc.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 :class:!HashInfo record which will defer throwing the error until it's constructor function is called. This is mainly used by :func:norm_hash_name.

• return_unknown –

  .. deprecated:: 1.7.3

  deprecated, and will be removed in passlib 2.0.
  this acts like inverse of **required**.
  

Returns:

• –

  :class:HashInfo instance containing information about specified digest.

  Multiple calls resolving to the same hash should always return the same :class:!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.

HashInfo

HashInfo(const, names, required=True)

Record containing information about a given hash algorithm, as returned :func:lookup_hash.

This class exposes the following attributes:

.. autoattribute:: const .. autoattribute:: digest_size .. autoattribute:: block_size .. autoattribute:: name .. autoattribute:: iana_name .. autoattribute:: aliases .. autoattribute:: supported

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

initialize new instance.

Parameters:

• const –

  hash constructor

• names –

  list of 2+ names. should be list of (name, iana_name, ... 0+ aliases). names must be lower-case. only iana name may be None.

supported

supported()

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

PKCS#5 Key Derivation Functions

pbkdf1

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 :class:!bytes or :class:str (encoded using UTF-8).

• salt –

  salt string to use when generating key. may be :class:!bytes or :class: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 :class: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.
  

pbkdf2_hmac

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 (bytes) –

  digest name or constructor.

• secret (bytes) –

  passphrase to use to generate key. may be :class:!bytes or :class:str (encoded using UTF-8).

• salt (bytes) –

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

• rounds (int) –

  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

  .. versionchanged:: 1.7

  This function will use the first available of the following backends:
  
  * :func:`hashlib.pbkdf2_hmac` (only available in py2 >= 2.7.8, and py3 >= 3.4)
  
  See :data:`passlib.crypto.digest.PBKDF2_BACKENDS` to determine
  which backend(s) are in use.
  

PBKDF2_BACKENDS

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

Note

Added in 1.7.

PBKDF2_BACKENDS module-attribute

PBKDF2_BACKENDS = ['hashlib-ssl']

Note

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