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

AEGIS.AEGIS_128L

16

16

Up to 248 messages

AEGIS-256

AEGIS.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:
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 nonce attribute).

  • 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:

AegisCipher

Returns:

an AegisCipher object

Crypto.Cipher.AEGIS.AEGIS_128L: Literal[1] = 1

AEGIS-128L (16-byte key and nonce)

Crypto.Cipher.AEGIS.AEGIS_256: Literal[2] = 2

AEGIS-256 (32-byte key and nonce)

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: prefer decrypt_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:

Optional[bytes]

Returns:

If output is None, the plaintext is returned as bytes. Otherwise, None.

decrypt_and_verify(ciphertext, received_mac_tag, output=None)

Perform decrypt() and verify() 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:

Optional[bytes]

Returns:

If output is None, the plaintext is returned as bytes. 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).

Return:

the MAC tag, as bytes (16 or 32, see mac_len in new()).

Return type:

bytes

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:

Optional[bytes]

Returns:

If output is None, the ciphertext is returned as bytes. Otherwise, None.

encrypt_and_digest(plaintext, output=None)

Perform encrypt() and digest() 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:

tuple[Optional[bytes], bytes]

Returns:

a tuple with the ciphertext (as bytes, or None if output is 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:

str

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:

None

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 to decrypt() or encrypt(). 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:

AegisCipher

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:

None