PyCryptodomeX

Warnings

• breaking Support for Python 3.6 was removed in PyCryptodomeX version 3.22.0. Users on Python 3.6 must use an older version (<= 3.21.x) or upgrade their Python interpreter.
  Fix: Upgrade Python to 3.7+ or pin pycryptodomex to <3.22.0.
• gotcha PyCryptodomeX imports its modules under the `Cryptodome` namespace, not `Crypto`. Attempting to import from `Crypto` (e.g., `from Crypto.Cipher import AES`) will result in a `ModuleNotFoundError` if `pycryptodome` (which uses `Crypto`) is not installed, or can lead to subtle bugs and security issues if both `pycryptodome` and `pycryptodomex` are present, as `Crypto` might resolve to the wrong package.
  Fix: Always use `from Cryptodome.<module> import <Symbol>` for `pycryptodomex` installations.
• deprecated ECB (Electronic Codebook) mode for symmetric ciphers (e.g., AES) is no longer the default and is explicitly discouraged for most uses due to its lack of semantic security. Since version 3.5.0, `AES.new(key)` will raise an error, requiring the mode to be explicitly specified.
  Fix: Always explicitly specify a secure mode of operation, such as `AES.MODE_CBC`, `AES.MODE_GCM`, or `AES.MODE_EAX`, during cipher initialization (e.g., `AES.new(key, AES.MODE_CBC, iv)`). If ECB is truly intended (rarely), use `AES.new(key, AES.MODE_ECB)`.
• breaking Older versions of PyCryptodome (prior to v3.19.1) had a side-channel leakage vulnerability in OAEP decryption that could be exploited to carry out a Manger attack. This was fixed in v3.19.1.
  Fix: Upgrade to PyCryptodomeX 3.19.1 or newer to mitigate this side-channel attack.
• gotcha In version 3.22.0, CCM ciphers were updated to fail before encrypting or decrypting data if the data length exceeds the limit imposed by the nonce length. This prevents potential issues with integrity and confidentiality.
  Fix: Ensure that the data length used with CCM ciphers is compatible with the chosen nonce length to avoid early termination. Consult documentation for specific limits.
• gotcha An infinite loop issue with RC4 for data larger than 4GB was resolved in version 3.22.0. Users processing very large data with RC4 in older versions may encounter this.
  Fix: Upgrade to PyCryptodomeX 3.22.0 or newer if using RC4 with large data, or consider using a more modern stream cipher.

Install

• pip install pycryptodomex Install PyCryptodomeX

Imports

• AES

  from Cryptodome.Cipher import AES

  PyCryptodomeX installs its modules under the 'Cryptodome' namespace to avoid conflicts with the legacy PyCrypto or `pycryptodome` library. Importing from `Crypto` will fail or import a different library if `pycryptodome` is also installed.
• get_random_bytes

  from Cryptodome.Random import get_random_bytes

  PyCryptodomeX uses the 'Cryptodome' namespace.
• PKCS7

  from Cryptodome.Util.Padding import PKCS7

  The `Padding` utility is located under `Cryptodome.Util`.

Quickstart

This quickstart demonstrates symmetric encryption and decryption using AES in CBC mode with PyCryptodomeX. It covers key and IV generation, data padding, encryption, and subsequent decryption and unpadding.

from Cryptodome.Cipher import AES
from Cryptodome.Random import get_random_bytes
from Cryptodome.Util.Padding import pad, unpad

# --- Encryption ---

# Generate a random 16-byte key for AES-128
key = get_random_bytes(16)

# Generate a random 16-byte IV for CBC mode
iv = get_random_bytes(16)

# The data to encrypt must be bytes
data_to_encrypt = b"My secret message that needs to be encrypted."

# Create an AES cipher object in CBC mode
cipher = AES.new(key, AES.MODE_CBC, iv)

# Pad the data to be a multiple of the block size (16 bytes for AES)
padded_data = pad(data_to_encrypt, AES.block_size)

# Encrypt the padded data
ciphertext = cipher.encrypt(padded_data)

print(f"Original data: {data_to_encrypt}")
print(f"Key (hex): {key.hex()}")
print(f"IV (hex): {iv.hex()}")
print(f"Ciphertext (hex): {ciphertext.hex()}")

# --- Decryption ---

# In a real scenario, key, iv, and ciphertext would be transmitted
# to the receiver. For this example, we reuse them.

# Create a new AES cipher object for decryption (same key and IV)
decipher = AES.new(key, AES.MODE_CBC, iv)

# Decrypt the ciphertext
decrypted_padded_data = decipher.decrypt(ciphertext)

# Unpad the decrypted data to get the original plaintext
decrypted_data = unpad(decrypted_padded_data, AES.block_size)

print(f"Decrypted data: {decrypted_data}")

assert decrypted_data == data_to_encrypt
print("Encryption and decryption successful!")