Danger

This is a “Hazardous Materials” module. You should ONLY use it if you’re 100% absolutely sure that you know what you’re doing because this module is full of land mines, dragons, and dinosaurs with laser guns.

# Authenticated encryption

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 cryptography.hazmat.primitives.ciphers.aead.ChaCha20Poly1305(key)

  New in version 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.

  Parameters

    key (bytes-like) – A 32-byte key. This must be kept secret.

  Raises

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

      >>> 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.

  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.

    Parameters

      - nonce (bytes-like) – A 12 byte value. NEVER REUSE A NONCE with a key.

      - data (bytes) – The data to encrypt.

      - associated_data (bytes) – 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 232 bytes.

  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.

    Parameters

      - nonce (bytes-like) – A 12 byte value. NEVER REUSE A NONCE with a key.

      - data (bytes) – The data to decrypt (with tag appended).

      - associated_data (bytes) – 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 cryptography.hazmat.primitives.ciphers.aead.AESGCM(key)

  New in version 2.0.

  The AES-GCM construction is composed of the `AES` block cipher utilizing Galois Counter Mode (GCM).

  Parameters

    key (bytes-like) – A 128, 192, or 256-bit key. This must be kept secret.

      >>> 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.

    Parameters

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

    Returns bytes

      The generated key.

  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.

    Parameters

      - nonce (bytes-like) – NIST recommends a 96-bit IV length for best performance but it can be up to 264 - 1 bits. NEVER REUSE A NONCE with a key.

      - data (bytes) – The data to encrypt.

      - associated_data (bytes) – 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 232 bytes.

  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.

    Parameters

      - nonce (bytes-like) – NIST recommends a 96-bit IV length for best performance but it can be up to 264 - 1 bits. NEVER REUSE A NONCE with a key.

      - data (bytes) – The data to decrypt (with tag appended).

      - associated_data (bytes) – 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 cryptography.hazmat.primitives.ciphers.aead.AESCCM(key, tag_length=16)

  New in version 2.0.

  The AES-CCM construction is composed of the `AES` block cipher utilizing Counter with CBC-MAC (CCM) (specified in RFC 3610).

  Parameters

    - key (bytes-like) – A 128, 192, or 256-bit key. This must be kept secret.

    - tag_length (int) – 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.

      >>> 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.

    Parameters

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

    Returns bytes

      The generated key.

  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.

    Parameters

      - nonce (bytes-like) – 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.

      - data (bytes) – The data to encrypt.

      - associated_data (bytes) – 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 232 bytes.

  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.

    Parameters

      - nonce (bytes-like) – 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.

      - data (bytes) – The data to decrypt (with tag appended).

      - associated_data (bytes) – 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.