# `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

- 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 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.

      Added 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.