Merge pull request #1422 from alex/multi-fernet

Fixes #1327 -- adds multifernet

1 files changed, 33 insertions, 3 deletions

diff --git a/docs/fernet.rst b/docs/fernet.rst
index 4b713a54..f1a4c748 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,35 @@ 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)
+
+    .. versionadded:: 0.7
+
+    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