Skip to main content

bcrypt_rust/
core.rs

1//! The public hashing API: the raw core, the single-hash convenience
2//! functions, and the multi-lane batch entry points.
3//!
4//! One bcrypt hash is a strictly sequential chain of Blowfish key expansions,
5//! so the single-hash functions here always run the scalar kernel — SIMD
6//! never enters them. SIMD backends speed up **batch throughput only** and
7//! are reached exclusively through [`bcrypt_many`], [`hash_many`],
8//! [`hash_many_with_salts`] and [`verify_many`], which hash one password per
9//! vector lane.
10//!
11//! Key preparation matches the `bcrypt` crate and OpenBSD: the password is
12//! NUL-terminated and truncated at 72 bytes (see [`padded_key`]); the
13//! `non_truncating_*` family instead rejects passwords of 72 bytes or more
14//! with [`BcryptError::Truncation`].
15
16// `String` appears only in the random-salt API, which is `std`-gated (std
17// implies alloc). `Vec` appears in the batch API, which is `alloc`-gated.
18#[cfg(feature = "std")]
19use alloc::string::String;
20#[cfg(feature = "alloc")]
21use alloc::vec::Vec;
22
23#[cfg(feature = "alloc")]
24use crate::eks::Backend;
25use crate::encoding::{HashParts, Version};
26use crate::error::{BcryptError, BcryptResult};
27
28/// Smallest allowed cost: `2^4` expansion-loop iterations.
29pub const MIN_COST: u32 = 4;
30/// Largest allowed cost: `2^31` expansion-loop iterations.
31pub const MAX_COST: u32 = 31;
32/// The cost used when none is specified.
33///
34/// This is a convention, not a recommendation: measure and pick the largest
35/// cost your latency budget tolerates.
36pub const DEFAULT_COST: u32 = 12;
37
38/// bcrypt key preparation: the password bytes copied into a zeroed 72-byte
39/// buffer, with the key stream cycling at `min(len + 1, 72)` — i.e.
40/// NUL-terminated, truncated at 72. Only 18 words (72 bytes) are ever read
41/// from the stream, so the NUL appended to a ≥72-byte password never
42/// participates, which is exactly why a 72-byte and a 73-byte password with
43/// the same prefix hash identically.
44fn padded_key(password: &[u8]) -> ([u8; 72], usize) {
45    let mut key = [0u8; 72];
46    let copied = password.len().min(72);
47    key[..copied].copy_from_slice(&password[..copied]);
48    (key, (copied + 1).min(72))
49}
50
51/// Validate a cost *argument*. (A cost inside a hash *string* is a parse
52/// error instead — see `HashParts`' `FromStr`.)
53#[inline]
54fn check_cost(cost: u32) -> BcryptResult<()> {
55    if (MIN_COST..=MAX_COST).contains(&cost) {
56        Ok(())
57    } else {
58        Err(BcryptError::CostNotAllowed(cost))
59    }
60}
61
62/// The `non_truncating_*` gate: reject inputs bcrypt would silently cut.
63/// The payload is the key-stream length including the terminator bcrypt
64/// appends, matching the `bcrypt` crate.
65#[inline]
66fn check_truncation(password_len: usize) -> BcryptResult<()> {
67    if password_len >= 72 {
68        Err(BcryptError::Truncation(password_len + 1))
69    } else {
70        Ok(())
71    }
72}
73
74/// A fresh 16-byte salt from the OS CSPRNG.
75#[cfg(feature = "std")]
76fn random_salt() -> BcryptResult<[u8; 16]> {
77    let mut salt = [0u8; 16];
78    crate::random::os_random(&mut salt).map_err(BcryptError::Rand)?;
79    Ok(salt)
80}
81
82/// Wipe helpers: real wipes under `zeroize`, no-ops otherwise. Taking `&mut`
83/// (rather than cfg-ing out the call sites) keeps every caller's `mut`
84/// binding used in every feature configuration; the empty bodies inline away.
85#[inline(always)]
86fn wipe_key(key: &mut [u8; 72]) {
87    #[cfg(feature = "zeroize")]
88    crate::wipe::secure_wipe_bytes(key);
89    #[cfg(not(feature = "zeroize"))]
90    let _ = key;
91}
92
93/// See [`wipe_key`].
94#[inline(always)]
95fn wipe_words(words: &mut [u32]) {
96    #[cfg(feature = "zeroize")]
97    crate::wipe::secure_wipe_u32(words);
98    #[cfg(not(feature = "zeroize"))]
99    let _ = words;
100}
101
102/// See [`wipe_key`].
103#[cfg(feature = "alloc")]
104#[inline(always)]
105fn wipe_bytes(bytes: &mut [u8]) {
106    #[cfg(feature = "zeroize")]
107    crate::wipe::secure_wipe_bytes(bytes);
108    #[cfg(not(feature = "zeroize"))]
109    let _ = bytes;
110}
111
112/// Compare two 23-byte hash payloads in data-independent time.
113///
114/// This guards [`verify`]'s verdict: an early-exit `memcmp` would leak the
115/// position of the first differing byte to a timing side channel. The fold
116/// always reads all 23 bytes, and the [`black_box`](core::hint::black_box)
117/// forces the fold to actually execute — without it the compiler is entitled
118/// to prove the loop equivalent to `memcmp` and reintroduce the early exit.
119/// `#[inline(never)]` keeps the fold opaque so no caller-side specialization
120/// can do the same.
121#[inline(never)]
122#[must_use]
123pub fn constant_time_eq(a: &[u8; 23], b: &[u8; 23]) -> bool {
124    let diff = a.iter().zip(b.iter()).fold(0u8, |d, (x, y)| d | (x ^ y));
125    core::hint::black_box(diff) == 0
126}
127
128/// The raw bcrypt core: one hash of `password` with a caller-supplied salt,
129/// returning the full 24-byte ciphertext.
130///
131/// `cost` is **not validated** here — matching the `bcrypt` crate's raw
132/// function (debug builds assert it is in `4..=31`; release builds would
133/// just run). Every other entry point in this crate validates the cost up
134/// front and ends up here. The password is NUL-terminated and truncated at
135/// 72 bytes; use the `non_truncating_*` family to reject instead of
136/// truncate.
137///
138/// The string format drops the last of the 24 bytes; the hash-string APIs
139/// encode only `out[..23]`.
140#[must_use]
141pub fn bcrypt(cost: u32, salt: [u8; 16], password: &[u8]) -> [u8; 24] {
142    let (mut key, key_len) = padded_key(password);
143    // One-lane arrays, so the scalar kernel runs exactly one hash.
144    let mut key_words = [crate::eks::expand_key_words(&key, key_len)];
145    wipe_key(&mut key);
146    let salt_words = [crate::eks::salt_words(&salt)];
147    let mut out = [0u8; 24];
148    crate::eks::scalar::bcrypt_lanes(
149        cost,
150        &key_words,
151        &salt_words,
152        core::slice::from_mut(&mut out),
153    );
154    wipe_words(key_words.as_flattened_mut());
155    out
156}
157
158// ---------------------------------------------------------------------------
159// Single-hash API
160// ---------------------------------------------------------------------------
161
162/// Hash a password with a fresh random salt, returning the 60-byte `$2b$`
163/// hash string.
164///
165/// The salt comes from the OS CSPRNG (hence `std`). Like every single-hash
166/// function here, this never touches the SIMD backends: one bcrypt hash is
167/// strictly sequential, so it always runs the scalar kernel.
168///
169/// # Errors
170///
171/// [`CostNotAllowed`](BcryptError::CostNotAllowed) if `cost` is outside
172/// `4..=31`; [`Rand`](BcryptError::Rand) if the OS entropy source fails.
173#[cfg(feature = "std")]
174pub fn hash<P: AsRef<[u8]>>(password: P, cost: u32) -> BcryptResult<String> {
175    Ok(hash_with_result(password, cost)?.format_for_version(Version::TwoB))
176}
177
178/// Like [`hash`], but returns the hash string as stack bytes.
179///
180/// # Errors
181///
182/// Same as [`hash`].
183#[cfg(feature = "std")]
184pub fn hash_bytes<P: AsRef<[u8]>>(password: P, cost: u32) -> BcryptResult<[u8; 60]> {
185    Ok(hash_with_result(password, cost)?.format_bytes(Version::TwoB))
186}
187
188/// Like [`hash`], but returns the parsed parts rather than the string.
189///
190/// # Errors
191///
192/// Same as [`hash`].
193#[cfg(feature = "std")]
194pub fn hash_with_result<P: AsRef<[u8]>>(password: P, cost: u32) -> BcryptResult<HashParts> {
195    check_cost(cost)?;
196    let salt = random_salt()?;
197    hash_with_salt(password, cost, salt)
198}
199
200/// Hash a password with a caller-supplied salt — no OS entropy, no `std`,
201/// no `alloc`.
202///
203/// # Errors
204///
205/// [`CostNotAllowed`](BcryptError::CostNotAllowed) if `cost` is outside
206/// `4..=31`.
207pub fn hash_with_salt<P: AsRef<[u8]>>(
208    password: P,
209    cost: u32,
210    salt: [u8; 16],
211) -> BcryptResult<HashParts> {
212    check_cost(cost)?;
213    let out = bcrypt(cost, salt, password.as_ref());
214    let mut hash = [0u8; 23];
215    hash.copy_from_slice(&out[..23]);
216    Ok(HashParts::new(cost, salt, hash))
217}
218
219/// Like [`hash_with_salt`], but returns the 60-byte hash string as stack
220/// bytes.
221///
222/// # Errors
223///
224/// Same as [`hash_with_salt`].
225pub fn hash_with_salt_bytes<P: AsRef<[u8]>>(
226    password: P,
227    cost: u32,
228    salt: [u8; 16],
229) -> BcryptResult<[u8; 60]> {
230    Ok(hash_with_salt(password, cost, salt)?.format_bytes(Version::TwoB))
231}
232
233/// Verify `password` against a hash string, in constant time per candidate.
234///
235/// The cost and salt come from the parsed string; any of the four `$2*$`
236/// prefixes is accepted, and all compute the same algorithm (see the
237/// crate-level "Variant semantics" section). Needs neither `std` nor `alloc`.
238///
239/// # Errors
240///
241/// [`InvalidHash`](BcryptError::InvalidHash) if the string does not parse.
242pub fn verify<P: AsRef<[u8]>>(password: P, hash: &str) -> BcryptResult<bool> {
243    let parts: HashParts = hash.parse()?;
244    let out = bcrypt(parts.get_cost(), parts.get_salt_raw(), password.as_ref());
245    let mut computed = [0u8; 23];
246    computed.copy_from_slice(&out[..23]);
247    Ok(constant_time_eq(&computed, &parts.get_hash()))
248}
249
250/// [`hash`], but rejects passwords of 72 bytes or more instead of silently
251/// truncating them.
252///
253/// # Errors
254///
255/// [`Truncation`](BcryptError::Truncation) for `password.len() >= 72`;
256/// otherwise same as [`hash`].
257#[cfg(feature = "std")]
258pub fn non_truncating_hash<P: AsRef<[u8]>>(password: P, cost: u32) -> BcryptResult<String> {
259    check_truncation(password.as_ref().len())?;
260    hash(password, cost)
261}
262
263/// [`hash_bytes`], but rejects passwords of 72 bytes or more.
264///
265/// # Errors
266///
267/// [`Truncation`](BcryptError::Truncation) for `password.len() >= 72`;
268/// otherwise same as [`hash_bytes`].
269#[cfg(feature = "std")]
270pub fn non_truncating_hash_bytes<P: AsRef<[u8]>>(
271    password: P,
272    cost: u32,
273) -> BcryptResult<[u8; 60]> {
274    check_truncation(password.as_ref().len())?;
275    hash_bytes(password, cost)
276}
277
278/// [`hash_with_result`], but rejects passwords of 72 bytes or more.
279///
280/// # Errors
281///
282/// [`Truncation`](BcryptError::Truncation) for `password.len() >= 72`;
283/// otherwise same as [`hash_with_result`].
284#[cfg(feature = "std")]
285pub fn non_truncating_hash_with_result<P: AsRef<[u8]>>(
286    password: P,
287    cost: u32,
288) -> BcryptResult<HashParts> {
289    check_truncation(password.as_ref().len())?;
290    hash_with_result(password, cost)
291}
292
293/// [`hash_with_salt`], but rejects passwords of 72 bytes or more.
294///
295/// # Errors
296///
297/// [`Truncation`](BcryptError::Truncation) for `password.len() >= 72`;
298/// otherwise same as [`hash_with_salt`].
299pub fn non_truncating_hash_with_salt<P: AsRef<[u8]>>(
300    password: P,
301    cost: u32,
302    salt: [u8; 16],
303) -> BcryptResult<HashParts> {
304    check_truncation(password.as_ref().len())?;
305    hash_with_salt(password, cost, salt)
306}
307
308/// [`hash_with_salt_bytes`], but rejects passwords of 72 bytes or more.
309///
310/// # Errors
311///
312/// [`Truncation`](BcryptError::Truncation) for `password.len() >= 72`;
313/// otherwise same as [`hash_with_salt_bytes`].
314pub fn non_truncating_hash_with_salt_bytes<P: AsRef<[u8]>>(
315    password: P,
316    cost: u32,
317    salt: [u8; 16],
318) -> BcryptResult<[u8; 60]> {
319    check_truncation(password.as_ref().len())?;
320    hash_with_salt_bytes(password, cost, salt)
321}
322
323/// [`verify`], but rejects passwords of 72 bytes or more.
324///
325/// # Errors
326///
327/// [`Truncation`](BcryptError::Truncation) for `password.len() >= 72`;
328/// otherwise same as [`verify`].
329pub fn non_truncating_verify<P: AsRef<[u8]>>(password: P, hash: &str) -> BcryptResult<bool> {
330    check_truncation(password.as_ref().len())?;
331    verify(password, hash)
332}
333
334// ---------------------------------------------------------------------------
335// Batch API — the SIMD entry points
336// ---------------------------------------------------------------------------
337
338/// The dispatch point behind every batch function: routes to
339/// [`bcrypt_many_chunked`], the sequential lane-group loop — or, with the
340/// `parallel` feature and a batch of at least the `parallel_workers`
341/// threshold, to the scoped-worker split in `bcrypt_many_scoped`. Either
342/// way `outs[i]` receives item `i`'s 24-byte ciphertext: input order is
343/// preserved, and the outputs are byte-identical across both paths.
344///
345/// # Safety
346///
347/// `backend.is_available()` must hold on this CPU: the resolved kernel is a
348/// `#[target_feature]` function and there is no fallback at this level.
349/// Safe callers pass `crate::eks::backend()`, which by construction only
350/// ever names a backend this CPU advertises.
351#[cfg(feature = "alloc")]
352unsafe fn bcrypt_many_inner(
353    backend: Backend,
354    cost: u32,
355    kws: &[[u32; 18]],
356    sws: &[[u32; 4]],
357    outs: &mut [[u8; 24]],
358) {
359    debug_assert_eq!(kws.len(), sws.len());
360    debug_assert_eq!(kws.len(), outs.len());
361    if kws.is_empty() {
362        return;
363    }
364    #[cfg(feature = "parallel")]
365    {
366        let workers = parallel_workers(kws.len());
367        if workers > 1 {
368            // SAFETY: this function's contract, forwarded; the worker split
369            // writes disjoint index ranges of `outs`.
370            unsafe { bcrypt_many_scoped(backend, cost, kws, sws, outs, workers) };
371            return;
372        }
373    }
374    // SAFETY: this function's contract, forwarded unchanged.
375    unsafe { bcrypt_many_chunked(backend, cost, kws, sws, outs) };
376}
377
378/// The shared chunk loop behind every batch function: `kws[i]`/`sws[i]` are
379/// the pre-digested key and salt words of item `i`; `outs[i]` receives its
380/// 24-byte ciphertext. Preserves input order. Also the per-worker body of
381/// the `parallel` path, which hands each worker a disjoint sub-slice.
382///
383/// # Safety
384///
385/// Same contract as [`bcrypt_many_inner`].
386#[cfg(feature = "alloc")]
387unsafe fn bcrypt_many_chunked(
388    backend: Backend,
389    cost: u32,
390    kws: &[[u32; 18]],
391    sws: &[[u32; 4]],
392    outs: &mut [[u8; 24]],
393) {
394    debug_assert_eq!(kws.len(), sws.len());
395    debug_assert_eq!(kws.len(), outs.len());
396    if kws.is_empty() {
397        return;
398    }
399    // One dispatch for the whole batch: the caller picked `backend`; resolve
400    // its kernel pointer before entering the loop — nothing dispatches per
401    // chunk.
402    let kernel = crate::eks::bcrypt_lanes_fn(backend);
403    let scalar = crate::eks::bcrypt_lanes_fn(Backend::Scalar);
404    let lanes = backend.lanes();
405    // The stack arrays are sized for the widest backend that exists
406    // (AVX-512, 16 lanes), so the layout is backend-independent; only
407    // `0..lanes` is ever read by a kernel call.
408    debug_assert!(lanes <= 16);
409    let mut kw = [[0u32; 18]; 16];
410    let mut sw = [[0u32; 4]; 16];
411    let mut out = [[0u8; 24]; 16];
412    let mut base = 0;
413    while base < kws.len() {
414        let remaining = kws.len() - base;
415        // A remainder of one or two hashes runs faster on the scalar
416        // kernel than padded to a full-width group: a padded call costs
417        // `lanes x t_scalar / S`, and a backend's per-hash speedup S never
418        // exceeds its lane count, so the wide call cannot beat two
419        // sequential scalar hashes. Measured: r=1 saves 88% (Zen 4,
420        // AVX-512) and 50% (M5 Max, NEON); r=2 wins or ties everywhere.
421        // Larger remainders break even at host-dependent points (r=3 on
422        // M5 Max, r=12-13 on Zen 4 under AVX-512), so they keep lockstep.
423        if remaining <= 2 && remaining < lanes {
424            for (slot, (&kw_in, &sw_in)) in kws[base..].iter().zip(&sws[base..]).enumerate() {
425                kw[0] = kw_in;
426                sw[0] = sw_in;
427                // SAFETY: the scalar kernel runs on every CPU, the slices
428                // are exactly its one lane, and `out` is a stack array
429                // owned by this frame — nothing else aliases it here.
430                unsafe { scalar(cost, &kw[..1], &sw[..1], &mut out[..1]) };
431                outs[base + slot] = out[0];
432            }
433            wipe_words(kw.as_flattened_mut());
434            wipe_words(sw.as_flattened_mut());
435            wipe_bytes(out.as_flattened_mut());
436            break;
437        }
438        let group = lanes.min(remaining);
439        debug_assert!(group >= 1);
440        kw[..group].copy_from_slice(&kws[base..base + group]);
441        sw[..group].copy_from_slice(&sws[base..base + group]);
442        // A short tail chunk is padded by repeating this chunk's first lane:
443        // duplicate work whose outputs are discarded, so every kernel call
444        // is exactly `lanes` wide. (A tail of one or two never reaches
445        // here — it runs on the scalar kernel, above.)
446        let fill_kw = kw[0];
447        let fill_sw = sw[0];
448        for slot in &mut kw[group..lanes] {
449            *slot = fill_kw;
450        }
451        for slot in &mut sw[group..lanes] {
452            *slot = fill_sw;
453        }
454        // SAFETY: `backend` is available on this CPU (this function's
455        // contract), so this CPU supports the instruction set `kernel`
456        // targets. All three slices are exactly `lanes` long, as the kernel
457        // contract requires, and `out` is a stack array exclusively owned
458        // by this frame — nothing else aliases it for the duration of the
459        // call.
460        unsafe { kernel(cost, &kw[..lanes], &sw[..lanes], &mut out[..lanes]) };
461        outs[base..base + group].copy_from_slice(&out[..group]);
462        base += group;
463        wipe_words(kw.as_flattened_mut());
464        wipe_words(sw.as_flattened_mut());
465        wipe_bytes(out.as_flattened_mut());
466    }
467}
468
469/// Worker count for the `parallel` path: one per available core, and only
470/// when the batch gives every worker at least two items.
471///
472/// Why two items per worker: a scoped spawn+join costs tens of microseconds
473/// on every supported OS, while the cheapest legal bcrypt (cost 4) is a
474/// sub-millisecond unit of work. At one item per worker that fixed cost is a
475/// visible fraction of the work it parallelises; at two it is amortised.
476/// The threshold doubles as the guarantee that small batches run the exact
477/// same sequential loop as a build without this feature. The crossover on a
478/// given machine is what the `batch` group of `benches/bcrypt.rs` measures.
479#[cfg(feature = "parallel")]
480fn parallel_workers(items: usize) -> usize {
481    let cores = std::thread::available_parallelism().map_or(1, core::num::NonZero::get);
482    if cores > 1 && items >= 2 * cores { cores } else { 1 }
483}
484
485/// `outs`' base pointer, shared with the scoped workers of
486/// `bcrypt_many_scoped`. Workers claim whole chunks through an atomic
487/// counter, so no two workers ever write the same index; this wrapper is
488/// what lets the pointer cross the `std::thread::scope`.
489#[cfg(feature = "parallel")]
490#[derive(Copy, Clone)]
491struct OutBase(*mut [u8; 24]);
492
493// SAFETY: sound exactly as used by `bcrypt_many_scoped`: chunk claims are
494// unique (`fetch_add`), the claimed ranges are disjoint, and the scope join
495// orders every worker's writes before the caller reads `outs`.
496#[cfg(feature = "parallel")]
497unsafe impl Send for OutBase {}
498// SAFETY: same as the `Send` impl just above.
499#[cfg(feature = "parallel")]
500unsafe impl Sync for OutBase {}
501
502#[cfg(feature = "parallel")]
503impl OutBase {
504    /// The `outs[start]` pointer, for a `start` the caller claimed uniquely.
505    /// A method (rather than field access at the call site) so the scoped
506    /// closure captures this whole `Send` wrapper, not the `!Send` field.
507    ///
508    /// # Safety
509    ///
510    /// `start` must be in bounds, and no other thread may write through the
511    /// returned pointer — in `bcrypt_many_scoped` both come from the
512    /// `fetch_add` chunk claim.
513    unsafe fn at(self, start: usize) -> *mut [u8; 24] {
514        // SAFETY: in-bounds is the caller's documented promise; this only
515        // re-bases the pointer.
516        unsafe { self.0.add(start) }
517    }
518}
519
520/// The `parallel` path: split the batch into lane-aligned chunks and run
521/// [`bcrypt_many_chunked`] on each inside a [`std::thread::scope`]. Claims
522/// are dynamic (an atomic counter), so a worker the OS refuses to spawn
523/// simply means the surviving workers claim its chunks. Output is
524/// byte-identical to the sequential loop: chunking only changes *which*
525/// duplicate lane-padding work is discarded, never an item's output. Wipe
526/// behaviour is unchanged — each worker wipes its own per-group stack
527/// buffers inside the chunk loop, and the caller wipes `key_words` after
528/// the scope has joined.
529///
530/// # Safety
531///
532/// Same contract as [`bcrypt_many_inner`]; every worker forwards `backend`
533/// to the same kernel.
534#[cfg(feature = "parallel")]
535unsafe fn bcrypt_many_scoped(
536    backend: Backend,
537    cost: u32,
538    kws: &[[u32; 18]],
539    sws: &[[u32; 4]],
540    outs: &mut [[u8; 24]],
541    workers: usize,
542) {
543    use core::sync::atomic::{AtomicUsize, Ordering};
544
545    debug_assert!(workers > 1);
546    // Whole lane-groups per chunk: a chunk ending mid-group pads its tail
547    // with duplicate work (see `bcrypt_many_chunked`), so ragged boundaries
548    // would pay that padding once per worker instead of once per batch.
549    let per = kws.len().div_ceil(workers).next_multiple_of(backend.lanes());
550    let chunks = kws.len().div_ceil(per);
551
552    let base = OutBase(outs.as_mut_ptr());
553    let next = AtomicUsize::new(0);
554    let next = &next;
555
556    let run = move || loop {
557        // Relaxed: the counter only partitions work. The happens-before the
558        // *data* needs comes from `thread::scope` joining every worker.
559        let i = next.fetch_add(1, Ordering::Relaxed);
560        if i >= chunks {
561            return;
562        }
563        let start = i * per;
564        let end = (start + per).min(kws.len());
565        // SAFETY: `i` was claimed exactly once (`fetch_add`), so only this
566        // worker writes `start..end`; `start < kws.len()` because
567        // `i < chunks`.
568        let out = unsafe { core::slice::from_raw_parts_mut(base.at(start), end - start) };
569        // SAFETY: `backend` availability is this function's contract,
570        // forwarded to the chunk loop unchanged.
571        unsafe { bcrypt_many_chunked(backend, cost, &kws[start..end], &sws[start..end], out) };
572    };
573
574    std::thread::scope(|scope| {
575        for _ in 1..workers {
576            // `Builder::spawn_scoped` returns an error where `scope.spawn`
577            // panics, and this crate must not panic. A refused thread just
578            // means the remaining workers claim its chunks.
579            let _ = std::thread::Builder::new().spawn_scoped(scope, run);
580        }
581        run();
582    });
583}
584
585/// The cost and length validation shared by [`bcrypt_many`] and
586/// [`bcrypt_many_with_backend`].
587#[cfg(feature = "alloc")]
588fn check_batch(cost: u32, passwords: &[&[u8]], salts: &[[u8; 16]]) -> BcryptResult<()> {
589    check_cost(cost)?;
590    if passwords.len() != salts.len() {
591        return Err(BcryptError::BatchLengthMismatch {
592            passwords: passwords.len(),
593            salts: salts.len(),
594        });
595    }
596    Ok(())
597}
598
599/// The key/salt word digestion shared by [`bcrypt_many`] and
600/// [`bcrypt_many_with_backend`].
601#[cfg(feature = "alloc")]
602fn prep_words(passwords: &[&[u8]], salts: &[[u8; 16]]) -> (Vec<[u32; 18]>, Vec<[u32; 4]>) {
603    let mut key_words: Vec<[u32; 18]> = Vec::with_capacity(passwords.len());
604    let mut salt_words: Vec<[u32; 4]> = Vec::with_capacity(salts.len());
605    for (password, salt) in passwords.iter().zip(salts) {
606        let (mut key, key_len) = padded_key(password);
607        key_words.push(crate::eks::expand_key_words(&key, key_len));
608        wipe_key(&mut key);
609        salt_words.push(crate::eks::salt_words(salt));
610    }
611    (key_words, salt_words)
612}
613
614/// Batch-hash passwords at one cost with caller-supplied salts, returning the
615/// raw 24-byte ciphertexts in input order.
616///
617/// This is the low-level SIMD entry point: the runtime-detected backend
618/// kernel is resolved once, then the inputs are hashed in lane-width chunks.
619/// An empty input returns an empty `Vec` without touching any kernel.
620///
621/// # Errors
622///
623/// [`CostNotAllowed`](BcryptError::CostNotAllowed) if `cost` is outside
624/// `4..=31` (checked once, up front);
625/// [`BatchLengthMismatch`](BcryptError::BatchLengthMismatch) if the two
626/// slices differ in length.
627#[cfg(feature = "alloc")]
628pub fn bcrypt_many(
629    cost: u32,
630    passwords: &[&[u8]],
631    salts: &[[u8; 16]],
632) -> BcryptResult<Vec<[u8; 24]>> {
633    check_batch(cost, passwords, salts)?;
634    if passwords.is_empty() {
635        // Return before `backend()` is evaluated: on a cold process an
636        // empty batch would otherwise pay the one-time width shootout
637        // (~0.4 s on AVX-512 hosts) to hash nothing.
638        return Ok(Vec::new());
639    }
640    let (mut key_words, salt_words) = prep_words(passwords, salts);
641    let mut outs = alloc::vec![[0u8; 24]; passwords.len()];
642    // SAFETY: `crate::eks::backend()` only ever names a backend this CPU
643    // advertises, which is the whole contract `bcrypt_many_inner` asks for.
644    unsafe { bcrypt_many_inner(crate::eks::backend(), cost, &key_words, &salt_words, &mut outs) };
645    wipe_words(key_words.as_flattened_mut());
646    Ok(outs)
647}
648
649/// [`bcrypt_many`] with the backend chosen by the caller instead of the
650/// runtime cascade — the differential-testing hook behind `internal-api`.
651///
652/// Everything else (cost and length validation, key preparation, output
653/// order, empty-batch behaviour) is identical to [`bcrypt_many`].
654///
655/// # Safety
656///
657/// The caller must ensure `backend.is_available()` holds on this CPU: the
658/// resolved kernel is a `#[target_feature]` function and calling it without
659/// its instruction set is undefined behaviour (`SIGILL` in practice). Note
660/// that an off-architecture backend resolves to the scalar kernel, so on an
661/// off-arch build any backend is *sound* to pass — but that is not the
662/// contract, and on-arch it will fault.
663///
664/// # Errors
665///
666/// Same as [`bcrypt_many`].
667///
668/// # Examples
669///
670/// Check availability, then make the safety promise:
671///
672/// ```
673/// use bcrypt_rust::{Backend, BcryptResult};
674/// use bcrypt_rust::__internal::bcrypt_many_with_backend;
675///
676/// # fn run() -> BcryptResult<()> {
677/// let backend = Backend::Scalar; // always available
678/// assert!(backend.is_available());
679/// let passwords: [&[u8]; 2] = [b"alpha", b"bravo"];
680/// let salts = [[7u8; 16], [9u8; 16]];
681/// // SAFETY: `backend.is_available()` was asserted just above.
682/// let outs = unsafe { bcrypt_many_with_backend(backend, 4, &passwords, &salts)? };
683/// assert_eq!(outs.len(), 2);
684/// #     Ok(())
685/// # }
686/// # run().unwrap();
687/// ```
688///
689/// The promise is required — this does not compile:
690///
691/// ```compile_fail
692/// use bcrypt_rust::Backend;
693/// use bcrypt_rust::__internal::bcrypt_many_with_backend;
694///
695/// let passwords: [&[u8]; 1] = [b"alpha"];
696/// let salts = [[7u8; 16]];
697/// // ERROR: call to an unsafe function requires an unsafe block.
698/// let _ = bcrypt_many_with_backend(Backend::Scalar, 4, &passwords, &salts);
699/// ```
700#[cfg(all(feature = "internal-api", feature = "alloc"))]
701pub unsafe fn bcrypt_many_with_backend(
702    backend: Backend,
703    cost: u32,
704    passwords: &[&[u8]],
705    salts: &[[u8; 16]],
706) -> BcryptResult<Vec<[u8; 24]>> {
707    check_batch(cost, passwords, salts)?;
708    let (mut key_words, salt_words) = prep_words(passwords, salts);
709    let mut outs = alloc::vec![[0u8; 24]; passwords.len()];
710    // SAFETY: the caller guarantees `backend.is_available()` — this
711    // function's documented safety contract, forwarded to
712    // `bcrypt_many_inner` unchanged.
713    unsafe { bcrypt_many_inner(backend, cost, &key_words, &salt_words, &mut outs) };
714    wipe_words(key_words.as_flattened_mut());
715    Ok(outs)
716}
717
718/// [`bcrypt_many`], but returns parsed [`HashParts`] instead of raw
719/// ciphertexts.
720///
721/// # Errors
722///
723/// Same as [`bcrypt_many`].
724#[cfg(feature = "alloc")]
725pub fn hash_many_with_salts(
726    passwords: &[&[u8]],
727    salts: &[[u8; 16]],
728    cost: u32,
729) -> BcryptResult<Vec<HashParts>> {
730    let outs = bcrypt_many(cost, passwords, salts)?;
731    Ok(outs
732        .iter()
733        .zip(salts.iter())
734        .map(|(out, salt)| {
735            let mut hash = [0u8; 23];
736            hash.copy_from_slice(&out[..23]);
737            HashParts::new(cost, *salt, hash)
738        })
739        .collect())
740}
741
742/// Batch-hash passwords at one cost with fresh random salts, returning the
743/// 60-byte `$2b$` hash strings in input order.
744///
745/// One salt per password is drawn from the OS CSPRNG up front (hence `std`),
746/// then the batch runs through the SIMD path.
747///
748/// # Errors
749///
750/// [`CostNotAllowed`](BcryptError::CostNotAllowed) if `cost` is outside
751/// `4..=31`; [`Rand`](BcryptError::Rand) if the OS entropy source fails.
752#[cfg(feature = "std")]
753pub fn hash_many(passwords: &[&[u8]], cost: u32) -> BcryptResult<Vec<String>> {
754    check_cost(cost)?;
755    let mut salts: Vec<[u8; 16]> = Vec::with_capacity(passwords.len());
756    for _ in passwords {
757        salts.push(random_salt()?);
758    }
759    let parts = hash_many_with_salts(passwords, &salts, cost)?;
760    Ok(parts
761        .iter()
762        .map(|p| p.format_for_version(Version::TwoB))
763        .collect())
764}
765
766/// One [`verify_many`] work item: input position, salt, expected payload.
767#[cfg(feature = "alloc")]
768type VerifyItem = (usize, [u8; 16], [u8; 23]);
769
770/// [`verify_many`]'s grouping table: one entry per distinct cost.
771#[cfg(feature = "alloc")]
772type CostGroups = Vec<(u32, Vec<VerifyItem>)>;
773
774/// Verify a batch of password/hash-string pairs, one [`BcryptResult`] per
775/// input position.
776///
777/// Per-item failures stay per-item: a malformed hash string yields
778/// [`InvalidHash`](BcryptError::InvalidHash) at its position while the rest
779/// of the batch verifies normally. A `passwords` slice shorter than `hashes`
780/// yields [`BatchLengthMismatch`](BcryptError::BatchLengthMismatch) at the
781/// missing positions (its `salts` field carries `hashes.len()` here).
782///
783/// Surviving items are grouped by cost — a linear scan over a
784/// `Vec<(u32, …)>`: costs are `4..=31`, so at most 28 groups exist and a map
785/// would buy nothing — and each group runs through the SIMD chunk loop, so
786/// mixed-cost batches work in one call. Every verdict uses the same
787/// constant-time compare as [`verify`].
788#[cfg(feature = "alloc")]
789pub fn verify_many(passwords: &[&[u8]], hashes: &[&str]) -> Vec<BcryptResult<bool>> {
790    let mut results: Vec<BcryptResult<bool>> = Vec::with_capacity(hashes.len());
791    let mut groups: CostGroups = Vec::new();
792    for (i, hash) in hashes.iter().enumerate() {
793        if passwords.get(i).is_none() {
794            results.push(Err(BcryptError::BatchLengthMismatch {
795                passwords: passwords.len(),
796                salts: hashes.len(),
797            }));
798            continue;
799        }
800        match hash.parse::<HashParts>() {
801            Ok(parts) => {
802                let cost = parts.get_cost();
803                let pos = match groups.iter().position(|&(c, _)| c == cost) {
804                    Some(p) => p,
805                    None => {
806                        groups.push((cost, Vec::new()));
807                        groups.len() - 1
808                    }
809                };
810                groups[pos]
811                    .1
812                    .push((i, parts.get_salt_raw(), parts.get_hash()));
813                // Placeholder; every grouped index is overwritten below.
814                results.push(Ok(false));
815            }
816            Err(e) => results.push(Err(e)),
817        }
818    }
819    for (cost, items) in &groups {
820        let mut key_words: Vec<[u32; 18]> = Vec::with_capacity(items.len());
821        let mut salt_words: Vec<[u32; 4]> = Vec::with_capacity(items.len());
822        for &(i, salt, _) in items {
823            // `i` entered the group only after `passwords.get(i)` succeeded.
824            let (mut key, key_len) = padded_key(passwords[i]);
825            key_words.push(crate::eks::expand_key_words(&key, key_len));
826            wipe_key(&mut key);
827            salt_words.push(crate::eks::salt_words(&salt));
828        }
829        let mut outs = alloc::vec![[0u8; 24]; items.len()];
830        // SAFETY: same as in `bcrypt_many` — `crate::eks::backend()` only
831        // names a backend this CPU advertises.
832        unsafe { bcrypt_many_inner(crate::eks::backend(), *cost, &key_words, &salt_words, &mut outs) };
833        for (j, &(i, _, expected)) in items.iter().enumerate() {
834            let mut computed = [0u8; 23];
835            computed.copy_from_slice(&outs[j][..23]);
836            results[i] = Ok(constant_time_eq(&computed, &expected));
837        }
838        wipe_words(key_words.as_flattened_mut());
839    }
840    results
841}
842
843#[cfg(test)]
844mod tests {
845    use super::*;
846
847    #[cfg(feature = "alloc")]
848    use alloc::vec::Vec;
849
850    /// OpenBSD's vector hash of "U*U" at cost 5.
851    const VECTOR_2A: &str = "$2a$05$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW";
852
853    #[test]
854    fn padded_key_edge_cases() {
855        // Empty password: nothing copied, the stream is just the NUL.
856        let (key, len) = padded_key(b"");
857        assert_eq!(len, 1);
858        assert!(key.iter().all(|&b| b == 0));
859
860        // 71 bytes: the NUL terminator is the last byte, stream covers all.
861        let pw71 = [b'a'; 71];
862        let (key, len) = padded_key(&pw71);
863        assert_eq!(len, 72);
864        assert_eq!(&key[..71], &pw71[..]);
865        assert_eq!(key[71], 0);
866
867        // 72 bytes: the buffer is full; the NUL never participates.
868        let pw72 = [b'a'; 72];
869        let (key, len) = padded_key(&pw72);
870        assert_eq!(len, 72);
871        assert_eq!(key, pw72);
872
873        // 73 and 100 bytes: identical buffers and stream lengths to the
874        // 72-byte case.
875        for too_long in [&[b'a'; 73][..], &[b'a'; 100][..]] {
876            let (key_long, len_long) = padded_key(too_long);
877            assert_eq!(len_long, 72);
878            assert_eq!(key_long, key);
879        }
880    }
881
882    // Five cost-4 hashes; Miri interprets one in ~20 s, so this functional
883    // coverage is native-owned (padded_key itself is unit-tested above).
884    #[cfg(not(miri))]
885    #[test]
886    fn passwords_longer_than_72_bytes_hash_like_their_prefix() {
887        let salt = [0x42; 16];
888        let pw72 = [b'x'; 72];
889        let pw73 = [b'x'; 73];
890        let pw100 = [b'x'; 100];
891        assert_eq!(bcrypt(4, salt, &pw72), bcrypt(4, salt, &pw73));
892        assert_eq!(bcrypt(4, salt, &pw72), bcrypt(4, salt, &pw100));
893        // …but a difference inside the first 72 bytes changes everything.
894        let mut other = pw72;
895        other[71] = b'y';
896        assert_ne!(bcrypt(4, salt, &pw72), bcrypt(4, salt, &other));
897    }
898
899    #[test]
900    fn openbsd_vector_end_to_end() {
901        assert_eq!(verify(b"U*U", VECTOR_2A), Ok(true));
902        // Every verify hashes at cost 5 (~40 s under the interpreter):
903        // Miri runs the happy path, natives own the negatives.
904        #[cfg(not(miri))]
905        {
906            assert_eq!(verify(b"U*U*", VECTOR_2A), Ok(false));
907            assert_eq!(verify(b"", VECTOR_2A), Ok(false));
908        }
909
910        // The same vector through the hashing side, with the salt decoded
911        // out of the string.
912        let salt = crate::base64::decode_16(b"CCCCCCCCCCCCCCCCCCCCC.").expect("salt decodes");
913        let bytes = hash_with_salt_bytes(b"U*U", 5, salt).expect("valid cost");
914        assert_eq!(
915            core::str::from_utf8(&bytes).expect("ASCII"),
916            "$2b$05$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW"
917        );
918    }
919
920    // Four cost-4 hashes; native-owned (see openbsd_vector_end_to_end).
921    #[cfg(not(miri))]
922    #[test]
923    fn round_trip_and_wrong_password() {
924        let salt = [7u8; 16];
925        let bytes = hash_with_salt_bytes(b"hunter2", 4, salt).expect("valid cost");
926        let s = core::str::from_utf8(&bytes).expect("ASCII");
927        assert!(s.starts_with("$2b$04$"));
928        assert_eq!(s.len(), 60);
929        assert_eq!(verify(b"hunter2", s), Ok(true));
930        assert_eq!(verify(b"hunter3", s), Ok(false));
931        assert_eq!(verify(b"", s), Ok(false));
932    }
933
934    // Six cost-4 hashes; native-owned (see openbsd_vector_end_to_end).
935    #[cfg(not(miri))]
936    #[test]
937    fn all_version_markers_verify_the_same() {
938        let salt = [3u8; 16];
939        let parts = hash_with_salt(b"correct horse", 4, salt).expect("valid cost");
940        for version in [Version::TwoA, Version::TwoB, Version::TwoX, Version::TwoY] {
941            let bytes = parts.format_bytes(version);
942            let s = core::str::from_utf8(&bytes).expect("ASCII");
943            assert_eq!(verify(b"correct horse", s), Ok(true), "{version}");
944        }
945        assert_eq!(parts.get_cost(), 4);
946        assert_eq!(parts.get_salt_raw(), salt);
947        let raw = bcrypt(4, salt, b"correct horse");
948        assert_eq!(&parts.get_hash()[..], &raw[..23]);
949    }
950
951    #[test]
952    fn cost_arguments_are_validated() {
953        let salt = [0u8; 16];
954        assert!(check_cost(MIN_COST).is_ok());
955        assert!(check_cost(MAX_COST).is_ok());
956        for bad in [0, 3, 32, 100] {
957            assert_eq!(
958                hash_with_salt(b"pw", bad, salt),
959                Err(BcryptError::CostNotAllowed(bad))
960            );
961            assert_eq!(
962                hash_with_salt_bytes(b"pw", bad, salt),
963                Err(BcryptError::CostNotAllowed(bad))
964            );
965            assert_eq!(
966                non_truncating_hash_with_salt(b"pw", bad, salt),
967                Err(BcryptError::CostNotAllowed(bad))
968            );
969        }
970        // A bad cost inside a string is a parse error, not CostNotAllowed,
971        // and verify never computes with it.
972        assert_eq!(
973            verify(b"pw", "$2b$03$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW"),
974            Err(BcryptError::InvalidHash("cost"))
975        );
976        assert_eq!(
977            verify(b"pw", "$2b$32$CCCCCCCCCCCCCCCCCCCCC.E5YPO9kmyuRGyh0XouQYb4YMJKvyOeW"),
978            Err(BcryptError::InvalidHash("cost"))
979        );
980    }
981
982    #[test]
983    fn non_truncating_variants_reject_72_bytes_and_up() {
984        let salt = [5u8; 16];
985        #[cfg(not(miri))]
986        let pw71 = [b'a'; 71];
987        let pw72 = [b'a'; 72];
988        let pw100 = [b'a'; 100];
989
990        // The hashing asserts are native-owned (~20 s each under Miri).
991        #[cfg(not(miri))]
992        assert!(non_truncating_hash_with_salt(pw71, 4, salt).is_ok());
993        assert_eq!(
994            non_truncating_hash_with_salt(pw72, 4, salt),
995            Err(BcryptError::Truncation(73))
996        );
997        assert_eq!(
998            non_truncating_hash_with_salt(pw100, 4, salt),
999            Err(BcryptError::Truncation(101))
1000        );
1001        assert_eq!(
1002            non_truncating_hash_with_salt_bytes(pw72, 4, salt),
1003            Err(BcryptError::Truncation(73))
1004        );
1005        assert_eq!(
1006            non_truncating_verify(pw72, VECTOR_2A),
1007            Err(BcryptError::Truncation(73))
1008        );
1009        // Truncation is reported before a malformed hash is looked at.
1010        assert_eq!(
1011            non_truncating_verify(pw72, "not a hash"),
1012            Err(BcryptError::Truncation(73))
1013        );
1014
1015        // At the boundary the two families agree.
1016        #[cfg(not(miri))]
1017        {
1018            let a = hash_with_salt(pw71, 4, salt).expect("valid cost");
1019            let b = non_truncating_hash_with_salt(pw71, 4, salt).expect("71 bytes pass");
1020            assert_eq!(a, b);
1021        }
1022    }
1023
1024    #[test]
1025    fn verify_rejects_malformed_hashes() {
1026        assert_eq!(
1027            verify(b"pw", "not a hash"),
1028            Err(BcryptError::InvalidHash("length"))
1029        );
1030    }
1031
1032    #[test]
1033    fn constant_time_eq_basics() {
1034        let a = [0xABu8; 23];
1035        let mut b = a;
1036        assert!(constant_time_eq(&a, &b));
1037        b[22] ^= 1;
1038        assert!(!constant_time_eq(&a, &b));
1039        b[22] ^= 1;
1040        b[0] ^= 0x80;
1041        assert!(!constant_time_eq(&a, &b));
1042    }
1043
1044    #[cfg(feature = "alloc")]
1045    #[test]
1046    fn bcrypt_many_matches_bcrypt_for_sizes_0_to_17() {
1047        // 306 cost-4 hashes is instant natively but many minutes under an
1048        // interpreter; Miri covers the same dispatch shapes (empty, single,
1049        // multi-lane) with sizes 0..=2.
1050        let max = if cfg!(miri) { 2 } else { 17 };
1051        for n in 0..=max {
1052            let store: Vec<[u8; 8]> = (0..n)
1053                .map(|i| {
1054                    let mut a = [0xA5u8; 8];
1055                    a[0] = i as u8;
1056                    a
1057                })
1058                .collect();
1059            let pws: Vec<&[u8]> = store.iter().map(|a| &a[..]).collect();
1060            let salts: Vec<[u8; 16]> = (0..n)
1061                .map(|i| {
1062                    let mut s = [0u8; 16];
1063                    s[0] = i as u8;
1064                    s[15] = 0xFF - i as u8;
1065                    s
1066                })
1067                .collect();
1068            let batch = bcrypt_many(4, &pws, &salts).expect("valid cost");
1069            assert_eq!(batch.len(), n);
1070            for (i, ((got, &salt), &pw)) in
1071                batch.iter().zip(&salts).zip(&pws).enumerate()
1072            {
1073                assert_eq!(*got, bcrypt(4, salt, pw), "size {n} lane {i}");
1074            }
1075        }
1076    }
1077
1078    #[cfg(feature = "alloc")]
1079    #[test]
1080    fn bcrypt_many_empty_and_mismatched_inputs() {
1081        let empty_p: [&[u8]; 0] = [];
1082        let empty_s: [[u8; 16]; 0] = [];
1083        assert_eq!(bcrypt_many(4, &empty_p, &empty_s), Ok(Vec::new()));
1084        // Cost is validated before anything else, even for empty input.
1085        assert_eq!(
1086            bcrypt_many(3, &empty_p, &empty_s),
1087            Err(BcryptError::CostNotAllowed(3))
1088        );
1089        let pws: [&[u8]; 2] = [b"a", b"b"];
1090        let salts = [[0u8; 16]];
1091        assert_eq!(
1092            bcrypt_many(4, &pws, &salts),
1093            Err(BcryptError::BatchLengthMismatch {
1094                passwords: 2,
1095                salts: 1
1096            })
1097        );
1098        assert_eq!(
1099            hash_many_with_salts(&pws, &salts, 4),
1100            Err(BcryptError::BatchLengthMismatch {
1101                passwords: 2,
1102                salts: 1
1103            })
1104        );
1105    }
1106
1107    // Six cost-4 hashes; native-owned (see openbsd_vector_end_to_end).
1108    #[cfg(all(feature = "alloc", not(miri)))]
1109    #[test]
1110    fn hash_many_with_salts_round_trip() {
1111        let pws: [&[u8]; 3] = [b"alpha", b"bravo", b"charlie"];
1112        let salts = [[1u8; 16], [2u8; 16], [3u8; 16]];
1113        let parts = hash_many_with_salts(&pws, &salts, 4).expect("valid cost");
1114        assert_eq!(parts.len(), 3);
1115        for ((part, &salt), pw) in parts.iter().zip(&salts).zip(&pws) {
1116            assert_eq!(part.get_cost(), 4);
1117            assert_eq!(part.get_salt_raw(), salt);
1118            let bytes = part.format_bytes(Version::TwoB);
1119            let s = core::str::from_utf8(&bytes).expect("ASCII");
1120            assert_eq!(verify(pw, s), Ok(true));
1121        }
1122    }
1123
1124    // Nine hashes across cost 4 and 5; native-owned (see above).
1125    #[cfg(all(feature = "alloc", not(miri)))]
1126    #[test]
1127    fn verify_many_mixed_costs_with_failures() {
1128        let parts4 = hash_with_salt(b"correct horse", 4, [1u8; 16]).expect("valid cost");
1129        let parts5 = hash_with_salt(b"battery staple", 5, [2u8; 16]).expect("valid cost");
1130        let h4 = parts4.format_bytes(Version::TwoB);
1131        let h5 = parts5.format_bytes(Version::TwoA);
1132        let h4 = core::str::from_utf8(&h4).expect("ASCII");
1133        let h5 = core::str::from_utf8(&h5).expect("ASCII");
1134
1135        let pws: [&[u8]; 4] = [
1136            b"correct horse",
1137            b"battery staple",
1138            b"wrong",
1139            b"correct horse",
1140        ];
1141        let hashes: [&str; 4] = [h4, h5, h5, "not a real hash"];
1142        let results = verify_many(&pws, &hashes);
1143        assert_eq!(results.len(), 4);
1144        assert_eq!(results[0], Ok(true));
1145        assert_eq!(results[1], Ok(true), "cost-5 group in the same call");
1146        assert_eq!(results[2], Ok(false), "wrong password, right hash");
1147        assert_eq!(
1148            results[3],
1149            Err(BcryptError::InvalidHash("length")),
1150            "malformed hash stays a per-item error"
1151        );
1152
1153        // A shorter passwords slice is a per-item BatchLengthMismatch.
1154        let results = verify_many(&pws[..1], &hashes[..2]);
1155        assert_eq!(results.len(), 2);
1156        assert_eq!(results[0], Ok(true));
1157        assert_eq!(
1158            results[1],
1159            Err(BcryptError::BatchLengthMismatch {
1160                passwords: 1,
1161                salts: 2
1162            })
1163        );
1164
1165        // Empty batch: no results, no kernel.
1166        assert!(verify_many(&[], &[]).is_empty());
1167    }
1168
1169    // Seven cost-4 hashes; native-owned (see openbsd_vector_end_to_end).
1170    #[cfg(all(feature = "std", not(miri)))]
1171    #[test]
1172    fn hash_family_with_random_salts() {
1173        let h = hash(b"hunter2", 4).expect("hashing works");
1174        assert_eq!(h.len(), 60);
1175        assert!(h.starts_with("$2b$04$"));
1176        assert_eq!(verify(b"hunter2", &h), Ok(true));
1177        assert_eq!(verify(b"hunter3", &h), Ok(false));
1178
1179        let hb = hash_bytes(b"hunter2", 4).expect("hashing works");
1180        assert_eq!(verify(b"hunter2", core::str::from_utf8(&hb).expect("ASCII")), Ok(true));
1181
1182        let parts = hash_with_result(b"hunter2", 4).expect("hashing works");
1183        assert_eq!(parts.get_cost(), 4);
1184
1185        // Random salts: two hashes of one password differ.
1186        assert_ne!(hash(b"hunter2", 4).expect("hashing works"), h);
1187
1188        // Cost is still validated, and truncation still reported.
1189        assert_eq!(hash(b"pw", 3), Err(BcryptError::CostNotAllowed(3)));
1190        assert_eq!(hash_bytes(b"pw", 32), Err(BcryptError::CostNotAllowed(32)));
1191        assert_eq!(
1192            non_truncating_hash([b'a'; 72], 4),
1193            Err(BcryptError::Truncation(73))
1194        );
1195        assert_eq!(
1196            non_truncating_hash_bytes([b'a'; 72], 4),
1197            Err(BcryptError::Truncation(73))
1198        );
1199        assert_eq!(
1200            non_truncating_hash_with_result([b'a'; 72], 4),
1201            Err(BcryptError::Truncation(73))
1202        );
1203    }
1204
1205    // Six cost-4 hashes; native-owned (see openbsd_vector_end_to_end).
1206    #[cfg(all(feature = "std", not(miri)))]
1207    #[test]
1208    fn hash_many_round_trip() {
1209        let pws: [&[u8]; 3] = [b"alpha", b"bravo", b"charlie"];
1210        let hashes = hash_many(&pws, 4).expect("hashing works");
1211        assert_eq!(hashes.len(), 3);
1212        for (pw, h) in pws.iter().zip(&hashes) {
1213            assert!(h.starts_with("$2b$04$"));
1214            assert_eq!(verify(pw, h), Ok(true));
1215        }
1216        // Random salts: distinct strings for distinct passwords.
1217        assert_ne!(hashes[0], hashes[1]);
1218
1219        assert_eq!(hash_many(&pws, 3), Err(BcryptError::CostNotAllowed(3)));
1220        let empty: [&[u8]; 0] = [];
1221        assert_eq!(hash_many(&empty, 4), Ok(Vec::new()));
1222    }
1223
1224    /// The `2 x cores` threshold: below it the parallel path never engages,
1225    /// at it the worker count equals the core count.
1226    #[cfg(feature = "parallel")]
1227    #[test]
1228    fn parallel_workers_threshold() {
1229        let cores = std::thread::available_parallelism().map_or(1, core::num::NonZero::get);
1230        assert_eq!(parallel_workers(0), 1);
1231        assert_eq!(parallel_workers(2 * cores - 1), 1);
1232        // `available_parallelism` never yields 0, so `cores` is also the
1233        // expected count when the single-core host stays sequential.
1234        assert_eq!(parallel_workers(2 * cores), cores);
1235        assert_eq!(parallel_workers(1_000_000), cores);
1236    }
1237
1238    /// The parallel path must be byte-identical to hashing each item on its
1239    /// own: chunking only changes which duplicate lane-padding work is
1240    /// discarded, never an item's output. The last two sizes sit at and just
1241    /// above the `2 x cores` threshold, so the threaded path itself runs on
1242    /// any multi-core host.
1243    #[cfg(all(feature = "alloc", feature = "parallel"))]
1244    #[test]
1245    fn parallel_batch_matches_single_hashes() {
1246        let cores = std::thread::available_parallelism().map_or(1, core::num::NonZero::get);
1247        let sizes = [0usize, 1, 2, 3, 7, 8, 16, 17, 33, 64];
1248        for &n in sizes.iter().chain([2 * cores, 2 * cores + 1].iter()) {
1249            let store: Vec<Vec<u8>> = (0..n)
1250                .map(|i| alloc::vec![(i as u8).wrapping_mul(37); 4 + i % 29])
1251                .collect();
1252            let pws: Vec<&[u8]> = store.iter().map(Vec::as_slice).collect();
1253            let salts: Vec<[u8; 16]> = (0..n)
1254                .map(|i| {
1255                    let mut s = [0x5Au8; 16];
1256                    s[0] = i as u8;
1257                    s
1258                })
1259                .collect();
1260            let batch = bcrypt_many(4, &pws, &salts).expect("valid cost");
1261            assert_eq!(batch.len(), n);
1262            for (i, ((got, &salt), &pw)) in batch.iter().zip(&salts).zip(&pws).enumerate() {
1263                assert_eq!(*got, bcrypt(4, salt, pw), "size {n} lane {i}");
1264            }
1265        }
1266    }
1267}