Skip to content

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.

Tip

  • 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

cta_pbkdf2_sha1 

cta_pbkdf2_sha1(rounds=None, **kwds)

This class implements Cryptacular'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 (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, 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$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.

  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 ↩