passlib.hash.cta_pbkdf2_sha1 - Cryptacular’s PBKDF2 hash

This class provides an implementation of Cryptacular’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.
• dlitz_pbkdf2_sha1 for another hash which looks almost exactly like this one.

Interface

class passlib.hash.cta_pbkdf2_sha1

This class implements Cryptacular’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 (bytes) – Optional salt bytes. If specified, it may be any length. If not specified, a one 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$oX9ZZOcNgYoAsYL-8bqxKg==$AU2JLf2rNxWoZxWxRCluY0u6h6c=

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 encoding using base64 (with -_ as the high values). oX9ZZOcNgYoAsYL-8bqxKg== in the example.
• checksum is 28 characters encoding the resulting 20-byte PBKDF2 derived key using base64 (with -_ as the high values). AU2JLf2rNxWoZxWxRCluY0u6h6c= in the example.

In order to generate the checksum, the password is first encoded into UTF-8 if it’s unicode. The salt is decoded from it’s base64 representation. PBKDF2 is called using the encoded password, the full salt, the specified number of rounds, and using HMAC-SHA1 as it’s psuedorandom function. 20 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 - https://bitbucket.org/dholth/cryptacular/.

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