diff options
Diffstat (limited to 'docs/fernet.rst')
| -rw-r--r-- | docs/fernet.rst | 53 |
1 files changed, 46 insertions, 7 deletions
diff --git a/docs/fernet.rst b/docs/fernet.rst index 9b95621ef..5e2655d3a 100644 --- a/docs/fernet.rst +++ b/docs/fernet.rst @@ -23,9 +23,10 @@ has support for implementing key rotation via :class:`MultiFernet`. >>> f.decrypt(token) b'my deep dark secret' - :param bytes key: A URL-safe base64-encoded 32-byte key. This **must** be - kept secret. Anyone with this key is able to create and - read messages. + :param key: A URL-safe base64-encoded 32-byte key. This **must** be + kept secret. Anyone with this key is able to create and + read messages. + :type key: bytes or str .. classmethod:: generate_key() @@ -53,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 @@ -80,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 @@ -189,7 +229,6 @@ password through a key derivation function such as >>> import base64 >>> import os >>> from cryptography.fernet import Fernet - >>> from cryptography.hazmat.backends import default_backend >>> from cryptography.hazmat.primitives import hashes >>> from cryptography.hazmat.primitives.kdf.pbkdf2 import PBKDF2HMAC >>> password = b"password" @@ -199,7 +238,6 @@ password through a key derivation function such as ... length=32, ... salt=salt, ... iterations=100000, - ... backend=default_backend() ... ) >>> key = base64.urlsafe_b64encode(kdf.derive(password)) >>> f = Fernet(key) @@ -236,8 +274,9 @@ Limitations ----------- Fernet is ideal for encrypting data that easily fits in memory. As a design -feature it does not expose unauthenticated bytes. Unfortunately, this makes it -generally unsuitable for very large files at this time. +feature it does not expose unauthenticated bytes. This means that the complete +message contents must be available in memory, making Fernet generally +unsuitable for very large files at this time. .. _`Fernet`: https://github.com/fernet/spec/ |