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.
2.0
The ChaCha20Poly1305 construction is defined in 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
bytes-like
- 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'
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.
- param nonce
A 12 byte value. NEVER REUSE A NONCE with a key.
- type nonce
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
orassociated_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.
- param nonce
A 12 byte value. NEVER REUSE A NONCE with a key.
- type nonce
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.
2.0
The AES-GCM construction is composed of the ~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
bytes-like
>>> 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'
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.
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 264 - 1
bits
. NEVER REUSE A NONCE with a key.- type nonce
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
orassociated_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.
- param nonce
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.- type nonce
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.
2.0
The AES-CCM construction is composed of the ~cryptography.hazmat.primitives.ciphers.algorithms.AES
block cipher utilizing Counter with CBC-MAC (CCM) (specified in 3610
).
- param key
A 128, 192, or 256-bit key. This must be kept secret.
- type key
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.
>>> 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'
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.
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
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
orassociated_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.
- 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
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.