PyCryptodome

Warnings

• breaking PyCryptodome uses the `Crypto` top-level package name. Installing `pycryptodome` in an environment that also has the unmaintained `PyCrypto` library will cause import conflicts and unexpected behavior. Always use virtual environments and ensure only one is installed.
  Fix: Always install `pycryptodome` in a dedicated virtual environment. If a project requires coexistence with `PyCrypto`, install `pycryptodomex` instead, which uses the `Cryptodome` namespace.
• breaking Python 3.6 support was removed in version 3.22.0. Users on Python 3.6 will need to pin to an older version of PyCryptodome (e.g., <3.22.0).
  Fix: Upgrade to Python 3.7 or newer, or pin `pycryptodome` to a version older than 3.22.0 (e.g., `pycryptodome<3.22.0`).
• breaking ECB mode is no longer the default for symmetric ciphers. Calling `AES.new(key)` will now fail. ECB is not semantically secure and should generally be avoided.
  Fix: Explicitly specify the desired mode, e.g., `AES.new(key, AES.MODE_GCM)` or `AES.new(key, AES.MODE_CBC)`. If ECB is intentionally needed, use `AES.new(key, AES.MODE_ECB)`.
• breaking Several methods like `sign()`, `verify()`, `encrypt()`, `decrypt()`, `blind()`, `unblind()` were removed from public key objects (RSA, DSA, ElGamal) due to security concerns or maintenance difficulties.
  Fix: Use dedicated modules for public-key operations: `Crypto.Cipher.PKCS1_OAEP` for RSA encryption/decryption, `Crypto.Signature.pkcs1_15` or `Crypto.Signature.pss` for RSA signing, and `Crypto.Signature.DSS` for DSA signing.
• gotcha A side-channel leakage vulnerability (Manger attack) in OAEP decryption was fixed.
  Fix: Upgrade to version 3.19.1 or newer to mitigate potential side-channel attacks on OAEP decryption.
• gotcha An infinite loop bug affecting RC4 ciphers when processing data larger than 4GB was resolved.
  Fix: Upgrade to version 3.22.0 or newer if using RC4 with potentially large datasets. Consider migrating away from RC4 as it is generally considered insecure for modern applications.
• gotcha For HashEdDSA and Ed448, the `sign()` and `verify()` methods incorrectly modified the state of the XOF (eXtendable Output Function).
  Fix: Upgrade to version 3.23.0 or newer to ensure correct state management for HashEdDSA and Ed448 operations.

Install

• pip install pycryptodome Install PyCryptodome

Imports

• AES

  from Crypto.Cipher import AES

  The `pycryptodome` package installs its modules under the `Crypto` namespace for backward compatibility with the old `PyCrypto` library. Avoid `Cryptodome` unless `pycryptodomex` is explicitly installed.
• get_random_bytes

  from Crypto.Random import get_random_bytes

  Standard import path for cryptographic random number generation.
• PBKDF2

  from Crypto.Protocol.KDF import PBKDF2

  Standard import path for Password-Based Key Derivation Function 2.
• RSA

  from Crypto.PublicKey import RSA

  Standard import path for RSA public key operations.

Quickstart

This quickstart demonstrates symmetric encryption and decryption using AES in GCM (Galois/Counter Mode), an authenticated encryption mode. It shows how to derive a key from a password using PBKDF2, generate a random salt and nonce, encrypt data, and then decrypt and verify its integrity.

from Crypto.Cipher import AES
from Crypto.Random import get_random_bytes
from Crypto.Protocol.KDF import PBKDF2
import os

# Simulate a password for key derivation
password = os.environ.get('CRYPTO_PASSWORD', 'mysecretpassword').encode('utf-8')

# Generate a random salt
salt = get_random_bytes(16)

# Derive a strong key from the password and salt
# Use default iterations (or a high number like 1000000)
key = PBKDF2(password, salt, dkLen=32) # 32 bytes for AES-256

# The data to encrypt
data = b"This is a super secret message."

# Encrypt with AES GCM
# A nonce is automatically generated by AES.new() in GCM mode
cipher = AES.new(key, AES.MODE_GCM)
ciphertext, tag = cipher.encrypt_and_digest(data)
nonce = cipher.nonce

print(f"Original: {data}")
print(f"Salt: {salt.hex()}")
print(f"Nonce: {nonce.hex()}")
print(f"Ciphertext: {ciphertext.hex()}")
print(f"Tag: {tag.hex()}")

# --- Decryption ---
# Re-derive the key using the same password and salt
decryption_key = PBKDF2(password, salt, dkLen=32)

# Create a new cipher object for decryption using the received key and nonce
decrypt_cipher = AES.new(decryption_key, AES.MODE_GCM, nonce=nonce)

# Decrypt and verify
try:
    plaintext = decrypt_cipher.decrypt_and_verify(ciphertext, tag)
    print(f"Decrypted: {plaintext}")
except ValueError:
    print("Decryption failed or message was tampered with!")