Functional Weave
Code in TypeScript

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 bytes
  • pbkdf2Sha256(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[]
passwordint[]the password's bytes (encoding.utf8 for text)
saltint[]random bytes, unique per password; at least 16 in practice
iterationsintthe work factor, 1 or more; see the README for a figure
keyLengthintbytes of key to derive, 1 or more; 32 is one SHA-256 block
returnsint[]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";
impl/typescript.ts · 193 lines · open · raw
// 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
Download for TypeScript crypto.pbkdf2-sha256-1.0.0-typescript.fune · 16,908 bytes sha256 2b529e2c3d079a557c67cf4a10bcdab3e86a797c79d0e3f7a2a8952655c22adb

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.

CaseArgumentsExpected
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
CaseArgumentsExpected
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

PathBytes
README.md2,634
impl/python.py1,166
impl/rust.rs7,251
impl/typescript.ts7,962
vectors.json4,123