From b964a5cfb006229c1cdb1a4cf97df845ef5e754e Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 18:53:47 +0800 Subject: Add some text regarding using passwords with Fernet. --- docs/fernet.rst | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) (limited to 'docs/fernet.rst') diff --git a/docs/fernet.rst b/docs/fernet.rst index 8ea33eef..b6ee87f7 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -106,6 +106,43 @@ has support for implementing key rotation via :class:`MultiFernet`. 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 like +:class:`~cryptography.hazmat.primitives.kdf.PBKDF2`: + +.. code-block:: python + + import base64 + import os + from cryptography.hazmat.primitives import hashes + from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC + from cryptography.hazmat.backends import default_backend + from cryptography.fernet import Fernet + + 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 100k iterations which is what Django +`recommends`_. + Implementation -------------- @@ -125,3 +162,4 @@ For complete details consult the `specification`_. .. _`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 -- cgit v1.2.3 From 1ef3aa3ea3bfe10f234aa4292d6f65d76c89b192 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 19:04:57 +0800 Subject: Fix link. --- docs/fernet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/fernet.rst') diff --git a/docs/fernet.rst b/docs/fernet.rst index b6ee87f7..1cea0a7a 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -162,4 +162,4 @@ For complete details consult the `specification`_. .. _`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 +.. _`recommends`: https://github.com/django/django/blob/master/django/utils/crypto.py#L148 -- cgit v1.2.3 From d9f8bfaaa8c0f416a468e47e7b494661b30f42c8 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 19:08:39 +0800 Subject: Fixed PBKDF2 class target. --- docs/fernet.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'docs/fernet.rst') diff --git a/docs/fernet.rst b/docs/fernet.rst index 1cea0a7a..d4a7d284 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -112,7 +112,7 @@ 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 like -:class:`~cryptography.hazmat.primitives.kdf.PBKDF2`: +:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`: .. code-block:: python -- cgit v1.2.3 From 7126e61fc31d9684314c3749f4b552f6d43e39fc Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sat, 29 Aug 2015 22:28:51 +0800 Subject: Fix imports and wordings. --- docs/fernet.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) (limited to 'docs/fernet.rst') diff --git a/docs/fernet.rst b/docs/fernet.rst index d4a7d284..18aab439 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -111,17 +111,18 @@ 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 like +password through a key derivation function such as :class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`: .. 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 - from cryptography.hazmat.backends import default_backend - from cryptography.fernet import Fernet password = b"password" salt = os.urandom(16) @@ -140,8 +141,8 @@ 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 100k iterations which is what Django -`recommends`_. +tolerate. A good default is at least 100,000 iterations which is what Django +`recommends`_ in 2014. Implementation -------------- -- cgit v1.2.3 From b1903b0d4caaac29f78b7421704caf01255b3c13 Mon Sep 17 00:00:00 2001 From: Terry Chia Date: Sun, 30 Aug 2015 11:09:22 +0800 Subject: Mention bcrypt and scrypt. --- docs/fernet.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'docs/fernet.rst') diff --git a/docs/fernet.rst b/docs/fernet.rst index 18aab439..a066ae63 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -112,7 +112,8 @@ 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`: +:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`, bcrypt or +scrypt. .. code-block:: python -- cgit v1.2.3