The Passlib documentation has moved to https://passlib.readthedocs.io

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

Warning

Due to a small flaw, this hash is not as strong as other PBKDF1-HMAC-SHA1 based hashes. It should probably not be used for new applications.

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

Interface

class passlib.hash.dlitz_pbkdf2_sha1

This class implements Dwayne Litzenberger’s PBKDF2-based crypt algorithm, and follows the PasswordHash API.

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

The using() method accepts 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 hexadecimal 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 its pseudorandom function. 24 bytes of derived key are requested, and the resulting key is encoded and used as the checksum portion of the hash.

Security Issues

  • Extra Block: This hash generates 24 bytes using PBKDF2-HMAC-SHA1. Since SHA1 has a digest size of only 20 bytes, this means an second PBKDF2 block must be generated for each dlitz_pbkdf2_sha1 hash. While a normal user has to calculate both blocks, a dedicated attacker would only have to calculate the first block when brute-forcing, taking half the time. That means this hash is half as strong as other PBKDF2-HMAC-SHA1 based hashes (given a fixed amount of time spent by the user).

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.