@eryx/crypto/kdf Module

JSON

Key Derivation Functions (KDF).

Derives cryptographically strong keys from input key material (IKM) or passwords. Two families are provided:

local kdf = require("@eryx/crypto/kdf")
local hex = require("@eryx/encoding/hex")

-- Derive a 32-byte AES key from a shared secret
local ikm  = buffer.fromstring("shared-secret")
local salt = buffer.fromstring("random-salt")
local info = buffer.fromstring("aes-256-key")
local key  = kdf.hkdf_sha256(ikm, salt, info, 32)

-- Derive a key from a password
local dkey = kdf.pbkdf2_sha256(
    buffer.fromstring("hunter2"),
    buffer.fromstring("random-salt"),
    600000, 32
)

Summary

Functions

kdf.hkdf_sha256(ikm: buffer, salt: buffer?, info: buffer?, length: number) → buffer
kdf.hkdf_sha512(ikm: buffer, salt: buffer?, info: buffer?, length: number) → buffer
kdf.pbkdf2_sha256(password: buffer, salt: buffer, iterations: number, length: number) → buffer
kdf.pbkdf2_sha512(password: buffer, salt: buffer, iterations: number, length: number) → buffer

API Reference

Functions

kdf.hkdf_sha256

Derives length bytes of key material using HKDF-SHA256.

HKDF first extracts a pseudorandom key from ikm and salt, then expands it using info as context. Pass nil for salt to use the default all-zeros salt; pass nil for info if no context is needed.

kdf.hkdf_sha256(ikm: buffer, salt: buffer?, info: buffer?, length: number) → buffer

Parameters

ikm: buffer

Input key material (the initial secret).

salt: buffer?

Optional random salt (recommended; improves extraction).

info: buffer?

Optional context string to bind the output to a purpose.

length: number

Number of bytes to derive (must not exceed 255 × 32 = 8160).

Returns

buffer

Derived key material of the requested length.

kdf.hkdf_sha512

Derives length bytes of key material using HKDF-SHA512.

Same semantics as hkdf_sha256 but uses SHA-512 internally, raising the maximum output to 255 × 64 = 16320 bytes.

kdf.hkdf_sha512(ikm: buffer, salt: buffer?, info: buffer?, length: number) → buffer

Parameters

ikm: buffer

Input key material.

salt: buffer?

Optional random salt.

info: buffer?

Optional context string.

length: number

Number of bytes to derive (max 16320).

Returns

buffer

Derived key material.

kdf.pbkdf2_sha256

Derives length bytes from a password using PBKDF2-HMAC-SHA256.

PBKDF2 applies the HMAC in iterations rounds, deliberately slowing down brute-force attacks. Use a unique random salt per password and enough iterations to make the computation take ~100 ms on your hardware (NIST SP 800-132 recommends ≥ 600,000 iterations with SHA-256 as of 2023).

kdf.pbkdf2_sha256(password: buffer, salt: buffer, iterations: number, length: number) → buffer

Parameters

password: buffer

The password to derive from (as a buffer).

salt: buffer

A unique random salt (at least 16 bytes recommended).

iterations: number

Iteration count - higher is slower but more secure.

length: number

Number of output bytes to derive.

Returns

buffer

Derived key material.

kdf.pbkdf2_sha512

Derives length bytes from a password using PBKDF2-HMAC-SHA512.

Same semantics as pbkdf2_sha256 but uses SHA-512. Equivalent iteration counts are roughly half those of SHA-256 variants for the same wall-clock time budget, since each round does more work.

kdf.pbkdf2_sha512(password: buffer, salt: buffer, iterations: number, length: number) → buffer

Parameters

password: buffer

The password to derive from.

salt: buffer

A unique random salt.

iterations: number

Iteration count.

length: number

Number of output bytes to derive.

Returns

buffer

Derived key material.