Registry / auth-security / pycryptodomex

pycryptodomex

JSON →
library3.23.0pypypi✓ verified 29d ago

PyCryptodomeX is a self-contained Python package providing low-level cryptographic primitives. It is a fork of the unmaintained PyCrypto library, offering numerous enhancements like authenticated encryption modes, Hybrid Public Key Encryption (HPKE), accelerated AES, and elliptic curve cryptography. It is actively maintained, with version 3.23.0 being the latest, and releases occur frequently. It supports Python 2.7, Python 3.7 and newer, and PyPy.

pip install pycryptodomex
INSTALL
IMPORT
SIG · PYCRYPTODOMEX
P
pycryptodomex
auth-securitypythonv3.23.0
Install
2.1s avg
Import
53ms
Disk
25MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.9–3.13
musl
3.9–3.13
Install & Compatibility
Where this runs
tested against v3.23.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.10–3.95 runs
installs and imports cleanly · install 0.0s · import 0.048s · 26.3MB
glibc
py 3.10–3.95 runs
installs and imports cleanly · install 2.1s · import 0.058s · 27MB
25MB installed
● package 25MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

AES
✓ from Cryptodome.Cipher import AES
✗ from Crypto.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
✗ from Crypto.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`.

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!")
Debug
Known issues
breakingSupport 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.
affects: >=3.22.0
gotchaPyCryptodomeX 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.
affects: All versions
deprecatedECB (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)`.
affects: >=3.5.0
breakingOlder 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.
affects: <3.19.1
gotchaIn 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.
affects: >=3.22.0
gotchaAn 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.
affects: <3.22.0
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'Crypto'
You have installed the `pycryptodomex` package, but are attempting to import modules using the `Crypto` namespace, which is reserved for the `pycryptodome` package or the legacy `PyCrypto` library. `pycryptodomex` installs its modules under the `Cryptodome` namespace to prevent conflicts.
fix
If you installed `pycryptodomex`, change your import statements to use `Cryptodome` instead of `Crypto` (e.g., `from Cryptodome.Cipher import AES`). If you intended to use the `Crypto` namespace, install `pycryptodome` instead (`pip install pycryptodome`).
ModuleNotFoundError: No module named 'Cryptodome'
You have likely installed the `pycryptodome` package, which installs its modules under the `Crypto` namespace, but your code is trying to import from `Cryptodome`. This can also occur if `pycryptodomex` was installed, but in a conflicting environment, or if there's a typo in the import statement.
fix
If you installed `pycryptodome`, change your import statements to use `Crypto` instead of `Cryptodome` (e.g., `from Crypto.Cipher import AES`). If you intended to use the `Cryptodome` namespace, ensure `pycryptodomex` is correctly installed (`pip install pycryptodomex`) and check for environment conflicts.
ERROR: Command errored out with exit status 1
This error during `pycryptodomex` installation, particularly on Windows, usually indicates that the necessary C/C++ build tools are missing. `pycryptodomex` includes C extensions that require a compiler to build if a pre-compiled wheel is not available or compatible.
fix
Install the appropriate C++ build tools for your Python version and operating system. On Windows, this typically means installing 'Build Tools for Visual Studio' (e.g., from visualstudio.microsoft.com) and selecting the C++ development workload.
'utf-8' codec can't decode byte 0x81 in position X: invalid start byte
This error often occurs when attempting to decode raw encrypted binary data (which is not plain text) directly into a string using an encoding like UTF-8. Encrypted data should be treated as bytes until decrypted, and only then decoded if it represents a text string.
fix
Ensure that encrypted data is handled as raw bytes. If you need to transmit encrypted data as a string (e.g., over HTTP), first encode the bytes using a binary-to-text encoding like Base64 (`import base64; base64.b64encode(ciphertext)`). On receipt, decode from Base64 back to bytes *before* attempting decryption (`base64.b64decode(encoded_ciphertext)`).
Upgrade
Version history
3.23.0latest on PyPI · released May 17, 2025
Audit
Dependencies

No dependency data recorded yet.

Agent activity
15 hits · last 30 days
node
12
OpenAI (training)
1
Resources
pycryptodomex — pip install pycryptodomex · libregistry