From 0d0d70bd78f432397b91eee4d9743000686037a6 Mon Sep 17 00:00:00 2001 From: Jakub Stasiak Date: Sun, 14 Jun 2020 20:30:18 +0200 Subject: 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 --- docs/fernet.rst | 39 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) (limited to 'docs') 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 -- cgit v1.2.3