nish/crypto/bcrypt-batch
A login batcher: it queues bcrypt verifies and hashes as they arrive, sends them as bcryptVerifyN / bcryptHashN batches, and runs the batches on std/threads tasks, one per core.
import {
BcryptAnswer,
BcryptBatchConfig,
BcryptBatcher,
bcryptBatcher,
} from "nish/crypto/bcrypt-batch";
import { bcryptCalibrate } from "nish/crypto/bcrypt"
import { BcryptAnswer, BcryptBatcher, bcryptBatcher } from "nish/crypto/bcrypt-batch"
import { availableParallelism, monotonicNanos } from "nish:process"
const noHold: i64 = 0
const made = bcryptBatcher({ width: bcryptCalibrate(), holdNanos: noHold, cores: availableParallelism(), cost: 10 })
const batcher: BcryptBatcher = made.value
// In the server's loop, for each login that arrives:
const ticket: i32 = batcher.verify(password, storedHash, monotonicNanos())
// ... wait at most batcher.waitNanos(now) for the next readiness event, then:
for (const a of batcher.run(monotonicNanos())) { reply(a.ticket, a.ok) }
bcryptBatcher
A new batcher for config, or an Err naming the field out of range: a width outside 1 to 6, a negative hold, fewer than one core, or a cost outside 4 to 31.
BcryptAnswer
What a request answered, under the ticket verify or hash gave it.
BcryptBatcher
A queue of bcrypt requests and the policy that sends them: made by bcryptBatcher.
BcryptBatchConfig
How a batcher sends its work: see bcryptBatcher.
Why
How full a batch is moves the time per password by more than any instruction-set work does: on one core a full six-lane cost-10 batch takes 15.7 ms per hash and a lone hash 56.9 ms (docs/security/crypto-bcrypt.md, "Speed"). A server whose logins arrive one at a time never fills a batch by itself; this module holds them until there are enough, or until a short window has passed.
When a batch is sent
run(now) sends work when the queue holds at least
width requests, or when the oldest has waited holdNanos; a hold of 0
sends whatever is queued at every run. It takes at most width × cores
requests a run, the oldest first, and spreads them evenly over min(cores, taken) tasks, each running its share as one batch, so a run takes about one
batch's time and the event loop gets control back between runs.
Spreading rather than filling is deliberate: while a run is going nothing
else can use the free cores, and a batch of two on each of three cores ends
sooner than one of six on one. Under load the requests that arrive during a
run fill the next one, so the batches fill on their own; at light load each
request runs alone on a core, as a task per login would. waitNanos(now)
says how long the loop may sleep before a run is due.
`run` blocks
It opens a scope, runs the shares, one on the calling thread, and returns once every share has finished: about one batch, 60–95 ms of cost 10 on the core this was measured on. That is the pause the password-hashing guide describes for a scope on the event loop's thread; give the batcher a thread of its own to avoid it.
On several cores, a batcher per process
One batcher over every core
cannot start a run while one is going, so at light load a login waits for
the run in progress while cores sit idle. A prefork server with one process
a core, each with a batcher of cores: 1, overlaps the processes' runs:
measured, it matched a plain process per core at light load and one
batcher over every core under load (docs/security/crypto-bcrypt.md, "One
batcher per process").
The batcher keeps its own copy of each password
verify and hash
borrow the caller's Secret<u8[]>, as any function taking one does: they
copy it, inside exposeWith, into a holder of the batcher's own (a class
with one readonly Secret field), and the caller wipes its password as
it would after bcryptVerify. run calls each copy's wipe() on the
calling thread once the scope that read it has joined, so no task can
still be reading it. A request that never runs (a batcher dropped with
requests queued) is not wiped: call run until pending() is 0 before
dropping one. The tasks call only bcryptVerifyN, bcryptHashN and
bcryptVerify, which wipe everything they make
(docs/security/crypto-bcrypt.md, BCRYPT-9, BCRYPT-11).
Every request gets its own answer
A verify against a hash string that
is not one makes bcryptVerifyN an Err for the whole batch; the share
then verifies each of that batch's lanes alone, so only the damaged row
answers the Err and the rest answer as they would have. A hash whose
salt is not 16 bytes is answered with its Err at the next run, without
being batched. A run does not answer in arrival order: bad-salt answers
come first, then verifies grouped by cost, then hashes, so match answers to
requests by ticket.
Names carry the bcryptBatch prefix because a std/ module's private
functions share the importing program's flat symbol namespace
(docs/wp26-stdlib.md §3e).
Functions
bcryptBatcher
A new batcher for config, or an Err naming the field out of range: a
width outside 1 to 6, a negative hold, fewer than one core, or a cost
outside 4 to 31.
const bcryptBatcher: (
config: BcryptBatchConfig,
) => Result<BcryptBatcher, string>
configBcryptBatchConfigrequiredThe policy: width, hold, cores and cost.
returnsResult<BcryptBatcher, string>A new, empty batcher, or an Err naming the field out of range.
Classes
BcryptAnswer
What a request answered, under the ticket verify or hash gave it.
class BcryptAnswer
| Member | |
|---|---|
new BcryptAnswer(ticket: i32, ok: boolean, hash: string, error: string) |
Holds one answer as given; run makes these. |
error: string |
"" unless the request is an Err, as bcryptVerify or bcryptHash words it. |
hash: string |
A hash request's $2b$ hash; "" for a verify and for an error. |
ok: boolean |
A verify: whether the password is the hash's. A hash: whether it was made. False with an error. |
ticket: i32 |
The ticket of the request. |
BcryptBatcher
A queue of bcrypt requests and the policy that sends them: made by
bcryptBatcher. verify and hash queue, run sends and answers,
waitNanos says when the next run is due.
class BcryptBatcher
| Member | |
|---|---|
new BcryptBatcher(config: BcryptBatchConfig) |
Takes config as it is and starts an empty queue. bcryptBatcher checks the config first; make batchers with it. |
hash(password: Secret<u8[]>, salt: u8[], now: i64): i32 |
Queues a new hash of password under salt (16 bytes, fresh from crypto.getRandomValues) at the batcher's cost, which arrived at now, and answers its ticket. The batcher queues a copy of password and wipes the copy once the hash is made; a salt of another length is answered with its Err by the next run, and no copy is made. |
pending(): i32 |
How many requests are queued or answered and not yet handed out by run. |
run(now: i64): BcryptAnswer[] |
Sends what is due and answers it: nothing (bar answers made without a batch) until waitNanos(now) is 0, then up to width × cores of the oldest requests, spread evenly over up to cores tasks, each running its share as batches of up to width. Returns once every task has finished, with the copy of each password it ran wiped. |
verify(password: Secret<u8[]>, hash: string, now: i64): i32 |
Queues a verify of password against hash, which arrived at now (monotonicNanos()), and answers its ticket. The batcher queues a copy of password and wipes the copy once the verify has run; the caller wipes its own. |
waitNanos(now: i64): i64 |
Nanoseconds from now until a run is due: 0 when it is due now (a full batch is queued, the oldest request has waited holdNanos, or an answer is waiting), -1 when nothing is queued. |
Interfaces
BcryptBatchConfig
How a batcher sends its work: see bcryptBatcher.
interface BcryptBatchConfig
| Member | |
|---|---|
cores: i32 |
How many tasks a run may use, at least 1: availableParallelism(). |
cost: i32 |
The cost hash requests are made at, 4 to 31. Verifies take theirs from the hash. |
holdNanos: i64 |
How long the oldest request may wait for a batch to fill, in nanoseconds; 0 never waits. |
width: i32 |
Lanes per batch, 1 to 6: bcryptCalibrate()'s answer. |

