purepycrypto
Pure Python Cryptography Toolkit — a zero-dependency pure-Python cryptography library. SHA-2 / SHA-3 / SHAKE / BLAKE2b · PBKDF2 / HKDF / scrypt / Argon2id · AES (ECB/CBC/CTR/CFB/OFB/GCM) · AES-GCM-SIV · ChaCha20-Poly1305 / XChaCha20-Poly1305 · X25519 · Ed25519 · RSA-OAEP / PSS · PKCS#1 / PKCS#8 / SPKI / PEM
Current version: v3.2.0 (this release adds the kdf2 / encoding / rand modules, see § New in v3.2.0).
🆕 What's New in This Release (v3.2.0)
Version numbering rule:
v{major}.{feature upgrades}.{bug fixes}→ this release contains both feature upgrades and bug fixes.
1. Unified Error System (⚠️ Breaking Change)
Library-wide error handling is unified into two categories, semantically clear and never mixed:
- Fatal error → raise
PPYC_ERR(code, message, suggestion)Raised only when the program can no longer continue safely (internal invariant broken, fatal environment problem, unable to construct an object during initialization). - Non-fatal error → return a 3-tuple
(error_code, error_message, suggestion)Expected failures (invalid input, failed validation, authentication failure, missing file, parse failure) no longer raise exceptions; the caller can handle them gracefully by checking the return value. - 41 standard error codes, unified prefix
PPYC_ERR_, covering 9 major categories. - Helper functions:
ok()/err()/is_ok()/is_err()/raise_ppyc()/OK_TUPLE/PPYCResult. - Legacy exception names
CryptoError/DecryptionError/Ed25519Errorare kept as subclasses ofPPYC_ERR(backward compatible). - CLI exit codes:
0success /2PPYC_ERR/3file not found /4argument error. - See
docs/errors.mdfor details.
2. TUI CN/EN Language Switch (default EN)
The TUI supports Chinese / English interface switching, defaulting to English, and can be overridden with the environment variable PUREPYCRYPTO_LANG=cn.
3. Performance Optimization
| Algorithm | Before | After | Speedup |
|---|---|---|---|
SHA-3 keccak_f1600 |
1410 µs/perm | 191 µs/perm | 7.4x |
SHA-3 sha3_256 throughput |
425 KB/s | 838 KB/s | 1.97x |
SHA-3 hmac_sha3_256 |
277 KB/s | 628 KB/s | 2.27x |
| AES-GCM-SIV large message | 146 KB/s | 1101 KB/s | 7.5x |
| AES-GCM-SIV 32B small message | 1693 µs | 198 µs | 8.5x |
Ed25519 sign |
3.52 ms | 1.79 ms | 2.0x |
Ed25519 verify |
3.89 ms | 1.95 ms | 2.0x |
Techniques: SHA-3 uses SWAR packed integers; AES-GCM-SIV adds a POLYVAL table cache + derived-key cache + CTR multiprocessing; Ed25519 window and precomputation optimizations.
4. Fixes for 6 Real Defects
Including the sha3.py hex wrapper crash, the CLI _write_binary() crash, the CLI x25519 wrong exit code,
TUI hash / KDF menu crashes, TUI x25519/rsa unpacking crashes, TUI self-test false positives, etc. See CHANGELOG.md for details.
📖 Table of Contents
- Project Overview
- Feature Overview
- Requirements
- Installation
- Three Usage Modes
- Quick Start
- Unified Error System
- New in v3.2.0
- Windows Multiprocessing Notes
- TUI Language Switch
- API Cheat Sheet
- Security Notes
- Known Limitations
- Testing
- FAQ
- Contributing
- License
- Author
🎯 Project Overview
purepycrypto is a cryptography toolkit implemented entirely in pure Python with zero third-party dependencies. Its goal is not to replace heavily audited libraries such as
cryptography / OpenSSL that call high-performance C implementations, but to provide:
- Readable, auditable, portable — every algorithm is written line by line in pure Python, with no reliance on any C extension or system library;
- Teaching- and embedded-friendly — runs in any environment that can run CPython, with no compilation;
- Correctness first — strictly follows RFC / FIPS / NIST standards and self-tests against official vectors;
- Modern algorithm portfolio — covers hashing, message authentication, key derivation, symmetric encryption, authenticated encryption, key exchange, and public-key signatures.
⚠️ The performance and side-channel characteristics of pure Python make it unsuitable for high-throughput, strongly adversarial, long-running production-critical scenarios. Be sure to read the Security Notes and
docs/security.md.
Author: Dvs(DvsXT) · License: MIT · Current version: v3.2.0
✨ Feature Overview
| Category | Algorithm / Feature | Standard | Status |
|---|---|---|---|
| Hashing | SHA-256 / SHA-512 | FIPS 180-4 | ✅ |
| BLAKE2b (variable digest length 1–64 bytes) | RFC 7693 | ✅ | |
| SHA3-224 / 256 / 384 / 512 | FIPS 202 | ✅ | |
| SHAKE128 / SHAKE256 (extendable-output XOF) | FIPS 202 | ✅ | |
| Message Authentication | HMAC-SHA256 / HMAC-SHA512 | RFC 2104 | ✅ |
| HMAC-SHA3-256 / HMAC-SHA3-512 | RFC 2104 / FIPS 198-1 | ✅ | |
| Poly1305 (one-time authenticator) | RFC 8439 | ✅ | |
| Key Derivation | PBKDF2-HMAC-SHA256 / SHA512 | RFC 8018 / RFC 6070 | ✅ |
| HKDF (extract / expand / one-shot) | RFC 5869 | ✅ | |
| scrypt | RFC 7914 | ✅ | |
| Argon2id (with secret / associated data) | RFC 9106 | ✅ | |
| Symmetric Encryption | AES-128 / 192 / 256 | FIPS 197 | ✅ |
| Modes: ECB / CBC / CTR / CFB / OFB | NIST SP 800-38A | ✅ | |
| GCM (AEAD, with AAD) | NIST SP 800-38D | ✅ | |
| Authenticated Encryption | ChaCha20-Poly1305 | RFC 8439 | ✅ |
| XChaCha20-Poly1305 (192-bit nonce) | draft-irtf-cfrg-xchacha | ✅ | |
| AES-GCM-SIV (nonce-misuse resistant) | RFC 8452 | ✅ | |
| Key Exchange | X25519 | RFC 7748 | ✅ |
| Public-Key Encryption | RSA-OAEP | RFC 8017 | ✅ |
| Digital Signatures | RSA-PSS | RFC 8017 | ✅ |
| Ed25519 (Pure EdDSA) | RFC 8032 | ✅ | |
| Serialization | PKCS#1 / PKCS#8 / SPKI / PEM | RFC 8017 / 5958 / 5280 | ✅ |
| Engineering Utilities | Constant-time comparison, secure random | — | ✅ |
| Multiprocessing acceleration (pool reuse + SharedMemory) | — | ✅ | |
| Interactive TUI (CN/EN bilingual) / command-line CLI | — | ✅ | |
Single-file bundle purepycrypto/single/purepycrypto.py |
— | ✅ | |
| New in v3.2.0 | kdf2 (hardened KDF) / encoding (encoding) / rand (CSPRNG) |
— | ✅ |
| Not Included | Post-quantum algorithms (Kyber / Dilithium / Falcon / SPHINCS+, etc.) | — | ❌ Not provided |
Explicitly excludes any post-quantum (PQC) algorithm. For signatures, choose Ed25519 (recommended for new protocols) or RSA-PSS; for key exchange, use the X25519 + HKDF + AES-GCM / AES-GCM-SIV / ChaCha20-Poly1305 combination.
🧩 Requirements
- Python ≥ 3.7 (
pyproject.tomldeclaresrequires-python = ">=3.7"; CI covers 3.7–3.13) - No third-party runtime dependencies (uses only the standard library:
struct,os,math,base64,multiprocessing, etc.) - Optional: multiprocessing acceleration is enabled automatically on platforms that support
multiprocessing.shared_memory(Python ≥ 3.8), otherwise it falls back to serial execution automatically
📦 Installation
Install from PyPI:
pip install purepycrypto
Upgrade to the latest version:
pip install --upgrade purepycrypto
Install from source (development mode):
git clone https://git.dvscloud.net/dvs/purepycrypto.git
cd purepycrypto
pip install -e .
After installation, a single command purepycrypto is available (no arguments enters the TUI, arguments go to the command line).
🎛️ Three Usage Modes (One Command, Three Forms)
After installation only one command, purepycrypto, is registered; its behavior is dispatched automatically based on whether arguments are present:
# (1) no arguments -> interactive TUI (default English; PUREPYCRYPTO_LANG=cn switches to Chinese)
purepycrypto
purepycrypto tui # explicitly launch the TUI (equivalent)
# (2) with arguments -> command-line mode (subcommands: hash / hmac / kdf / aes / chacha / x25519 / rsa / rand / selftest / version)
purepycrypto hash --text abc --hex
purepycrypto --help # show command-line help
# (3) import as a library
python -c "import purepycrypto; print(purepycrypto.__version__)"
When not installed (inside the source directory), the equivalent form is:
python -m purepycrypto # TUI
python -m purepycrypto hash --text abc --hex # command line
python -c "import purepycrypto" # library
⚠️ Important: The command-line entry point has been unified into a single command
purepycrypto(no arguments = TUI, arguments = CLI). The only single-file artifact is the in-packagepurepycrypto/single/purepycrypto.py(generated byscripts/build_single.py --mode one), whose behavior is likewise "no arguments = TUI, arguments = CLI".
Single-File Bundle
# generate the single file in the source directory (no arguments = TUI, arguments = CLI)
python purepycrypto/scripts/build_single.py --mode one -o purepycrypto/single/purepycrypto.py
# run it directly
python purepycrypto/single/purepycrypto.py # TUI
python purepycrypto/single/purepycrypto.py hash --text abc --hex # command line
Used as a library (when there is no entry point):
import purepycrypto as ppc
print(ppc.sha3_256(b"abc").hex())
🚀 Quick Start
All examples are based on the purepycrypto v3.2.0 public API and can be run directly (Python ≥ 3.8).
1. Hashing
from purepycrypto import sha256, sha512, blake2b
print(sha256(b"abc").hex())
# ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad
print(len(sha512(b"abc"))) # 64
print(len(blake2b(b"abc"))) # 64 (default)
print(len(blake2b(b"abc", digest_size=32))) # 32
Input must be
bytes; for strings, call.encode("utf-8")first. Whenblake2b'sdigest_sizeis invalid (outside 1–64), it returns an error tuple instead of raising (see Unified Error System).
2. Key Derivation (KDF)
from purepycrypto import (
hmac_sha256, pbkdf2_hmac, hkdf, hkdf_extract, hkdf_expand, scrypt, argon2id,
)
import os
# --- HMAC ---
mac = hmac_sha256(b"key", b"message")
# --- PBKDF2 ---
salt = os.urandom(16)
dk = pbkdf2_hmac(b"password", salt, iterations=200_000, dklen=32, hash_name="sha256")
# --- HKDF (RFC 5869) ---
prk = hkdf_extract(salt=salt, ikm=b"input key material") # extract
okm = hkdf_expand(prk=prk, info=b"app-context", length=32) # expand
okm2 = hkdf(ikm=b"input key material", salt=salt, info=b"app-context", length=32)
# --- scrypt (RFC 7914) ---
sk = scrypt(b"password", b"NaCl", N=2**14, r=8, p=1, dklen=32)
# --- Argon2id (RFC 9106, recommended for new systems) ---
tag = argon2id(
password=b"password",
salt=os.urandom(16), # recommended ≥ 16 bytes
t=3, # number of iterations
m=65536, # memory (KiB)
p=4, # parallelism
tag_length=32,
)
3. AES Symmetric Encryption
from purepycrypto import AES
import os
key = os.urandom(32) # 16 / 24 / 32 bytes -> AES-128 / 192 / 256
aes = AES(key)
# --- GCM (AEAD, recommended) ---
nonce = os.urandom(12) # 96-bit nonce
ct, tag = aes.gcm_encrypt(nonce, b"secret data", aad=b"header")
pt = aes.gcm_decrypt(nonce, ct, tag, aad=b"header") # returns bytes on success
# on auth failure returns an (error_code, message, suggestion) tuple, see "Unified Error System"
# --- CBC (automatic PKCS#7 padding) ---
iv = os.urandom(16)
ct = aes.encrypt_cbc(b"secret data", iv)
pt = aes.decrypt_cbc(ct, iv)
# --- CTR (nonce is 8 bytes) ---
ct = aes.encrypt_ctr(b"secret data", os.urandom(8))
Other modes: encrypt_ecb / decrypt_ecb, encrypt_cfb / decrypt_cfb, encrypt_ofb / decrypt_ofb.
4. ChaCha20-Poly1305 / XChaCha20-Poly1305
from purepycrypto import (
chacha20poly1305_encrypt, chacha20poly1305_decrypt,
xchacha20poly1305_encrypt, xchacha20poly1305_decrypt,
poly1305_mac,
)
import os
key = os.urandom(32)
# ChaCha20-Poly1305 (12-byte nonce, RFC 8439) -- returns ciphertext || tag
blob = chacha20poly1305_encrypt(key, os.urandom(12), b"secret", aad=b"aad")
pt = chacha20poly1305_decrypt(key, nonce, blob, aad=b"aad") # returns a tuple on failure
# XChaCha20-Poly1305 (24-byte nonce, safe to generate randomly)
blob = xchacha20poly1305_encrypt(key, os.urandom(24), b"secret", aad=b"aad")
pt = xchacha20poly1305_decrypt(key, nonce24, blob, aad=b"aad")
# raw Poly1305 authenticator
mac = poly1305_mac(os.urandom(32), b"message")
5. X25519 Key Exchange
from purepycrypto import x25519, x25519_base, x25519_shared, x25519_generate_keypair
priv_a, pub_a = x25519_generate_keypair() # both 32 bytes
priv_b, pub_b = x25519_generate_keypair()
shared_a, is_zero_a = x25519_shared(priv_a, pub_b)
shared_b, is_zero_b = x25519_shared(priv_b, pub_a)
assert shared_a == shared_b
if is_zero_a or is_zero_b: # must check for a low-order point (all zero)
raise RuntimeError("low-order or forged public key detected")
pub = x25519_base(priv_a) # base point u=9
raw = x25519(priv_a, pub_b) # same as shared_a
6. Ed25519 Digital Signatures
from purepycrypto import ed25519_keygen, ed25519_publickey, ed25519_sign, ed25519_verify
seed, pub = ed25519_keygen() # seed (private key) 32 bytes, pub 32 bytes
sig = ed25519_sign(b"hello", seed) # 64-byte signature (R || S)
assert ed25519_verify(sig, b"hello", pub) is True
assert ed25519_verify(sig, b"hell0", pub) is False # verification failure returns False, does not raise
# derive the public key from a known seed (RFC 8032 §7.1 TEST 1)
seed = bytes.fromhex("9d61b19deffd5a60ba844af492ec2cc44449c5697b326919703bac031cae7f60")
print(ed25519_publickey(seed).hex())
# d75a980182b10ab7d54bfed3c964073a0ee172f3daa62325af021a68f707511a
7. RSA Public-Key Encryption and Signing
from purepycrypto import (
rsa_keygen, rsa_oaep_encrypt, rsa_oaep_decrypt,
rsa_pss_sign, rsa_pss_verify,
)
pub, priv = rsa_keygen(bits=2048, parallel=True) # parallel=True uses multiprocessing to speed up prime search
# OAEP encryption (RFC 8017)
ct = rsa_oaep_encrypt(b"secret message", pub, label=b"ctx")
pt = rsa_oaep_decrypt(ct, priv, label=b"ctx")
# PSS sign / verify
sig = rsa_pss_sign(b"message to sign", priv)
assert rsa_pss_verify(b"message to sign", sig, pub) is True
assert rsa_pss_verify(b"tampered", sig, pub) is False
RSA keys must be at least 521 bits (below this a
PPYC_ERRis raised; OAEP/PSS need a sufficient modulus length). 2048 / 3072 / 4096 are recommended.
8. PEM / DER Serialization
from purepycrypto import (
rsa_keygen, private_key_to_pem, public_key_to_pem, parse_private_pem,
private_key_to_pkcs8_der, public_key_to_spki_der,
)
pub, priv = rsa_keygen(2048)
pem_priv = private_key_to_pem(priv) # -----BEGIN PRIVATE KEY----- (PKCS#8)
pem_pub = public_key_to_pem(pub) # -----BEGIN PUBLIC KEY----- (SPKI)
der_priv = private_key_to_pkcs8_der(priv)
der_pub = public_key_to_spki_der(pub)
priv2 = parse_private_pem(pem_priv) # parse a PKCS#8 PEM private key
assert priv2.n == priv.n
with open("private_key.pem", "w", encoding="ascii") as f:
f.write(pem_priv)
9. SHA-3 / SHAKE
from purepycrypto import sha3_256, sha3_512, shake128, hmac_sha3_256, sha3_batch
print(sha3_256(b"abc").hex())
# 3a985da74fe225b2045c172d6bd390bd855f086e3e9d525b46bfe24511431532
print(shake128(b"abc", 32).hex()) # XOF: outputs an arbitrary outlen bytes
# 5881092dd818bf5cf8a3ddb793fbcba74097d5c526a6d35f97b83351940f2cc8
mac = hmac_sha3_256(b"key", b"message") # 32 bytes
# batch parallel hashing (multiple independent messages; n_workers=None auto-detects CPU count)
digests = sha3_batch([b"a", b"b", b"c"], algo="sha3_256", n_workers=4)
10. AES-GCM-SIV
from purepycrypto import (
aes128_gcm_siv_encrypt, aes128_gcm_siv_decrypt, # 16-byte key
aes256_gcm_siv_encrypt, aes256_gcm_siv_decrypt, # 32-byte key
aes_gcm_siv_encrypt, aes_gcm_siv_decrypt, # unified entry (dispatches by key length)
set_cache_enabled, cache_enabled, clear_caches,
)
import os
key = os.urandom(16) # 16 -> AES-128; 32 -> AES-256
nonce = os.urandom(12) # fixed 12 bytes
ct, tag = aes128_gcm_siv_encrypt(key, nonce, b"secret", aad=b"header")
pt = aes128_gcm_siv_decrypt(key, nonce, ct, tag, aad=b"header")
assert pt == b"secret"
# cache control (enabled by default; disable if the threat model disallows derived keys residing in memory)
set_cache_enabled(False) # disable cache
assert cache_enabled() is False
clear_caches() # clear cached content
⚠️ GCM-SIV only reduces the harm of nonce reuse; it does not permit unlimited reuse. When possible, still keep nonces unique.
11. Unified Error Handling (Overview)
from purepycrypto import AES, is_err, PPYC_ERR, PPYC_ERR_INVALID_KEY_LEN
# fatal error -> raise PPYC_ERR
try:
AES(b"short") # invalid key length
except PPYC_ERR as e:
print(e.code) # 'PPYC_ERR_INVALID_KEY_LEN'
print(e.message) # human-readable reason
print(e.suggestion) # human-readable fix suggestion
# non-fatal error -> return a 3-tuple
aes = AES(b"0" * 16)
out = aes.gcm_decrypt(b"\x00" * 12, b"ct", b"\x00" * 16) # tag mismatch
if is_err(out):
code, msg, hint = out
print(code, msg, hint) # PPYC_ERR_AUTH_FAILED ...
else:
plaintext = out
🔐 Unified Error System
As of v3.2.0, library-wide errors are unified into two categories (see docs/errors.md for details):
| Type | Handling | Applicable scenarios |
|---|---|---|
| Fatal error | Raise PPYC_ERR |
Internal invariant broken (library bug), fatal environment problem, unable to construct an object during initialization |
| Non-fatal error | Return a 3-tuple (error_code, error_message, suggestion) |
Invalid input, failed validation, authentication failure, missing file, parse failure |
from purepycrypto import PPYC_ERR, err, ok, is_ok, is_err, OK_TUPLE, PPYC_ERR_INVALID_KEY_LEN
# fatal error
raise PPYC_ERR(PPYC_ERR_INTERNAL, "state machine inconsistent", "please file an issue")
# non-fatal error (returns a tuple)
return err(PPYC_ERR_INVALID_KEY_LEN, "AES key must be 16/24/32 bytes", "pass a correct length")
# -> ('PPYC_ERR_INVALID_KEY_LEN', 'AES key must be 16/24/32 bytes', 'pass a correct length')
# success (validation-style API)
return OK_TUPLE # (None, None, None)
Caller check:
result = some_api(...)
if is_err(result): # generic check: works for any API
code, msg, hint = result
...
else:
value = result
Legacy exception names are still compatible (all are subclasses of PPYC_ERR): CryptoError (default PPYC_ERR_INTERNAL),
DecryptionError (default PPYC_ERR_AUTH_FAILED), Ed25519Error (default PPYC_ERR_INVALID_ARG).
CLI exit codes:
| Exit code | Meaning |
|---|---|
0 |
success |
1 |
other (e.g. rsa --op verify verification FAIL) |
2 |
PPYC_ERR (fatal error) |
3 |
file not found |
4 |
argument error |
✅ New in v3.2.0
The following modules are officially available as of v3.2.0 and are all merged into the top-level exports.
| Module | Responsibility | Representative interfaces |
|---|---|---|
purepycrypto.kdf2 |
Hardened key derivation (stricter validation on top of kdf: minimum salt length, Argon2 encoded strings, etc.) |
pbkdf2, argon2id_hash / argon2id_verify, argon2id_hash_encoded / argon2_verify_encoded, scrypt_simple, hkdf_expand_multi |
purepycrypto.encoding |
Pure-Python encoding (byte-for-byte identical to the standard library) | b64encode / b64decode (including URL-safe / nopad), b32encode / b32decode, hex_encode / hex_decode, b58encode / b58decode |
purepycrypto.rand |
Cryptographically secure random (CSPRNG) toolkit | random_bytes / random_int, token_bytes / token_hex / token_urlsafe, random_password, random_uuid4, random_choice / random_sample |
# example
from purepycrypto import b64encode, b58encode, token_hex, random_password
print(b64encode(b"abc")) # b'YWJj'
print(b58encode(b"\x00\x01\x02hello")) # b'13DgQxdPmp'
print(token_hex(4)) # 8-char hex string
print(random_password(16)) # random password
⚠️ Windows Multiprocessing Notes (Important)
Some APIs use a multiprocessing process pool for acceleration in large-input or batch scenarios:
| API | Condition that triggers multiprocessing |
|---|---|
sha3_batch(items, algo, n_workers) |
n_workers > 1 and enough messages |
aes128/256_gcm_siv_encrypt(...) |
large input and n_workers is None (auto) or > 1 |
rsa_keygen(..., parallel=True) |
multiprocessing prime search enabled by default |
Windows starts child processes via spawn (which re-imports the main module), so caller scripts must be wrapped in
if __name__ == "__main__":, otherwise a RuntimeError: ... bootstrapping phase is raised.
✅ Correct pattern
# my_script.py
from purepycrypto import sha3_batch, aes256_gcm_siv_encrypt
def main():
digests = sha3_batch([b"a", b"b"], "sha3_256", n_workers=4)
ct, tag = aes256_gcm_siv_encrypt(key, nonce, big_data)
if __name__ == "__main__": # <- mandatory on Windows
main()
⛔ Incorrect pattern (raises an error or silently slows down)
from purepycrypto import sha3_batch, aes256_gcm_siv_encrypt
# called directly at module level -- on Windows the child process re-executes this module, causing a RuntimeError
digests = sha3_batch(messages, "sha3_256", n_workers=4)
ct, tag = aes256_gcm_siv_encrypt(key, nonce, big_data)
🛡️ Two ways to avoid it
- Add the
if __name__ == "__main__":guard (recommended; you keep the parallel speedup); - Explicitly pass
n_workers=1to force serial (no startup overhead; actually faster for small data).
Fault tolerance note:
sha3_batchhas a built-in fallback — if multiprocessing fails to start it automatically degenerates to serial and returns the correct result, without crashing (but loses the speedup); the AES-GCM-SIV multiprocessing branch raises aRuntimeErrorin the same situation, so be sure to add the guard. Linux / macOS default toforkand usually have no such limitation, but for cross-platform consistency it is still recommended to add the guard uniformly.
🌐 TUI Language Switch (CN / EN)
The TUI supports Chinese/English interface switching, defaulting to English.
# Windows (cmd)
set PUREPYCRYPTO_LANG=cn && purepycrypto
# Windows (PowerShell)
$env:PUREPYCRYPTO_LANG="cn"; purepycrypto
# Linux / macOS
PUREPYCRYPTO_LANG=cn purepycrypto
# default (English)
purepycrypto
You can also switch it in the TUI menu, or call it in code:
from purepycrypto.cli import set_language, get_language
set_language("cn") # or "en"
print(get_language()) # 'cn' / 'en'
Values:
en(default) /cn. An invalid value falls back toen.
📚 API Cheat Sheet
The complete API is in docs/api.md. Basic interfaces can be imported from the top-level purepycrypto,
while SHA-3 / Ed25519 / AES-GCM-SIV etc. can be imported from their own submodules (or from the top level).
Hashing
| Function | Signature |
|---|---|
sha256 / sha512 |
(message: bytes) -> bytes |
blake2b |
(data: bytes, digest_size: int = 64) -> bytes |
sha3_224 / sha3_256 / sha3_384 / sha3_512 |
(data: bytes) -> bytes |
shake128 / shake256 |
(data: bytes, outlen: int) -> bytes |
sha3_batch |
(items, algo="sha3_256", n_workers=None) -> list[bytes] (v3.2.0) |
KDF / MAC
| Function | Signature |
|---|---|
hmac_sha256 / hmac_sha512 |
(key: bytes, message: bytes) -> bytes |
hmac_sha3_256 / hmac_sha3_512 |
(key: bytes, message: bytes) -> bytes |
pbkdf2_hmac |
(password, salt, iterations, dklen, hash_name="sha256") -> bytes |
hkdf_extract |
(salt, ikm, hash_name="sha256") -> bytes |
hkdf_expand |
(prk, info, length, hash_name="sha256") -> bytes |
hkdf |
(ikm, salt=b"", info=b"", length=32, hash_name="sha256") -> bytes |
scrypt |
(password, salt, N=4096, r=8, p=1, dklen=32) -> bytes |
argon2id |
(password, salt, t=1, m=256, p=1, tag_length=32, secret=b"", ad=b"", version=0x13) -> bytes |
poly1305_mac |
(key32: bytes, msg: bytes) -> bytes |
Symmetric Encryption
| Interface | Description |
|---|---|
AES(key) |
construct an AES object (key is 16/24/32 bytes) |
AES.gcm_encrypt(nonce, plaintext, aad=b"", n_workers=None) |
returns (ciphertext, tag) |
AES.gcm_decrypt(nonce, ct, tag, aad=b"") |
returns the plaintext bytes on success, an error tuple on authentication failure |
AES.encrypt_cbc / decrypt_cbc |
CBC (16-byte IV, automatic PKCS#7 padding) |
AES.encrypt_ecb / decrypt_ecb |
ECB |
AES.encrypt_ctr / decrypt_ctr |
CTR (8-byte nonce) |
AES.encrypt_cfb / decrypt_cfb |
CFB |
AES.encrypt_ofb / decrypt_ofb |
OFB |
chacha20poly1305_encrypt / decrypt |
ChaCha20-Poly1305 (12-byte nonce) |
xchacha20poly1305_encrypt / decrypt |
XChaCha20-Poly1305 (24-byte nonce) |
aes_gcm_siv_encrypt / decrypt |
unified entry dispatched by key length (16/32) |
aes128_gcm_siv_encrypt / decrypt |
AES-128-GCM-SIV (submodule purepycrypto.aes_gcm_siv) |
aes256_gcm_siv_encrypt / decrypt |
AES-256-GCM-SIV (submodule) |
set_cache_enabled / cache_enabled / clear_caches |
GCM-SIV cache control (v3.2.0) |
Public Key
| Interface | Signature |
|---|---|
x25519 |
(k: bytes, u: bytes) -> bytes (invalid input returns an error tuple) |
x25519_base |
(scalar: bytes) -> bytes |
x25519_shared |
(priv, peer_pub) -> (shared, is_zero) |
x25519_generate_keypair |
() -> (priv, pub) |
rsa_keygen |
(bits=2048, parallel=True) -> (RSAPublicKey, RSAPrivateKey) |
rsa_oaep_encrypt |
(message, pub, label=b"") -> bytes |
rsa_oaep_decrypt |
(ciphertext, priv, label=b"") -> bytes |
rsa_pss_sign |
(message, priv, salt_len=None) -> bytes |
rsa_pss_verify |
(message, signature, pub, salt_len=None) -> bool |
ed25519_keygen |
() -> (seed32, pub32) |
ed25519_publickey |
(seed32: bytes) -> bytes |
ed25519_sign |
(message: bytes, seed32: bytes) -> bytes (64 bytes) |
ed25519_verify |
(signature64, message, pub32) -> bool |
private_key_to_pem / public_key_to_pem |
(key) -> str |
parse_private_pem |
(pem: str) -> RSAPrivateKey |
private_key_to_pkcs8_der / public_key_to_spki_der |
(key) -> bytes |
private_key_to_pkcs1_der / public_key_to_pkcs1_der |
(key) -> bytes |
Utilities and Errors
| Interface | Description |
|---|---|
rand_bytes(n) |
returns n bytes of cryptographically secure random data (os.urandom) |
rand_int(a, b) |
returns a uniformly random integer in [a, b] (rejection sampling) |
PPYC_ERR / PPYCError |
fatal-error exception (carries code/message/suggestion) |
CryptoError / DecryptionError / Ed25519Error |
legacy exception names (subclasses of PPYC_ERR) |
err / ok / is_ok / is_err / raise_ppyc / OK_TUPLE / PPYCResult |
non-fatal error helpers |
ALL_ERROR_CODES |
all 41 error code constants (tuple) |
🔐 Security Notes
This section is a summary; the full statement is in docs/security.md.
- Randomness source: all random bytes come from
os.urandom()(the OS CSPRNG); the library does not contain any PRNG that can be seeded. - Constant-time comparison: sensitive comparisons (Tag / MAC / shared key) use
_consttime_eq/_consttime_int_eqto avoid early-return timing differences. - X25519 low-order point detection:
x25519_sharedreturnsis_zero; callers must check it and reject an all-zero result. - AEAD authentication: GCM / ChaCha20-Poly1305 / XChaCha20-Poly1305 / AES-GCM-SIV return an error tuple
on authentication failure (
PPYC_ERR_AUTH_FAILED) and never return unauthenticated plaintext. - Error codes do not leak sensitive information: error codes and messages describe only the category and fix suggestion, never key / nonce / plaintext content (see
docs/security.md). - RSA blinding: the private-key decryption path includes blinding to mitigate timing side-channel risk.
- Ed25519 signatures: Pure EdDSA (RFC 8032); scalar multiplication uses a masked lookup-table constant-time approach (best-effort).
- ⚠️ Do not use it for highly adversarial, long-running production-critical systems. Pure Python cannot guarantee memory zeroization and cannot fully eliminate timing / branch / cache side channels.
⚠️ Known Limitations
- Performance: pure-Python throughput is far below C implementations that call OpenSSL; large-file encryption/decryption and high-parameter PBKDF2/Argon2id will be noticeably slow.
- Side channels: core comparisons and X25519/Ed25519 scalar multiplication have constant-time handling, but the Python interpreter's own branching, object allocation, and big-integer arithmetic timing cannot be fully controlled, making it unsuitable for strongly adversarial scenarios that directly face untrusted input.
- Memory zeroization: Python has no reliable memory-erasure mechanism; keys may remain in heap memory until GC.
- Algorithm scope: includes SHA-3/SHAKE, Ed25519, and AES-GCM-SIV; excludes any post-quantum (PQC) algorithm.
- nonce length:
gcm_encryptuses a 96-bit (12-byte) nonce; CTR uses an 8-byte nonce; do not reuse a nonce under the same key. - PEM support scope:
parse_private_pemonly parses PKCS#8 RSA private keys (labelPRIVATE KEY); it does not support the legacy PKCS#1 labelRSA PRIVATE KEY, nor EC / Ed25519. - Minimum RSA size:
rsa_keygenrequiresbits >= 521; below this aPPYC_ERRis raised.
🧪 Testing
# run all tests (tests live in the in-package purepycrypto/tests)
pytest purepycrypto/tests -q
Standard vectors covered by the tests (NIST / RFC):
- SHA-256 / SHA-512 (FIPS 180-4), BLAKE2b (RFC 7693)
- HMAC-SHA256 / 512 (RFC 4231), PBKDF2 (RFC 6070), HKDF (RFC 5869), scrypt (RFC 7914), Argon2id (RFC 9106)
- SHA-3 / SHAKE (FIPS 202, cross-verified against
hashlib) - AES (FIPS 197) and GCM (NIST SP 800-38D)
- ChaCha20 / Poly1305 / ChaCha20-Poly1305 (RFC 8439)
- X25519 (RFC 7748), Ed25519 (RFC 8032 §7.1), AES-GCM-SIV (RFC 8452)
- RSA-OAEP / PSS (RFC 8017)
- Unified error system
test_errors.py/test_errors_edge.py
❓ FAQ
Q: Why not use the hashlib / hmac standard libraries?
A: This library is positioned as a "pure-Python auditable implementation"; hashing and HMAC are also implemented from scratch to keep the algorithm logic fully visible and portable. If you only care about performance, the standard library or cryptography is more suitable.
Q: How does the AES(key) key length determine the variant?
A: 16 → AES-128; 24 → AES-192; 32 → AES-256. Any other length raises PPYC_ERR(PPYC_ERR_INVALID_KEY_LEN).
Q: Does authentication failure raise an exception or return an error?
A: As of v3.2.0, gcm_decrypt / chacha*decrypt etc. return a 3-tuple (code, msg, hint) (code is PPYC_ERR_AUTH_FAILED); check with is_err(). The historical name DecryptionError can still be caught.
Q: Why does X25519 return is_zero?
A: When the shared secret is all zeros it means the peer public key is a low-order point and the shared secret is unsafe, so it must be rejected (RFC 7748 §6.1).
Q: Can it be used for both signing and encryption? A: Yes. Use RSA-PSS or Ed25519 for signing, and RSA-OAEP for encryption; the two use different padding schemes, so do not mix them.
Q: Are there multiple command-line entry points?
A: There is only one command, purepycrypto: no arguments launches the TUI, arguments enter the command line (subcommands hash / hmac / kdf / aes / chacha / x25519 / rsa / rand / selftest / version).
Q: Is Ed25519 available?
A: Yes. ed25519_keygen / ed25519_sign / ed25519_verify. It still does not provide any post-quantum algorithm.
🤝 Contributing
- New algorithms must come with standard test vectors (RFC / FIPS / NIST) and test cases added under
purepycrypto/tests/. - Keep zero third-party dependencies (standard library only).
- Use constant-time functions for sensitive comparisons; use
os.urandomfor randomness. - Follow the unified error system: parameter validation / authentication failure →
return err(...); internal contradiction →raise PPYC_ERR(...); do not invent error codes. - Code must pass
pytest -q. Commit messages and documentation may be in Chinese or English; code identifiers stay in English.
📄 License
This project is released under the MIT License. See LICENSE for details.
👤 Author
Dvs(DvsXT) — self-developed cryptography library · purepycrypto
- Email: dvs6666@163.com
- Repository: https://git.dvscloud.net/dvs/purepycrypto
💡 Disclaimer: This library is designed for learning, experimentation, teaching, and embedded prototypes, and the author accepts no liability for any direct or indirect loss caused by its use. For production-critical scenarios, please prefer implementations that have been widely audited and maintained by professional cryptography engineering teams.
purepycrypto v3.2.0 · Made with ❤️ by Dvs(DvsXT)
Metadata
Release files for purepycrypto 3.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| purepycrypto-3.2.0.tar.gz | 336.3 kB | Without provenance | Details for purepycrypto-3.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| purepycrypto-3.2.0-py3-none-any.whl | Python 3 | none | any | Details for purepycrypto-3.2.0-py3-none-any.whl |
Total release size: 634.2 kB
Release files / purepycrypto-3.2.0.tar.gz
| Download URL | purepycrypto-3.2.0.tar.gz |
|---|---|
| Size | 336.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
e6e4a25b410ed44d4b35b28c1ffc5e6ae85fca6e7b85a7c797f73f5fc9a02866
|
|
BLAKE2b-256 checksum How to use checksums |
da5dfaffb290a405a352db4b6ef05f6b8c3ee044c64df4a010c68e0e794a3692
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.4
|
Release files / purepycrypto-3.2.0-py3-none-any.whl
| Download URL | purepycrypto-3.2.0-py3-none-any.whl |
|---|---|
| Size | 297.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
ddf86a66228f898550f442ee201942b6ce70f7105612a5a8ed94125d557af5e0
|
|
BLAKE2b-256 checksum How to use checksums |
a8fcdc63c0314fc5cce3d55d5fd49fd6253cc08d2a0389e2817bf5da18bdcd0d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.13.4
|
Security for purepycrypto 3.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.