Files
dvs 5dfdd87c06 Release v3.2.1: performance overhaul (1.96x geometric-mean speed-up)
Pure-Python, zero-dependency speed-up across every hot path. No public API,
error-semantics or security change.

Measured (interleaved A/B min-of-N, idle 16-core, 1 KiB payload):
  Base64 decode      21.98x
  Base58 encode       8.01x
  ChaCha20-Poly1305   3.54x
  XChaCha20-Poly1305  3.28x
  Base64 encode       2.98x
  AES-256-GCM (enc)   2.25x   (dec) 2.26x
  AES-GCM-SIV enc     2.06x
  AES-256 CTR/ECB/CBC 2.01x / 1.96x / 1.88x
  AES single block    1.87x
  Poly1305 MAC        1.41x
  Ed25519 sign        1.41x
  X25519 base         1.19x
  BLAKE2b / SHA3-512 / SHAKE128  1.34x / 1.33x / 1.30x
  => 24 improved, 3 unchanged, 0 regressed.

Techniques (all pure Python):
  - code-generated, fully unrolled AES round function and Keccak-f[1600]
  - big-integer bulk operations for GHASH, POLYVAL, buffer XOR, Base64 pack
  - precomputed lookup tables (AES T-tables, GHASH/POLYVAL 4-bit windows)
  - branch-free constant-time selection in Ed25519 scan and X25519 ladder
  - lazy modular reduction in X25519 field arithmetic
  - batched Base58/Base64 processing
  - inlined inner loops in AEAD assembly and the SHA-2 message schedule

Verification:
  - full test suite: 639 passed, 1 skipped, 0 failed
  - all FIPS / RFC / NIST vectors reproduce byte-for-byte
  - differential probe of 1266 deterministic inputs: identical
    (one unreachable private-helper edge case, no caller can reach it)
  - public API signature comparison: 0 removals, 0 changes
  - independent security regression suite: 35 / 35

Also adds docs/benchmark.md, bench/benchmark.py and the v3.2.1 documentation.
2026-09-27 11:37:33 +08:00

36 KiB
Raw Permalink Blame History

purepycrypto

Repository Python License Dependencies Author

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.1 (a performance release: 1.96x geometric-mean speed-up, see § Performance and docs/benchmark.md).


⚡ Performance (v3.2.1)

v3.2.1 is a pure optimization release. Every hot path was reworked while keeping the public API, the error semantics and the security properties unchanged. The library is still 100% pure Python, zero dependencies — no primitive was replaced by a C-backed shortcut.

Operation Speed-up vs v3.2.0
Base64 decode 21.98x
Base58 encode 8.01x
ChaCha20-Poly1305 encrypt 3.54x
XChaCha20-Poly1305 encrypt 3.28x
Base64 encode 2.98x
AES-256-GCM decrypt / encrypt 2.26x / 2.25x
AES-GCM-SIV encrypt 2.06x
AES-256-CTR / ECB / CBC 2.01x / 1.96x / 1.88x
AES single block (256-bit) 1.87x
Poly1305 MAC 1.41x
Ed25519 sign 1.41x
X25519 base 1.19x
BLAKE2b / SHA3-512 / SHAKE128 1.34x / 1.33x / 1.30x

24 improved, 3 unchanged, 0 regressed. Geometric-mean speed-up over 27 measured operations: 1.96x.

Techniques: code-generated fully-unrolled AES / Keccak round functions, big-integer bulk operations for GHASH and POLYVAL, precomputed lookup tables, branch-free constant-time selection, lazy modular reduction in X25519, and batched Base58 / Base64 processing. Full data and methodology are in docs/benchmark.md.


🆕 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 / Ed25519Error are kept as subclasses of PPYC_ERR (backward compatible).
  • CLI exit codes: 0 success / 2 PPYC_ERR / 3 file not found / 4 argument error.
  • See docs/errors.md for 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

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.1


✨ 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.toml declares requires-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-package purepycrypto/single/purepycrypto.py (generated by scripts/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. When blake2b's digest_size is 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_ERR is 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

  1. Add the if __name__ == "__main__": guard (recommended; you keep the parallel speedup);
  2. Explicitly pass n_workers=1 to force serial (no startup overhead; actually faster for small data).

Fault tolerance note: sha3_batch has 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 a RuntimeError in the same situation, so be sure to add the guard. Linux / macOS default to fork and 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 to en.


📚 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_eq to avoid early-return timing differences.
  • X25519 low-order point detection: x25519_shared returns is_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

  1. 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.
  2. 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.
  3. Memory zeroization: Python has no reliable memory-erasure mechanism; keys may remain in heap memory until GC.
  4. Algorithm scope: includes SHA-3/SHAKE, Ed25519, and AES-GCM-SIV; excludes any post-quantum (PQC) algorithm.
  5. nonce length: gcm_encrypt uses a 96-bit (12-byte) nonce; CTR uses an 8-byte nonce; do not reuse a nonce under the same key.
  6. PEM support scope: parse_private_pem only parses PKCS#8 RSA private keys (label PRIVATE KEY); it does not support the legacy PKCS#1 label RSA PRIVATE KEY, nor EC / Ed25519.
  7. Minimum RSA size: rsa_keygen requires bits >= 521; below this a PPYC_ERR is 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

  1. New algorithms must come with standard test vectors (RFC / FIPS / NIST) and test cases added under purepycrypto/tests/.
  2. Keep zero third-party dependencies (standard library only).
  3. Use constant-time functions for sensitive comparisons; use os.urandom for randomness.
  4. Follow the unified error system: parameter validation / authentication failure → return err(...); internal contradiction → raise PPYC_ERR(...); do not invent error codes.
  5. 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

💡 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.1 · Made with ❤️ by Dvs(DvsXT)