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).

PBKDF2¶

PBKDF2 is the most widespread algorithm for deriving keys from a password, originally defined in version 2.0 of the PKCS#5 standard or in RFC2898.

It is computationally expensive (a property that can be tuned via the count parameter) so as to thwart dictionary and rainbow tables attacks. However, it uses a very limited amount of RAM which makes it insufficiently protected against advanced and motivated adversaries that can leverage GPUs.

New applications and protocols should use scrypt or bcrypt instead.

Always pass the count and hmac_hash_module parameters: their defaults (1000 iterations and HMAC-SHA1) are weak, deprecated (they emit a DeprecationWarning), and will be removed.

For example, if you need to derive two AES256 keys:

from Crypto.Protocol.KDF import PBKDF2
from Crypto.Hash import SHA512
from Crypto.Random import get_random_bytes

password = b'my super secret'
salt = get_random_bytes(16)
keys = PBKDF2(password, salt, 64, count=1000000, hmac_hash_module=SHA512)
key1 = keys[:32]
key2 = keys[32:]

Crypto.Protocol.KDF.PBKDF2(password, salt, dkLen=16, count=None, prf=None, hmac_hash_module=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 or byte string) –
The secret password to generate the key from.

Strings will be encoded as ISO 8859-1 (also known as Latin-1), which does not allow any characters with codepoints > 255.
salt (string or byte string) –
A (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. It is recommended to use at least 16 bytes.

Strings will be encoded as ISO 8859-1 (also known as Latin-1), which does not allow any characters with codepoints > 255.
dkLen (integer) –
The cumulative length of the keys to produce.

Due to a flaw in the PBKDF2 design, you should not request more bytes than the prf can output. For instance, dkLen should not exceed 20 bytes in combination with HMAC-SHA1.
count (integer) –
The number of iterations to carry out. The higher the value, the slower and the more secure the function becomes. It is mandatory.

You should find the maximum number of iterations that keeps the key derivation still acceptable on the slowest hardware you must support. For passwords, OWASP recommends at least 600 000 iterations with HMAC-SHA256.

Deprecated since version 4.0: If omitted, 1000 iterations are used, with a DeprecationWarning. This default will be removed.
prf (callable) – A pseudorandom function. It must be a function that returns a pseudorandom byte string from two parameters: a secret and a salt. The slower the algorithm, the more secure the derivation function. This parameter is mutually exclusive with hmac_hash_module.
hmac_hash_module (module) –
A module from Crypto.Hash implementing a Merkle-Damgard cryptographic hash, which PBKDF2 must use in combination with HMAC (for instance, Crypto.Hash.SHA256). This parameter is mutually exclusive with prf, and one of the two is mandatory.

Deprecated since version 4.0: If both are omitted, HMAC-SHA1 is used, with a DeprecationWarning. This default will be removed.

Return type:

bytes

Returns:

A byte string of length dkLen that can be used as key material. If you want multiple keys, just break up this string into segments of the desired length.

scrypt¶

scrypt is a password-based key derivation function created by Colin Percival, described in his paper “Stronger key derivation via sequential memory-hard functions” and in RFC7914.

In addition to being computationally expensive, it is also memory intensive and therefore more secure against the risk of custom ASICs.

Example:

from Crypto.Protocol.KDF import scrypt
from Crypto.Random import get_random_bytes

password = b'my super secret'
salt = get_random_bytes(16)
key = scrypt(password, salt, 16, N=2**14, r=8, p=1)

With a parallelization parameter p larger than 1, scrypt computes p independent flows, which can run on several CPU cores with the threads parameter:

key = scrypt(password, salt, 16, N=2**14, r=8, p=4, threads=4)

With threads=0, it uses as many threads as the CPU cores available to the process. The output does not depend on the number of threads, but each thread uses its own $128 \cdot r \cdot N$ bytes of memory, at the same time: with 4 threads, scrypt needs 4 times as much memory as with one.

Crypto.Protocol.KDF.scrypt(password, salt, key_len, N, r, p, num_keys=1, *, threads=1)¶

Derive one or more keys from a passphrase.

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 16 bytes long.
key_len (integer) – The length in bytes of each 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).
threads (integer) – The maximum number of threads used to compute the p independent flows in parallel (default: 1, no extra threads; 0 for all CPU cores). At most p threads are used, so there is no benefit when p is 1. Each thread needs its own $128 \cdot r \cdot N$ bytes of memory, at the same time: in total, $\min(threads, p) \cdot 128 \cdot r \cdot N$ bytes. The output does not depend on the number of threads.

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

( 2¹⁴, 8, 1 ) for interactive logins (≤100ms)
( 2²⁰, 8, 1 ) for file encryption (≤5s)

Return type:: Union[bytes, list[bytes]]
Returns:: A byte string or a tuple of byte strings.

bcrypt¶

bcrypt is a password hashing function designed by Niels Provos and David Mazières.

In addition to being computationally expensive, it is also memory intensive and therefore more secure against the risk of custom ASICs.

This implementation only supports bcrypt hashes with prefix $2a.

By design, bcrypt only accepts passwords up to 72 byte long. If you want to hash passwords with no restrictions on their length, it is common practice to apply a cryptographic hash and then BASE64-encode For instance:

from base64 import b64encode
from Crypto.Hash import SHA256
from Crypto.Protocol.KDF import bcrypt

password = b"test"
b64pwd = b64encode(SHA256.new(password).digest())
bcrypt_hash = bcrypt(b64pwd, 12)

and to check them:

from base64 import b64encode
from Crypto.Hash import SHA256
from Crypto.Protocol.KDF import bcrypt

password_to_test = b"test"
try:
    b64pwd = b64encode(SHA256.new(password).digest())
    bcrypt_check(b64pwd, bcrypt_hash)
except ValueError:
    print("Incorrect password")

The bcrypt hash states its own cost (up to 31), and the time doubles at every step. To protect against a hash from an untrusted source, bcrypt_check() rejects a cost above 20 (about one minute on a recent laptop): use the parameter max_cost to change this limit (see the limits).

Warning

The output of bcrypt is only meant to be stored. It is not meant to be used as key material.

Crypto.Protocol.KDF.bcrypt(password, cost, salt=None)¶

Hash a password into a key, using the OpenBSD bcrypt protocol.

Parameters:

password (byte string or string) – The secret password or pass phrase. It must be at most 72 bytes long. It must not contain the zero byte. Unicode strings will be encoded as UTF-8.
cost (integer) – The exponential factor that makes it slower to compute the hash. It must be in the range 4 to 31. A value of at least 12 is recommended.
salt (byte string) – Optional. Random byte string to thwarts dictionary and rainbow table attacks. It must be 16 bytes long. If not passed, a random value is generated.

Return type:

bytes

Return (byte string):: The bcrypt hash

Raises:: ValueError – if password is longer than 72 bytes or if it contains the zero byte

Crypto.Protocol.KDF.bcrypt_check(password, bcrypt_hash, *, max_cost=None)¶

Verify if the provided password matches the given bcrypt hash.

Parameters:

password (byte string or string) – The secret password or pass phrase to test. It must be at most 72 bytes long. It must not contain the zero byte. Unicode strings will be encoded as UTF-8.
bcrypt_hash (byte string, bytearray) – The reference bcrypt hash the password needs to be checked against.
max_cost (integer) – The maximum cost allowed for the bcrypt hash. The hash states its own cost (up to 31), and the time doubles at every step: a hash from an untrusted source could tie up the CPU for a day. The default value is None (a limit of 20, about one minute on a recent laptop). Set it to 0 to disable the check. See the limits for decryption.

Raises:

KdfIterationLimitError – (a ValueError) if the cost of the hash is above max_cost
ValueError – if the password does not match

Return type:

None

HKDF¶

The HMAC-based Extract-and-Expand key derivation function (HKDF) was designed by Hugo Krawczyk. It is standardized in RFC 5869 and in NIST SP-800 56C.

This KDF is not suitable for deriving keys from a password or for key stretching.

Example, for deriving two AES256 keys:

from Crypto.Protocol.KDF import HKDF
from Crypto.Hash import SHA512
from Crypto.Random import get_random_bytes

salt = get_random_bytes(16)
key1, key2 = HKDF(master_secret, 32, salt, SHA512, 2)

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.

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.
key_len (integer) – The length in bytes of every derived key.
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.
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.

Return type:

Union[bytes, list[bytes]]

Returns:

A byte string or a tuple of byte strings.

SP 800-108 Counter Mode¶

A KDF can be generically constructed with a pseudorandom function (PRF). If the PRF has a fixed-length output, you can evaluate the PRF multiple times and concatenate the results until you collect enough derived keying material.

This function implements such type of KDF, where a counter contributes to each invokation of the PRF, as defined in NIST SP 800-108 Rev 1. The NIST standard only allows the use of HMAC (recommended) and CMAC (not recommended) as PRF.

This KDF is not suitable for deriving keys from a password.

Example 1 (HMAC as PRF, one AES128 key to derive):

>> from Crypto.Hash import SHA256, HMAC
>>
>> def prf(s, x):
>>     return HMAC.new(s, x, SHA256).digest()
>>
>> key_derived = SP800_108_Counter(secret, 16, prf, label=b'Key A')

Example 2 (HMAC as PRF, two AES128 keys to derive):

>> from Crypto.Hash import SHA256, HMAC
>>
>> def prf(s, x):
>>     return HMAC.new(s, x, SHA256).digest()
>>
>> key_A, key_B = SP800_108_Counter(secret, 16, prf, num_keys=2, label=b'Key AB')

Example 3 (CMAC as PRF, two AES256 keys to derive):

>> from Crypto.Cipher import AES
>> from Crypto.Hash import SHA256, CMAC
>>
>> def prf(s, x):
>>     return CMAC.new(s, x, AES).digest()
>>
>> key_A, key_B = SP800_108_Counter(secret, 32, prf, num_keys=2, label=b'Key AB')

Crypto.Protocol.KDF.SP800_108_Counter(master, key_len, prf, num_keys=None, label=b'', context=b'')¶

Derive one or more keys from a master secret using a pseudorandom function in Counter Mode, as specified in NIST SP 800-108r1.

Parameters:

master (byte string) – The secret value used by the KDF to derive the other keys. It must not be a password. The length on the secret must be consistent with the input expected by the prf function.
key_len (integer) – The length in bytes of each derived key.
prf (function) – A pseudorandom function that takes two byte strings as parameters: the secret and an input. It returns another byte string.
num_keys (integer) – The number of keys to derive. Every key is key_len bytes long. By default, only 1 key is derived.
label (byte string) – Optional description of the purpose of the derived keys (for instance, an ASCII string). It must not contain zero bytes.
context (byte string) – Optional information pertaining to the protocol that uses the keys, such as the identity of the participants, nonces, session IDs, etc. It can contain any byte value.

Return type:

Union[bytes, list[bytes]]

Returns:

a byte string (if num_keys is not specified, or it is 1), or
a list of byte strings (if num_keys is 2 or more).

PBKDF1¶

PBKDF1 is an old key derivation function defined in version 2.0 of the PKCS#5 standard (v1.5) or in RFC2898.

Warning

Newer applications should use the more secure and versatile scrypt instead.

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), still described in RFC 8018.

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.

Return type:

bytes

Returns:

A byte string of length dkLen that can be used as key.