# `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 PasswordHash API.

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

  The `using()` method accepts 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.

      Added 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 hexadecimal 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 its base64 representation. PBKDF2 is called using the encoded password, the full salt, the specified number of rounds, and using HMAC-SHA1 as its pseudorandom 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.