From 3d8c66f9a01b8982902f69ae960fcc85aa43bfb8 Mon Sep 17 00:00:00 2001 From: Paul Kehrer Date: Tue, 28 Jan 2014 17:36:50 -0600 Subject: update docs with more detailed info re: PBKDF2 usage --- .../hazmat/primitives/key-derivation-functions.rst | 51 ++++++++++++++++++++-- 1 file changed, 48 insertions(+), 3 deletions(-) (limited to 'docs/hazmat/primitives') diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst index 4cb67701..e16a9900 100644 --- a/docs/hazmat/primitives/key-derivation-functions.rst +++ b/docs/hazmat/primitives/key-derivation-functions.rst @@ -5,13 +5,21 @@ Key Derivation Functions .. currentmodule:: cryptography.hazmat.primitives.kdf -Key derivation functions derive key material from information such as passwords -using a pseudo-random function (PRF). +Key derivation functions derive key material from passwords or other data +sources using a pseudo-random function (PRF). Each KDF is suitable for +different tasks (cryptographic key derivation, password storage, +key stretching) so match your needs to their capabilities. .. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend): .. versionadded:: 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 other key storage KDFs such as `scrypt`_ or `bcrypt`_ + are generally considered better solutions since they are designed to be + slow. + This class conforms to the :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction` interface. @@ -52,10 +60,47 @@ using a pseudo-random function (PRF). longer. :param int iterations: The number of iterations to perform of the hash function. See OWASP's `Password Storage Cheat Sheet`_ for more - detailed recommendations. + detailed recommendations if you intend to use this for password storage. :param backend: A :class:`~cryptography.hazmat.backends.interfaces.CipherBackend` provider. + .. method:: derive(key_material) + + :param key_material bytes: The input key material. For PBKDF2 this + should be a password. + :return: The new key. + :raises cryptography.exceptions.AlreadyFinalized: This is raised when + :meth:`derive` or + :meth:`verify` is + called more than + once. + + This generates and returns a new key from the supplied password. + + .. method:: verify(key_material, expected_key) + + :param key_material bytes: The input key material. This is the same as + ``key_material`` in :meth:`derive`. + :param expected_key bytes: The expected result of deriving a new key, + this is the same as the return value of + :meth:`derive`. + :raises cryptography.exceptions.InvalidKey: This is raised when the + derived key does not match + the expected key. + :raises cryptography.exceptions.AlreadyFinalized: This is raised when + :meth:`derive` or + :meth:`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 + checking whether a user's password attempt matches the stored derived + key. + .. _`NIST SP 800-132`: http://csrc.nist.gov/publications/nistpubs/800-132/nist-sp800-132.pdf .. _`Password Storage Cheat Sheet`: https://www.owasp.org/index.php/Password_Storage_Cheat_Sheet +.. _`bcrypt`: http://en.wikipedia.org/wiki/Bcrypt +.. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt -- cgit v1.2.3