a bit more language work + changelog changes for pbkdf2hmac
diff --git a/docs/changelog.rst b/docs/changelog.rst
index be42b5d..f401fe7 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -14,7 +14,7 @@
* Improved thread-safety for the OpenSSL backend.
* Fixed compilation on systems where OpenSSL's ``ec.h`` header is not
available, such as CentOS.
-* Added PBKDF2HMAC support to OpenSSL backend.
+* Added :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`.
0.1 - 2014-01-08
~~~~~~~~~~~~~~~~
diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index 56c3a2b..529f441 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -5,18 +5,18 @@
.. currentmodule:: cryptography.hazmat.primitives.kdf
-Key derivation functions derive key material from passwords or other data
-sources using a pseudo-random function (PRF). Different KDFs are suitable for
-different tasks such as:
+Key derivation functions derive bytes suitable for cryptographic operations
+from passwords or other data sources using a pseudo-random function (PRF).
+Different KDFs are suitable for different tasks such as:
-- Cryptographic key derivation
+* Cryptographic key derivation
Deriving a key suitable for use as input to an encryption algorithm.
Typically this means taking a password and running it through an algorithm
- such as :class:`~cryptography.hazmat.primitives.kdf.PBKDF2HMAC` or HKDF.
+ such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC` or HKDF.
This process is typically known as `key stretching`_.
-- Password storage
+* Password storage
When storing passwords you want to use an algorithm that is computationally
intensive. Legitimate users will only need to compute it once (for example,
@@ -25,13 +25,15 @@
Ideal password storage KDFs will be demanding on both computational and
memory resources.
-.. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend):
+.. currentmodule:: cryptography.hazmat.primitives.kdf.pbkdf2
+
+.. 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 an alternate key storage KDF such as `scrypt` is generally
+ key storage, but an alternate key storage KDF such as `scrypt`_ is generally
considered a better solution.
This class conforms to the
@@ -85,7 +87,7 @@
:param key_material bytes: The input key material. For PBKDF2 this
should be a password.
- :return: The new key.
+ :return bytes: the derived key.
:raises cryptography.exceptions.AlreadyFinalized: This is raised when
:meth:`derive` or
:meth:`verify` is