Key Derivation Functions

This module contains a collection of standard key derivation functions.

A key derivation function derives one or more secondary secret keys from one primary secret (a master key or a pass phrase).

This is typically done to insulate the secondary keys from each other, to avoid that leakage of a secondary key compromises the security of the master key, or to thwart attacks on pass phrases (e.g. via rainbow tables).

Crypto.Protocol.KDF.HKDF(master, key_len, salt, hashmod, num_keys=1, context=None)

Derive one or more keys from a master secret using the HMAC-based KDF defined in RFC5869.

This KDF is not suitable for deriving keys from a password or for key stretching. Use PBKDF2() instead.

HKDF is a key derivation method approved by NIST in SP 800 56C.

Parameters:
  • master (byte string) – The unguessable value used by the KDF to generate the other keys. It must be a high-entropy secret, though not necessarily uniform. It must not be a password.
  • salt (byte string) – A non-secret, reusable value that strengthens the randomness extraction step. Ideally, it is as long as the digest size of the chosen hash. If empty, a string of zeroes in used.
  • key_len (integer) – The length in bytes of every derived key.
  • hashmod (module) – A cryptographic hash algorithm from Crypto.Hash. Crypto.Hash.SHA512 is a good choice.
  • num_keys (integer) – The number of keys to derive. Every key is key_len bytes long. The maximum cumulative length of all keys is 255 times the digest size.
  • context (byte string) – Optional identifier describing what the keys are used for.
Returns:

A byte string or a tuple of byte strings.
Crypto.Protocol.KDF.PBKDF1(password, salt, dkLen, count=1000, hashAlgo=None)

Derive one key from a password (or passphrase).

This function performs key derivation according to an old version of the PKCS#5 standard (v1.5) or RFC2898.

Warning

Newer applications should use the more secure and versatile PBKDF2() instead.

Parameters:
  • password (string) – The secret password to generate the key from.
  • salt (byte string) – An 8 byte string to use for better protection from dictionary attacks. This value does not need to be kept secret, but it should be randomly chosen for each derivation.
  • dkLen (integer) – The length of the desired key. The default is 16 bytes, suitable for instance for Crypto.Cipher.AES.
  • count (integer) – The number of iterations to carry out. The recommendation is 1000 or more.
  • hashAlgo (module) – The hash algorithm to use, as a module or an object from the Crypto.Hash package. The digest length must be no shorter than dkLen. The default algorithm is Crypto.Hash.SHA1.
Returns:

A byte string of length dkLen that can be used as key.
Crypto.Protocol.KDF.PBKDF2(password, salt, dkLen=16, count=1000, prf=None)

Derive one or more keys from a password (or passphrase).

This function performs key derivation according to the PKCS#5 standard (v2.0).

Parameters:
  • password (string) – The secret password to generate the key from.
  • salt (string) – A string to use for better protection from dictionary attacks. This value does not need to be kept secret, but it should be randomly chosen for each derivation. It is recommended to be at least 8 bytes long.
  • dkLen (integer) – The cumulative length of the desired keys.
  • count (integer) – The number of iterations to carry out.
  • prf (callable) – A pseudorandom function. It must be a function that returns a pseudorandom string from two parameters: a secret and a salt. If not specified, HMAC-SHA1 is used.
Returns:

A byte string of length dkLen that can be used as key material. If you wanted multiple keys, just break up this string into segments of the desired length.
Crypto.Protocol.KDF.scrypt(password, salt, key_len, N, r, p, num_keys=1)

Derive one or more keys from a passphrase.

This function performs key derivation according to the scrypt algorithm, introduced in Percival’s paper “Stronger key derivation via sequential memory-hard functions”.

This implementation is based on RFC7914.

Parameters:
  • password (string) – The secret pass phrase to generate the keys from.
  • salt (string) – A string to use for better protection from dictionary attacks. This value does not need to be kept secret, but it should be randomly chosen for each derivation. It is recommended to be at least 8 bytes long.
  • key_len (integer) – The length in bytes of every derived key.
  • N (integer) – CPU/Memory cost parameter. It must be a power of 2 and less than \(2^{32}\).
  • r (integer) – Block size parameter.
  • p (integer) – Parallelization parameter. It must be no greater than \((2^{32}-1)/(4r)\).
  • num_keys (integer) – The number of keys to derive. Every key is key_len bytes long. By default, only 1 key is generated. The maximum cumulative length of all keys is \((2^{32}-1)*32\) (that is, 128TB).

A good choice of parameters (N, r , p) was suggested by Colin Percival in his presentation in 2009:

  • (16384, 8, 1) for interactive logins (<=100ms)
  • (1048576, 8, 1) for file encryption (<=5s)
Returns:A byte string or a tuple of byte strings.