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
pbkdf2_sha256(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)pbkdf2_sha256(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 bytespbkdf2_sha256(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.
pub fn pbkdf2_sha256(password: &[i64], salt: &[i64], iterations: i64, key_length: i64) -> Vec<i64>
| 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 |
| key_length | 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
fune!(crypto.pbkdf2-sha256@^1); // then call pbkdf2_sha256(…)
Imports name this capability’s declared dependencies, which fune builds next to it in your project; each one links to its page.
use super::funejson::Value; ← the fune runtime: the JSON value the test vectors use; fune build keeps it only where a signature takes one
// PBKDF2 calls HMAC-SHA256 once per iteration, so a login at 600,000
// iterations is 1.2 million SHA-256 compressions. The key's inner and outer
// pad blocks are the same every time, so their compressed states are
// computed once and reused, and each iteration hashes a 32-byte value that
// fits one block, so the loop runs on fixed arrays 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: [u32; 64] = [
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: [u32; 8] = [
0x6a09e667, 0xbb67ae85, 0x3c6ef372, 0xa54ff53a, 0x510e527f, 0x9b05688c, 0x1f83d9ab, 0x5be0cd19,
];
fn compress(state: &mut [u32; 8], block: &[u32; 16]) {
let mut w = [0u32; 64];
w[..16].copy_from_slice(block);
for t in 16..64 {
let s0 = w[t - 15].rotate_right(7) ^ w[t - 15].rotate_right(18) ^ (w[t - 15] >> 3);
let s1 = w[t - 2].rotate_right(17) ^ w[t - 2].rotate_right(19) ^ (w[t - 2] >> 10);
w[t] = w[t - 16].wrapping_add(s0).wrapping_add(w[t - 7]).wrapping_add(s1);
}
let [mut a, mut b, mut c, mut d, mut e, mut f, mut g, mut h] = *state;
for t in 0..64 {
let s1 = e.rotate_right(6) ^ e.rotate_right(11) ^ e.rotate_right(25);
let t1 = h
.wrapping_add(s1)
.wrapping_add((e & f) ^ (!e & g))
.wrapping_add(K[t])
.wrapping_add(w[t]);
let s0 = a.rotate_right(2) ^ a.rotate_right(13) ^ a.rotate_right(22);
let t2 = s0.wrapping_add((a & b) ^ (a & c) ^ (b & c));
h = g;
g = f;
f = e;
e = d.wrapping_add(t1);
d = c;
c = b;
b = a;
a = t1.wrapping_add(t2);
}
for (slot, v) in state.iter_mut().zip([a, b, c, d, e, f, g, h]) {
*slot = slot.wrapping_add(v);
}
}
/// SHA-256 of `bytes`, continuing from `state` after `prefix_blocks` blocks
/// already absorbed.
fn hash_from(state: &[u32; 8], prefix_blocks: u64, bytes: &[u8]) -> [u32; 8] {
let mut s = *state;
let bit_length = (prefix_blocks * 64 + bytes.len() as u64).wrapping_mul(8);
let mut padded = bytes.to_vec();
padded.push(0x80);
while padded.len() % 64 != 56 {
padded.push(0);
}
padded.extend_from_slice(&bit_length.to_be_bytes());
let mut block = [0u32; 16];
for chunk in padded.chunks_exact(64) {
for t in 0..16 {
block[t] = u32::from_be_bytes([chunk[t * 4], chunk[t * 4 + 1], chunk[t * 4 + 2], chunk[t * 4 + 3]]);
}
compress(&mut s, &block);
}
s
}
fn to_bytes(value: &[i64], name: &str) -> Vec<u8> {
value
.iter()
.map(|&b| {
if !(0..=255).contains(&b) {
panic!("{} must be a list of integers from 0 to 255", name);
}
b as u8
})
.collect()
}
/// 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.
///
/// # Panics
/// Panics on a value outside 0-255, fewer than 1 iteration or a key length
/// below 1.
pub fn pbkdf2_sha256(password: &[i64], salt: &[i64], iterations: i64, key_length: i64) -> Vec<i64> {
let mut key = to_bytes(password, "password");
let salt = to_bytes(salt, "salt");
if iterations < 1 {
panic!("iterations must be a whole number of at least 1");
}
if key_length < 1 {
panic!("keyLength must be a whole number of at least 1");
}
if key.len() > 64 {
key = hash_from(&H0, 0, &key).iter().flat_map(|w| w.to_be_bytes()).collect();
}
let mut pad = [0u32; 16];
for t in 0..16 {
let mut word = 0u32;
for k in 0..4 {
let i = t * 4 + k;
word = (word << 8) | u32::from(key.get(i).copied().unwrap_or(0) ^ 0x36);
}
pad[t] = word;
}
let mut inner_state = H0;
compress(&mut inner_state, &pad);
for word in pad.iter_mut() {
*word ^= 0x3636_3636 ^ 0x5c5c_5c5c;
}
let mut outer_state = H0;
compress(&mut outer_state, &pad);
// 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.
let mut msg = [0u32; 16];
msg[8] = 0x8000_0000;
msg[15] = 768;
let key_length = key_length as usize;
let mut out: Vec<i64> = Vec::with_capacity(key_length);
let blocks = (key_length + 31) / 32;
for block_index in 1..=blocks as u32 {
let mut first = salt.clone();
first.extend_from_slice(&block_index.to_be_bytes());
let inner_digest = hash_from(&inner_state, 1, &first);
msg[..8].copy_from_slice(&inner_digest);
let mut state = outer_state;
compress(&mut state, &msg);
let mut u = state;
let mut acc = state;
for _ in 1..iterations {
msg[..8].copy_from_slice(&u);
let mut s = inner_state;
compress(&mut s, &msg);
msg[..8].copy_from_slice(&s);
let mut s2 = outer_state;
compress(&mut s2, &msg);
u = s2;
for t in 0..8 {
acc[t] ^= s2[t];
}
}
for b in acc.iter().flat_map(|w| w.to_be_bytes()) {
if out.len() < key_length {
out.push(b as i64);
}
}
}
out
}
fn bytes_from_value(value: &Value, name: &str) -> Vec<i64> {
match value {
Value::Arr(items) => items
.iter()
.map(|item| match item {
Value::Int(i) => *i,
_ => panic!("{} must be a list of integers from 0 to 255", name),
})
.collect(),
_ => panic!("{} must be a list of integers from 0 to 255", name),
}
}
fn whole(value: &Value, message: &str) -> i64 {
match value {
Value::Int(i) => *i,
_ => panic!("{}", message),
}
}
pub fn fune_vector(args: &[Value]) -> Value {
let password = bytes_from_value(&args[0], "password");
let salt = bytes_from_value(&args[1], "salt");
let iterations = whole(&args[2], "iterations must be a whole number of at least 1");
let key_length = whole(&args[3], "keyLength must be a whole number of at least 1");
Value::Arr(pbkdf2_sha256(&password, &salt, iterations, key_length).into_iter().map(Value::Int).collect())
}Install
fune build
With that line in your source, in a Rust project (language rust in fune.project), fune build resolves it and nothing else, pins them in fune.lock, downloads only the Rust 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. A crate’s build.rs runs it before every compile. 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 Rust implementation. Install it without the registry with fune add ./crypto.pbkdf2-sha256-1.0.0-rust.fune, or fetch it from a terminal with fune pull crypto.pbkdf2-sha256@1.0.0:rust.
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 |