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}