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
dexported 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.