AEGIS-128L and AEGIS-256¶
AEGIS is a family of authenticated ciphers with associated data (AEAD), specified in RFC 10032. It is built on the AES round function, and it is very fast on CPUs with AES instructions.
This module supports the two variants of RFC 10032 that use a single AES state (AEGIS-128X and AEGIS-256X, specialized for wide vector registers, are not supported):
Variant |
Constant |
Key (bytes) |
Nonce (bytes) |
Random nonces with the same key |
|---|---|---|---|---|
AEGIS-128L |
16 |
16 |
Up to 248 messages |
|
AEGIS-256 |
32 |
32 |
No practical limit |
The authentication tag is 16 bytes (default) or 32 bytes long (parameter mac_len).
With a 32-byte tag, it is also infeasible to find a different key and nonce
for which the same associated data, ciphertext and tag are valid (key commitment,
see Section 9.1.2 of RFC 10032).
Use mac_len=32 when the key may be derived from a password, or when the ciphertext
must not be valid under several keys.
Warning
A nonce must never be reused with the same key, not even with a different tag length: it reveals the internal state, which allows decrypting the messages and forging new ones.
The message and the associated data can be up to 261 - 1 bytes long each.
The API of the cipher and its finite state machine are the same as for the
modern modes of operation of block ciphers.
As with GCM and ChaCha20-Poly1305, AegisCipher.decrypt() returns the plaintext
before the tag is checked: do not use it until AegisCipher.verify() succeeds,
or use AegisCipher.decrypt_and_verify().
The implementation uses the AES instructions of the CPU (AES-NI on x86, the ARMv8 Cryptography Extensions on 64-bit ARM) when present. AEGIS is then considerably faster than ChaCha20-Poly1305 and XChaCha20-Poly1305.
Without them, it uses a bitsliced AES round, which runs in constant time, and uses SIMD instructions such as NEON on ARM and SSE2 on x86 when available. With NEON, , AEGIS-128L is then faster than ChaCha20-Poly1305, and AEGIS-256 about as fast; on x86, both are slower.
Without AES instructions, ChaCha20-Poly1305 is the better choice, except on ARM with NEON.
This is an example of encryption with AEGIS-256:
>>> from Crypto.Cipher import AEGIS
>>> from Crypto.Random import get_random_bytes
>>>
>>> header = b"header"
>>> data = b"secret"
>>> key = get_random_bytes(32)
>>> cipher = AEGIS.new(key, AEGIS.AEGIS_256)
>>> cipher.update(header)
>>> ciphertext, tag = cipher.encrypt_and_digest(data)
>>> nonce = cipher.nonce
The 32-byte nonce is generated randomly, and it is in the nonce attribute:
it must be sent along with the ciphertext and the tag.
This is how the receiver decrypts the data and checks its authenticity:
>>> from Crypto.Cipher import AEGIS
>>>
>>> # We assume that the key was securely shared beforehand
>>> cipher = AEGIS.new(key, AEGIS.AEGIS_256, nonce=nonce)
>>> cipher.update(header)
>>> try:
... plaintext = cipher.decrypt_and_verify(ciphertext, tag)
... print("The message was: " + plaintext.decode())
... except ValueError:
... print("Incorrect decryption")
AEGIS-128L and AEGIS-256 authenticated encryption (RFC 10032)
- Crypto.Cipher.AEGIS.new(key, variant, *, nonce=None, mac_len=16)¶
Create a new AEGIS cipher object, for authenticated encryption.
- Parameters:
key (bytes/bytearray/memoryview) – The secret key: 16 bytes for AEGIS-128L, 32 bytes for AEGIS-256. It must be random (for instance, from
Crypto.Random.get_random_bytes()).variant (
Literal[1,2]) –AEGIS_128LorAEGIS_256.
- Keyword Arguments:
nonce (bytes/bytearray/memoryview) – A value that must never be reused for any other encryption done with this key: 16 bytes for AEGIS-128L, 32 bytes for AEGIS-256. If not provided, a random nonce is generated (you can find it back in the
nonceattribute).mac_len (integer) – The length of the authentication tag, in bytes: 16 (default) or 32. With a 32-byte tag, it is also infeasible to find another key and nonce for which the same associated data, ciphertext and tag are valid.
- Return type:
- Returns:
an
AegisCipherobject
- class Crypto.Cipher.AEGIS.AegisCipher(key, variant, nonce, mac_len, backend)¶
AEGIS-128L or AEGIS-256 cipher object. Do not create it directly. Use
new()instead.- Variables:
nonce (bytes) – The nonce (16 bytes for AEGIS-128L, 32 bytes for AEGIS-256)
- decrypt(ciphertext, output=None)¶
Decrypt a piece of data.
The message can be passed in pieces of any size, with several calls. The plaintext must not be used before
verify()succeeds: preferdecrypt_and_verify().- Parameters:
ciphertext (bytes/bytearray/memoryview) – The data to decrypt, of any size.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext is written to. If
None, the plaintext is returned.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.
- decrypt_and_verify(ciphertext, received_mac_tag, output=None)¶
Perform
decrypt()andverify()in one step.- Parameters:
ciphertext (bytes/bytearray/memoryview) – The data to decrypt, of any size.
received_mac_tag (bytes/bytearray/memoryview) – The binary MAC, as received from the sender.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the plaintext is written to. If
None, the plaintext is returned. If the MAC does not match, the location is filled with zeroes.- Return type:
- Returns:
If
outputisNone, the plaintext is returned asbytes. Otherwise,None.- Raises:
ValueError – if the MAC does not match. The message has been tampered with or the key is incorrect.
- digest()¶
Compute the binary authentication tag (MAC).
- encrypt(plaintext, output=None)¶
Encrypt a piece of data.
The message can be passed in pieces of any size, with several calls.
- Parameters:
plaintext (bytes/bytearray/memoryview) – The data to encrypt, of any size.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext is written to. If
None, the ciphertext is returned.- Return type:
- Returns:
If
outputisNone, the ciphertext is returned asbytes. Otherwise,None.
- encrypt_and_digest(plaintext, output=None)¶
Perform
encrypt()anddigest()in one step.- Parameters:
plaintext (bytes/bytearray/memoryview) – The data to encrypt, of any size.
- Keyword Arguments:
output (bytearray/memoryview) – The location where the ciphertext is written to. If
None, the ciphertext is returned.- Return type:
- Returns:
a tuple with the ciphertext (as
bytes, orNoneifoutputis given) and the MAC tag.
- hexdigest()¶
Compute the printable authentication tag (MAC).
This method is like
digest().- Return:
the MAC tag, as a hexadecimal string.
- Return type:
- hexverify(hex_mac_tag)¶
Validate the printable authentication tag (MAC).
This method is like
verify().- Parameters:
hex_mac_tag (string) – This is the printable MAC.
- Raises ValueError:
if the MAC does not match. The message has been tampered with or the key is incorrect.
- Return type:
- update(assoc_data)¶
Protect the associated data.
Associated data (also known as additional authenticated data - AAD) is the piece of the message that must stay in the clear, while still allowing the receiver to verify its integrity. An example is packet headers.
The associated data (possibly split into multiple segments) is fed into
update()before any call todecrypt()orencrypt(). If there is no associated data,update()is not called.- Parameters:
assoc_data (bytes/bytearray/memoryview) – A piece of associated data. There are no restrictions on its size.
- Return type:
- verify(received_mac_tag)¶
Validate the binary authentication tag (MAC).
The receiver invokes this method at the very end, to check if the associated data (if any) and the decrypted messages are valid.
- Parameters:
received_mac_tag (bytes/bytearray/memoryview) – This is the binary MAC, as received from the sender.
- Raises ValueError:
if the MAC does not match. The message has been tampered with or the key is incorrect.
- Return type: