Skip to content

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.

Tip

  • 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

dlitz_pbkdf2_sha1 

dlitz_pbkdf2_sha1(rounds=None, **kwds)

This class implements Dwayne Litzenberger's PBKDF2-based crypt algorithm, and follows the :ref:password-hash-api.

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

The :meth:~passlib.ifc.PasswordHash.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, default: None ) –

    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 :exc:ValueError. If relaxed=True, and the error can be corrected, a :exc:~passlib.exc.PasslibHashWarning will be issued instead. Correctable errors include rounds that are too small or too large, and salt strings that are too long.

    .. versionadded:: 1.6

encrypt classmethod 

encrypt(*args, **kwds)

Legacy alias for :meth:hash.

.. deprecated:: 1.7 This method was renamed to :meth:!hash in version 1.7. This alias will be removed in version 2.0, and should only be used for compatibility with Passlib 1.3 - 1.6.

parsehash classmethod 

parsehash(hash, checksum=True, sanitize=False)

[experimental method] parse hash into dictionary of settings.

this essentially acts as the inverse of :meth:hash: for most cases, if hash = cls.hash(secret, **opts), then cls.parsehash(hash) will return a dict matching the original options (with the extra keyword checksum).

this method may not work correctly for all hashes, and may not be available on some few. its interface may change in future releases, if it's kept around at all.

Parameters:

  • hash –

    hash to parse

  • checksum –

    include checksum keyword? (defaults to True)

  • sanitize –

    mask data for sensitive fields? (defaults to False)

bitsize classmethod 

bitsize(rounds=None, vary_rounds=0.1, **kwds)

[experimental method] return info about bitsizes of hash

default_salt_chars 

default_salt_chars()

charset used to generate new salt strings (defaults to salt_chars)

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 <passlib.utils.binary.HASH64_CHARS> (.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).

  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 ↩