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
+466
View File
@@ -0,0 +1,466 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
purepycrypto benchmark suite
============================
Measures the throughput of every public algorithm / mode in purepycrypto.
Run it from the repository root so the package is importable:
python bench/benchmark.py
python bench/benchmark.py --budget 0.05 --repeats 3
python bench/benchmark.py --sizes 64,1024,65536
Why this design
---------------
* Pure-Python crypto is CPU-bound. On a many-core machine, **multiprocessing
is the only thing that makes a full-suite run fast**, so every task is
dispatched to a process pool with one worker per CPU core and the whole
suite completes in a single parallel wave.
* Windows uses the ``spawn`` start method, which means **lambdas and closures
cannot be pickled** and therefore cannot be sent to a worker. Every
benchmark is expressed as a *spec*: a plain, picklable dict of primitives
(operation name + parameters). Each worker rebuilds the callable locally.
* Inside a worker each task is warmed up, then the loop count is
auto-calibrated to fill a small time budget, and the reported figure is the
best of N repeats. That makes fast primitives (sub-microsecond) and slow
ones (hundreds of milliseconds) both measured meaningfully.
Output is a set of tables grouped by category, sorted by speed within each
group, plus a summary of the wall clock and any failures.
See ``docs/benchmark.md`` for the published results, environment details and
an honest discussion of the performance trade-offs.
"""
import argparse
import os
import sys
import time
from concurrent.futures import ProcessPoolExecutor, as_completed
# ---------------------------------------------------------------- defaults
DEFAULT_BUDGET = 0.03 # seconds of measurement per task
DEFAULT_REPEATS = 1 # best of N
KB = 1024
MB = 1024 * 1024
# =================================================================== timing
def _timeit(call, budget):
"""Warm up, auto-calibrate, and return (seconds_per_op, iterations)."""
call() # warm-up
n = 1
while True:
t0 = time.perf_counter()
for _ in range(n):
call()
dt = time.perf_counter() - t0
if dt >= budget or n >= (1 << 22):
break
n = max(n * 2, int(n * budget / max(dt, 1e-9)))
t0 = time.perf_counter()
for _ in range(n):
call()
return (time.perf_counter() - t0) / n, n
def _payload(size):
"""Deterministic payload, identical in every worker (no RNG involved)."""
return (b"purepycrypto-benchmark-payload-" * (size // 29 + 2))[:size]
def run_spec(args):
"""Executed inside a worker process. ``args`` = (spec, budget, repeats)."""
spec, budget, repeats = args
import purepycrypto as ppc
try:
call, unit_bytes, unit_ops = _build(ppc, spec)
# calibrate once, then take the best of `repeats` measurements
best = float("inf")
iters = 0
for _ in range(max(1, repeats)):
sec, n = _timeit(call, budget)
best = min(best, sec)
iters = n
except Exception as e: # noqa: BLE001
return {"name": spec["name"], "group": spec["group"],
"error": f"{type(e).__name__}: {e}"}
res = {"name": spec["name"], "group": spec["group"],
"sec_per_op": best, "ops_per_sec": unit_ops / best, "iters": iters}
if unit_bytes:
res["mb_per_sec"] = (unit_bytes * unit_ops) / best / MB
return res
# =================================================================== builders
def _build(ppc, spec):
"""Map a spec to (callable, unit_bytes, unit_ops)."""
op = spec["op"]
sz = spec.get("size", 0)
P = spec.get("p", {})
# ---- hashes -------------------------------------------------------
if op in ("sha256", "sha512", "sha3_256", "sha3_512", "blake2b"):
d = _payload(sz)
f = getattr(ppc, op)
fn = (lambda: f(d, 64)) if op == "blake2b" else (lambda: f(d))
return fn, sz, 1
if op in ("shake128", "shake256"):
d = _payload(sz)
f = getattr(ppc, op)
return (lambda: f(d, P["outlen"])), sz, 1
if op.startswith("hmac_"):
d = _payload(sz)
f = getattr(ppc, op)
return (lambda: f(bytes(range(min(P["klen"], 256))), d)), sz, 1
# ---- AES ----------------------------------------------------------
if op == "aes_block":
aes = ppc.AES(bytes(range(16 if P["bits"] == 128 else 32)))
return (lambda: aes.encrypt_block(bytes(range(16)))), 16, 1
if op.startswith("aes_"):
aes = ppc.AES(bytes(range(32)))
pt = _payload(sz)
n12, n8, iv = bytes(range(12)), bytes(range(8)), bytes(range(16))
modes = {
"aes_gcm_enc": lambda: aes.gcm_encrypt(n12, pt),
"aes_cbc_enc": lambda: aes.encrypt_cbc(pt, iv),
"aes_ctr_enc": lambda: aes.encrypt_ctr(pt, n8),
"aes_cfb_enc": lambda: aes.encrypt_cfb(pt, iv),
"aes_ofb_enc": lambda: aes.encrypt_ofb(pt, iv),
"aes_ecb_enc": lambda: aes.encrypt_ecb(pt),
}
if op == "aes_gcm_dec":
ct, tag = aes.gcm_encrypt(n12, pt)
return (lambda: aes.gcm_decrypt(n12, ct, tag)), sz, 1
return modes[op], sz, 1
# ---- AES-GCM-SIV --------------------------------------------------
if op in ("gcm_siv_enc", "gcm_siv_dec", "gcm_siv_enc128"):
k = bytes(range(16 if op == "gcm_siv_enc128" else 32))
n12 = bytes(range(12))
pt = _payload(sz)
enc = (ppc.aes128_gcm_siv_encrypt if op == "gcm_siv_enc128"
else ppc.aes256_gcm_siv_encrypt)
if op == "gcm_siv_dec":
ct, tag = enc(k, n12, pt)
return (lambda: ppc.aes256_gcm_siv_decrypt(k, n12, ct, tag)), sz, 1
return (lambda: enc(k, n12, pt)), sz, 1
# ---- ChaCha -------------------------------------------------------
if op in ("chacha_enc", "chacha_dec", "xchacha_enc"):
k, pt = bytes(range(32)), _payload(sz)
n12, n24 = bytes(range(12)), bytes(range(24))
if op == "chacha_dec":
ct = ppc.chacha20poly1305_encrypt(k, n12, pt)
return (lambda: ppc.chacha20poly1305_decrypt(k, n12, ct)), sz, 1
if op == "xchacha_enc":
return (lambda: ppc.xchacha20poly1305_encrypt(k, n24, pt)), sz, 1
return (lambda: ppc.chacha20poly1305_encrypt(k, n12, pt)), sz, 1
if op == "poly1305":
return (lambda: ppc.poly1305_mac(bytes(range(32)), _payload(sz))), sz, 1
# ---- KDF ----------------------------------------------------------
if op == "pbkdf2":
it, h = P["iters"], P.get("hash", "sha256")
return (lambda: ppc.pbkdf2_hmac(b"password", b"salt" * 4, it, 32, h)), None, 1
if op == "hkdf":
return (lambda: ppc.hkdf(bytes(range(32)), b"salt", b"info", 32)), None, 1
if op == "scrypt":
N, r, p = P["N"], P["r"], P["p"]
return (lambda: ppc.scrypt(b"password", b"salt" * 4, N, r, p, 32)), None, 1
if op == "argon2id":
t, m, p = P["t"], P["m"], P["p"]
return (lambda: ppc.argon2id(b"password", b"salt" * 4, t, m, p, 32)), None, 1
# ---- X25519 -------------------------------------------------------
if op == "x25519_keygen":
return (lambda: ppc.x25519_generate_keypair()), None, 1
if op == "x25519_base":
return (lambda: ppc.x25519_base(bytes(range(31)) + b"\x7f")), None, 1
if op == "x25519_shared":
a, _ = ppc.x25519_generate_keypair()
_, bp = ppc.x25519_generate_keypair()
return (lambda: ppc.x25519_shared(a, bp)), None, 1
# ---- Ed25519 ------------------------------------------------------
if op.startswith("ed25519_"):
seed = bytes(range(32))
pub = ppc.ed25519_publickey(seed)
msg = b"purepycrypto benchmark message"
sig = ppc.ed25519_sign(msg, seed)
if op == "ed25519_public":
return (lambda: ppc.ed25519_publickey(seed)), None, 1
if op == "ed25519_sign":
return (lambda: ppc.ed25519_sign(msg, seed)), None, 1
return (lambda: ppc.ed25519_verify(sig, msg, pub)), None, 1
# ---- RSA (keygen once per worker) ---------------------------------
if op.startswith("rsa_"):
pub, priv = ppc.rsa_keygen(bits=1024, parallel=False)
msg = b"benchmark"
if op == "rsa_oaep_enc":
return (lambda: ppc.rsa_oaep_encrypt(msg, pub)), None, 1
if op == "rsa_oaep_dec":
ct = ppc.rsa_oaep_encrypt(msg, pub)
return (lambda: ppc.rsa_oaep_decrypt(ct, priv)), None, 1
if op == "rsa_pss_sign":
return (lambda: ppc.rsa_pss_sign(msg, priv)), None, 1
if op == "rsa_pss_verify":
sig = ppc.rsa_pss_sign(msg, priv)
return (lambda: ppc.rsa_pss_verify(msg, sig, pub)), None, 1
# ---- Encoding -----------------------------------------------------
if op.startswith("enc_"):
d = _payload(sz)
if op == "enc_b64":
return (lambda: ppc.b64encode(d)), sz, 1
if op == "enc_b64dec":
e = ppc.b64encode(d)
return (lambda: ppc.b64decode(e)), len(e), 1
if op == "enc_b32":
return (lambda: ppc.b32encode(d)), sz, 1
if op == "enc_hex":
return (lambda: ppc.hex_encode(d)), sz, 1
if op == "enc_b58":
return (lambda: ppc.b58encode(d)), sz, 1
# ---- Random -------------------------------------------------------
if op == "rand_bytes":
return (lambda: ppc.random_bytes(sz)), None, 1
if op == "token_hex":
return (lambda: ppc.token_hex(32)), None, 1
if op == "token_urlsafe":
return (lambda: ppc.token_urlsafe(32)), None, 1
if op == "uuid4":
return (lambda: ppc.random_uuid4()), None, 1
if op == "password":
return (lambda: ppc.random_password(length=16)), None, 1
if op == "rand_int":
return (lambda: ppc.random_int(1, 1 << 64)), None, 1
if op == "rand_bit":
return (lambda: ppc.random_bit()), None, 1
if op == "random_string":
alpha = "abcdefghijklmnopqrstuvwxyz0123456789"
return (lambda: ppc.random_string(16, alpha)), None, 1
# ---- Parallel helpers ---------------------------------------------
if op == "sha3_batch":
items = [bytes(range(256)) * 4] * 64 # 64 x 1 KiB
return (lambda: ppc.sha3_batch(items)), 64 * KB, 1
raise ValueError("unknown op: " + op)
# =================================================================== spec table
GROUPS = ["Hash", "AES", "AES-GCM-SIV", "ChaCha", "KDF", "X25519",
"Ed25519", "RSA", "Encoding", "Random", "Parallel"]
def make_specs(sizes, groups=None):
"""Build the task list. ``sizes`` is a list of (label, byte-size)."""
S = []
a = S.append
# Hash
for label, size in sizes:
for op, disp in [("sha256", "SHA-256"), ("sha512", "SHA-512"),
("blake2b", "BLAKE2b-64"), ("sha3_256", "SHA3-256"),
("sha3_512", "SHA3-512")]:
a({"op": op, "size": size, "name": f"{disp} [{label}]", "group": "Hash"})
a({"op": "shake128", "size": size, "p": {"outlen": 32},
"name": f"SHAKE128-32B [{label}]", "group": "Hash"})
a({"op": "shake256", "size": size, "p": {"outlen": 64},
"name": f"SHAKE256-64B [{label}]", "group": "Hash"})
a({"op": "hmac_sha256", "size": KB, "p": {"klen": 32},
"name": "HMAC-SHA256 [1KB]", "group": "Hash"})
a({"op": "hmac_sha512", "size": KB, "p": {"klen": 64},
"name": "HMAC-SHA512 [1KB]", "group": "Hash"})
a({"op": "hmac_sha3_256", "size": KB, "p": {"klen": 32},
"name": "HMAC-SHA3-256 [1KB]", "group": "Hash"})
a({"op": "hmac_sha3_512", "size": KB, "p": {"klen": 64},
"name": "HMAC-SHA3-512 [1KB]", "group": "Hash"})
# AES
a({"op": "aes_block", "p": {"bits": 128}, "name": "AES-128 block encrypt", "group": "AES"})
a({"op": "aes_block", "p": {"bits": 256}, "name": "AES-256 block encrypt", "group": "AES"})
for label, size in sizes:
for op, disp in [("aes_gcm_enc", "AES-256-GCM enc"),
("aes_gcm_dec", "AES-256-GCM dec"),
("aes_cbc_enc", "AES-256-CBC enc"),
("aes_ctr_enc", "AES-256-CTR enc"),
("aes_cfb_enc", "AES-256-CFB enc"),
("aes_ofb_enc", "AES-256-OFB enc"),
("aes_ecb_enc", "AES-256-ECB enc")]:
a({"op": op, "size": size, "name": f"{disp} [{label}]", "group": "AES"})
# AES-GCM-SIV
for label, size in sizes:
a({"op": "gcm_siv_enc128", "size": size,
"name": f"AES-128-GCM-SIV enc [{label}]", "group": "AES-GCM-SIV"})
a({"op": "gcm_siv_enc", "size": size,
"name": f"AES-256-GCM-SIV enc [{label}]", "group": "AES-GCM-SIV"})
a({"op": "gcm_siv_dec", "size": size,
"name": f"AES-256-GCM-SIV dec [{label}]", "group": "AES-GCM-SIV"})
# ChaCha
for label, size in sizes:
a({"op": "chacha_enc", "size": size,
"name": f"ChaCha20-Poly1305 enc [{label}]", "group": "ChaCha"})
a({"op": "chacha_dec", "size": size,
"name": f"ChaCha20-Poly1305 dec [{label}]", "group": "ChaCha"})
a({"op": "xchacha_enc", "size": size,
"name": f"XChaCha20-Poly1305 enc [{label}]", "group": "ChaCha"})
a({"op": "poly1305", "size": KB, "name": "Poly1305 MAC [1KB]", "group": "ChaCha"})
# KDF
a({"op": "pbkdf2", "p": {"iters": 100},
"name": "PBKDF2-SHA256 100 iters", "group": "KDF"})
a({"op": "pbkdf2", "p": {"iters": 100, "hash": "sha512"},
"name": "PBKDF2-SHA512 100 iters", "group": "KDF"})
a({"op": "hkdf", "name": "HKDF-SHA256 (32B out)", "group": "KDF"})
a({"op": "scrypt", "p": {"N": 1024, "r": 8, "p": 1},
"name": "scrypt N=2^10 r=8 p=1", "group": "KDF"})
a({"op": "argon2id", "p": {"t": 1, "m": 256, "p": 1},
"name": "Argon2id t=1 m=256KiB p=1", "group": "KDF"})
# X25519 / Ed25519
a({"op": "x25519_keygen", "name": "X25519 keygen", "group": "X25519"})
a({"op": "x25519_base", "name": "X25519 base (scalar*B)", "group": "X25519"})
a({"op": "x25519_shared", "name": "X25519 shared (ECDH)", "group": "X25519"})
a({"op": "ed25519_public", "name": "Ed25519 publickey", "group": "Ed25519"})
a({"op": "ed25519_sign", "name": "Ed25519 sign", "group": "Ed25519"})
a({"op": "ed25519_verify", "name": "Ed25519 verify", "group": "Ed25519"})
# RSA
a({"op": "rsa_oaep_enc", "name": "RSA-1024 OAEP encrypt", "group": "RSA"})
a({"op": "rsa_oaep_dec", "name": "RSA-1024 OAEP decrypt", "group": "RSA"})
a({"op": "rsa_pss_sign", "name": "RSA-1024 PSS sign", "group": "RSA"})
a({"op": "rsa_pss_verify", "name": "RSA-1024 PSS verify", "group": "RSA"})
# Encoding
for label, size in sizes:
for op, disp in [("enc_b64", "Base64 encode"), ("enc_b64dec", "Base64 decode"),
("enc_b32", "Base32 encode"), ("enc_hex", "Hex encode"),
("enc_b58", "Base58 encode")]:
a({"op": op, "size": size, "name": f"{disp} [{label}]", "group": "Encoding"})
# Random
a({"op": "rand_bytes", "size": 32, "name": "random_bytes(32)", "group": "Random"})
a({"op": "rand_bytes", "size": KB, "name": "random_bytes(1KB)", "group": "Random"})
a({"op": "token_hex", "name": "token_hex(32)", "group": "Random"})
a({"op": "token_urlsafe", "name": "token_urlsafe(32)", "group": "Random"})
a({"op": "uuid4", "name": "random_uuid4()", "group": "Random"})
a({"op": "password", "name": "random_password(16)", "group": "Random"})
a({"op": "rand_int", "name": "random_int(1, 2^64)", "group": "Random"})
a({"op": "rand_bit", "name": "random_bit()", "group": "Random"})
a({"op": "random_string", "name": "random_string(16)", "group": "Random"})
# Parallel helpers
a({"op": "sha3_batch", "name": "sha3_batch 64x1KB", "group": "Parallel"})
if groups:
want = {g.lower() for g in groups}
S = [s for s in S if s["group"].lower() in want]
return S
# =================================================================== reporting
def report(results, wall, cores):
ok = [r for r in results if "error" not in r]
bad = [r for r in results if "error" in r]
groups = {}
for r in ok:
groups.setdefault(r["group"], []).append(r)
for g in GROUPS:
rows = groups.get(g)
if not rows:
continue
rows.sort(key=lambda r: r["sec_per_op"])
print("=" * 96)
print(f" {g}")
print("=" * 96)
print(f" {'operation':42s} {'ops/sec':>15s} {'us/op':>10s} "
f"{'MB/s':>10s} {'iters':>10s}")
print(" " + "-" * 92)
for r in rows:
mbs = f"{r['mb_per_sec']:10.2f}" if "mb_per_sec" in r else f"{'-':>10s}"
print(f" {r['name']:42s} {r['ops_per_sec']:15,.0f} "
f"{r['sec_per_op'] * 1e6:10.3f} {mbs} {r['iters']:10,d}")
print()
if bad:
print("=" * 96)
print(" FAILED")
print("=" * 96)
for r in bad:
print(f" {r['name']:42s} {r['error']}")
print()
print("=" * 96)
print(f" {len(ok)} OK | {len(bad)} failed | wall clock {wall:.2f}s | {cores} cores")
print("=" * 96)
# =================================================================== main
def main(argv=None):
ap = argparse.ArgumentParser(
description="purepycrypto benchmark suite (multiprocess)",
formatter_class=argparse.ArgumentDefaultsHelpFormatter,
)
ap.add_argument("--budget", type=float, default=DEFAULT_BUDGET,
help="seconds of measurement per task")
ap.add_argument("--repeats", type=int, default=DEFAULT_REPEATS,
help="take the best of N measurement rounds")
ap.add_argument("--sizes", default="64,1024",
help="comma-separated payload sizes in bytes")
ap.add_argument("--workers", type=int, default=0,
help="worker processes (0 = one per CPU core)")
ap.add_argument("--groups", default="",
help="comma-separated category filter, e.g. "
"'Hash,AES,RSA' (default: all)")
args = ap.parse_args(argv)
sizes = []
for s in args.sizes.split(","):
s = s.strip()
if not s:
continue
n = int(s)
label = f"{n}B" if n < KB else (f"{n // KB}KB" if n < MB else f"{n // MB}MB")
sizes.append((label, n))
if not sizes:
ap.error("no valid --sizes given")
groups = [g.strip() for g in args.groups.split(",") if g.strip()]
specs = make_specs(sizes, groups or None)
if not specs:
ap.error("no benchmarks selected for the given --groups / --sizes")
cores = os.cpu_count() or 4
workers = args.workers or min(cores, len(specs))
print(f"[*] purepycrypto benchmark: {len(specs)} tasks / {workers} workers "
f"({cores} cores)", flush=True)
print(f"[*] budget {args.budget}s x {args.repeats} repeats, "
f"sizes {[l for l, _ in sizes]}"
+ (f", groups {groups}" if groups else "") + "\n", flush=True)
t0 = time.perf_counter()
results = []
with ProcessPoolExecutor(max_workers=workers) as ex:
futs = [ex.submit(run_spec, (s, args.budget, args.repeats)) for s in specs]
for i, f in enumerate(as_completed(futs), 1):
results.append(f.result())
print(f"\r {i}/{len(specs)}", end="", flush=True)
wall = time.perf_counter() - t0
print(f"\n[*] wall clock: {wall:.2f}s\n")
report(results, wall, cores)
return 0
if __name__ == "__main__":
sys.exit(main())