cryptography

Warnings

• breaking The `backend` parameter was removed from all hazmat constructors (Cipher, rsa.generate_private_key, ec.generate_private_key, etc.). Passing `backend=default_backend()` now raises TypeError.
  Fix: Remove all `backend=` keyword arguments. Modern API: `rsa.generate_private_key(public_exponent=65537, key_size=2048)` with no backend argument.
• breaking `signer()` and `verifier()` methods on public/private key objects were removed in 44.0.0 after being deprecated since 2.0.
  Fix: Replace `key.signer(...)` with `key.sign(...)` and `key.verifier(...)` with `key.verify(...)` directly.
• breaking OpenSSL 1.1.x support was removed; OpenSSL 3.0.0 or later is now required when building from source. LibreSSL < 4.1 also dropped.
  Fix: Upgrade system OpenSSL to 3.0+, or use pre-built wheels (which bundle a recent OpenSSL statically).
• breaking Loading keys with unsupported algorithms or explicit curve encodings now raises `UnsupportedAlgorithm` instead of `ValueError`.
  Fix: Catch `cryptography.exceptions.UnsupportedAlgorithm` instead of (or in addition to) `ValueError` when loading keys.
• deprecated CFB, OFB, and CFB8 modes have been moved to 'Decrepit cryptography' and deprecated in `cryptography.hazmat.primitives.ciphers.modes`. They will be removed in 49.0.0. Camellia cipher is similarly deprecated.
  Fix: Migrate to AES-GCM or ChaCha20-Poly1305 (AEAD modes) for new code. Import from `cryptography.hazmat.decrepit` if you must keep using them temporarily.
• gotcha ECB mode (`modes.ECB`) is available but insecure—it encrypts identical plaintext blocks to identical ciphertext blocks, leaking data patterns. The library does not prevent its use.
  Fix: Always prefer authenticated encryption: use `AESGCM`, `ChaCha20Poly1305`, or `Cipher` with `modes.GCM`. Never use ECB in production.
• gotcha When building from source (not from a wheel), a Rust toolchain (cargo) is required. On Alpine Linux < 3.21 and older Debian/Ubuntu, the default Rust is too old.
  Fix: Install via `pip install cryptography` with an up-to-date pip to receive a pre-built binary wheel. If building from source, install Rust via rustup and ensure version >= 1.83.0.

Install

• pip install cryptography Install (standard)
• pip install --upgrade pip && pip install cryptography Install with updated pip (avoids source builds)

Imports

• Fernet

  from cryptography.fernet import Fernet

  High-level authenticated symmetric encryption; preferred over raw hazmat APIs for most use cases
• Cipher, algorithms, modes

  from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes

  The `backend` parameter was removed in 3.x; passing `default_backend()` to Cipher() raises TypeError on modern versions
• AESGCM (AEAD shortcut)

  from cryptography.hazmat.primitives.ciphers.aead import AESGCM

  Simpler authenticated encryption API; handles IV/tag automatically compared to the Cipher+GCM mode pattern
• rsa.generate_private_key

  from cryptography.hazmat.primitives.asymmetric import rsa

  The `backend` keyword argument was removed; call without it: rsa.generate_private_key(public_exponent=65537, key_size=2048)
• padding (asymmetric)

  from cryptography.hazmat.primitives.asymmetric import padding

  Use padding.OAEP for RSA encryption and padding.PSS for RSA signatures; PKCS1v15 is legacy only
• hashes

  from cryptography.hazmat.primitives import hashes

  Used with asymmetric sign/verify and HMAC; e.g. hashes.SHA256()
• serialization

  from cryptography.hazmat.primitives import serialization

  For loading/serializing PEM/DER keys; use serialization.load_pem_private_key(), not legacy OpenSSL backend helpers
• x509

  from cryptography import x509

  X.509 certificate parsing and building; use x509.load_pem_x509_certificate()

Quickstart

Fernet high-level symmetric encryption (recommended starting point) plus AES-GCM via hazmat for authenticated low-level encryption.

# --- High-level: Fernet (recommended for most use cases) ---
from cryptography.fernet import Fernet

key = Fernet.generate_key()          # Must be stored securely; bytes
f = Fernet(key)
token = f.encrypt(b"secret message")  # Returns URL-safe base64 token
plaintext = f.decrypt(token)          # Raises InvalidToken if tampered
assert plaintext == b"secret message"

# --- Low-level: AES-GCM via hazmat (authenticated encryption) ---
import os
from cryptography.hazmat.primitives.ciphers.aead import AESGCM

aes_key = AESGCM.generate_key(bit_length=256)  # 32 random bytes
aesgcm = AESGCM(aes_key)
nonce = os.urandom(12)               # 96-bit nonce; NEVER reuse with same key
ciphertext = aesgcm.encrypt(nonce, b"secret data", b"optional AAD")
decrypted = aesgcm.decrypt(nonce, ciphertext, b"optional AAD")
assert decrypted == b"secret data"

# --- RSA key generation & sign/verify ---
from cryptography.hazmat.primitives.asymmetric import rsa, padding
from cryptography.hazmat.primitives import hashes

private_key = rsa.generate_private_key(public_exponent=65537, key_size=2048)
public_key = private_key.public_key()
message = b"message to sign"
signature = private_key.sign(
    message,
    padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.MAX_LENGTH),
    hashes.SHA256()
)
public_key.verify(
    signature, message,
    padding.PSS(mgf=padding.MGF1(hashes.SHA256()), salt_length=padding.PSS.MAX_LENGTH),
    hashes.SHA256()
)  # Raises InvalidSignature if verification fails
print("All operations succeeded")