HKDF Key Derivation

Category: Key Derivation · Node Type ID: kdf-hkdf

HMAC-based Extract-and-Expand Key Derivation (RFC 5869)

Overview

Derives cryptographically strong Output Keying Material (OKM) from high-entropy Input Keying Material (IKM) using the two-stage HKDF (HMAC-based Extract-and-Expand Key Derivation Function, RFC 5869 / NIST SP 800-56C) with SHA-256, SHA-384, or SHA-512.

Stage 1 (HKDF-Extract) concentrates entropy from IKM and the optional Salt into a fixed-length pseudorandom key ($PRK$). Stage 2 (HKDF-Expand) expands $PRK$ and the optional Info / Context string into the requested number of output bytes. Note that HKDF is designed for high-entropy secrets (such as Diffie-Hellman or KEM shared secrets), not low-entropy human passwords (use PBKDF2 for passwords).

When to Use

Converting raw shared secrets produced by ECDH Key Agreement, X25519 Key Exchange, ML-KEM, or Hybrid KEM into uniform symmetric keys and IVs.
Deriving multiple domain-separated subkeys from a single master secret by passing distinct Info / Context labels (e.g., "enc-key" vs. "mac-key").

Parameter Configuration

Parameter (ID)	Type & Default	Visibility Condition	Description & Options
Output Length (bytes) `keyLength`	`number` Default: `32` Supports Variable Reference (`$var`: `int`)	Always visible	Desired Output Keying Material (`OKM`) length in bytes (clamped to `1..255 * HashLen`, up to `1024`; default `32`).
Hash Algorithm `hashAlgorithm`	`select` Default: `SHA-256`	Always visible	HMAC hash function used for both Extract and Expand stages (`SHA-256`, `SHA-384`, or `SHA-512`). `SHA-256`: SHA-256 `SHA-512`: SHA-512

Port I/O Specification

See Ports & Connections for general wiring rules, data type colors, and dynamic port creation.

Input Ports

Port Nature: Fixed Input Ports (3 total).

Port Name	Port ID	Data Type	Required	Visibility Condition	Description
`Input Keying Material`	`ikm`	`Bytes`	Required	Always visible	Input Keying Material (`Uint8Array`; must be at least 1 byte), such as a Diffie-Hellman or KEM shared secret.
`Salt`	`salt`	`Bytes`	Optional	Always visible	Optional non-secret salt (`Uint8Array`). If unconnected, RFC 5869 defaults to a hash-length string of zero bytes.
`Context Info`	`info`	`Bytes`	Optional	Always visible	Optional protocol context and application-specific information bytes (`Uint8Array`) used to bind the derived key to a specific purpose. Defaults to 0 bytes if unconnected.

Output Ports

Port Nature: Fixed Output Ports (1 total).

Port Name	Port ID	Data Type	Visibility Condition	Description
`Output Key`	`okm`	`Bytes` (OKM)	Always visible	Derived Output Keying Material (`Uint8Array`) of `Output Length` bytes.

Error Cases

When any of the following conditions occurs at runtime, this node transitions to an ERROR state and downstream nodes connected to its outputs do not execute.

Error Code	Default Engine Message	Trigger Condition
`INVALID_KDF_PARAMS`	Invalid KDF parameters	Raised when the KDF input secret/password is empty or the requested output length/iterations are outside the valid range.

Examples

Deriving an AES-256 Key from an X25519 Shared Secret

Pass the raw 32-byte X25519 shared secret through HKDF-SHA256 with a domain-separation label.

Connect the Shared Secret output of X25519 Key Exchange to IKM (Input Key).
Connect "session-aes-key" (via String to Bytes) to Info / Context, set Output Length to 32, and connect OKM to AES Encrypt.