bcrypt-rust 1.0.2

Pure-Rust bcrypt with runtime-dispatched SIMD backends for batch hashing
Documentation
# bcrypt-rust

[![CI](https://github.com/Brooooooklyn/bcrypt-rust/actions/workflows/ci.yml/badge.svg)](https://github.com/Brooooooklyn/bcrypt-rust/actions/workflows/ci.yml)

Pure-Rust [bcrypt](https://www.usenix.org/legacy/events/usenix99/provos/provos.pdf)
(Provos & Mazières, USENIX 1999) with runtime-dispatched SIMD backends for
**batch** hashing. **Zero dependencies**, `#![no_std]`-capable, MSRV 1.89.

Wire-compatible with every implementation that speaks the `$2*$` hash-string
format (`$2v$cc$<22-char salt><31-char hash>`, exactly 60 ASCII bytes), and
API-compatible with the [`bcrypt`](https://crates.io/crates/bcrypt) crate
(0.19): same names, same semantics, same `BcryptError` variant set.

## Security and audit status

This crate implements security-sensitive cryptographic code and has **not**
received an independent third-party audit. Its defense-in-depth is the
verification suite described below. See [SECURITY.md](SECURITY.md) for the
support policy and how to report a vulnerability privately.

## What SIMD does — and does not — do here

bcrypt's cost loop is strictly sequential: **one hash cannot be
parallelized**. The SIMD backends therefore speed up **batch throughput
only**, by interleaving N *independent* hashes in lockstep, one per vector
lane. Single-hash latency is unchanged — `hash` / `verify` always run the
scalar kernel.

The one other data-parallel step, the base64 codec, is vectorized too:
NEON on aarch64, an AVX2/SSSE3 runtime pick on x86-64, v128 under wasm
simd128, scalar tables elsewhere — every path byte-exact against the
scalar reference, with the decode reject set pinned exhaustively in tests.
Measured codec cost is ~20 ns against a 163 µs cost-4 hash (0.012%), so
this is completeness of the SIMD story, not a throughput claim;
`benches/base64.rs` is its regression net.

## Performance

Measured via `benches/micro.rs` (correctness-gated: every timed iteration's
output is asserted byte-identical to the scalar batch, so a divergent kernel
aborts instead of posting a fast-but-wrong number).

**Apple M5 Max** (aarch64), rustc 1.98.0, cost 5:

| backend | lanes | batch | hashes/s | vs scalar |
|---|---|---|---|---|
| scalar | 1 | 16 | 790.4 | 1.00 |
| NEON | 8 | 8 | 3193.1 | **4.04×** |
| NEON | 8 | 16 | 3187.1 | 4.03× |
| NEON | 8 | 32 | 3167.5 | 4.00× |
| wasm128 (under wasmtime 48, cost 4) | 8 | 8 | 2006.8 | 1.56× |

The NEON backend is an 8-lane scalar-GPR interleave (John the Ripper's
design: vector registers appear only at pack/unpack; the name is
historical). It replaced a 4-lane vector kernel after measurement
(2.78× → 4.03×). The wasm128 backend likewise runs two interleaved
4-lane states (1.21× → 1.56×).

**AMD EPYC Zen 4** (x86_64, Cloudflare sandbox, 4 vCPU), rustc 1.99.0, cost 5,
batch 16 (ranges span the ±10% drift between sandbox windows):

| backend | lanes | hashes/s | vs scalar |
|---|---|---|---|
| scalar | 1 | 568.8 | 1.00 |
| SSE4.1 | 4 | 631.4 | 1.11× |
| AVX2 | 8 | 896.8–950.2 | **1.58–1.67×** |
| AVX-512 | 16 | 883.9–932.5 | 1.55–1.64× |

AVX2 and AVX-512 sit at parity on Zen 4 (the width shootout picked AVX2 in
this window): AVX-512's SoA S-boxes are 64 KiB against Zen 4's 32 KiB L1d,
and Zen 4 double-pumps 512-bit ops anyway. On Sapphire Rapids — the one
µarch with a fast zmm gather (6 cycles) — the wide kernel pulls ahead, so
runtime dispatch answers the width question by measurement (one-time
shootout; see "Dispatch notes"). Both x86-64 backends also shoot out three
S-box lookup flavors (gather/insert/extract) per process the same way;
prescaled byte offsets plus an opaque-asm blocker that stops LLVM from
re-forming microcoded gathers took the AVX-512 path from 383 h/s to
parity.

A 12-lane AVX2 kernel (`avx2_12`) targets 48 KiB-L1d chips (Zen 5, Ice
Lake+, and AVX2-only 48 KiB parts — Alder/Raptor Lake client, Xeon
E-2400): it joins the width shootout only when cpuid reports L1d ≥ 48
KiB, and only when it wins outright. Our lab has no such hardware, so no
win is claimed — forced on Zen 4 it measures 0.76× (48 KiB thrashing a
32 KiB L1d), which is exactly why the gate exists.

Single-hash latency, cost 4: **646 µs** (criterion, M5 Max). Throughput
scales with `2^cost`, so cost 12 runs 128× slower per hash than cost 5.

### vs the `bcrypt` crate (0.19.3)

Same machine runs of `benches/vs_bcrypt.rs` (criterion; the sanity gate
asserts both crates produce byte-identical strings before timing). The
incumbent has no batch API, so its batch arm is the sequential `hash` loop —
the pattern real callers use today.

**Apple M5 Max:**

| workload | `bcrypt` | `bcrypt-rust` | speedup |
|---|---|---|---|
| single hash, cost 4 | 741 µs | 662 µs | 1.12× |
| single hash, cost 12 | 174.7 ms | 161.2 ms | 1.08× |
| batch 16, cost 4 | 1417 h/s | 6118 h/s | **4.32×** |
| batch 16, cost 12 | 5.79 h/s | 25.13 h/s | **4.34×** |
| verify, cost 4 | 718 µs | 666 µs | 1.08× |

**AMD EPYC Zen 4, 4 vCPU** (batch arms re-measured after the x86 work;
±10% sandbox drift applies):

| workload | `bcrypt` | `bcrypt-rust` | speedup |
|---|---|---|---|
| single hash, cost 4 | 972 µs | 899 µs | 1.08× |
| single hash, cost 12 | 239.4 ms | 240.2 ms | 1.00× |
| batch 16, cost 4 | 897 h/s | 1737 h/s | **1.94×** |
| batch 16, cost 12 | 3.69 h/s | 7.27 h/s | **1.97×** |
| verify, cost 4 | 977 µs | 998 µs | 0.98× |

### `parallel` feature (batch 64, cost 5)

**Apple M5 Max** (18 cores, medians of 4 runs):

| configuration | hashes/s | vs 1-core scalar |
|---|---|---|
| scalar | 768.7 | 1.00 |
| NEON | 2966.4 | 3.86× |
| scalar + `parallel` | 7402.2 | 9.63× |
| NEON + `parallel` | 15543.4 | **20.22×** |

**AMD EPYC Zen 4** (4 vCPU):

| configuration | hashes/s | vs 1-core scalar |
|---|---|---|
| scalar | 565.5 | 1.00 |
| AVX2 | 910.6 | 1.61× |
| scalar + `parallel` | 1896.0 | 3.35× |
| AVX2 + `parallel` | 2753.2 | **4.87×** |

Chunks are lane-group-aligned, so on AVX-512 the parallel split engages only
when each worker gets at least one full 16-lane group (`items ≥ cores × 16`);
a batch of 16 on 4 cores stays single-worker by design. John the Ripper's
bcrypt data shows SMT siblings add +20–40% for this latency-bound loop, and
`available_parallelism` counts logical CPUs, so on SMT hosts the split
already engages siblings.

### Per-backend verification status

| backend | lanes | targets | execution evidence |
|---|---|---|---|
| scalar | 1 | all | everywhere; the reference every other backend is checked against |
| NEON | 8 | aarch64 | native: full suite + the measurements above (M5 Max) |
| SSE4.1 | 4 | x86, x86_64 | full suite under Rosetta 2 **and** under QEMU TCG (Debian 12, real cpuid) |
| AVX2 | 8 | x86_64 | full suite under Rosetta 2 (`+avx2`) and QEMU TCG; the gather/insert/extract shootout asserts all three lookup flavors byte-identical before timing |
| AVX2×12 | 12 | x86_64 | forced-run full suite (`BCRYPT_REQUIRE_BACKEND=avx2_12`, byte-exact vs scalar and crypt_blowfish) under Rosetta 2 and on the Zen 4 sandbox; self-selects only on 48 KiB-L1d µarchs (Zen 5, Ice Lake+) — no lab hardware, no perf claim |
| AVX-512 | 16 | x86_64 | full suite on real Zen 4 hardware (Cloudflare sandbox) with `BCRYPT_REQUIRE_BACKEND=avx512` — byte-exact vs scalar, every other backend, and crypt_blowfish C; CI **requires** it on any runner advertising `avx512f` (macOS cannot execute it locally: Rosetta SIGILLs, QEMU TCG has no AVX-512 emulation) |
| wasm128 | 8 | wasm32 | full suite + micro bench under wasmtime (`+simd128`), scalar-fallback leg without it |

### Dispatch notes

Which width wins is a µarch question (working-set and
double-pump reasons above on Zen; the fast zmm hardware gather on Sapphire
Rapids), so `detect()` answers it by measurement: on `std` release builds,
a host with at least two width candidates (AVX2 + AVX-512, or AVX2 with
L1d ≥ 48 KiB) runs a one-time width shootout — a cost-4, 48-item batch
through every candidate's kernel, outputs asserted byte-identical before
anything is timed, three interleaved reps each, min wins, strict-win only
(ties keep the wider incumbent). The pick is single-flight (`OnceLock`):
racing cold callers park instead of duplicating the ~0.4 s measurement.
Debug, `no_std` and Miri builds keep the static capability order. To
override the pick entirely, set `BCRYPT_FORCE_BACKEND=<name>` (std builds;
panics on an unknown or unavailable name — intended for simulators and
benchmark harnesses), or drive kernels explicitly through
`__internal::bcrypt_many_with_backend` (`internal-api` feature), as
`benches/micro.rs` does.

## Quick start

```rust
// Cost 4 keeps the example fast; use DEFAULT_COST (12) or higher in real code.
let hash = bcrypt_rust::hash(b"hunter2", 4)?;
assert_eq!(hash.len(), 60);
assert!(bcrypt_rust::verify(b"hunter2", &hash)?);
assert!(!bcrypt_rust::verify(b"hunter3", &hash)?);
```

Batch hashing (where the SIMD backends engage):

```rust
let passwords: [&[u8]; 3] = [b"alpha", b"bravo", b"charlie"];
let hashes = bcrypt_rust::hash_many(&passwords, 4)?;
for (password, hash) in passwords.iter().zip(&hashes) {
    assert!(bcrypt_rust::verify(password, hash)?);
}
```

## How the dispatch works

```
bcrypt_many / hash_many / hash_many_with_salts / verify_many
                    │
                    ▼
              detect()            cached in an AtomicU8; #[cold] probe
                    │
      ┌─────────────┼──────────────────────────────┐
      ▼             ▼                              ▼
 runtime cpuid   compile-time cfg               scalar
 (std builds)    (no_std / miri)                (fallback)
      │
      ▼
 avx512 ×16 ─ avx2 ×8 ─ sse41 ×4 ─ neon ×8 ─ wasm128 ×8 ─ scalar ×1
              (avx2_12 ×12 — measured-shootout arm only, 48 KiB-L1d hosts)
      │
      ▼
 batch split into lane groups; tails of 1-2 hashes run scalar (measured
 win everywhere), larger short groups padded, padding discarded
      │
      ▼
 per-item outputs — byte-identical on every backend (asserted in tests)
```

With the `parallel` feature, large batches (≥ 2 × available cores) are
additionally split across `std::thread::scope` workers on lane-group
boundaries — output stays byte-identical to the sequential loop.

## Feature flags

| feature | default | what it gates |
|---|---|---|
| `std` | ✓ | runtime CPU detection; OS-entropy salts for `hash`, `hash_many`, … |
| `alloc` | via `std` | `String`/`Vec` APIs: `bcrypt_many`, `hash_many_with_salts`, `verify_many`, `HashParts::format_for_version` |
| `zeroize` | ✓ | wipe internal buffers that held key material so `-O3` cannot elide it |
| `parallel` | — | thread-scoped batch splitting; throughput knob for large batches only |
| `internal-api` | — | exposes `__internal` for this crate's tests/benches; not stable |

With `alloc` but no `std`, everything works except the random-salt
conveniences and runtime detection (compile-time `target_feature` cfgs, then
scalar). With neither, the byte-oriented core (`bcrypt`, `hash_with_salt`,
`verify`, `HashParts` parsing/formatting) is fully functional.

## Semantics and compatibility

* Key preparation: password is NUL-appended then truncated at 72 bytes
  (`min(len + 1, 72)` key schedule bytes) — the OpenBSD/`bcrypt`-crate
  semantics.
* All four `$2a$`/`$2b$/`$2x$`/`$2y$` prefixes are accepted on parse and
  hashed with `$2b$` (correct-algorithm) semantics; `$2b$` is emitted on
  format.
* Two crypt_blowfish bug-compatibilities are deliberately **not** reproduced:
  the `$2x$` sign-extension bug and the `$2a$` 8-bit "safety XOR". The pinned
  rows, including the three survey rows reclassified against the vendored C
  source, live in `tests/vectors.rs`.

## Verification

* **Authoritative vectors** — 61 rows transcribed from jBCrypt, Openwall
  `wrapper.c`, the `bcrypt` crate, and pyca/bcrypt, plus divergent rows with
  per-row `must_verify` expectations (`tests/vectors.rs`).
* **Cross-backend differential** — every backend on the host must produce
  byte-identical output to scalar across lane-boundary batch sizes
  (0–33), costs 4–6, and the 71/72/73 password boundary
  (`tests/backends.rs`). `BCRYPT_REQUIRE_BACKEND=<name>` turns a skip into a
  failure for CI.
* **Differential vs reference C** — 360 seeded cases compared against the
  real `crypt_rn` of the vendored [crypt_blowfish]https://www.openwall.com/crypt/
  1.3 (public domain), replayed through every available backend, including
  accept/reject parity on malformed settings (`tests/differential.rs`).
* **Fuzzing** — two `cargo-fuzz` targets: `decode` (the `$2*$` parser must
  never panic) and `tiny_hash` (cost validation + the whole pipeline at
  fuzzer-derived tiny parameters).
* **CI** — Linux/macOS/Windows, no-std check, docs, MSRV 1.89, Miri,
  ASAN/LSAN, wasm (simd128 + scalar fallback), entropy-target matrix,
  old-glibc, bench-compile, and a 5-minute fuzz leg per target.

## Reproducing the benchmarks

```console
# correctness-gated micro harness, per-backend, prints hashes/s and ratio
cargo bench --bench micro -- --backend all --batch 16 --cost 5 --iters 100 --vs-scalar

# criterion suite (single-hash latency, per-backend batch, verify)
cargo bench --bench bcrypt

# the CI regression net (CodSpeed)
cargo bench --bench codspeed

# wasm, under wasmtime
RUSTFLAGS="-C target-feature=+simd128" cargo test --release --target wasm32-wasip1
RUSTFLAGS="-C target-feature=+simd128" cargo bench --target wasm32-wasip1 --bench micro -- --backend all --batch 8 --cost 4 --iters 50 --vs-scalar
```

## MSRV

Rust **1.89**, pinned by exactly one thing: `stdarch_x86_avx512` (the AVX-512
intrinsics and the `avx512f` target feature) stabilized there. The CI `msrv`
job enforces it; raise it only with a reason.

## License

MIT. The `crypt_blowfish/` directory contains Openwall's crypt_blowfish 1.3
(public domain), vendored for differential testing only — it is never linked
into the crate.