Advanced Encryption Standard

AES is a symmetric block cipher that encrypts and decrypts data using the same key. It supports multiple modes of operation:

  • ECB – encrypts each block independently (no chaining).

  • CBC – chains blocks to provide diffusion, requiring an IV.

  • CTR – turns AES into a stream cipher using a counter.

  • GCM – provides both encryption and authentication with a nonce.

AES is commonly used in secure messaging, file encryption, and TLS.

class pycrypt.symmetric.AES_ECB(key)[source]

Bases: _AESMode

AES in ECB (Electronic Codebook) mode.

ECB mode encrypts each 16-byte block independently. For messages that are not multiples of 16 bytes, padding (e.g., PKCS7) is required. This mode does not provide integrity/authentication, and identical plaintext blocks produce identical ciphertext blocks.

Example

>>> key = b"0123456789abcdef"
>>> aes = AES_ECB(key)
>>> plaintext = b"Secret Message"
>>> ct = aes.encrypt(plaintext)
>>> aes.decrypt(ct)
b'Secret Message'
Parameters:

key (bytes)

encrypt(plaintext, *, pad=True)[source]

Encrypt plaintext using AES-ECB.

Parameters:

  • plaintext (bytes) – The data to encrypt.

  • pad (bool, optional) – Whether to apply PKCS7 padding (default True).

Returns:

The ciphertext.

Return type:

bytes

decrypt(ciphertext, *, unpad=True)[source]

Decrypt ciphertext using AES-ECB.

Parameters:

  • ciphertext (bytes) – The ciphertext to decrypt.

  • unpad (bool, optional) – Whether to remove PKCS7 padding (default True).

Returns:

The decrypted plaintext.

Return type:

bytes

class pycrypt.symmetric.AES_CBC(key)[source]

Bases: _AESMode

AES in CBC (Cipher Block Chaining) mode.

CBC mode XORs each plaintext block with the previous ciphertext block before encryption. Requires a 16-byte IV (initialization vector). Padding is required for non-multiple-of-block-length messages.

Example

>>> key = b"0123456789abcdef"
>>> iv = b"abcdef0123456789"
>>> aes = AES_CBC(key)
>>> ct = aes.encrypt(b"Secret Message", iv=iv)
>>> aes.decrypt(ct, iv=iv)
b'Secret Message'
Parameters:

key (bytes)

encrypt(plaintext, *, iv, pad=True)[source]

Encrypt plaintext using AES-CBC.

Parameters:

  • plaintext (bytes) – The data to encrypt.

  • iv (bytes) – 16-byte initialization vector.

  • pad (bool, optional) – Whether to apply PKCS7 padding (default True).

Returns:

The ciphertext.

Return type:

bytes

decrypt(ciphertext, *, iv, unpad=True)[source]

Decrypt ciphertext using AES-CBC.

Parameters:

  • ciphertext (bytes) – The ciphertext to decrypt.

  • iv (bytes) – 16-byte initialization vector used during encryption.

  • unpad (bool, optional) – Whether to remove PKCS7 padding (default True).

Returns:

The decrypted plaintext.

Return type:

bytes

class pycrypt.symmetric.AES_CTR(key)[source]

Bases: _AESMode

AES in CTR (Counter) mode.

CTR mode turns AES into a stream cipher. It combines a nonce with a counter to produce a keystream. Encryption and decryption are symmetric operations. Does not require padding. Requires an 8-byte nonce.

Example

>>> key = b"0123456789abcdef"
>>> nonce = b"12345678"
>>> aes = AES_CTR(key)
>>> ct = aes.encrypt(b"Secret Message", nonce=nonce)
>>> aes.decrypt(ct, nonce=nonce)
b'Secret Message'
Parameters:

key (bytes)

encrypt(plaintext, *, nonce)[source]

Encrypt plaintext using AES-CTR.

Parameters:

  • plaintext (bytes) – Data to encrypt.

  • nonce (bytes) – 8-byte nonce for the counter block.

Returns:

Ciphertext.

Return type:

bytes

decrypt(ciphertext, *, nonce)[source]

Decrypt ciphertext using AES-CTR.

Parameters:

  • ciphertext (bytes) – Data to decrypt.

  • nonce (bytes) – 8-byte nonce used during encryption.

Returns:

Decrypted plaintext.

Return type:

bytes

class pycrypt.symmetric.AES_GCM(key)[source]

Bases: _AESMode

AES in GCM (Galois/Counter Mode) with authentication.

Provides both confidentiality and integrity. Requires a 12-byte nonce. Optional additional authenticated data (AAD) can be provided. Raises AES_GCM.GCMAuthenticationError if authentication fails.

Example

>>> key = b"0123456789abcdef"
>>> nonce = b"123456789012"
>>> aes = AES_GCM(key)
>>> ct, tag = aes.encrypt(b"Secret Message", nonce=nonce)
>>> aes.decrypt(ct, nonce=nonce, tag=tag)
b'Secret Message'
Parameters:

key (bytes)

exception GCMAuthenticationError[source]

Bases: Exception

Raised when GCM authentication fails.

add_note(note, /)

Add a note to the exception

args
with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

encrypt(plaintext, *, nonce, aad=b'')[source]

Encrypt and authenticate data using AES-GCM.

Parameters:

  • plaintext (bytes) – Data to encrypt.

  • nonce (bytes) – 12-byte nonce.

  • aad (bytes, optional) – Additional authenticated data.

Returns:

Ciphertext and 16-byte authentication tag.

Return type:

tuple[bytes, bytes]

decrypt(ciphertext, *, nonce, tag, aad=b'')[source]

Decrypt and verify data using AES-GCM.

Parameters:

  • ciphertext (bytes) – Ciphertext to decrypt.

  • nonce (bytes) – 12-byte nonce used during encryption.

  • tag (bytes) – 16-byte authentication tag from encryption.

  • aad (bytes, optional) – Additional authenticated data.

Returns:

Decrypted plaintext.

Return type:

bytes

Raises:

AES_GCM.GCMAuthenticationError – If authentication tag verification fails.