crypto.pbkdf2-sha256
PBKDF2 with HMAC-SHA256 (RFC 8018): derive a key from a password and salt, slowly, fast enough for a login request.
1.0.0 · published 2026-10-03 by charlie · Anterra
Pinned by 14 tests, run in TypeScript, Python and Rust.
What it does
PBKDF2 (RFC 8018 section 5.2) with HMAC-SHA256 as its pseudorandom function: it stretches a password and a salt into a key by running HMAC `iterations` times, so that every guess an attacker makes costs the same. It is the algorithm under `auth.password-hash`, which is what an application should normally call; use this directly only to derive keys.
Bytes in and out are lists of integers 0 to 255, as everywhere in the registry (see `encoding.hex`). Encode a text password with `encoding.utf8` first.
For example
pbkdf2Sha256(112, 97, 115, 115, 119, 100, 115, 97, 108, 116, 1, 64)→ 85, 172, 4, 110, 86, 227, 8, 159, 236, 22, 145, 194, 37, 68, 182, 5, 249, 65, 133, 33, 109, 222, 4, 101, 230, 139, 157, 87, 194, 13, 172, 188, 73, 202, 156, 204, 241, 121, 182, 69… RFC 7914 section 11: "passwd" / "salt", 1 iteration, 64 bytes (two blocks)pbkdf2Sha256(80, 97, 115, 115, 119, 111, 114, 100, 78, 97, 67, 108, 80,000, 64)→ 77, 220, 216, 246, 11, 152, 190, 33, 131, 12, 238, 94, 242, 39, 1, 249, 100, 26, 68, 24, 208, 76, 4, 20, 174, 255, 8, 135, 107, 52, 171, 86, 161, 212, 37, 161, 34, 88, 51, 84, 154… RFC 7914 section 11: "Password" / "NaCl", 80,000 iterations, 64 bytespbkdf2Sha256(112, 97, 115, 115, 119, 111, 114, 100, 115, 97, 108, 116, 1, 32)→ 18, 15, 182, 207, 252, 248, 179, 44, 67, 231, 34, 82, 86, 196, 248, 55, 168, 101, 72, 201, 44, 204, 53, 72, 8, 5, 152, 124, 183, 11, 225, 123 RFC 6070's inputs with SHA-256: 1 iteration
The function
The same function in TypeScript, Python and Rust, pinned by the same tests. Pick your language; the choice follows you around the registry.
export function pbkdf2Sha256(password: readonly number[], salt: readonly number[], iterations: number, keyLength: number): readonly number[]
| password | int[] | the password's bytes (encoding.utf8 for text) |
| salt | int[] | random bytes, unique per password; at least 16 in practice |
| iterations | int | the work factor, 1 or more; see the README for a figure |
| keyLength | int | bytes of key to derive, 1 or more; 32 is one SHA-256 block |
| returns | int[] | the derived key, keyLength integers from 0 to 255 |
Your code names it in one line, in the file that uses it
import { pbkdf2Sha256 } from "#fune/crypto.pbkdf2-sha256@^1";
// PBKDF2 calls HMAC-SHA256 once per iteration, so a login at 600,000
// iterations is 1.2 million SHA-256 compressions. Two things make that
// affordable in pure code: the key's inner and outer pad blocks are the same
// every time, so their compressed states are computed once and reused (half
// the work of calling HMAC naively), and each iteration hashes a 32-byte
// value that fits one block, so the loop runs on fixed Int32Arrays with no
// allocation. That needs SHA-256's compression function itself, which the
// crypto.sha256 capability does not expose, so it is written out here.
/** FIPS 180-4 section 4.2.2. */
const K = new Int32Array([
0x428a2f98, 0x71374491, 0xb5c0fbcf, 0xe9b5dba5, 0x3956c25b, 0x59f111f1, 0x923f82a4, 0xab1c5ed5,
0xd807aa98, 0x12835b01, 0x243185be, 0x550c7dc3, 0x72be5d74, 0x80deb1fe, 0x9bdc06a7, 0xc19bf174,
0xe49b69c1, 0xefbe4786, 0x0fc19dc6, 0x240ca1cc, 0x2de92c6f, 0x4a7484aa, 0x5cb0a9dc, 0x76f988da,
0x983e5152, 0xa831c66d, 0xb00327c8, 0xbf597fc7, 0xc6e00bf3, 0xd5a79147, 0x06ca6351, 0x14292967,
0x27b70a85, 0x2e1b2138, 0x4d2c6dfc, 0x53380d13, 0x650a7354, 0x766a0abb, 0x81c2c92e, 0x92722c85,
0xa2bfe8a1, 0xa81a664b, 0xc24b8b70, 0xc76c51a3, 0xd192e819, 0xd6990624, 0xf40e3585, 0x106aa070,
0x19a4c116, 0x1e376c08, 0x2748774c, 0x34b0bcb5, 0x391c0cb3, 0x4ed8aa4a, 0x5b9cca4f, 0x682e6ff3,
0x748f82ee, 0x78a5636f, 0x84c87814, 0x8cc70208, 0x90befffa, 0xa4506ceb, 0xbef9a3f7, 0xc67178f2,
]);
const H0 = [0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19];
const W = new Int32Array(64);
/** One SHA-256 compression of the 16 words in `block` into `state`, in place. */
function compress(state: Int32Array, block: Int32Array): void {
const w = W;
for (let t = 0; t < 16; t++) w[t] = block[t];
for (let t = 16; t < 64; t++) {
const x = w[t - 15];
const y = w[t - 2];
const s0 = ((x >>> 7) | (x << 25)) ^ ((x >>> 18) | (x << 14)) ^ (x >>> 3);
const s1 = ((y >>> 17) | (y << 15)) ^ ((y >>> 19) | (y << 13)) ^ (y >>> 10);
w[t] = (w[t - 16] + s0 + w[t - 7] + s1) | 0;
}
let a = state[0], b = state[1], c = state[2], d = state[3], e = state[4], f = state[5], g = state[6], h = state[7];
for (let t = 0; t < 64; t++) {
const S1 = ((e >>> 6) | (e << 26)) ^ ((e >>> 11) | (e << 21)) ^ ((e >>> 25) | (e << 7));
const t1 = (h + S1 + ((e & f) ^ (~e & g)) + K[t] + w[t]) | 0;
const S0 = ((a >>> 2) | (a << 30)) ^ ((a >>> 13) | (a << 19)) ^ ((a >>> 22) | (a << 10));
const t2 = (S0 + ((a & b) ^ (a & c) ^ (b & c))) | 0;
h = g;
g = f;
f = e;
e = (d + t1) | 0;
d = c;
c = b;
b = a;
a = (t1 + t2) | 0;
}
state[0] = (state[0] + a) | 0;
state[1] = (state[1] + b) | 0;
state[2] = (state[2] + c) | 0;
state[3] = (state[3] + d) | 0;
state[4] = (state[4] + e) | 0;
state[5] = (state[5] + f) | 0;
state[6] = (state[6] + g) | 0;
state[7] = (state[7] + h) | 0;
}
/** SHA-256 of a whole byte string, continuing from `state` after `prefixBlocks` blocks already absorbed. */
function hashFrom(state: Int32Array, prefixBlocks: number, bytes: Uint8Array): Int32Array {
const s = new Int32Array(state);
const length = prefixBlocks * 64 + bytes.length;
const blocks = Math.floor((bytes.length + 8) / 64) + 1;
const padded = new Uint8Array(blocks * 64);
padded.set(bytes);
padded[bytes.length] = 0x80;
const bitsHigh = Math.floor(length / 0x20000000);
const bitsLow = (length * 8) >>> 0;
const end = padded.length;
padded[end - 8] = bitsHigh >>> 24;
padded[end - 7] = (bitsHigh >>> 16) & 255;
padded[end - 6] = (bitsHigh >>> 8) & 255;
padded[end - 5] = bitsHigh & 255;
padded[end - 4] = bitsLow >>> 24;
padded[end - 3] = (bitsLow >>> 16) & 255;
padded[end - 2] = (bitsLow >>> 8) & 255;
padded[end - 1] = bitsLow & 255;
const block = new Int32Array(16);
for (let i = 0; i < blocks; i++) {
for (let t = 0; t < 16; t++) {
const j = i * 64 + t * 4;
block[t] = (padded[j] << 24) | (padded[j + 1] << 16) | (padded[j + 2] << 8) | padded[j + 3];
}
compress(s, block);
}
return s;
}
function toBytes(value: readonly number[], name: string): Uint8Array {
if (!Array.isArray(value) && !(value instanceof Uint8Array)) {
throw new TypeError(`${name} must be a list of integers from 0 to 255`);
}
const out = new Uint8Array(value.length);
for (let i = 0; i < value.length; i++) {
const b = value[i];
if (typeof b !== "number" || !Number.isInteger(b) || b < 0 || b > 255) {
throw new RangeError(`${name} must be a list of integers from 0 to 255`);
}
out[i] = b;
}
return out;
}
/**
* PBKDF2-HMAC-SHA256 (RFC 8018 section 5.2): for each 32-byte block i of the
* key, U1 = HMAC(P, S || INT(i)), Uj = HMAC(P, Uj-1), and the block is the
* XOR of U1..Uc.
*/
export function pbkdf2Sha256(password: readonly number[], salt: readonly number[], iterations: number, keyLength: number): readonly number[] {
let key = toBytes(password, "password");
const saltBytes = toBytes(salt, "salt");
if (typeof iterations !== "number" || !Number.isInteger(iterations) || iterations < 1) {
throw new RangeError("iterations must be a whole number of at least 1");
}
if (typeof keyLength !== "number" || !Number.isInteger(keyLength) || keyLength < 1) {
throw new RangeError("keyLength must be a whole number of at least 1");
}
// HMAC key preparation (RFC 2104): a key longer than a block is hashed.
if (key.length > 64) {
const digest = hashFrom(new Int32Array(H0), 0, key);
key = new Uint8Array(32);
for (let i = 0; i < 8; i++) {
key[i * 4] = digest[i] >>> 24;
key[i * 4 + 1] = (digest[i] >>> 16) & 255;
key[i * 4 + 2] = (digest[i] >>> 8) & 255;
key[i * 4 + 3] = digest[i] & 255;
}
}
const padBlock = new Int32Array(16);
const innerState = new Int32Array(H0);
const outerState = new Int32Array(H0);
for (let t = 0; t < 16; t++) {
let word = 0;
for (let k = 0; k < 4; k++) {
const i = t * 4 + k;
word = (word << 8) | ((i < key.length ? key[i] : 0) ^ 0x36);
}
padBlock[t] = word;
}
compress(innerState, padBlock);
for (let t = 0; t < 16; t++) padBlock[t] ^= 0x36363636 ^ 0x5c5c5c5c;
compress(outerState, padBlock);
// A 32-byte message after a 64-byte pad block is one padded block: the
// digest words, 0x80, zeros and the length, 96 bytes = 768 bits.
const msg = new Int32Array(16);
msg[8] = 0x80000000 | 0;
msg[15] = 768;
const state = new Int32Array(8);
const u = new Int32Array(8);
const acc = new Int32Array(8);
const out: number[] = [];
const blocks = Math.ceil(keyLength / 32);
for (let blockIndex = 1; blockIndex <= blocks; blockIndex++) {
// U1 = HMAC(P, S || INT(i)), through the general path since the salt can be any length.
const first = new Uint8Array(saltBytes.length + 4);
first.set(saltBytes);
first[saltBytes.length] = blockIndex >>> 24;
first[saltBytes.length + 1] = (blockIndex >>> 16) & 255;
first[saltBytes.length + 2] = (blockIndex >>> 8) & 255;
first[saltBytes.length + 3] = blockIndex & 255;
const innerDigest = hashFrom(innerState, 1, first);
for (let t = 0; t < 8; t++) msg[t] = innerDigest[t];
state.set(outerState);
compress(state, msg);
u.set(state);
acc.set(state);
for (let j = 1; j < iterations; j++) {
for (let t = 0; t < 8; t++) msg[t] = u[t];
state.set(innerState);
compress(state, msg);
for (let t = 0; t < 8; t++) msg[t] = state[t];
state.set(outerState);
compress(state, msg);
for (let t = 0; t < 8; t++) {
u[t] = state[t];
acc[t] ^= state[t];
}
}
for (let t = 0; t < 8 && out.length < keyLength; t++) {
const word = acc[t];
const bytes = [word >>> 24, (word >>> 16) & 255, (word >>> 8) & 255, word & 255];
for (let k = 0; k < 4 && out.length < keyLength; k++) out.push(bytes[k]);
}
}
return out;
}Install
fune build
With that line in your source, in a TypeScript project (language typescript in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the TypeScript package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:
fune add crypto.pbkdf2-sha256
The manifest, vectors and README with only the TypeScript implementation. Install it without the registry with fune add ./crypto.pbkdf2-sha256-1.0.0-typescript.fune, or fetch it from a terminal with fune pull crypto.pbkdf2-sha256@1.0.0:typescript.
The whole function, every language, is one file too: crypto.pbkdf2-sha256-1.0.0.fune, 25,612 bytes, sha256 ddf20f8864a274ed88673b3d29c00fb42f617b380f0b400ef48c77bc67f193b0. It installs into a project of any language.
Customise it in your app
The seams this capability offers. Put a marker directly above a function of your own and fune build wires it into the built code; the package on the registry is not changed, the built file’s header lists it under CUSTOMISED, and fune hooks lists every hook in the project. How hooks work.
before — your function gets the arguments and returns them, changed or not, or throws to refuse the call.
// fune: before crypto.pbkdf2-sha256
after — your function gets the result and the arguments, and returns the final result.
// fune: after crypto.pbkdf2-sha256
replace — it requires no other capability, so there is no dependency to replace.
step — your function runs at a numbered point inside the function’s body, receives the in-scope values it names as parameters, and may return replacements. List the points with fune show crypto.pbkdf2-sha256 --steps.
// fune: step crypto.pbkdf2-sha256 after <n|label>
Tests
A version published now needs at least 8 tests for every function, and one that expects the error for each function that throws; the registry refuses it otherwise. fune verify --all runs each case in TypeScript, Python and Rust, and a project runs them again with fune verify. This page lists the cases; it does not run them. The exact JSON is vectors.json.
| Case | Arguments | Expected | |
|---|---|---|---|
| RFC 7914 section 11: "passwd" / "salt", 1 iteration, 64 bytes (two blocks) | 112, 97, 115, 115, 119, 100, 115, 97, 108, 116, 1, 64 | → | 85, 172, 4, 110, 86, 227, 8, 159, 236, 22, 145, 194, 37, 68, 182, 5, 249, 65, 133, 33, 109, 222, 4, 101, 230, 139, 157, 87, 194, 13, 172, 188, 73, 202, 156, 204, 241, 121, 182, 69… |
| RFC 7914 section 11: "Password" / "NaCl", 80,000 iterations, 64 bytes | 80, 97, 115, 115, 119, 111, 114, 100, 78, 97, 67, 108, 80,000, 64 | → | 77, 220, 216, 246, 11, 152, 190, 33, 131, 12, 238, 94, 242, 39, 1, 249, 100, 26, 68, 24, 208, 76, 4, 20, 174, 255, 8, 135, 107, 52, 171, 86, 161, 212, 37, 161, 34, 88, 51, 84, 154… |
| RFC 6070's inputs with SHA-256: 1 iteration | 112, 97, 115, 115, 119, 111, 114, 100, 115, 97, 108, 116, 1, 32 | → | 18, 15, 182, 207, 252, 248, 179, 44, 67, 231, 34, 82, 86, 196, 248, 55, 168, 101, 72, 201, 44, 204, 53, 72, 8, 5, 152, 124, 183, 11, 225, 123 |
| RFC 6070's inputs with SHA-256: 2 iterations | 112, 97, 115, 115, 119, 111, 114, 100, 115, 97, 108, 116, 2, 32 | → | 174, 77, 12, 149, 175, 107, 70, 211, 45, 10, 223, 249, 40, 240, 109, 208, 42, 48, 63, 142, 243, 194, 81, 223, 214, 226, 216, 90, 149, 71, 76, 67 |
| RFC 6070's inputs with SHA-256: 4096 iterations | 112, 97, 115, 115, 119, 111, 114, 100, 115, 97, 108, 116, 4,096, 32 | → | 197, 228, 120, 213, 146, 136, 200, 65, 170, 83, 13, 182, 132, 92, 76, 141, 150, 40, 147, 160, 1, 206, 78, 17, 164, 150, 56, 115, 170, 152, 19, 74 |
| RFC 6070's inputs with SHA-256: long password and salt, 40 bytes cut from two blocks | 112, 97, 115, 115, 119, 111, 114, 100, 80, 65, 83, 83, 87, 79, 82, 68, 112, 97, 115, 115, 119, 111, 114, 100, 115, 97, 108, 116, 83, 65, 76, 84, 115, 97, 108, 116, 83, 65, 76, 84,… | → | 52, 140, 137, 219, 203, 211, 43, 47, 50, 216, 20, 184, 17, 110, 132, 207, 43, 23, 52, 126, 188, 24, 0, 24, 28, 78, 42, 31, 184, 221, 83, 225, 198, 53, 81, 140, 125, 172, 71, 233 |
| RFC 6070's inputs with SHA-256: NUL bytes inside password and salt, 16 bytes | 112, 97, 115, 115, 0, 119, 111, 114, 100, 115, 97, 0, 108, 116, 4,096, 16 | → | 137, 182, 157, 5, 22, 248, 41, 137, 60, 105, 98, 38, 101, 10, 134, 135 |
| a password longer than 64 bytes is hashed first, as HMAC requires (hashlib as the reference) | 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83, 84, 85, 86, 87, 88, 89, 90, 65, 66, 67, 68, 69, 70, 71, 72, 73, 74, 75, 76, 77, 78, 79, 80, 81, 82, 83,… | → | 9, 49, 133, 24, 41, 76, 78, 138, 90, 59, 13, 19, 48, 156, 20, 90, 25, 210, 255, 202, 49, 170, 31, 31, 35, 246, 76, 127, 54, 202, 172, 146 |
| an empty password and a one-byte key (hashlib as the reference) | , 115, 97, 108, 116, 2, 1 | → | 98 |
| zero iterations | 112, 115, 0, 32 | → | error: iterations must be a whole number of at least 1 |
Show the other 4 tests
| Case | Arguments | Expected | |
|---|---|---|---|
| a fractional iteration count | 112, 115, 1.5, 32 | → | error: iterations must be a whole number of at least 1 |
| a zero-length key | 112, 115, 1, 0 | → | error: keyLength must be a whole number of at least 1 |
| a salt byte above 255 | 112, 300, 1, 32 | → | error: salt must be a list of integers from 0 to 255 |
| a password given as text rather than bytes | password, 115, 1, 32 | → | error: password must be a list of integers from 0 to 255 |
More from the author
**How many iterations.** OWASP's Password Storage Cheat Sheet recommends 600,000 for PBKDF2-HMAC-SHA256 (2023). Measured on an Apple Silicon laptop, one 32-byte key at a time:
| iterations | Python (hashlib) | Rust (release) | TypeScript (Node 24) | |-----------:|-----------------:|---------------:|---------------------:| | 100,000 | 8 ms | 48 ms | 39 ms | | 310,000 | 24 ms | 95 ms | 113 ms | | 600,000 | 47 ms | 178 ms | 222 ms |
so 600,000 is affordable in a login request in every language. Record the count with the hash (`auth.password-hash` does) so it can be raised later.
**Implementation.** Python uses the standard library's `hashlib.pbkdf2_hmac`, which runs the loop in C. TypeScript and Rust are written out with no `node:crypto` or crates; they precompute the HMAC key's inner and outer pad states once, and hash each 32-byte intermediate as a single pre-padded block, which halves the work of calling HMAC naively and allocates nothing inside the loop. That needs SHA-256's compression function itself, which `crypto.sha256` does not expose, so it is repeated here rather than required.
A password longer than 64 bytes is hashed first, as HMAC requires (RFC 2104), and the key may be longer than 32 bytes: each further 32-byte block runs the full iteration count again (RFC 8018's `T_i`), so ask for only what you use.
Empty passwords and empty salts are computed, as the RFC allows; refusing a weak salt is `auth.password-hash`'s job (it wants 16 bytes or more).
Sources: RFC 8018, PKCS #5: Password-Based Cryptography Specification Version 2.1, section 5.2 (https://www.rfc-editor.org/rfc/rfc8018); the PBKDF2-HMAC-SHA256 test vectors of RFC 7914 section 11 (https://www.rfc-editor.org/rfc/rfc7914#section-11); RFC 6070's inputs (https://www.rfc-editor.org/rfc/rfc6070) with their published SHA-256 results, each confirmed against Python's hashlib; OWASP Password Storage Cheat Sheet (https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html).
Files
| Path | Bytes |
|---|---|
| README.md | 2,634 |
| impl/python.py | 1,166 |
| impl/rust.rs | 7,251 |
| impl/typescript.ts | 7,962 |
| vectors.json | 4,123 |