ECDH Key Agreement

Category: Asymmetric & Elliptic Curve · Node Type ID: asymmetric-ecc-ecdh

Computes Elliptic Curve Diffie-Hellman shared secret on Weierstrass curves (NIST SP 800-56A / RFC 5903)

Overview

Computes an Elliptic Curve Diffie-Hellman (ECDH, NIST SP 800-56A / RFC 5903) shared secret by multiplying the local party's private scalar ($d_A$) with the peer's public point ($Q_B$) on the selected Weierstrass curve ($P = d_A \cdot Q_B = (x_P, y_P)$).

The node provides two output ports: Shared Secret formatted according to Output Secret Format (Raw X-Coordinate, SHA-256 KDF, Compressed Point, or Uncompressed Point) and Raw Secret X, which always emits the raw big-endian $x_P$ coordinate per NIST SP 800-56A for feeding into HKDF.

When to Use

Establishing a shared secret between two keypairs generated on the same Weierstrass curve (P-256, P-384, P-521, secp256k1, or brainpool).
Deriving symmetric session keys by feeding Raw Secret X or Shared Secret into HKDF Key Derivation.

Parameter Configuration

Parameter (ID)	Type & Default	Visibility Condition	Description & Options
Elliptic Curve `curve`	`select` Default: `p256`	Always visible	Elliptic curve on which both `My Private Key` and `Peer Public Key` reside. `secp256k1`: secp256k1 (Bitcoin / Ethereum) `p256`: NIST P-256 (secp256r1 / prime256v1) `p384`: NIST P-384 (secp384r1) `p521`: NIST P-521 (secp521r1) `brainpoolP256r1`: Brainpool P256r1 (RFC 5639) `brainpoolP384r1`: Brainpool P384r1 (RFC 5639) `brainpoolP512r1`: Brainpool P512r1 (RFC 5639)
Output Secret Format `format`	`select` Default: `raw_x`	Always visible	Format of the primary `Shared Secret` output port: `raw_x` (NIST SP 800-56A raw X coordinate), `sha256_kdf` ($\text{SHA-256}(x_P)$, always 32 bytes), `compressed` ($0x02/0x03 \parallel x_P$), or `uncompressed` ($0x04 \parallel x_P \parallel y_P$). `raw_x`: Raw X-Coordinate (NIST SP 800-56A Standard) `sha256_kdf`: SHA-256 KDF (32-byte Symmetric Key) `compressed`: Compressed Point (02/03 + X) `uncompressed`: Uncompressed Point (04 + X + Y)

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 (2 total).

Port Name	Port ID	Data Type	Required	Visibility Condition	Description
`My Private Key`	`privateKey`	`Bytes`	Required	Always visible	Local party's private scalar bytes on the selected curve.
`Peer Public Key`	`peerPublicKey`	`Bytes`	Required	Always visible	Remote peer's public key point on the same curve (validates that the point lies on the curve).

Output Ports

Port Nature: Fixed Output Ports (2 total).

Port Name	Port ID	Data Type	Visibility Condition	Description
`Shared Secret`	`sharedSecret`	`Bytes`	Always visible	Computed ECDH shared secret formatted according to Output Secret Format.
`Raw Secret X`	`rawSecretX`	`Bytes` (32B)	Always visible	Raw big-endian X-coordinate ($x_P$) of the shared curve point before any KDF (32B on 256-bit curves, 48B on 384-bit curves, 66B on P-521).

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_KEY_MATERIAL`	Invalid key length or format	Raised when `My Private Key` is out of range or `Peer Public Key` is not a valid point on the selected curve (prevents invalid-curve attacks).

Examples

Two-Party P-256 ECDH Key Agreement

Verify that Alice and Bob derive the exact same shared secret.

Place two ECC KeyGen nodes (Alice and Bob) on P-256.
Wire Alice's Private Key and Bob's Public Key to one ECDH Key Agreement node, and Bob's Private Key and Alice's Public Key to a second ECDH Key Agreement node.
Compare both Shared Secret outputs with Compare (==); the result is true.