passlib.utils.pbkdf2 - PBKDF2 key derivation algorithm

This module provides a couple of key derivation functions, as well as supporting utilities. Primarily, it offers pbkdf2(), which provides the ability to generate an arbitrary length key using the PBKDF2 key derivation algorithm, as specified in rfc 2898. This function can be helpful in creating password hashes using schemes which have been based around the pbkdf2 algorithm.

PKCS#5 Key Derivation Functions

passlib.utils.pbkdf2.pbkdf1(secret, salt, rounds, keylen=None, hash='sha1')

pkcs#5 password-based key derivation v1.5

Parameters:

• secret – passphrase to use to generate key
• salt – salt string to use when generating key
• rounds – number of rounds to use to generate key
• keylen – number of bytes to generate (if None, uses digest’s native size)
• hash – hash function to use. must be name of a hash recognized by hashlib.

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.utils.pbkdf2.pbkdf2(secret, salt, rounds, keylen=None, prf='hmac-sha1')

pkcs#5 password-based key derivation v2.0

Parameters:

• secret – passphrase to use to generate key
• salt – salt string to use when generating key
• rounds – number of rounds to use to generate key
• keylen – number of bytes to generate. if set to None, will use digest size of selected prf.
• prf – psuedo-random family to use for key strengthening. this can be any string or callable accepted by get_prf(). this defaults to "hmac-sha1" (the only prf explicitly listed in the PBKDF2 specification)

Returns:

raw bytes of generated key

Note

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

Helper Functions

passlib.utils.pbkdf2.norm_hash_name(name, format='hashlib')

Normalize hash function name

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, issues a warning, and then uses a heuristic to give a “best guess”.

Returns:

Hash name, returned as native str.

passlib.utils.pbkdf2.get_prf(name)

lookup pseudo-random family (prf) by name.

Parameters:

name –

this must be the name of a recognized prf. currently this only recognizes names with the format hmac-digest, where digest is the name of a hash function such as md5, sha256, etc.

this can also be a callable with the signature prf(secret, message) -> digest, in which case it will be returned unchanged.

Raises:

• ValueError – if the name is not known
• TypeError – if the name is not a callable or string

Returns:

a tuple of (func, digest_size).

• func is a function implementing the specified prf, and has the signature func(secret, message) -> digest.
• digest_size is an integer indicating the number of bytes the function returns.

usage example:

>>> from passlib.utils.pbkdf2 import get_prf
>>> hmac_sha256, dsize = get_prf("hmac-sha256")
>>> hmac_sha256
<function hmac_sha256 at 0x1e37c80>
>>> dsize
32
>>> digest = hmac_sha256('password', 'message')

this function will attempt to return the fastest implementation it can find; if M2Crypto is present, and supports the specified prf, M2Crypto.EVP.hmac() will be used behind the scenes.