update docs with more detailed info re: PBKDF2 usage
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index 4cb6770..e16a990 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -5,13 +5,21 @@
.. 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 @@
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