Add a way to pass current time to Fernet (#5256)

* Add a way to pass current time to Fernet

The motivation behind this is to be able to unit test code using Fernet
easily without having to monkey patch global state.

* Reformat to satisfy flake8

* Trigger a Fernet.encrypt() branch missing from coverage

* Revert specifying explicit current time in MultiFernet.rotate()

Message's timestamp is not verified anyway since ttl is None.

* Change the Fernet's explicit current time API slightly

This's been suggested in code review.

* Fix a typo

* Fix a typo

* Restore full MultiFernet test coverage and fix a typo

* Restore more coverage

time.time() is not called by MultiFernet.rotate() anymore so the monkey
patching and lambda need to go, because the patched function is not used
and coverage calculation will rightfully notice it.

* Remove an unused import

* Document when the *_at_time Fernet methods were added

1 files changed, 39 insertions, 0 deletions

diff --git a/docs/fernet.rst b/docs/fernet.rst
index c01d18ca..dd9d75bd 100644
--- a/docs/fernet.rst
+++ b/docs/fernet.rst
@@ -54,6 +54,28 @@ has support for implementing key rotation via :class:`MultiFernet`.
             generated in *plaintext*, the time a message was created will
             therefore be visible to a possible attacker.
 
+    .. method:: encrypt_at_time(data, current_time)
+
+       .. versionadded:: 3.0
+
+       Encrypts data passed using explicitly passed current time. See
+       :meth:`encrypt` for the documentation of the ``data`` parameter, the
+       return type and the exceptions raised.
+
+       The motivation behind this method is for the client code to be able to
+       test token expiration. Since this method can be used in an insecure
+       manner one should make sure the correct time (``int(time.time())``)
+       is passed as ``current_time`` outside testing.
+
+       :param int current_time: The current time.
+
+       .. note::
+
+            Similarly to :meth:`encrypt` the encrypted message contains the
+            timestamp in *plaintext*, in this case the timestamp is the value
+            of the ``current_time`` parameter.
+
+
     .. method:: decrypt(token, ttl=None)
 
         Decrypts a Fernet token. If successfully decrypted you will receive the
@@ -81,6 +103,23 @@ has support for implementing key rotation via :class:`MultiFernet`.
         :raises TypeError: This exception is raised if ``token`` is not
                            ``bytes``.
 
+    .. method:: decrypt_at_time(token, ttl, current_time)
+
+       .. versionadded:: 3.0
+
+       Decrypts a token using explicitly passed current time. See
+       :meth:`decrypt` for the documentation of the ``token`` and ``ttl``
+       parameters (``ttl`` is required here), the return type and the exceptions
+       raised.
+
+       The motivation behind this method is for the client code to be able to
+       test token expiration. Since this method can be used in an insecure
+       manner one should make sure the correct time (``int(time.time())``)
+       is passed as ``current_time`` outside testing.
+
+       :param int current_time: The current time.
+
+
     .. method:: extract_timestamp(token)
 
         .. versionadded:: 2.3