Files
dvs 0d69391aa9 Release v3.2.0: pure-Python cryptography library (English docs/comments/errors)
- Zero-dependency pure-Python cryptography: SHA-2 / SHA-3 / SHAKE / BLAKE2b,
  HMAC, PBKDF2 / HKDF / scrypt / Argon2id, AES (ECB/CBC/CTR/CFB/OFB/GCM),
  AES-GCM-SIV, ChaCha20-Poly1305 / XChaCha20-Poly1305, X25519, Ed25519,
  RSA (keygen / OAEP / PSS / PEM), ASN.1 DER
- Unified error system: PPYC_ERR fatal exception vs (code, message, suggestion)
  non-fatal 3-tuple return
- Interactive TUI (Chinese / English i18n) + non-interactive CLI
- v3.2.0 adds the encoding, rand and kdf2 modules
- Documentation, code comments and error messages fully in English;
  the interactive TUI keeps its Chinese interface
- Tests: RFC / FIPS / NIST test vectors, 639 passing
2026-09-27 09:40:12 +08:00

15 KiB

Security Statement

Please read this file in full before using purepycrypto.

purepycrypto is a pure-Python, zero-dependency cryptography library, aimed at learning, teaching, experimentation, and embedded prototypes. It is not a cryptography engineering implementation for highly adversarial, long-running, production-critical scenarios. This document honestly explains its security properties, implementation boundaries, and known limitations.


1. Positioning Statement

Design goals of purepycrypto:

  • Readable, auditable — a line-by-line pure-Python implementation, with the algorithm logic fully visible and no black-box binary dependencies;
  • Portable — depends only on the standard library; runs in any environment that can run CPython;
  • Correctness first — strictly follows RFC / FIPS / NIST standards and self-tests against official vectors.

purepycrypto is not:

  • ❌ an equivalent replacement for libsodium / OpenSSL / BoringSSL / cryptography (pyca);
  • ❌ a library that has undergone third-party cryptographic audit, formal verification, or side-channel hardening;
  • ❌ designed for high-throughput, strongly adversarial scenarios (where holding keys is safer and the attacker has precise timing capability).

If you need production-grade cryptography, prefer implementations that have been widely deployed and professionally audited (such as cryptography, libsodium, or cryptography APIs provided by the operating system).


2. Randomness Source

Purpose Source Description
All random bytes os.urandom() OS CSPRNG (Windows BCryptGenRandom / Linux getrandom / macOS arc4random backend)
rand_bytes(n) os.urandom(n) direct wrapper
rand_int(a, b) os.urandom + rejection sampling avoids modulo bias
X25519 private key os.urandom(32) generated by x25519_generate_keypair
RSA prime-factor search os.urandom random starting point + prime stepping
OAEP / PSS salt os.urandom random for each encryption/signature
RSA blinding factor os.urandom mitigates timing side channels

Guarantee: the library contains no PRNG that an attacker can seed, nor any predictable or weak random generator. All randomness comes from the OS CSPRNG.

Responsibility: callers must use cryptographically secure randomness for IV / nonce / salt (preferably os.urandom or this library's rand_bytes) and must not use the random module.


3. Constant-Time Implementation

To reduce timing side-channel risk, the following sensitive paths use constant-time code:

Location Measure
Constant-length comparison _consttime_eq: XOR-OR accumulation over all bytes, no early return
Integer comparison _consttime_int_eq: accumulates differences in 64-bit chunks
Conditional selection _consttime_select: selects with bitmasks, no branches
X25519 scalar multiplication uses a Montgomery ladder + constant-time cswap, avoiding secret-dependent if
Ed25519 scalar multiplication fixed 4-bit window + masked lookup table (linear masked selection over 16 entries), 256-round fixed-length main loop, no secret-dependent branches / early exit (best-effort)
GCM / AEAD tag verification uses constant-time comparison; authentication failure does not expose the differing position
RSA private-key operations uses CRT + Montgomery modular exponentiation and introduces blinding

Note

: the measures above only mitigate algorithm-level timing differences. See §5 Side Channels and Implementation Risks.


4. Secure-Usage Points for Each Algorithm

4.1 Symmetric Encryption

  • AES-GCM (recommended): nonce must be 12 bytes and never repeated under the same key; aad binds context that is not encrypted but needs authentication. Authentication failure raises DecryptionError.
  • AES-CTR: nonce is 8 bytes; the counter space must not overlap under the same key, otherwise keystream reuse causes catastrophic leakage.
  • AES-CBC: iv must be random and unpredictable (to prevent IV-prediction attacks under chosen plaintext); a MAC is required to prevent tampering.
  • AES-ECB: does not hide plaintext patterns; do not use it except for compatibility/deterministic needs.
  • CFB / OFB: no authentication; if used for encryption, an additional MAC is required.

4.2 AEAD (Authenticated Encryption)

  • ChaCha20-Poly1305: 12-byte nonce; the nonce must never be reused (one-time keystream).
  • XChaCha20-Poly1305: 24-byte nonce, safe to generate randomly, suitable for scenarios that do not need counter management.
  • Poly1305: key32 is a one-time key; never reuse the same Poly1305 key across two messages.

Golden rule: the (key, nonce) combination may be used only once. For GCM / CTR / ChaCha20-family algorithms, nonce reuse = disaster. The only exception: AES-GCM-SIV (RFC 8452) is resistant to nonce misuse, but is still bounded by a repetition limit, see §4.7.

4.3 Key Derivation

  • PBKDF2: iterations recommended ≥ 200000 (SHA-256); new systems should prefer Argon2id.
  • HKDF: used for material expansion of already high-entropy keys; not suitable for passwords.
  • scrypt: N, r, p determine the memory and time cost; increase them according to hardware capability.
  • Argon2id: the first choice for modern password hashing (RFC 9106). Larger m (memory, KiB), t (iterations), and p (parallelism) are safer, requiring a performance trade-off.

4.4 Key Exchange

  • X25519: x25519_shared returns is_zero. Must check it: if True, the peer public key is a low-order point and the shared secret is unsafe, so abort immediately (RFC 7748 §6.1).
  • Do not use the negotiated shared secret directly as a symmetric key; derive it through HKDF.

4.5 RSA

  • Key length: rsa_keygen requires bits >= 521; 2048 / 3072 / 4096 are recommended.
  • Encryption: use OAEP (rsa_oaep_encrypt/decrypt), not raw RSA or PKCS#1 v1.5.
  • Signatures: use PSS (rsa_pss_sign/verify), not PKCS#1 v1.5.
  • Encryption and signing are different primitives; do not mix up padding and purpose.
  • The message length for RSA encryption is limited; for large messages, use RSA to wrap a symmetric key (KEM approach) and then encrypt the data with an AEAD.

4.6 Ed25519 Digital Signatures

  • Standard and variant: purepycrypto.ed25519 implements Pure Ed25519 from RFC 8032 (not Ed25519ph / Ed25519ctx). Signatures are a fixed 64 bytes, and both the public key and the private-key seed are 32 bytes.
  • Verification semantics: ed25519_verify always returns False for invalid length, invalid point encoding, S ≥ L, etc. (no exception); callers must treat False explicitly as a verification failure and must not ignore the return value.
  • Constant time: scalar multiplication uses a fixed 4-bit window + masked lookup table (linear masked selection over 16 candidates) and a 256-round fixed-length main loop, striving to eliminate secret-dependent branches and early exits; but pure Python cannot provide true constant time (see §5).
  • Private-key form: the private key is a 32-byte random seed; the public key can be re-derived with ed25519_publickey(seed); protect this seed like any other key.
  • RSA-PSS can still be used when interoperability with an existing RSA ecosystem is needed; new protocols should prefer Ed25519 (shorter public keys / signatures, no randomness source needed, deterministic signatures).

4.7 AES-GCM-SIV

  • Positioning: a nonce-misuse resistant AEAD (RFC 8452). key is a key-generating key (16 or 32 bytes), nonce is a fixed 12 bytes, and the tag is a fixed 16 bytes.
  • Nonce-misuse resistance principle: (key, nonce) first derives a per-message authentication-key and encryption-key; the synthesized IV (tag) varies with the plaintext / AAD. Therefore, when (key, nonce) repeats, the keystream is not reused as long as the plaintext or AAD differs; the attacker can at most tell whether two messages are exactly identical.
  • A repetition limit still exists: GCM-SIV is not "free to reuse nonces". RFC 8452 gives upper bounds on both the total number of messages encrypted under a single key and the number of repetitions of a single nonce; security degrades beyond them. Unless nonce management is genuinely difficult, still keep nonces unique.
  • Performance cost: encryption requires two passes (authenticate first, then encrypt), slower than AES-GCM; suitable for scenarios where nonce consistency is hard to guarantee strictly (e.g. multiple devices sharing a key but generating counters independently).
  • Authentication failure: when the ciphertext / tag / AAD is tampered with, *_decrypt raises DecryptionError and never returns unauthenticated plaintext.

5. Side Channels and Implementation Risks

⚠️ A reality that must be recognized: a pure-Python implementation cannot guarantee the following security properties.

5.1 Timing and Branch Side Channels

Although the core paths use constant-time handling, the Python interpreter itself introduces variability that cannot be fully controlled:

  • The execution time of big-integer arithmetic (RSA, X25519, modular exponentiation) in the underlying implementation (int) depends on the operand values, so in theory an attacker has room for timing/power/cache side channels;
  • the timing of object allocation and garbage collection (GC) is uncontrollable;
  • branch prediction, cache hits, and memory access patterns are hard to keep constant at the Python level;
  • the modular inverse in the form pow(z2, P-2, P) is executed at the end of X25519, and its timing may leak limited information.

Therefore: do not place this library in a strongly adversarial environment where the attacker can precisely measure timing.

5.2 Memory Residue

  • Python has no reliable key-erasure mechanism. Key objects may remain in heap memory until GC, and may even be paged to disk (swap);
  • this library does not provide mlock (memory locking), memset_s (secure zeroing), etc.;
  • when a long-running process handles sensitive keys, memory protection must be considered separately (e.g. using restricted-process / memory-encryption OS mechanisms).

5.3 Faults and Exceptions

  • Authentication failures uniformly raise DecryptionError (without distinguishing the cause) to reduce oracle information;
  • but Python exception tracebacks, string formatting, etc. may still leak internal state (e.g. paths, line numbers).

6. Known Limitations

  1. Performance: pure-Python throughput is far below C implementations. Large-file encryption, high-iteration PBKDF2, and large-memory-parameter Argon2id are noticeably slower in Python.
  2. Algorithm scope:
    • ✅ includes SHA-3 / SHAKE, Ed25519, AES-GCM-SIV;
    • ❌ excludes any post-quantum (PQC) algorithm (Kyber / Dilithium / Falcon / SPHINCS+, etc.);
    • signatures may use Ed25519 (recommended) or RSA-PSS; for key exchange, use X25519.
  3. 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, etc.
  4. GCM nonce length: gcm_encrypt uses a 12-byte nonce; CTR uses an 8-byte nonce. Note the length conventions.
  5. Multiprocessing: parallel=True automatically falls back to serial on environments that do not support multiprocessing / SharedMemory, with no functional impact; however, parallel workers still pass data via standard IPC, so do not casually place long-term keys in shared memory.
  6. Minimum RSA size: bits < 521 raises ValueError directly.
  7. No certificates / no TLS: this library does not provide X.509 certificates, TLS, protocol handshakes, or other higher-layer facilities; these must be built separately with correct authentication and anti-replay handling.

7. Prohibitions (Do NOT)

  • ❌ Do not use this library for production-critical, highly adversarial cryptographic systems;
  • ❌ Do not reuse the nonce of GCM / CTR / ChaCha20 under the same key;
  • ❌ Do not reuse Poly1305's one-time key;
  • ❌ Do not use the random module to generate IV / nonce / salt / keys;
  • ❌ Do not ignore the is_zero returned by x25519_shared;
  • ❌ Do not encrypt structured data with ECB;
  • ❌ Do not use raw RSA or PKCS#1 v1.5 in place of OAEP / PSS;
  • ❌ Do not use HKDF for low-entropy passwords (use PBKDF2 / scrypt / Argon2id);
  • ❌ Do not treat this library as a drop-in replacement for OpenSSL / libsodium.

  • ✅ Prefer AEAD: AES-GCM or ChaCha20-Poly1305 / XChaCha20-Poly1305;
  • ✅ Generate IV / nonce / salt randomly each time (os.urandom or rand_bytes);
  • ✅ Derive the key-exchange result through HKDF before use;
  • ✅ Use Argon2id for password storage (or scrypt / PBKDF2, with parameters raised according to hardware);
  • ✅ Verify all AEAD Tags / MACs and treat DecryptionError as authentication failure, then abort;
  • ✅ Use OAEP for RSA encryption and PSS for signatures, with a bit size ≥ 2048;
  • ✅ New protocols should prefer Ed25519 signatures (short public keys / short signatures, no randomness-source dependency); use RSA-PSS when RSA-ecosystem compatibility is needed;
  • ✅ When nonce uniqueness is hard to guarantee (multiple writers / weak randomness source), prefer AES-GCM-SIV or XChaCha20-Poly1305;
  • ✅ Validate the length and format of untrusted input to avoid leaking exception information.

9. Disclaimer

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

The author Dvs(DvsXT) accepts no liability for any direct or indirect loss caused by the use of this library (including but not limited to data leakage, key leakage, or property loss).


10. Vulnerability Reporting

If you find a security issue, please report it through the project Issues or the author's email me@dvsyun.top, and provide as much as possible:

  • reproduction steps and environment (Python version, operating system);
  • affected modules and functions;
  • expected behavior and actual behavior;
  • if standard vectors are involved, attach the vector source (RFC / NIST number).

11. Summary in One Sentence

purepycrypto is an honest, readable, auditable pure-Python cryptography toolkit; it helps you correctly understand and experiment with modern cryptographic primitives, but should not be misused as the security foundation of a highly adversarial production environment. For important systems, use mature, professionally audited implementations.