passlib.hash.dlitz_pbkdf2_sha1 - Dwayne Litzenberger’s PBKDF2 hash

This class provides an implementation of Dwayne Litzenberger’s PBKDF2-HMAC-SHA1 hash format [1]. PBKDF2 is a key derivation function [2] that is ideally suited as the basis for a password hash, as it provides variable length salts, variable number of rounds.

See also

• password hash usage – for examples of how to use this class via the common hash interface.
• cta_pbkdf2_sha1 for another hash which looks almost exactly like this one.

Interface

class passlib.hash.dlitz_pbkdf2_sha1

This class implements Dwayne Litzenberger’s PBKDF2-based crypt algorithm, 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 (str) – Optional salt string. If specified, it may be any length, but must use the characters in the regexp range [./0-9A-Za-z]. If not specified, a 16 character 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 60000, 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.

Format & Algorithm

A example hash (of password) is:

$p5k2$2710$.pPqsEwHD7MiECU0$b8TQ5AMQemtlaSgegw5Je.JBE3QQhLbO.

All of this scheme’s hashes have the format $p5k2$rounds$salt$checksum, where:

• $p5k2$ is used as the Modular Crypt Format identifier.
• rounds is the number of PBKDF2 iterations to perform, stored as lowercase hexidecimal number with no zero-padding (in the example: 2710 or 10000 iterations).
• salt is the salt string, which can be any number of characters, drawn from the hash64 charset (.pPqsEwHD7MiECU0 in the example).
• checksum is 32 characters, which encode the resulting 24-byte PBKDF2 derived key using ab64_encode() (b8TQ5AMQemtlaSgegw5Je.JBE3QQhLbO in the example).

In order to generate the checksum, the password is first encoded into UTF-8 if it’s unicode. Then, the entire configuration string (all of the hash except the checksum, ie $p5k2$rounds$salt) is used as the PBKDF2 salt. PBKDF2 is called using the encoded password, the full salt, the specified number of rounds, and using HMAC-SHA1 as it’s psuedorandom function. 24 bytes of derived key are requested, and the resulting key is encoded and used as the checksum portion of the hash.

Footnotes

[1]	The reference for this hash format - http://www.dlitz.net/software/python-pbkdf2/.

[2]	The specification for the PBKDF2 algorithm - http://tools.ietf.org/html/rfc2898#section-5.2.