finish PBKDF2HMAC rename, more docs

1 files changed, 20 insertions, 6 deletions

diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index bad7a36c..661b4611 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -8,7 +8,7 @@ Key Derivation Functions
 Key derivation functions derive key material from information such as passwords
 using a pseudo-random function (PRF).
 
-.. class:: PBKDF2(algorithm, length, salt, iterations, backend):
+.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend):
 
     .. versionadded:: 0.2
 
@@ -20,28 +20,42 @@ using a pseudo-random function (PRF).
 
         >>> import os
         >>> from cryptography.hazmat.primitives import hashes
-        >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2
+        >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
         >>> from cryptography.hazmat.backends import default_backend
         >>> backend = default_backend()
         >>> salt = os.urandom(16)
         >>> # derive
-        >>> kdf = PBKDF2(hashes.SHA1(), 20, salt, 10000, backend)
+        >>> kdf = PBKDF2HMAC(
+        ...     algorithm=hashes.SHA256(),
+        ...     length=32,
+        ...     salt=salt,
+        ...     iterations=50000,
+        ...     backend=backend
+        ... )
         >>> key = kdf.derive(b"my great password")
         >>> # verify
-        >>> kdf = PBKDF2(hashes.SHA1(), 20, salt, 10000, backend)
+        >>> kdf = PBKDF2HMAC(
+        ...     algorithm=hashes.SHA256(),
+        ...     length=32,
+        ...     salt=salt,
+        ...     iterations=50000,
+        ...     backend=backend
+        ... )
         >>> kdf.verify(b"my great password", key)
 
     :param algorithm: An instance of a
         :class:`~cryptography.hazmat.primitives.interfaces.HashAlgorithm`
         provider.
     :param int length: The desired length of the derived key. Maximum is
-        (2\ :sup:`32` - 1) * ``algorithm.digest_size``
+        (2\ :sup:`32` - 1) * ``algorithm.digest_size``.
     :param bytes salt: A salt. `NIST SP 800-132`_ recommends 128-bits or
         longer.
     :param int iterations: The number of iterations to perform of the hash
-        function.
+        function. See OWASP's `Password Storage Cheat Sheet`_ for more
+        detailed recommendations.
     :param backend: A
         :class:`~cryptography.hazmat.backends.interfaces.CipherBackend`
         provider.
 
 .. _`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