Files
purepycrypto/README.md
T
dvs f5c86d53e5 docs: point all project links at the real repository
- Replace placeholder/incorrect URLs with the actual Gitea repository
  https://git.dvscloud.net/dvs/purepycrypto
- CHANGELOG: github.com/dvs/purepycrypto -> git.dvscloud.net/dvs/purepycrypto
- README: PyPI badge -> Repository badge; real `git clone` URL in the
  source-install recipe; badges now link to the repository
- README / pyproject.toml / setup.py / PKG-INFO: remove the unrelated
  https://apds.top homepage that did not belong to this project
2026-09-27 09:45:27 +08:00

805 lines
35 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# purepycrypto
[![Repository](https://img.shields.io/badge/gitea-git.dvscloud.net-blue)](https://git.dvscloud.net/dvs/purepycrypto)
[![Python](https://img.shields.io/badge/python-3.7%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
[![Dependencies](https://img.shields.io/badge/dependencies-zero-brightgreen)](https://git.dvscloud.net/dvs/purepycrypto)
[![Author](https://img.shields.io/badge/author-Dvs(DvsXT)-orange)](https://git.dvscloud.net/dvs/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](#-new-in-v320)).
---
## 🆕 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`](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`](./CHANGELOG.md) for details.
---
## 📖 Table of Contents
- [Project Overview](#-project-overview)
- [Feature Overview](#-feature-overview)
- [Requirements](#-requirements)
- [Installation](#-installation)
- [Three Usage Modes](#-three-usage-modes-one-command-three-forms)
- [Quick Start](#-quick-start)
- [Unified Error System](#-unified-error-system)
- [New in v3.2.0](#-new-in-v320)
- [Windows Multiprocessing Notes](#-windows-multiprocessing-notes-important)
- [TUI Language Switch](#-tui-language-switch-cn--en)
- [API Cheat Sheet](#-api-cheat-sheet)
- [Security Notes](#-security-notes)
- [Known Limitations](#-known-limitations)
- [Testing](#-testing)
- [FAQ](#-faq)
- [Contributing](#-contributing)
- [License](#-license)
- [Author](#-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](#-security-notes) and [`docs/security.md`](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.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:
```bash
pip install purepycrypto
```
Upgrade to the latest version:
```bash
pip install --upgrade purepycrypto
```
Install from source (development mode):
```bash
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:
```bash
# (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:
```bash
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
```bash
# 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):
```python
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
```python
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](#-unified-error-system)).
### 2. Key Derivation (KDF)
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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
```python
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)
```python
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`](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 |
```python
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**:
```python
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` |
```python
# 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
```python
# 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)
```python
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**.
```bash
# 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:
```python
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`](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`](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
```bash
# 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`](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.
---
<div align="center">
**purepycrypto v3.2.0** · Made with ❤️ by **Dvs(DvsXT)**
</div>