Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

Key derivation functions 

Key derivation functions derive bytes suitable for cryptographic operations from passwords or other data sources using a pseudo-random function (PRF). Different KDFs are suitable for different tasks such as:

Cryptographic key derivation

Deriving a key suitable for use as input to an encryption algorithm. Typically this means taking a password and running it through an algorithm such as PBKDF2HMAC or HKDF . This process is typically known as key stretching .

Password storage

When storing passwords you want to use an algorithm that is computationally intensive. Legitimate users will only need to compute it once (for example, taking the user’s password, running it through the KDF, then comparing it to the stored value), while attackers will need to do it billions of times. Ideal password storage KDFs will be demanding on both computational and memory resources.

Variable cost algorithms 

PBKDF2 

class cryptography.hazmat.primitives.kdf.pbkdf2. PBKDF2HMAC ( algorithm , length , salt , iterations ) [source] 

Added in version 0.2.

PBKDF2 (Password Based Key Derivation Function 2) is typically used for deriving a cryptographic key from a password. It may also be used for key storage, but an alternate key storage KDF such as Scrypt is generally considered a better solution.

This class conforms to the KeyDerivationFunction interface.

>>> import os
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
>>> # Salts should be randomly generated
>>> salt = os.urandom(16)
>>> # derive
>>> kdf = PBKDF2HMAC(
...     algorithm=hashes.SHA256(),
...     length=32,
...     salt=salt,
...     iterations=480000,
... )
>>> key = kdf.derive(b"my great password")
>>> # verify
>>> kdf = PBKDF2HMAC(
...     algorithm=hashes.SHA256(),
...     length=32,
...     salt=salt,
...     iterations=480000,
... )
>>> kdf.verify(b"my great password", key)

>>> import os >>> from cryptography.hazmat.primitives.kdf.scrypt import Scrypt >>> salt = os.urandom(16) >>> # derive >>> kdf = Scrypt( ... salt=salt, ... length=32, ... n=2**14, ... r=8, ... p=1, ... ) >>> key = kdf.derive(b"my great password") >>> # verify >>> kdf = Scrypt( ... salt=salt, ... length=32, ... n=2**14, ... r=8, ... p=1, ... ) >>> kdf.verify(b"my great password", key)

Fixed cost algorithms 

ConcatKDF 

class cryptography.hazmat.primitives.kdf.concatkdf. ConcatKDFHash ( algorithm , length , otherinfo ) [source] 

Added in version 1.0.

ConcatKDFHash (Concatenation Key Derivation Function) is defined by the NIST Special Publication NIST SP 800-56Ar3 document, to be used to derive keys for use after a Key Exchange negotiation operation.

Warning

ConcatKDFHash should not be used for password storage.

>>> import os
>>> from cryptography.hazmat.primitives import hashes
>>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHash
>>> otherinfo = b"concatkdf-example"
>>> ckdf = ConcatKDFHash(
...     algorithm=hashes.SHA256(),
...     length=32,
...     otherinfo=otherinfo,
... )
>>> key = ckdf.derive(b"input key")
>>> ckdf = ConcatKDFHash(
...     algorithm=hashes.SHA256(),
...     length=32,
...     otherinfo=otherinfo,
... )
>>> ckdf.verify(b"input key", key)

>>> import os >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.kdf.concatkdf import ConcatKDFHMAC >>> salt = os.urandom(16) >>> otherinfo = b"concatkdf-example" >>> ckdf = ConcatKDFHMAC( ... algorithm=hashes.SHA256(), ... length=32, ... salt=salt, ... otherinfo=otherinfo, ... ) >>> key = ckdf.derive(b"input key") >>> ckdf = ConcatKDFHMAC( ... algorithm=hashes.SHA256(), ... length=32, ... salt=salt, ... otherinfo=otherinfo, ... ) >>> ckdf.verify(b"input key", key)

>>> import os >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDF >>> salt = os.urandom(16) >>> info = b"hkdf-example" >>> hkdf = HKDF( ... algorithm=hashes.SHA256(), ... length=32, ... salt=salt, ... info=info, ... ) >>> key = hkdf.derive(b"input key") >>> hkdf = HKDF( ... algorithm=hashes.SHA256(), ... length=32, ... salt=salt, ... info=info, ... ) >>> hkdf.verify(b"input key", key)

>>> import os >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.kdf.hkdf import HKDFExpand >>> info = b"hkdf-example" >>> key_material = os.urandom(16) >>> hkdf = HKDFExpand( ... algorithm=hashes.SHA256(), ... length=32, ... info=info, ... ) >>> key = hkdf.derive(key_material) >>> hkdf = HKDFExpand( ... algorithm=hashes.SHA256(), ... length=32, ... info=info, ... ) >>> hkdf.verify(key_material, key)

>>> import os >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.kdf.kbkdf import ( ... CounterLocation, KBKDFHMAC, Mode ... ) >>> label = b"KBKDF HMAC Label" >>> context = b"KBKDF HMAC Context" >>> kdf = KBKDFHMAC( ... algorithm=hashes.SHA256(), ... mode=Mode.CounterMode, ... length=32, ... rlen=4, ... llen=4, ... location=CounterLocation.BeforeFixed, ... label=label, ... context=context, ... fixed=None, ... ) >>> key = kdf.derive(b"input key") >>> kdf = KBKDFHMAC( ... algorithm=hashes.SHA256(), ... mode=Mode.CounterMode, ... length=32, ... rlen=4, ... llen=4, ... location=CounterLocation.BeforeFixed, ... label=label, ... context=context, ... fixed=None, ... ) >>> kdf.verify(b"input key", key)

>>> from cryptography.hazmat.primitives.ciphers import algorithms >>> from cryptography.hazmat.primitives.kdf.kbkdf import ( ... CounterLocation, KBKDFCMAC, Mode ... ) >>> label = b"KBKDF CMAC Label" >>> context = b"KBKDF CMAC Context" >>> kdf = KBKDFCMAC( ... algorithm=algorithms.AES, ... mode=Mode.CounterMode, ... length=32, ... rlen=4, ... llen=4, ... location=CounterLocation.BeforeFixed, ... label=label, ... context=context, ... fixed=None, ... ) >>> key = kdf.derive(b"32 bytes long input key material") >>> kdf = KBKDFCMAC( ... algorithm=algorithms.AES, ... mode=Mode.CounterMode, ... length=32, ... rlen=4, ... llen=4, ... location=CounterLocation.BeforeFixed, ... label=label, ... context=context, ... fixed=None, ... ) >>> kdf.verify(b"32 bytes long input key material", key)

>>> import os >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.kdf.x963kdf import X963KDF >>> sharedinfo = b"ANSI X9.63 Example" >>> xkdf = X963KDF( ... algorithm=hashes.SHA256(), ... length=32, ... sharedinfo=sharedinfo, ... ) >>> key = xkdf.derive(b"input key") >>> xkdf = X963KDF( ... algorithm=hashes.SHA256(), ... length=32, ... sharedinfo=sharedinfo, ... ) >>> xkdf.verify(b"input key", key)

Interface 

class cryptography.hazmat.primitives.kdf. KeyDerivationFunction [source] 

Added in version 0.2.

derive ( key_material ) [source] 

Parameters :: key_material ( bytes ) – The input key material. Depending on what key derivation function you are using this could be either random bytes, or a user supplied password.
Returns :: The new key.
Raises :: cryptography.exceptions.AlreadyFinalized – This is raised when derive() or verify() is called more than once.

This generates and returns a new key from the supplied key material.

verify ( key_material , expected_key ) [source] 

Parameters :

key_material ( bytes ) – The input key material. This is the same as key_material in derive() .
expected_key ( bytes ) – The expected result of deriving a new key, this is the same as the return value of derive() .

Raises :

cryptography.exceptions.InvalidKey – This is raised when the derived key does not match the expected key.
cryptography.exceptions.AlreadyFinalized – This is raised when derive() or verify() is called more than once.

This checks whether deriving a new key from the supplied key_material generates the same key as the expected_key , and raises an exception if they do not match. This can be used for something like checking whether a user’s password attempt matches the stored derived key.

Key derivation functions 

Variable cost algorithms 

PBKDF2 

Scrypt 

Fixed cost algorithms 

ConcatKDF 

HKDF 

KBKDF 

X963KDF 

Interface 