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 thandkLen
. The default algorithm isCrypto.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, 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.
- 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 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.
- hmac_hash_module (module) – A module from Crypto.Hash implementing a Merkle-Damgard cryptographic
hash, which PBKDF2 must use in combination with HMAC.
This parameter is mutually exclusive with
prf
.
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.