1Key Derivation Functions
2========================
3
4This module contains a collection of standard key derivation functions.
5
6A key derivation function derives one or more secondary secret keys from
7one primary secret (a master key or a pass phrase).
8
9This is typically done to insulate the secondary keys from each other,
10to avoid that leakage of a secondary key compromises the security of the
11master key, or to thwart attacks on pass phrases (e.g. via rainbow tables).
12
13PBKDF2
14+++++++
15
16PBKDF2 is the most widespread algorithm for deriving keys from a password,
17originally defined in version 2.0 of the PKCS#5 standard or in `RFC2898 <https://www.ietf.org/rfc/rfc2898.txt>`_.
18
19It is computationally expensive (a property that can be tuned via the ``count`` parameter) so as to thwart dictionary and rainbow tables attacks.
20However, it uses a very limited amount of RAM which makes it insufficiently
21protected against advanced and motivated adversaries that can leverage GPUs.
22
23New applications and protocols should use :ref:`scrypt <scrypt_func>` or :ref:`bcrypt <bcrypt_func>` instead.
24
25For example, if you need to derive two AES256 keys::
26
27    from Crypto.Protocol.KDF import PBKDF2
28    from Crypto.Hash import SHA512
29    from Crypto.Random import get_random_bytes
30
31    password = b'my super secret'
32    salt = get_random_bytes(16)
33    keys = PBKDF2(password, salt, 64, count=1000000, hmac_hash_module=SHA512)
34    key1 = keys[:32]
35    key2 = keys[32:]
36
37.. autofunction:: Crypto.Protocol.KDF.PBKDF2
38
39scrypt
40+++++++
41
42`scrypt <http://www.tarsnap.com/scrypt.html>`_ is a password-based key derivation function created by Colin Percival,
43described in his paper `"Stronger key derivation via sequential memory-hard functions" <http://www.tarsnap.com/scrypt/scrypt.pdf>`_
44and in `RFC7914 <https://tools.ietf.org/html/rfc7914>`_.
45
46In addition to being computationally expensive, it is also memory intensive and
47therefore more secure against the risk of custom ASICs.
48
49Example::
50
51    from Crypto.Protocol.KDF import scrypt
52    from Crypto.Random import get_random_bytes
53
54    password = b'my super secret'
55    salt = get_random_bytes(16)
56    key = scrypt(password, salt, 16, N=2**14, r=8, p=1)
57
58.. _scrypt_func:
59
60.. autofunction:: Crypto.Protocol.KDF.scrypt
61
62
63bcrypt
64+++++++
65
66`bcrypt <https://www.usenix.org/legacy/events/usenix99/provos/provos_html/node1.html>`_ is a password hashing function designed by Niels Provos and David Mazières.
67
68In addition to being computationally expensive, it is also memory intensive and
69therefore more secure against the risk of custom ASICs.
70
71This implementation only supports bcrypt hashes with prefix ``$2a``.
72
73By design, ``bcrypt`` only accepts passwords up to 72 byte long.
74If you want to hash passwords with no restrictions on their length, it is common practice to apply a cryptographic hash and then BASE64-encode
75For instance::
76
77    from base64 import b64encode
78    from Crypto.Hash import SHA256
79    from Crypto.Protocol.KDF import bcrypt
80
81    password = b"test"
82    b64pwd = b64encode(SHA256.new(password).digest())
83    bcrypt_hash = bcrypt(b64pwd, 12)
84
85and to check them::
86
87    from base64 import b64encode
88    from Crypto.Hash import SHA256
89    from Crypto.Protocol.KDF import bcrypt
90
91    password_to_test = b"test"
92    try:
93        b64pwd = b64encode(SHA256.new(password).digest())
94        bcrypt_check(b64pwd, bcrypt_hash)
95    except ValueError:
96        print("Incorrect password")
97
98.. warning:
99    The output of ``bcrypt`` is only meant to be stored. It is not meant to be
100    used as key material.
101
102.. _bcrypt_func:
103
104.. autofunction:: Crypto.Protocol.KDF.bcrypt
105.. autofunction:: Crypto.Protocol.KDF.bcrypt_check
106
107HKDF
108+++++
109
110The HMAC-based Extract-and-Expand key derivation function (HKDF) was `designed by Hugo Krawczyk <https://eprint.iacr.org/2010/264.pdf>`_.
111It is standardized in `RFC 5869 <https://tools.ietf.org/html/rfc5869>`_ and in `NIST SP-800 56C <http://csrc.nist.gov/publications/nistpubs/800-56C/SP-800-56C.pdf>`_.
112
113This KDF is not suitable for deriving keys from a password or for key stretching.
114
115Example, for deriving two AES256 keys::
116
117    from Crypto.Protocol.KDF import HKDF
118    from Crypto.Hash import SHA512
119    from Crypto.Random import get_random_bytes
120
121    salt = get_random_bytes(16)
122    key1, key2 = HKDF(master_secret, 32, salt, SHA512, 2)
123
124.. autofunction:: Crypto.Protocol.KDF.HKDF
125
126PBKDF1
127+++++++
128
129PBKDF1 is an old key derivation function defined in version 2.0 of the PKCS#5 standard (v1.5) or in `RFC2898 <https://www.ietf.org/rfc/rfc2898.txt>`_.
130
131.. warning::
132    Newer applications should use the more secure and versatile :ref:`scrypt <scrypt_func>` instead.
133
134.. autofunction:: Crypto.Protocol.KDF.PBKDF1
135