path: root/docs/fernet.rst

Fernet (symmetric encryption)
=============================

.. currentmodule:: cryptography.fernet

Fernet 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. Fernet also
has support for implementing key rotation via :class:`MultiFernet`.

.. class:: Fernet(key)

    This class provides both encryption and decryption facilities.

    .. doctest::

        >>> from cryptography.fernet import Fernet
        >>> key = Fernet.generate_key()
        >>> f = Fernet(key)
        >>> token = f.encrypt(b"my deep dark secret")
        >>> token
        b'...'
        >>> f.decrypt(token)
        b'my deep dark secret'

    :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()

        Generates a fresh fernet key. Keep this some place safe! If you lose it
        you'll no longer be able to decrypt messages; if anyone else gains
        access to it, they'll be able to decrypt all of your messages, and
        they'll also be able forge arbitrary messages that will be
        authenticated and decrypted.

    .. method:: encrypt(data)

        Encrypts data passed. The result of this encryption is known as a
        "Fernet token" and has strong privacy and authenticity guarantees.

        :param bytes data: The message you would like to encrypt.
        :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``.

        .. note::

            The encrypted message contains the current time when it was
            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
        original plaintext as the result, otherwise an exception will be
        raised. It is safe to use this data immediately as Fernet verifies
        that the data has not been tampered with prior to returning it.

        :param bytes token: The Fernet token. This is the result of calling
                            :meth:`encrypt`.
        :param int ttl: Optionally, the number of seconds old a message may be
                        for it to be valid. If the message is older than
                        ``ttl`` seconds (from the time it was originally
                        created) an exception will be raised. If ``ttl`` is not
                        provided (or is ``None``), the age of the message is
                        not considered.
        :returns bytes: The original plaintext.
        :raises cryptography.fernet.InvalidToken: If the ``token`` is in any
                                                  way invalid, this exception
                                                  is raised. A token may be
                                                  invalid for a number of
                                                  reasons: it is older than the
                                                  ``ttl``, it is malformed, or
                                                  it does not have a valid
                                                  signature.
        :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

        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)

    .. versionadded:: 0.7

    This class implements key rotation for Fernet. It takes a ``list`` of
    :class:`Fernet` instances and implements the same API with the exception
    of one additional method: :meth:`MultiFernet.rotate`:

    .. 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
        b'...'
        >>> f.decrypt(token)
        b'Secret message!'

    MultiFernet performs all encryption options using the *first* key in the
    ``list`` provided. MultiFernet attempts to decrypt tokens with each key in
    turn. A :class:`cryptography.fernet.InvalidToken` exception is raised if
    the correct key is not found in the ``list`` provided.

    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.

    Token rotation as offered by :meth:`MultiFernet.rotate` is a best practice
    and manner of cryptographic hygiene designed to limit damage in the event of
    an undetected event and to increase the difficulty of attacks. For example,
    if an employee who had access to your company's fernet keys leaves, you'll
    want to generate new fernet key, rotate all of the tokens currently deployed
    using that new key, and then retire the old fernet key(s) to which the
    employee had access.

    .. method:: rotate(msg)

        .. versionadded:: 2.2

        Rotates a token by re-encrypting it under the :class:`MultiFernet`
        instance's primary key. This preserves the timestamp that was originally
        saved with the token. If a token has successfully been rotated then the
        rotated token will be returned. If rotation fails this will raise an
        exception.

        .. 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
           b'...'
           >>> f.decrypt(token)
           b'Secret message!'
           >>> key3 = Fernet(Fernet.generate_key())
           >>> f2 = MultiFernet([key3, key1, key2])
           >>> rotated = f2.rotate(token)
           >>> f2.decrypt(rotated)
           b'Secret message!'

        :param bytes msg: The token to re-encrypt.
        :returns bytes: A secure message that cannot be read or altered without
           the key. This is URL-safe base64-encoded. This is referred to as a
           "Fernet token".
        :raises cryptography.fernet.InvalidToken: If a ``token`` is in any
           way invalid this exception is raised.
        :raises TypeError: This exception is raised if the ``msg`` is not
           ``bytes``.


.. class:: InvalidToken

    See :meth:`Fernet.decrypt` for more information.


Using passwords with Fernet
---------------------------

It is possible to use passwords with Fernet. To do this, you need to run the
password through a key derivation function such as
:class:`~cryptography.hazmat.primitives.kdf.pbkdf2.PBKDF2HMAC`, bcrypt or
:class:`~cryptography.hazmat.primitives.kdf.scrypt.Scrypt`.

.. doctest::

    >>> 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"
    >>> salt = os.urandom(16)
    >>> kdf = PBKDF2HMAC(
    ...     algorithm=hashes.SHA256(),
    ...     length=32,
    ...     salt=salt,
    ...     iterations=100000,
    ...     backend=default_backend()
    ... )
    >>> key = base64.urlsafe_b64encode(kdf.derive(password))
    >>> f = Fernet(key)
    >>> token = f.encrypt(b"Secret message!")
    >>> token
    b'...'
    >>> f.decrypt(token)
    b'Secret message!'

In this scheme, the salt has to be stored in a retrievable location in order
to derive the same key from the password in the future.

The iteration count used should be adjusted to be as high as your server can
tolerate. A good default is at least 100,000 iterations which is what Django
recommended in 2014.

Implementation
--------------

Fernet is built on top of a number of standard cryptographic primitives.
Specifically it uses:

* :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` in
  :class:`~cryptography.hazmat.primitives.ciphers.modes.CBC` mode with a
  128-bit key for encryption; using
  :class:`~cryptography.hazmat.primitives.padding.PKCS7` padding.
* :class:`~cryptography.hazmat.primitives.hmac.HMAC` using
  :class:`~cryptography.hazmat.primitives.hashes.SHA256` for authentication.
* Initialization vectors are generated using ``os.urandom()``.

For complete details consult the `specification`_.

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.


.. _`Fernet`: https://github.com/fernet/spec/
.. _`specification`: https://github.com/fernet/spec/blob/master/Spec.md