cryptography

cryptography is the standard cryptographic library for Python, providing both safe, high-level recipes and low-level primitives for developers who need fine-grained control. Its Fernet class offers authenticated symmetric encryption with sane defaults out of the box, while the hazmat (“hazardous materials”) layer exposes ciphers, hashes, KDFs, and asymmetric algorithms for building custom protocols — clearly separated so casual users don’t accidentally reach for unsafe building blocks.

Under the hood, nearly all cryptographic operations are implemented in a Rust workspace (cryptography-openssl, cryptography-key-parsing, cryptography-x509, cryptography-x509-verification) that wraps OpenSSL, BoringSSL, or AWS-LC and is exposed to Python through PyO3/maturin bindings. This design replaced most of the historical hand-written CFFI bindings, improving memory safety, while shipping prebuilt wheels for every major platform so most users never need a Rust or C toolchain to install it.

What You Get

• Fernet high-level symmetric encryption recipe with built-in key rotation via MultiFernet
• A hazmat primitives layer covering ciphers, hashes, HMAC/CMAC, AEAD, and KDFs for custom protocol design
• Full asymmetric crypto support: RSA, DSA, ECDSA/ECDH, Ed25519/Ed448, and X25519/X448
• An X.509 toolkit for parsing, building, and verifying certificates and CSRs, backed by a dedicated Rust verification engine
• Prebuilt wheels for every major platform so consumers never need a local Rust or OpenSSL toolchain

Common Use Cases

• Encrypting stored secrets, tokens, or session data with an authenticated symmetric cipher
• Parsing, validating, and building X.509 certificate chains for TLS/PKI tooling
• Signing and verifying payloads or webhooks with asymmetric keys
• Composing low-level primitives such as AES-GCM and HKDF to implement custom secure protocols

Under The Hood

Architecture cryptography splits into a Python-facing package (src/cryptography) and a Rust core (src/rust) compiled via PyO3/maturin and exposed through hazmat.bindings._rust. The Python layer has two tiers: a friendly “recipes” layer (fernet.py, the high-level x509 API) and the hazmat (“hazardous materials”) layer exposing low-level primitives (hazmat/primitives, hazmat/backends/openssl, hazmat/bindings). The Rust workspace is itself modularized into focused crates — cryptography-cffi (the PyO3/CFFI bridge), cryptography-crypto (constant-time ops, PKCS12/PBKDF1 helpers), cryptography-key-parsing (ASN.1/PKCS8/SPKI/RSA/DSA/EC parsing), cryptography-openssl (safe Rust wrappers over OpenSSL’s C API), and cryptography-x509 / cryptography-x509-verification (a from-scratch Rust X.509 chain-building and verification engine). Because nearly every primitive is implemented in Rust and merely exposed to Python as thin wrapper calls, changing the core OpenSSL binding surface ripples through ciphers, hashes, and asymmetric keys alike.

Tech Stack The build system is maturin (PyO3-based), combining Rust and Python in one wheel, configured via pyproject.toml plus Cargo.toml/Cargo.lock. The Python side depends on cffi for legacy platforms and typing-extensions for pre-3.11 interpreters. The Rust workspace links against OpenSSL by default, with dedicated CI workflows (boring-open-awslc-bump.yml) that build and test against BoringSSL and AWS-LC as alternate backends. Development tooling is orchestrated through nox (noxfile.py) driving pytest, pytest-xdist, pytest-randomly, and pytest-benchmark, with ruff/black for linting and Sphinx for documentation. Distribution ships as prebuilt, per-platform wheels via a dedicated wheel-builder.yml workflow, so most consumers install without a local Rust or C toolchain.

Code Quality The test suite is extensive, spanning hundreds of test files under tests/hazmat and tests/x509, plus an embedded Wycheproof test-vector suite (tests/wycheproof) for cross-implementation cryptographic correctness and a bench/ directory for performance regression tracking via pytest-benchmark. Type hints and from __future__ import annotations are used throughout, with a py.typed marker signaling first-class typing support. CI (ci.yml) runs across multiple OS and Python versions plus alternate OpenSSL-compatible backends, and errors are surfaced through explicit typed exceptions (InvalidSignature, InvalidToken) rather than swallowed silently.

API Design The high-level Fernet API is deliberately minimal — generate_key, encrypt, and decrypt — intentionally hiding cipher-mode and IV choices to prevent misuse, while the hazmat namespace is explicitly named and documented as “hazardous materials” to warn developers away from low-level primitives unless they specifically need them. Constructors compose consistently (Cipher, algorithms, and modes combine as orthogonal building blocks), and typed exceptions communicate failure clearly. Getting started requires almost no boilerplate for the common case (Fernet(key).encrypt(...)), while low-level usage requires deliberately assembling primitives by hand — a safety-first design choice rather than an oversight.