{ "classes": [ { "constants": [], "types": [], "name": "@eryx/crypto/kdf", "tags": [], "functions": [ { "source": { "path": "", "line": 50 }, "is_method": false, "signature": "kdf.hkdf_sha256(\n ikm: buffer, -- Input key material (the initial secret).\n salt: buffer?, -- Optional random salt (recommended; improves extraction).\n info: buffer?, -- Optional context string to bind the output to a purpose.\n length: number -- Number of bytes to derive (must not exceed 255 × 32 = 8160).\n) → (\n buffer -- Derived key material of the requested length. \n)", "owner": "kdf", "desc": "Derives `length` bytes of key material using HKDF-SHA256.\n\nHKDF first extracts a pseudorandom key from `ikm` and `salt`, then\nexpands it using `info` as context. Pass `nil` for `salt` to use the\ndefault all-zeros salt; pass `nil` for `info` if no context is needed.\n", "tags": [], "name": "hkdf_sha256", "return_str": "buffer", "function_type": "Function", "returns": [ { "lua_type": "buffer", "desc": "Derived key material of the requested length. " } ], "params": [ { "lua_type": "buffer", "name": "ikm", "desc": "Input key material (the initial secret)." }, { "lua_type": "buffer?", "name": "salt", "desc": "Optional random salt (recommended; improves extraction)." }, { "lua_type": "buffer?", "name": "info", "desc": "Optional context string to bind the output to a purpose." }, { "lua_type": "number", "name": "length", "desc": "Number of bytes to derive (must not exceed 255 × 32 = 8160)." } ] }, { "source": { "path": "", "line": 66 }, "is_method": false, "signature": "kdf.hkdf_sha512(\n ikm: buffer, -- Input key material.\n salt: buffer?, -- Optional random salt.\n info: buffer?, -- Optional context string.\n length: number -- Number of bytes to derive (max 16320).\n) → (\n buffer -- Derived key material. \n)", "owner": "kdf", "desc": "Derives `length` bytes of key material using HKDF-SHA512.\n\nSame semantics as [[hkdf_sha256]] but uses SHA-512 internally, raising\nthe maximum output to 255 × 64 = 16320 bytes.\n", "tags": [], "name": "hkdf_sha512", "return_str": "buffer", "function_type": "Function", "returns": [ { "lua_type": "buffer", "desc": "Derived key material. " } ], "params": [ { "lua_type": "buffer", "name": "ikm", "desc": "Input key material." }, { "lua_type": "buffer?", "name": "salt", "desc": "Optional random salt." }, { "lua_type": "buffer?", "name": "info", "desc": "Optional context string." }, { "lua_type": "number", "name": "length", "desc": "Number of bytes to derive (max 16320)." } ] }, { "source": { "path": "", "line": 85 }, "is_method": false, "signature": "kdf.pbkdf2_sha256(\n password: buffer, -- The password to derive from (as a buffer).\n salt: buffer, -- A unique random salt (at least 16 bytes recommended).\n iterations: number, -- Iteration count - higher is slower but more secure.\n length: number -- Number of output bytes to derive.\n) → (\n buffer -- Derived key material. \n)", "owner": "kdf", "desc": "Derives `length` bytes from a password using PBKDF2-HMAC-SHA256.\n\nPBKDF2 applies the HMAC in `iterations` rounds, deliberately slowing\ndown brute-force attacks. Use a unique random salt per password and\nenough iterations to make the computation take ~100 ms on your\nhardware (NIST SP 800-132 recommends ≥ 600,000 iterations with SHA-256\nas of 2023).\n", "tags": [], "name": "pbkdf2_sha256", "return_str": "buffer", "function_type": "Function", "returns": [ { "lua_type": "buffer", "desc": "Derived key material. " } ], "params": [ { "lua_type": "buffer", "name": "password", "desc": "The password to derive from (as a buffer)." }, { "lua_type": "buffer", "name": "salt", "desc": "A unique random salt (at least 16 bytes recommended)." }, { "lua_type": "number", "name": "iterations", "desc": "Iteration count - higher is slower but more secure." }, { "lua_type": "number", "name": "length", "desc": "Number of output bytes to derive." } ] }, { "source": { "path": "", "line": 102 }, "is_method": false, "signature": "kdf.pbkdf2_sha512(\n password: buffer, -- The password to derive from.\n salt: buffer, -- A unique random salt.\n iterations: number, -- Iteration count.\n length: number -- Number of output bytes to derive.\n) → (\n buffer -- Derived key material. \n)", "owner": "kdf", "desc": "Derives `length` bytes from a password using PBKDF2-HMAC-SHA512.\n\nSame semantics as [[pbkdf2_sha256]] but uses SHA-512. Equivalent\niteration counts are roughly half those of SHA-256 variants for the\nsame wall-clock time budget, since each round does more work.\n", "tags": [], "name": "pbkdf2_sha512", "return_str": "buffer", "function_type": "Function", "returns": [ { "lua_type": "buffer", "desc": "Derived key material. " } ], "params": [ { "lua_type": "buffer", "name": "password", "desc": "The password to derive from." }, { "lua_type": "buffer", "name": "salt", "desc": "A unique random salt." }, { "lua_type": "number", "name": "iterations", "desc": "Iteration count." }, { "lua_type": "number", "name": "length", "desc": "Number of output bytes to derive." } ] } ], "properties": [], "source": { "path": "", "line": 0 }, "desc": "Key Derivation Functions (KDF).\n\nDerives cryptographically strong keys from input key material (IKM)\nor passwords. Two families are provided:\n\n- **HKDF** (RFC 5869) - extract-and-expand KDF built on HMAC.\n Best for deriving multiple keys from a single high-entropy secret\n (e.g. a Diffie-Hellman shared secret).\n- **PBKDF2** (RFC 8018) - password-based KDF using iterated HMAC.\n Best for deriving keys from human-chosen passwords. Use at least\n 600,000 iterations (NIST 2023 guidance).\n\n```luau\nlocal kdf = require(\"@eryx/crypto/kdf\")\nlocal hex = require(\"@eryx/encoding/hex\")\n\n-- Derive a 32-byte AES key from a shared secret\nlocal ikm = buffer.fromstring(\"shared-secret\")\nlocal salt = buffer.fromstring(\"random-salt\")\nlocal info = buffer.fromstring(\"aes-256-key\")\nlocal key = kdf.hkdf_sha256(ikm, salt, info, 32)\n\n-- Derive a key from a password\nlocal dkey = kdf.pbkdf2_sha256(\n buffer.fromstring(\"hunter2\"),\n buffer.fromstring(\"random-salt\"),\n 600000, 32\n)\n```\n" } ] }