diff options
Diffstat (limited to 'docs/hazmat/primitives/aead.rst')
| -rw-r--r-- | docs/hazmat/primitives/aead.rst | 248 |
1 files changed, 248 insertions, 0 deletions
diff --git a/docs/hazmat/primitives/aead.rst b/docs/hazmat/primitives/aead.rst new file mode 100644 index 00000000..d318367b --- /dev/null +++ b/docs/hazmat/primitives/aead.rst @@ -0,0 +1,248 @@ +.. 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 |