You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
249 lines
10 KiB
249 lines
10 KiB
.. 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 bytes data: The data to encrypt.
|
|
:param bytes associated_data: Additional data that should be
|
|
authenticated with the key, but does not need to be encrypted. Can
|
|
be ``None``.
|
|
:returns bytes: The ciphertext bytes with the 16 byte tag appended.
|
|
:raises OverflowError: If ``data`` or ``associated_data`` is larger
|
|
than 2\ :sup:`32` 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 bytes data: The data to decrypt (with tag appended).
|
|
:param bytes associated_data: Additional data to authenticate. Can be
|
|
``None`` if none was passed 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, 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 bytes data: The data to encrypt.
|
|
:param bytes associated_data: Additional data that should be
|
|
authenticated with the key, but is not encrypted. Can be ``None``.
|
|
:returns bytes: The ciphertext bytes with the 16 byte tag appended.
|
|
:raises OverflowError: If ``data`` or ``associated_data`` is larger
|
|
than 2\ :sup:`32` 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 bytes data: The data to decrypt (with tag appended).
|
|
:param bytes associated_data: Additional data to authenticate. Can be
|
|
``None`` if none was passed 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, nonce, 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 bytes data: The data to encrypt.
|
|
:param bytes associated_data: Additional data that should be
|
|
authenticated with the key, but is not encrypted. Can be ``None``.
|
|
:returns bytes: The ciphertext bytes with the tag appended.
|
|
:raises OverflowError: If ``data`` or ``associated_data`` is larger
|
|
than 2\ :sup:`32` 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 bytes data: The data to decrypt (with tag appended).
|
|
:param bytes associated_data: Additional data to authenticate. Can be
|
|
``None`` if none was passed 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, nonce, or associated data are wrong.
|
|
|
|
.. _`recommends a 96-bit IV length`: https://csrc.nist.gov/publications/detail/sp/800-38d/final
|