Add support for extracting timestamp from a Fernet token (#4229)

* Add API for retrieving the seconds-to-expiry for the token, given a TTL.

* Process PR feedback:

* Do compute the TTL, but just the age of the token. The caller
can decided what to do next.

* Factored out the HMAC signature verification to a separate function.

* Fixed a copy&paste mistake in the test cases

* Tests cleanup.

* `struct` no longer needed

* Document `def age()`

* typo in `age()` documentation

* token, not data

* remove test for TTL expiry that is already covered by the parameterized `test_invalid()`.

* let's call this extract_timestamp and just return timestamp

* review comments

* it's UNIX I know this

1 files changed, 16 insertions, 0 deletions

diff --git a/docs/fernet.rst b/docs/fernet.rst
index a0ffe64f..2d7d2281 100644
--- a/docs/fernet.rst
+++ b/docs/fernet.rst
@@ -80,6 +80,22 @@ has support for implementing key rotation via :class:`MultiFernet`.
         :raises TypeError: This exception is raised if ``token`` is not
                            ``bytes``.
 
+    .. method:: extract_timestamp(token)
+
+        .. versionadded:: 2.3
+
+        Returns the timestamp for the token. The caller can then decide if
+        the token is about to expire and, for example, issue a new token.
+
+        :param bytes token: The Fernet token. This is the result of calling
+                            :meth:`encrypt`.
+        :returns int: The UNIX timestamp of the token.
+        :raises cryptography.fernet.InvalidToken: If the ``token``'s signature
+                                                  is invalid this exception
+                                                  is raised.
+        :raises TypeError: This exception is raised if ``token`` is not
+                           ``bytes``.
+
 
 .. class:: MultiFernet(fernets)