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) }
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>
configBcryptBatchConfigrequired

The 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.