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.
This commit is contained in:
dvs
2026-09-27 11:37:33 +08:00
parent f5c86d53e5
commit 5dfdd87c06
21 changed files with 5816 additions and 1701 deletions
+67
View File
@@ -9,6 +9,73 @@ and the version numbers follow [Semantic Versioning](https://semver.org/lang/zh-
## [Unreleased]
(none)
---
## [3.2.1] - 2026-09-27
### Changed — performance overhaul (pure Python, no API change)
Every hot path was reworked. The library is still **100% pure Python with zero
dependencies**; no primitive was replaced by a C-backed shortcut. The public
API, the error semantics and the security properties are unchanged.
**Measured speed-ups (v3.2.0 -> v3.2.1, interleaved A/B min-of-N on an idle
16-core machine, 1 KiB payload):**
| Operation | Speed-up |
|---|---:|
| Base64 decode | **21.98x** |
| Base58 encode / decode | **8.01x** / 3.98x |
| ChaCha20-Poly1305 / XChaCha20-Poly1305 encrypt | **3.54x** / 3.28x |
| Base64 encode | **2.98x** |
| AES-256-GCM encrypt / decrypt | **2.25x** / 2.26x |
| 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 / verify / publickey | 1.41x / 1.39x / 1.39x |
| X25519 base | 1.19x |
| BLAKE2b / SHA3-256 / SHA3-512 / SHAKE128 | 1.34x / 1.26x / 1.33x / 1.30x |
| **Geometric mean over 27 operations** | **1.96x** |
**24 improved, 3 unchanged, 0 regressed.** See [`docs/benchmark.md`](docs/benchmark.md)
for the full table and methodology.
**Techniques used (all pure-Python):**
- **Code-generated, fully unrolled functions** for the AES round function and
the Keccak-f[1600] permutation, eliminating per-round loops, indexing and
attribute lookups.
- **Big-integer bulk operations** for GHASH, POLYVAL, buffer XOR and the
Base64 pack/unpack paths (`int.from_bytes` / `to_bytes` / `^` execute in C
over a whole buffer in a single call).
- **Precomputed lookup tables**: AES T-tables, GHASH / POLYVAL 4-bit windows,
Keccak rho/pi offset tables, precomputed DER length headers.
- **Constant-time-safe selection** in the Ed25519 scalar scan and the X25519
Montgomery ladder (branch-free masking, timing proven comparable).
- **Lazy modular reduction** in X25519 field arithmetic, replacing a `% p`
per multiply with a cheaper fold.
- **Batch Base58 / Base64 processing**, removing the per-character `divmod`
(the previous Base58 hot spot).
- **Inlined inner loops** in AEAD assembly, the CTR/GCM block loops and the
message schedule of SHA-2.
### Verified — no behavior change
- Full test suite: **639 passed, 1 skipped, 0 failed**.
- Standard vectors (FIPS 180-4 / FIPS 197 / FIPS 202 / RFC 5869 / RFC 6070 /
RFC 7748 / RFC 7914 / RFC 8032 / RFC 8439 / RFC 8452 / RFC 9106 / NIST GCM)
reproduce byte-for-byte.
- Differential probe of 1266 deterministic inputs against v3.2.0: identical,
except one unreachable private helper (`der._der_len` with a **negative**
argument, which no caller can produce since every call site passes `len()`).
- Public API signature comparison: **0 removals, 0 changes**.
- Independent security regression suite: **35 / 35** (AEAD tamper detection,
constant-time comparison helpers, X25519 low-order points, Ed25519
constant-time selection, RSA failure paths, error-message hygiene).
### Changed — full English localization
- **Documentation, code comments and error messages are now entirely in English.**