diff options
| -rw-r--r-- | CHANGELOG.rst | 2 | ||||
| -rw-r--r-- | cryptography/fernet.py | 21 | ||||
| -rw-r--r-- | docs/fernet.rst | 36 | ||||
| -rw-r--r-- | tests/test_fernet.py | 36 |
4 files changed, 91 insertions, 4 deletions
diff --git a/CHANGELOG.rst b/CHANGELOG.rst index c8cec58d..1d69d9cb 100644 --- a/CHANGELOG.rst +++ b/CHANGELOG.rst @@ -6,6 +6,8 @@ Changelog .. note:: This version is not yet released and is under active development. +* Added key-rotation support to :doc:`Fernet </fernet>` with + :class:`~cryptography.fernet.MultiFernet`. * More bit-lengths are now support for ``p`` and ``q`` when loading DSA keys from numbers. * Added :class:`~cryptography.hazmat.primitives.interfaces.MACContext` as a diff --git a/cryptography/fernet.py b/cryptography/fernet.py index a8e0330e..4f98feec 100644 --- a/cryptography/fernet.py +++ b/cryptography/fernet.py @@ -127,3 +127,24 @@ class Fernet(object): except ValueError: raise InvalidToken return unpadded + + +class MultiFernet(object): + def __init__(self, fernets): + fernets = list(fernets) + if not fernets: + raise ValueError( + "MultiFernet requires at least one Fernet instance" + ) + self._fernets = fernets + + def encrypt(self, msg): + return self._fernets[0].encrypt(msg) + + def decrypt(self, msg, ttl=None): + for f in self._fernets: + try: + return f.decrypt(msg, ttl) + except InvalidToken: + pass + raise InvalidToken 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 diff --git a/tests/test_fernet.py b/tests/test_fernet.py index 0b4e3e87..5c630b9e 100644 --- a/tests/test_fernet.py +++ b/tests/test_fernet.py @@ -24,7 +24,7 @@ import pytest import six -from cryptography.fernet import Fernet, InvalidToken +from cryptography.fernet import Fernet, InvalidToken, MultiFernet from cryptography.hazmat.backends import default_backend from cryptography.hazmat.primitives.ciphers import algorithms, modes @@ -115,3 +115,37 @@ class TestFernet(object): def test_bad_key(self, backend): with pytest.raises(ValueError): Fernet(base64.urlsafe_b64encode(b"abc"), backend=backend) + + +@pytest.mark.supported( + only_if=lambda backend: backend.cipher_supported( + algorithms.AES("\x00" * 32), modes.CBC("\x00" * 16) + ), + skip_message="Does not support AES CBC", +) +class TestMultiFernet(object): + def test_encrypt(self, backend): + f1 = Fernet(base64.urlsafe_b64encode(b"\x00" * 32), backend=backend) + f2 = Fernet(base64.urlsafe_b64encode(b"\x01" * 32), backend=backend) + f = MultiFernet([f1, f2]) + + assert f1.decrypt(f.encrypt(b"abc")) == b"abc" + + def test_decrypt(self, backend): + f1 = Fernet(base64.urlsafe_b64encode(b"\x00" * 32), backend=backend) + f2 = Fernet(base64.urlsafe_b64encode(b"\x01" * 32), backend=backend) + f = MultiFernet([f1, f2]) + + assert f.decrypt(f1.encrypt(b"abc")) == b"abc" + assert f.decrypt(f2.encrypt(b"abc")) == b"abc" + + with pytest.raises(InvalidToken): + f.decrypt(b"\x00" * 16) + + def test_no_fernets(self, backend): + with pytest.raises(ValueError): + MultiFernet([]) + + def test_non_iterable_argument(self, backend): + with pytest.raises(TypeError): + MultiFernet(None) |