diff options
| -rw-r--r-- | docs/fernet.rst | 34 |
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 |