passlib.hash.pbkdf2_digest - Generic PBKDF2 Hashes

Passlib provides three custom hash schemes based on the PBKDF2 [1] algorithm which are compatible with the modular crypt format:

• pbkdf2_sha1
• pbkdf2_sha256
• pbkdf2_sha512

Security-wise, PBKDF2 is currently one of the leading key derivation functions, and has no known security issues. Though the original PBKDF2 specification uses the SHA-1 message digest, it is not vulnerable to any of the known weaknesses of SHA-1 [2], and can be safely used. However, for those still concerned, SHA-256 and SHA-512 versions are offered as well. PBKDF2-SHA512 is one of the three hashes Passlib recommends for new applications.

All of these classes can be used directly as follows:

>>> from passlib.hash import pbkdf2_sha256

>>> # generate new salt, encrypt password
>>> hash = pbkdf2_sha256.encrypt("password")
>>> hash
'$pbkdf2-sha256$6400$0ZrzXitFSGltTQnBWOsdAw$Y11AchqV4b0sUisdZd0Xr97KWoymNE0LNNrnEgY4H9M'

>>> # same, but with an explicit number of rounds and salt length
>>> pbkdf2_sha256.encrypt("password", rounds=8000, salt_size=10)
'$pbkdf2-sha256$8000$XAuBMIYQQogxRg$tRRlz8hYn63B9LYiCd6PRo6FMiunY9ozmMMI3srxeRE'

>>> # verify the password
>>> pbkdf2_sha256.verify("password", hash)
True
>>> pbkdf2_sha256.verify("wrong", hash)
False

See also

• password hash usage – for more usage examples
• ldap_pbkdf2_{digest} – alternate LDAP-compatible versions of these hashes.

Interface

class passlib.hash.pbkdf2_sha256

This class implements a generic PBKDF2-HMAC-SHA256-based password hash, and follows the Password Hash Interface.

It supports a variable-length salt, and a variable number of rounds.

The encrypt() and genconfig() methods accept the following optional keywords:

Parameters:

• salt (bytes) – Optional salt bytes. If specified, the length must be between 0-1024 bytes. If not specified, a 16 byte salt will be autogenerated (this is recommended).
• salt_size (int) – Optional number of bytes to use when autogenerating new salts. Defaults to 16 bytes, but can be any value between 0 and 1024.
• rounds (int) – Optional number of rounds to use. Defaults to 12000, but must be within range(1,1<<32).
• relaxed (bool) –

  By default, providing an invalid value for one of the other keywords will result in a ValueError. If relaxed=True, and the error can be corrected, a PasslibHashWarning will be issued instead. Correctable errors include rounds that are too small or too large, and salt strings that are too long.

  New in version 1.6.

class passlib.hash.pbkdf2_sha512

except for the choice of message digest, this class is the same as pbkdf2_sha256.

class passlib.hash.pbkdf2_sha1

except for the choice of message digest, this class is the same as pbkdf2_sha256.

Format & Algorithm

An example pbkdf2_sha256 hash (of password):

$pbkdf2-sha256$6400$.6UI/S.nXIk8jcbdHx3Fhg$98jZicV16ODfEsEZeYPGHU3kbrUrvUEXOPimVSQDD44

All of the pbkdf2 hashes defined by passlib follow the same format, $pbkdf2-digest$rounds$salt$checksum.

• $pbkdf2-digest$ is used as the Modular Crypt Format identifier ($pbkdf2-sha256$ in the example).
• digest - this specifies the particular cryptographic hash used in conjunction with HMAC to form PBKDF2’s pseudorandom function for that particular hash (sha256 in the example).
• rounds - the number of iterations that should be performed. this is encoded as a positive decimal number with no zero-padding (6400 in the example).
• salt - this is the adapted base64 encoding of the raw salt bytes passed into the PBKDF2 function.
• checksum - this is the adapted base64 encoding of the raw derived key bytes returned from the PBKDF2 function. Each scheme uses the digest size of it’s specific hash algorithm (digest) as the size of the raw derived key. This is enlarged by appromixately 4/3 by the base64 encoding, resulting in a checksum size of 27, 43, and 86 for each of the respective algorithms listed above.

The algorithm used by all of these schemes is deliberately identical and simple: The password is encoded into UTF-8 if not already encoded, and run through pbkdf2() along with the decoded salt, the number of rounds, and a prf built from HMAC + the respective message digest. The result is then encoded using ab64_encode().

Footnotes

[1]	The specification for the PBKDF2 algorithm - http://tools.ietf.org/html/rfc2898#section-5.2, part of RFC 2898.

[2]	While SHA1 has fallen to collision attacks, HMAC-SHA1 as used by PBKDF2 is still considered secure - http://www.schneier.com/blog/archives/2005/02/sha1_broken.html.