passlib.utils.pbkdf2 - PBKDF2 key derivation algorithm [deprecated]

PBKDF2 and related key derivation algorithms.

Warning

This module has been deprecated as of Passlib 1.7, and will be removed in Passlib 2.0. The functions in this module have been replaced by equivalent (but not identical) functions in the passlib.crypto module.

This module provides a couple of key derivation functions, as well as supporting utilities. Primarily, it offers pbkdf2(), which provides the ability to generate an arbitrary length key using the PBKDF2 key derivation algorithm, as specified in rfc 2898. This function can be helpful in creating password hashes using schemes which have been based around the pbkdf2 algorithm.

PKCS#5 Key Derivation Functions

pbkdf1

pbkdf1(secret, salt, rounds, keylen=None, hash='sha1')

pkcs#5 password-based key derivation v1.5

Parameters:

• secret –

  passphrase to use to generate key

• salt –

  salt string to use when generating key

• rounds –

  number of rounds to use to generate key

• keylen –

  number of bytes to generate (if None, uses digest's native size)

• hash –

  hash function to use. must be name of a hash recognized by hashlib.

Returns:

• –

  raw bytes of generated key

  .. note::

  This algorithm has been deprecated, new code should use PBKDF2.
  Among other limitations, ``keylen`` cannot be larger
  than the digest size of the specified hash.
  

  .. deprecated:: 1.7

  This has been relocated to :func:`passlib.crypto.digest.pbkdf1`,
  and this version will be removed in Passlib 2.0.
  *Note the call signature has changed.*
  

pbkdf2

pbkdf2(
    secret, salt, rounds, keylen=None, prf="hmac-sha1"
)

pkcs#5 password-based key derivation v2.0

Parameters:

• secret –

  passphrase to use to generate key

• salt –

  salt string to use when generating key

• rounds –

  number of rounds to use to generate key

• keylen –

  number of bytes to generate. if set to None, will use digest size of selected prf.

• prf –

  psuedo-random family to use for key strengthening. this must be a string starting with "hmac-", followed by the name of a known digest. this defaults to "hmac-sha1" (the only prf explicitly listed in the PBKDF2 specification)

  .. rst-class:: warning

  .. versionchanged 1.7:

  This argument no longer supports arbitrary PRF callables --
  These were rarely / never used, and created too many unwanted codepaths.
  

Returns:

• –

  raw bytes of generated key

  .. deprecated:: 1.7

  This has been deprecated in favor of :func:`passlib.crypto.digest.pbkdf2_hmac`,
  and will be removed in Passlib 2.0.  *Note the call signature has changed.*
  

Note

The details of PBKDF1 and PBKDF2 are specified in RFC 2898.

Helper Functions

get_prf

get_prf(name)

Lookup pseudo-random family (PRF) by name.

Parameters:

• name –

  This must be the name of a recognized prf. Currently this only recognizes names with the format :samp:hmac-{digest}, where :samp:{digest} is the name of a hash function such as md5, sha256, etc.

  todo: restore text about callables.

Returns:

• –

  a tuple of :samp:({prf_func}, {digest_size}), where:

  * :samp:`{prf_func}` is a function implementing
    the specified PRF, and has the signature
    ``prf_func(secret, message) -> digest``.
  
  * :samp:`{digest_size}` is an integer indicating
    the number of bytes the function returns.
  

  Usage example::

  >>> from passlib.utils.pbkdf2 import get_prf
  >>> hmac_sha256, dsize = get_prf("hmac-sha256")
  >>> hmac_sha256
  <function hmac_sha256 at 0x1e37c80>
  >>> dsize
  32
  >>> digest = hmac_sha256('password', 'message')
  

  .. deprecated:: 1.7

  This function is deprecated, and will be removed in Passlib 2.0.
  This only related replacement is :func:`passlib.crypto.digest.compile_hmac`.
  

Raises:

• ValueError –

  if the name is not known

• TypeError –

  if the name is not a callable or string