Merge pull request #2304 from Ayrx/fernet-docs-kdf
Add some text regarding using passwords with Fernet.
diff --git a/docs/fernet.rst b/docs/fernet.rst
index 8ea33ee..a066ae6 100644
--- a/docs/fernet.rst
+++ b/docs/fernet.rst
@@ -106,6 +106,45 @@
See :meth:`Fernet.decrypt` for more information.
+
+Using passwords with Fernet
+---------------------------
+
+It is possible to use passwords with Fernet. To do this, you need to run the
+password through a key derivation function such as
+:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`, bcrypt or
+scrypt.
+
+.. code-block:: python
+
+ import base64
+ import os
+
+ from cryptography.fernet import Fernet
+ from cryptography.hazmat.backends import default_backend
+ from cryptography.hazmat.primitives import hashes
+ from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC
+
+ password = b"password"
+ salt = os.urandom(16)
+
+ kdf = PBKDF2HMAC(
+ algorithm=hashes.SHA256(),
+ length=32,
+ salt=salt,
+ iterations=100000,
+ backend=default_backend
+ )
+ key = base64.urlsafe_b64encode(kdf.derive(password))
+ f = Fernet(key)
+
+In this scheme, the salt has to be stored in a retrievable location in order
+to derive the same key from the password in the future.
+
+The iteration count used should be adjusted to be as high as your server can
+tolerate. A good default is at least 100,000 iterations which is what Django
+`recommends`_ in 2014.
+
Implementation
--------------
@@ -125,3 +164,4 @@
.. _`Fernet`: https://github.com/fernet/spec/
.. _`specification`: https://github.com/fernet/spec/blob/master/Spec.md
+.. _`recommends`: https://github.com/django/django/blob/master/django/utils/crypto.py#L148
diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt
index 1eed7c7..7549784 100644
--- a/docs/spelling_wordlist.txt
+++ b/docs/spelling_wordlist.txt
@@ -1,6 +1,7 @@
affine
backend
backends
+bcrypt
Backends
Blowfish
boolean
@@ -22,6 +23,7 @@
deserialized
Diffie
Docstrings
+Django
Encodings
fernet
Fernet