pycryptodome

PyCryptodome is a fork of the long-abandoned PyCrypto library, rebuilt to give Python developers a self-contained set of cryptographic primitives that doesn’t depend on OpenSSL or any other external C library. It ships as either Crypto (a near drop-in PyCrypto replacement) or Cryptodome (an independent namespace that can coexist with PyCrypto), covering symmetric ciphers (AES, ChaCha20, Salsa20, DES3), authenticated modes (GCM, CCM, EAX, SIV, OCB), hash functions (SHA-2, SHA-3, BLAKE2, KangarooTwelve), and public-key cryptography (RSA, DSA, ECC over NIST curves and Ed25519/Ed448/Curve25519/Curve448).

Most of the codebase is pure Python for portability and auditability, with performance-critical primitives like block ciphers implemented as C extensions and accelerated further via AES-NI on supported Intel/AMD hardware. The project ships extensive .pyi type stubs for every public module and maintains a large per-algorithm self-test suite exercised through GitHub Actions CI, including CodeQL static analysis. It remains one of the most widely used cryptography packages in the Python ecosystem, commonly reached for whenever a project needs concrete primitives rather than a high-level protocol library.

What You Get

• Symmetric ciphers - AES, ChaCha20/XChaCha20, Salsa20, DES3, Blowfish, ARC2/ARC4/CAST with block modes CBC, CFB, OFB, CTR, GCM, CCM, EAX, SIV, OCB, KW, and KWP.
• Hash functions and MACs - SHA-2, SHA-3 (with SHAKE/cSHAKE/KMAC/TupleHash), BLAKE2b/BLAKE2s, KangarooTwelve, TurboSHAKE, HMAC, CMAC, and Poly1305.
• Public-key cryptography - RSA and DSA key generation/signing, elliptic curves (NIST P-curves plus Ed25519, Ed448, Curve25519, Curve448), and PKCS#1/PKCS#8 key containers.
• Key derivation and secret sharing - scrypt, bcrypt, HKDF, NIST SP 800-108r1 counter-mode KDF, and Shamir’s Secret Sharing.
• Hardware-accelerated performance - AES-NI acceleration on supported CPUs, with a pure Python fallback everywhere else and no dependency on system OpenSSL.
• Full type stubs - every public module ships a matching .pyi file, so static type checkers get complete coverage out of the box.

Common Use Cases

• Encrypting application data at rest with AES-GCM or ChaCha20-Poly1305 when you need an authenticated cipher without a heavyweight TLS-oriented dependency.
• Signing and verifying payloads (JWTs, webhooks, license files) with RSA, DSA, or Ed25519/Ed448.
• Deriving encryption keys from user passwords with scrypt, bcrypt, or HKDF before storing or transmitting secrets.
• Migrating a legacy codebase off the abandoned PyCrypto library with a near drop-in replacement (Crypto namespace) or a clean, coexisting install (Cryptodome namespace).
• Implementing custom protocols that need low-level primitives (raw block ciphers, MACs, secret sharing) rather than a pre-built high-level protocol stack.

Under The Hood

Architecture The library is organized by cryptographic category — Crypto.Cipher, Crypto.Hash, Crypto.PublicKey, Crypto.Protocol, Crypto.Signature, Crypto.Math, Crypto.Random, and Crypto.Util — with each algorithm module (e.g. lib/Crypto/Cipher/AES.py) acting as a thin Python wrapper around a compiled C extension exposed through Crypto.Util._raw_api.load_pycryptodome_raw_lib. Runtime CPU feature detection (Crypto.Util._cpu_features.have_aes_ni()) selects between a portable C implementation and an AES-NI accelerated one, falling back gracefully if the hardware path isn’t available; higher-level constructs like cipher modes (_mode_gcm.py, _mode_eax.py) and authenticated schemes are composed on top of these low-level primitives in pure Python. What breaks if a core abstraction changes: the raw-library loading indirection in _raw_api.py is the single seam nearly every cipher and hash module depends on, so it is the most load-bearing piece of the codebase.

Tech Stack The project targets CPython 3.7+ and PyPy, builds via setuptools (declared in pyproject.toml), and compiles a large set of C sources (src/*.c) for AES, SHA-2/3, ChaCha20, elliptic-curve arithmetic, and bignum operations, with platform-specific build logic in setup.py/compiler_opt.py handling AES-NI, CLMUL, and 32-bit toolchain variants. It has no runtime dependency on OpenSSL or any other cryptography library — everything performance-critical is implemented in-tree.

Code Quality Every algorithm module has a corresponding self-test suite under lib/Crypto/SelfTest/ built on the standard unittest framework, run through three separate GitHub Actions workflows (integration.yml, wheels.yml, codeql-analysis.yml) covering functional tests, wheel builds across platforms, and static security analysis via CodeQL. Every public module ships a matching .pyi stub, and pyproject.toml configures mypy overrides for the bundled test-vectors package, giving downstream consumers full static type coverage.

What Makes It Unique Unlike bindings that wrap OpenSSL or another external C library, PyCryptodome implements its cryptographic primitives itself — most of the codebase is pure Python, with only the extremely performance-critical pieces (block ciphers, hash compression functions) written as C extensions — which removes an entire class of deployment and version-skew problems tied to the system’s OpenSSL install. Its dual-namespace design (Crypto vs Cryptodome) is also a deliberate compatibility mechanism, letting it serve simultaneously as a drop-in PyCrypto successor and as an independent package that can be installed alongside PyCrypto without conflict.