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 )

Added 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-like ) – The data to encrypt.

  • associated_data ( bytes-like ) – 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 31 - 1 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-like ) – The data to decrypt (with tag appended).

  • associated_data ( bytes-like ) – 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 ) [source]

Added 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'