finish PBKDF2HMAC rename, more docs

2 files changed, 22 insertions, 8 deletions

diff --git a/cryptography/hazmat/primitives/kdf/pbkdf2.py b/cryptography/hazmat/primitives/kdf/pbkdf2.py
index 940d9910..a496cc27 100644
--- a/cryptography/hazmat/primitives/kdf/pbkdf2.py
+++ b/cryptography/hazmat/primitives/kdf/pbkdf2.py
@@ -23,7 +23,7 @@ from cryptography.hazmat.primitives import constant_time, interfaces
 @utils.register_interface(interfaces.KeyDerivationFunction)
 class PBKDF2HMAC(object):
     def __init__(self, algorithm, length, salt, iterations, backend):
-        if not backend.pbkdf2_hash_supported(algorithm):
+        if not backend.pbkdf2_hmac_supported(algorithm):
             raise UnsupportedAlgorithm(
                 "{0} is not supported for PBKDF2 by this backend".format(
                     algorithm.name)
@@ -40,7 +40,7 @@ class PBKDF2HMAC(object):
             raise AlreadyFinalized("PBKDF2 instances can only be called once")
         else:
             self._called = True
-        return self._backend.derive_pbkdf2(
+        return self._backend.derive_pbkdf2_hmac(
             self.algorithm,
             self._length,
             self._salt,
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