aboutsummaryrefslogtreecommitdiffstats
path: root/docs/fernet.rst
diff options
context:
space:
mode:
authorAlex Gaynor <alex.gaynor@gmail.com>2014-10-19 19:18:59 -0700
committerAlex Gaynor <alex.gaynor@gmail.com>2014-10-20 07:55:00 -0700
commite148d01e7587f39d3ce15a1592dbd5e2dc4e9bca (patch)
tree1182bb482e4984567550258da290d99756382cb6 /docs/fernet.rst
parent7b593e1b5ecf9741a1398a739815b8a11599a06a (diff)
downloadcryptography-e148d01e7587f39d3ce15a1592dbd5e2dc4e9bca.tar.gz
cryptography-e148d01e7587f39d3ce15a1592dbd5e2dc4e9bca.tar.bz2
cryptography-e148d01e7587f39d3ce15a1592dbd5e2dc4e9bca.zip
Added docs for multifernet
Diffstat (limited to 'docs/fernet.rst')
-rw-r--r--docs/fernet.rst34
1 files changed, 31 insertions, 3 deletions
diff --git a/docs/fernet.rst b/docs/fernet.rst
index 4b713a54..1ff6cdbf 100644
--- a/docs/fernet.rst
+++ b/docs/fernet.rst
@@ -5,7 +5,8 @@ Fernet (symmetric encryption)
Fernet provides guarantees that a message encrypted using it cannot be
manipulated or read without the key. `Fernet`_ is an implementation of
-symmetric (also known as "secret key") authenticated cryptography.
+symmetric (also known as "secret key") authenticated cryptography. Fernet also
+has support for implementing key rotation via :class:`MultiFernet`.
.. class:: Fernet(key)
@@ -40,7 +41,8 @@ symmetric (also known as "secret key") authenticated cryptography.
:returns bytes: A secure message that cannot be read or altered
without the key. It is URL-safe base64-encoded. This is
referred to as a "Fernet token".
- :raises TypeError: This exception is raised if ``data`` is not ``bytes``.
+ :raises TypeError: This exception is raised if ``data`` is not
+ ``bytes``.
.. note::
@@ -67,7 +69,33 @@ symmetric (also known as "secret key") authenticated cryptography.
``ttl``, it is malformed, or
it does not have a valid
signature.
- :raises TypeError: This exception is raised if ``token`` is not ``bytes``.
+ :raises TypeError: This exception is raised if ``token`` is not
+ ``bytes``.
+
+
+.. class:: MultiFernet(fernets)
+
+ This class implements key rotation for Fernet. It takes a ``list`` of
+ :class:`Fernet` instances, and implements the same API:
+
+ .. doctest::
+
+ >>> from cryptography.fernet import Fernet, MultiFernet
+ >>> key1 = Fernet(Fernet.generate_key())
+ >>> key2 = Fernet(Fernet.generate_key())
+ >>> f = MultiFernet([key1, key2])
+ >>> token = f.encrypt(b"Secret message!")
+ >>> token
+ '...'
+ >>> f.decrypt(token)
+ 'Secret message!'
+
+ Fernet performs all encryption options using the *first* key in the
+ ``list`` provided. Decryption supports using *any* of constituent keys.
+
+ Key rotation makes it easy to replace old keys. You can add your new key at
+ the front of the list to start encrypting new messages, and remove old keys
+ as they are no longer needed.
.. class:: InvalidToken