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