.. hazmat::


Authenticated encryption
========================

.. module:: cryptography.hazmat.primitives.ciphers.aead

Authenticated encryption with associated data (AEAD) are encryption schemes
which provide both confidentiality and integrity for their ciphertext. They
also support providing integrity for associated data which is not encrypted.

.. class:: ChaCha20Poly1305(key)

    .. versionadded:: 2.0

    The ChaCha20Poly1305 construction is defined in :rfc:`7539` section 2.8.
    It is a stream cipher combined with a MAC that offers strong integrity
    guarantees.

    :param key: A 32-byte key. This **must** be kept secret.
    :type key: :term:`bytes-like`

    :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
        OpenSSL does not support ChaCha20Poly1305.

    .. doctest::

        >>> import os
        >>> from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
        >>> data = b"a secret message"
        >>> aad = b"authenticated but unencrypted data"
        >>> key = ChaCha20Poly1305.generate_key()
        >>> chacha = ChaCha20Poly1305(key)
        >>> nonce = os.urandom(12)
        >>> ct = chacha.encrypt(nonce, data, aad)
        >>> chacha.decrypt(nonce, ct, aad)
        b'a secret message'

    .. classmethod:: generate_key()

        Securely generates a random ChaCha20Poly1305 key.

        :returns bytes: A 32 byte key.

    .. method:: encrypt(nonce, data, associated_data)

        .. warning::

            Reuse of a ``nonce`` with a given ``key`` compromises the security
            of any message with that ``nonce`` and ``key`` pair.

        Encrypts the ``data`` provided and authenticates the
        ``associated_data``.  The output of this can be passed directly
        to the ``decrypt`` method.

        :param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a key.
        :type nonce: :term:`bytes-like`
        :param data: The data to encrypt.
        :type data: :term:`bytes-like`
        :param associated_data: Additional data that should be
            authenticated with the key, but does not need to be encrypted. Can
            be ``None``.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The ciphertext bytes with the 16 byte tag appended.
        :raises OverflowError: If ``data`` or ``associated_data`` is larger
            than 2\ :sup:`31` - 1 bytes.

    .. method:: decrypt(nonce, data, associated_data)

        Decrypts the ``data`` and authenticates the ``associated_data``. If you
        called encrypt with ``associated_data`` you must pass the same
        ``associated_data`` in decrypt or the integrity check will fail.

        :param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a
            key.
        :type nonce: :term:`bytes-like`
        :param data: The data to decrypt (with tag appended).
        :type data: :term:`bytes-like`
        :param associated_data: Additional data to authenticate. Can be
            ``None`` if none was passed during encryption.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The original plaintext.
        :raises cryptography.exceptions.InvalidTag: If the authentication tag
            doesn't validate this exception will be raised. This will occur
            when the ciphertext has been changed, but will also occur when the
            key, nonce, or associated data are wrong.

.. class:: AESGCM(key)

    .. versionadded:: 2.0

    The AES-GCM construction is composed of the
    :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
    cipher utilizing Galois Counter Mode (GCM).

    :param key: A 128, 192, or 256-bit key. This **must** be kept secret.
    :type key: :term:`bytes-like`

    .. doctest::

        >>> import os
        >>> from cryptography.hazmat.primitives.ciphers.aead import AESGCM
        >>> data = b"a secret message"
        >>> aad = b"authenticated but unencrypted data"
        >>> key = AESGCM.generate_key(bit_length=128)
        >>> aesgcm = AESGCM(key)
        >>> nonce = os.urandom(12)
        >>> ct = aesgcm.encrypt(nonce, data, aad)
        >>> aesgcm.decrypt(nonce, ct, aad)
        b'a secret message'

    .. classmethod:: generate_key(bit_length)

        Securely generates a random AES-GCM key.

        :param bit_length: The bit length of the key to generate. Must be
            128, 192, or 256.

        :returns bytes: The generated key.

    .. method:: encrypt(nonce, data, associated_data)

        .. warning::

            Reuse of a ``nonce`` with a given ``key`` compromises the security
            of any message with that ``nonce`` and ``key`` pair.

        Encrypts and authenticates the ``data`` provided as well as
        authenticating the ``associated_data``.  The output of this can be
        passed directly to the ``decrypt`` method.

        :param nonce: NIST `recommends a 96-bit IV length`_ for best
            performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
            **NEVER REUSE A NONCE** with a key.
        :type nonce: :term:`bytes-like`
        :param data: The data to encrypt.
        :type data: :term:`bytes-like`
        :param associated_data: Additional data that should be
            authenticated with the key, but is not encrypted. Can be ``None``.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The ciphertext bytes with the 16 byte tag appended.
        :raises OverflowError: If ``data`` or ``associated_data`` is larger
            than 2\ :sup:`31` - 1 bytes.

    .. method:: decrypt(nonce, data, associated_data)

        Decrypts the ``data`` and authenticates the ``associated_data``. If you
        called encrypt with ``associated_data`` you must pass the same
        ``associated_data`` in decrypt or the integrity check will fail.

        :param nonce: NIST `recommends a 96-bit IV length`_ for best
            performance but it can be up to 2\ :sup:`64` - 1 :term:`bits`.
            **NEVER REUSE A NONCE** with a key.
        :type nonce: :term:`bytes-like`
        :param data: The data to decrypt (with tag appended).
        :type data: :term:`bytes-like`
        :param associated_data: Additional data to authenticate. Can be
            ``None`` if none was passed during encryption.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The original plaintext.
        :raises cryptography.exceptions.InvalidTag: If the authentication tag
            doesn't validate this exception will be raised. This will occur
            when the ciphertext has been changed, but will also occur when the
            key, nonce, or associated data are wrong.

.. class:: AESGCMSIV(key)

    .. versionadded:: 42.0.0

    The AES-GCM-SIV construction is defined in :rfc:`8452` and is composed of
    the :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
    cipher utilizing Galois Counter Mode (GCM) and a synthetic initialization
    vector (SIV).

    :param key: A 128, 192, or 256-bit key. This **must** be kept secret.
    :type key: :term:`bytes-like`

    :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
        OpenSSL does not support AES-GCM-SIV.

    .. doctest::

        >>> import os
        >>> from cryptography.hazmat.primitives.ciphers.aead import AESGCMSIV
        >>> data = b"a secret message"
        >>> aad = b"authenticated but unencrypted data"
        >>> key = AESGCMSIV.generate_key(bit_length=128)
        >>> aesgcmsiv = AESGCMSIV(key)
        >>> nonce = os.urandom(12)
        >>> ct = aesgcmsiv.encrypt(nonce, data, aad)
        >>> aesgcmsiv.decrypt(nonce, ct, aad)
        b'a secret message'

    .. classmethod:: generate_key(bit_length)

        Securely generates a random AES-GCM-SIV key.

        :param bit_length: The bit length of the key to generate. Must be
            128, 192, or 256.

        :returns bytes: The generated key.

    .. method:: encrypt(nonce, data, associated_data)

        Encrypts and authenticates the ``data`` provided as well as
        authenticating the ``associated_data``.  The output of this can be
        passed directly to the ``decrypt`` method.

        :param nonce: A 12-byte value.
        :type nonce: :term:`bytes-like`
        :param data: The data to encrypt.
        :type data: :term:`bytes-like`
        :param associated_data: Additional data that should be
            authenticated with the key, but is not encrypted. Can be ``None``.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The ciphertext bytes with the 16 byte tag appended.
        :raises OverflowError: If ``data`` or ``associated_data`` is larger
            than 2\ :sup:`32` - 1 bytes.

    .. method:: decrypt(nonce, data, associated_data)

        Decrypts the ``data`` and authenticates the ``associated_data``. If you
        called encrypt with ``associated_data`` you must pass the same
        ``associated_data`` in decrypt or the integrity check will fail.

        :param nonce: A 12-byte value.
        :type nonce: :term:`bytes-like`
        :param data: The data to decrypt (with tag appended).
        :type data: :term:`bytes-like`
        :param associated_data: Additional data to authenticate. Can be
            ``None`` if none was passed during encryption.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The original plaintext.
        :raises cryptography.exceptions.InvalidTag: If the authentication tag
            doesn't validate this exception will be raised. This will occur
            when the ciphertext has been changed, but will also occur when the
            key, nonce, or associated data are wrong.

.. class:: AESOCB3(key)

    .. versionadded:: 36.0.0

    The OCB3 construction is defined in :rfc:`7253`. It is an AEAD mode
    that offers strong integrity guarantees and good performance.

    :param key: A 128, 192, or 256-bit key. This **must** be kept secret.
    :type key: :term:`bytes-like`

    :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
        OpenSSL does not support AES-OCB3.

    .. doctest::

        >>> import os
        >>> from cryptography.hazmat.primitives.ciphers.aead import AESOCB3
        >>> data = b"a secret message"
        >>> aad = b"authenticated but unencrypted data"
        >>> key = AESOCB3.generate_key(bit_length=128)
        >>> aesocb = AESOCB3(key)
        >>> nonce = os.urandom(12)
        >>> ct = aesocb.encrypt(nonce, data, aad)
        >>> aesocb.decrypt(nonce, ct, aad)
        b'a secret message'

    .. classmethod:: generate_key(bit_length)

        Securely generates a random AES-OCB3 key.

        :param bit_length: The bit length of the key to generate. Must be
            128, 192, or 256.

        :returns bytes: The generated key.

    .. method:: encrypt(nonce, data, associated_data)

        .. warning::

            Reuse of a ``nonce`` with a given ``key`` compromises the security
            of any message with that ``nonce`` and ``key`` pair.

        Encrypts and authenticates the ``data`` provided as well as
        authenticating the ``associated_data``.  The output of this can be
        passed directly to the ``decrypt`` method.

        :param nonce: A 12-15 byte value. **NEVER REUSE A NONCE** with a key.
        :type nonce: :term:`bytes-like`
        :param data: The data to encrypt.
        :type data: :term:`bytes-like`
        :param associated_data: Additional data that should be
            authenticated with the key, but is not encrypted. Can be ``None``.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The ciphertext bytes with the 16 byte tag appended.
        :raises OverflowError: If ``data`` or ``associated_data`` is larger
            than 2\ :sup:`31` - 1 bytes.

    .. method:: decrypt(nonce, data, associated_data)

        Decrypts the ``data`` and authenticates the ``associated_data``. If you
        called encrypt with ``associated_data`` you must pass the same
        ``associated_data`` in decrypt or the integrity check will fail.

        :param nonce: A 12 byte value. **NEVER REUSE A NONCE** with a key.
        :type nonce: :term:`bytes-like`
        :param data: The data to decrypt (with tag appended).
        :type data: :term:`bytes-like`
        :param associated_data: Additional data to authenticate. Can be
            ``None`` if none was passed during encryption.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The original plaintext.
        :raises cryptography.exceptions.InvalidTag: If the authentication tag
            doesn't validate this exception will be raised. This will occur
            when the ciphertext has been changed, but will also occur when the
            key, nonce, or associated data are wrong.

.. class:: AESSIV(key)

    .. versionadded:: 37.0.0

    The SIV (synthetic initialization vector) construction is defined in
    :rfc:`5297`. Depending on how it is used, SIV allows either
    deterministic authenticated encryption or nonce-based,
    misuse-resistant authenticated encryption.

    :param key: A 256, 384, or 512-bit key (double sized from typical AES).
        This **must** be kept secret.
    :type key: :term:`bytes-like`

    :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
        OpenSSL does not support AES-SIV.

    .. doctest::

        >>> import os
        >>> from cryptography.hazmat.primitives.ciphers.aead import AESSIV
        >>> data = b"a secret message"
        >>> nonce = os.urandom(16)
        >>> aad = [b"authenticated but unencrypted data", nonce]
        >>> key = AESSIV.generate_key(bit_length=512)  # AES256 requires 512-bit keys for SIV
        >>> aessiv = AESSIV(key)
        >>> ct = aessiv.encrypt(data, aad)
        >>> aessiv.decrypt(ct, aad)
        b'a secret message'

    .. classmethod:: generate_key(bit_length)

        Securely generates a random AES-SIV key.

        :param bit_length: The bit length of the key to generate. Must be
            256, 384, or 512. AES-SIV splits the key into an encryption and
            MAC key, so these lengths correspond to AES 128, 192, and 256.

        :returns bytes: The generated key.

    .. method:: encrypt(data, associated_data)

        .. note::

            SIV performs nonce-based authenticated encryption when a component of
            the associated data is a nonce. The final associated data in the
            list is used for the nonce.

            Random nonces should have at least 128-bits of entropy. If a nonce is
            reused with SIV authenticity is retained and confidentiality is only
            compromised to the extent that an attacker can determine that the
            same plaintext (and same associated data) was protected with the same
            nonce and key.

            If you do not supply a nonce encryption is deterministic and the same
            (plaintext, key) pair will always produce the same ciphertext.

        Encrypts and authenticates the ``data`` provided as well as
        authenticating the ``associated_data``.  The output of this can be
        passed directly to the ``decrypt`` method.

        :param data: The data to encrypt.
        :type data: :term:`bytes-like`
        :param list associated_data: An optional ``list`` of ``bytes-like objects``. This
            is additional data that should be authenticated with the key, but
            is not encrypted. Can be ``None``.  In SIV mode the final element
            of this list is treated as a ``nonce``.
        :returns bytes: The ciphertext bytes with the 16 byte tag **prepended**.
        :raises OverflowError: If ``data`` or an ``associated_data`` element
            is larger than 2\ :sup:`31` - 1 bytes.

    .. method:: decrypt(data, associated_data)

        Decrypts the ``data`` and authenticates the ``associated_data``. If you
        called encrypt with ``associated_data`` you must pass the same
        ``associated_data`` in decrypt or the integrity check will fail.

        :param bytes data: The data to decrypt (with tag **prepended**).
        :param list associated_data: An optional ``list`` of ``bytes-like objects``. This
            is additional data that should be authenticated with the key, but
            is not encrypted. Can be ``None`` if none was used during
            encryption.
        :returns bytes: The original plaintext.
        :raises cryptography.exceptions.InvalidTag: If the authentication tag
            doesn't validate this exception will be raised. This will occur
            when the ciphertext has been changed, but will also occur when the
            key or associated data are wrong.

.. class:: AESCCM(key, tag_length=16)

    .. versionadded:: 2.0

    .. note:

        AES-CCM is provided largely for compatibility with existing protocols.
        Due to its construction it is not as computationally efficient as
        other AEAD ciphers.

    The AES-CCM construction is composed of the
    :class:`~cryptography.hazmat.primitives.ciphers.algorithms.AES` block
    cipher utilizing Counter with CBC-MAC (CCM) (specified in :rfc:`3610`).

    :param key: A 128, 192, or 256-bit key. This **must** be kept secret.
    :type key: :term:`bytes-like`
    :param int tag_length: The length of the authentication tag. This
        defaults to 16 bytes and it is **strongly** recommended that you
        do not make it shorter unless absolutely necessary. Valid tag
        lengths are 4, 6, 8, 10, 12, 14, and 16.

    :raises cryptography.exceptions.UnsupportedAlgorithm: If the version of
        OpenSSL does not support AES-CCM.

    .. doctest::

        >>> import os
        >>> from cryptography.hazmat.primitives.ciphers.aead import AESCCM
        >>> data = b"a secret message"
        >>> aad = b"authenticated but unencrypted data"
        >>> key = AESCCM.generate_key(bit_length=128)
        >>> aesccm = AESCCM(key)
        >>> nonce = os.urandom(13)
        >>> ct = aesccm.encrypt(nonce, data, aad)
        >>> aesccm.decrypt(nonce, ct, aad)
        b'a secret message'

    .. classmethod:: generate_key(bit_length)

        Securely generates a random AES-CCM key.

        :param bit_length: The bit length of the key to generate. Must be
            128, 192, or 256.

        :returns bytes: The generated key.

    .. method:: encrypt(nonce, data, associated_data)

        .. warning::

            Reuse of a ``nonce`` with a given ``key`` compromises the security
            of any message with that ``nonce`` and ``key`` pair.

        Encrypts and authenticates the ``data`` provided as well as
        authenticating the ``associated_data``.  The output of this can be
        passed directly to the ``decrypt`` method.

        :param nonce: A value of between 7 and 13 bytes. The maximum
            length is determined by the length of the ciphertext you are
            encrypting and must satisfy the condition:
            ``len(data) < 2 ** (8 * (15 - len(nonce)))``
            **NEVER REUSE A NONCE** with a key.
        :type nonce: :term:`bytes-like`
        :param data: The data to encrypt.
        :type data: :term:`bytes-like`
        :param associated_data: Additional data that should be
            authenticated with the key, but is not encrypted. Can be ``None``.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The ciphertext bytes with the tag appended.
        :raises OverflowError: If ``data`` or ``associated_data`` is larger
            than 2\ :sup:`31` - 1 bytes.

    .. method:: decrypt(nonce, data, associated_data)

        Decrypts the ``data`` and authenticates the ``associated_data``. If you
        called encrypt with ``associated_data`` you must pass the same
        ``associated_data`` in decrypt or the integrity check will fail.

        :param nonce: A value of between 7 and 13 bytes. This
            is the same value used when you originally called encrypt.
            **NEVER REUSE A NONCE** with a key.
        :type nonce: :term:`bytes-like`
        :param data: The data to decrypt (with tag appended).
        :type data: :term:`bytes-like`
        :param associated_data: Additional data to authenticate. Can be
            ``None`` if none was passed during encryption.
        :type associated_data: :term:`bytes-like`
        :returns bytes: The original plaintext.
        :raises cryptography.exceptions.InvalidTag: If the authentication tag
            doesn't validate this exception will be raised. This will occur
            when the ciphertext has been changed, but will also occur when the
            key, nonce, or associated data are wrong.

.. _`recommends a 96-bit IV length`: https://csrc.nist.gov/pubs/sp/800/38/d/final