A WireGuard handshake that never completes is very often a key problem: the PublicKey in the server's [Peer] is not the public key of the client's PrivateKey. The check is echo '<private key>' | wg pubkey, but that needs wg installed where you are. I wanted the same check in a web page, without sending the key anywhere, so I wrote it with WebCrypto's X25519. Three things did not work the way I expected. All results below were measured on Node 22.22 (its WebCrypto is backed by OpenSSL) and cross-checked with Python's cryptography library.

1. importKey("raw") does not read a private key

A WireGuard private key is 32 bytes in base64. The obvious call fails:

await crypto.subtle.importKey("raw", priv32, { name: "X25519" }, true, ["deriveBits"]); // SyntaxError: Unsupported key usage for a X25519 key 

With no key usages the same call succeeds, but it imports the 32 bytes as a public key. raw is the public-key format for X25519. A private key goes in as PKCS8 or JWK.

JWK is not a shortcut either: { kty: "OKP", crv: "X25519", d } without x is rejected (DataError: Invalid JWK), and x is precisely the value we are trying to compute.

2. PKCS8 for X25519 is a fixed 16-byte prefix

The PKCS8 wrapper of an X25519 private key has no variable part, so you can build it by hand:

const b64urlToBytes = s => Uint8Array.from(atob(s.replace(/-/g, "+").replace(/_/g, "/") + "===".slice((s.length + 3) % 4)), c => c.charCodeAt(0)); const toStdB64 = s => btoa(String.fromCharCode(...b64urlToBytes(s))); const PKCS8_X25519 = Uint8Array.from([ 0x30, 0x2e, 0x02, 0x01, 0x00, 0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x6e, 0x04, 0x22, 0x04, 0x20, ]); async function publicFromPrivate(privB64) { const raw = Uint8Array.from(atob(privB64), c => c.charCodeAt(0)); if (raw.length !== 32) throw new Error("not a WireGuard key"); const der = new Uint8Array(48); der.set(PKCS8_X25519); der.set(raw, 16); const key = await crypto.subtle.importKey("pkcs8", der, { name: "X25519" }, true, ["deriveBits"]); const jwk = await crypto.subtle.exportKey("jwk", key); // jwk.x = public key, base64url return toStdB64(jwk.x); } 

2b 65 6e is the OID 1.3.101.110 (X25519). Python's cryptography serializes a freshly generated key with exactly the same first 16 bytes (302e020100300506032b656e04220420). The export trick is the other half: exportKey("raw", privateKey) throws NotSupportedError, but the JWK export of the private key carries x, the public key, in base64url. WireGuard wants standard base64, so convert - and _ and restore the = padding.

I compared 4 public keys computed this way with X25519PrivateKey.from_private_bytes(...).public_key() in Python: 4 of 4 identical.

3. Clamping: already done, and it does not change the public key

X25519 private keys are "clamped" (low 3 bits of the first byte cleared, top bit of the last byte cleared, second-highest bit set). wg genkey outputs clamped keys, so I expected to clamp what WebCrypto generates. Measured:

  • 1,000 keys from generateKey({ name: "X25519" }), exported as JWK: 1,000 of 1,000 already clamped.
  • A random, unclamped 32-byte value imported through PKCS8 gives the same public key as its clamped version, because X25519 clamps the scalar internally. The JWK d exported afterwards is the unclamped input, unchanged.

So for deriving a public key, clamping is irrelevant. For generating a key to paste into a config, WebCrypto's output is already in the same form as wg genkey.

Generating a full set

const kp = await crypto.subtle.generateKey({ name: "X25519" }, true, ["deriveBits"]); const jwk = await crypto.subtle.exportKey("jwk", kp.privateKey); const privateKey = toStdB64(jwk.d); // [Interface] PrivateKey const publicKey = toStdB64(jwk.x); // the other side's [Peer] PublicKey const presharedKey = btoa(String.fromCharCode(...crypto.getRandomValues(new Uint8Array(32)))); // = wg genpsk 

A preshared key is just 32 random bytes. It has to be identical in both [Peer] sections of the pair, or the handshake fails with no error message.

Where this runs

I put the generator and the "public key from private key" check on a page: wg.vpnsmith.com/keys. It runs in the browser and nothing is sent, which you can confirm in the network tab. Paste a client's PrivateKey, compare the result with the PublicKey in the server's [Peer]: if they differ, that is your missing handshake. If the browser has no X25519 in WebCrypto, the page says so and gives the wg pubkey command instead. On a server, keep generating keys locally with wg genkey | tee priv | wg pubkey: keys that never leave the machine are still the best option.