expand docs to talk more about the purposes of KDFs

1 files changed, 20 insertions, 4 deletions

diff --git a/docs/hazmat/primitives/key-derivation-functions.rst b/docs/hazmat/primitives/key-derivation-functions.rst
index bf069faa..56c3a2bd 100644
--- a/docs/hazmat/primitives/key-derivation-functions.rst
+++ b/docs/hazmat/primitives/key-derivation-functions.rst
@@ -6,9 +6,24 @@ Key Derivation Functions
 .. currentmodule:: cryptography.hazmat.primitives.kdf
 
 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.
+sources using a pseudo-random function (PRF). Different KDFs are suitable for
+different tasks such as:
+
+- 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.
+    This process is typically known as `key stretching`_.
+
+- 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,
+    taking the user's password, running it through the KDF, then comparing it
+    to the stored value), while attackers will need to do it billions of times.
+    Ideal password storage KDFs will be demanding on both computational and
+    memory resources.
 
 .. class:: PBKDF2HMAC(algorithm, length, salt, iterations, backend):
 
@@ -17,7 +32,7 @@ key stretching) so match your needs to their capabilities.
     `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
-    considered a better solution since it is designed to be slow.
+    considered a better solution.
 
     This class conforms to the
     :class:`~cryptography.hazmat.primitives.interfaces.KeyDerivationFunction`
@@ -105,3 +120,4 @@ key stretching) so match your needs to their capabilities.
 .. _`Password Storage Cheat Sheet`: https://www.owasp.org/index.php/Password_Storage_Cheat_Sheet
 .. _`PBKDF2`: http://en.wikipedia.org/wiki/PBKDF2
 .. _`scrypt`: http://en.wikipedia.org/wiki/Scrypt
+.. _`key stretching`: http://en.wikipedia.org/wiki/Key_stretching