| Internet-Draft | PQC Bootstrap for WireGuard | November 2026 |
| Liu, et al. | Expires 22 May 2027 | [Page] |
This document specifies a post-quantum bootstrap profile for WireGuard. A mutually authenticated ML-KEM-768 and ML-DSA exchange derives a 32-octet preshared key (PSK), verifies key possession, and binds it to configured endpoint identities and WireGuard public keys. The resulting key is installed through the ordinary WireGuard PresharedKey configuration field.¶
The profile defines canonical binary control records carried over mutually authenticated TLS 1.3 on TCP, with explicit message lengths, freshness, state transitions, and failure processing. Bootstrap carries the post-quantum contribution into the WireGuard PSK input; it is therefore part of the post-quantum provisioning mechanism. The native WireGuard Noise handshake and transport packet format are unchanged.¶
This Internet-Draft is a proposal for Standards Track publication. It requests an ALPN protocol identifier for the bootstrap carrier. The request is pending; this document does not assign a native WireGuard packet type or a service port.¶
This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79.¶
Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet-Drafts is at https://datatracker.ietf.org/drafts/current/.¶
Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress."¶
This Internet-Draft will expire on 22 May 2027.¶
Copyright (c) 2026 IETF Trust and the persons identified as the document authors. All rights reserved.¶
This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License.¶
WireGuard uses the NoiseIKpsk2_25519_ChaChaPoly_BLAKE2s handshake with an optional 32-octet preshared key [WIREGUARD] [NOISE]. This document uses ML-KEM-768 and ML-DSA to establish and authenticate that PSK before the native handshake.¶
The bootstrap has a direct post-quantum role: ML-KEM contributes a secret to the PSK and ML-DSA authenticates the provisioning transcript. The carrier itself is not a post-quantum algorithm. TLS 1.3 provides a standard transport security layer for the control exchange; the post-quantum properties described here depend on the inner KEM and signatures rather than on an assumption that ordinary TLS certificates or key exchange are post-quantum.¶
This document defines the bootstrap record format and its TLS/TCP binding independently of any implementation. The proposed ALPN registration is specified in Section 14; it is not an existing allocation asserted by this draft. Remaining specification and review items are recorded in Section 15.¶
The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL in this document are to be interpreted as described in BCP 14 [RFC2119] and [RFC8174] when, and only when, they appear in all capitals.¶
In this document, the WireGuard endpoint that initiates provisioning is the Client and the other endpoint is the Server. The octet-string operator || denotes concatenation. The native WireGuard protocol terms and fields retain the meanings defined by the WireGuard protocol and configuration format.¶
The external control plane establishes a PSK bound to a configured pair of WireGuard static public keys, two expected ML-DSA identities, a tunnel name, a suite, and a fresh transaction. Both endpoints MUST obtain the WireGuard public keys from their authorized interface configuration and check peer-key bindings before installing the PSK.¶
Signature verification MUST check the configured peer identity, role, current credential validity, and authorization independently of the choice of PKI or signing API. A record does not introduce a new trust anchor or authorize a different identity. The carrier is separate from the native WireGuard UDP endpoint.¶
An adversary may observe, inject, modify, delay, reorder, and replay bootstrap traffic and may submit malformed keys, signatures, lengths, or confirmation values. The profile aims to provide authenticated post-quantum PSK establishment bound to authorized endpoint identities and WireGuard keys, with fresh sessions and explicit key confirmation.¶
A compromised endpoint, signing key, KEM key, trust anchor, PKI service, or WireGuard private key remains outside the threat model. The profile relies on local authorization and secure configuration installation and does not guarantee availability or prevent traffic analysis.¶
The local profile identifier is wireguard-pq-bootstrap-v2. It identifies the encoded exchange below and is not a native WireGuard or IANA allocation. The earlier logical-only v1 transcript is not accepted by this version.¶
| Function | Algorithm or value | Length |
|---|---|---|
| Endpoint signature | ML-DSA-44, ML-DSA-65, or ML-DSA-87 | Parameter-set dependent |
| Key encapsulation | ML-KEM-768 | Public key 1184; ciphertext 1088; secret 32 |
| Key derivation | HKDF-SHA-256 | 32-octet output |
| Native tunnel PSK | WireGuard PresharedKey | 32 octets, Base64 in configuration |
| Native tunnel | NoiseIKpsk2_25519_ChaChaPoly_BLAKE2s | WireGuard-defined |
Implementations MUST implement ML-KEM-768, ML-DSA-65, HKDF-SHA-256, and HMAC-SHA-256 as the common bootstrap interoperability baseline. ML-DSA-44 and ML-DSA-87 MAY additionally be supported. ML-KEM and ML-DSA MUST use the algorithm definitions in FIPS 203 and FIPS 204 [FIPS203][FIPS204]. This requirement does not assert cryptographic-module validation.¶
Both endpoints MUST use the same ML-DSA parameter set selected by authenticated local configuration and MUST reject a mismatch. Suite support alone does not authorize use of that suite for a peer. The profile does not negotiate the parameter set in either the bootstrap exchange or the native WireGuard handshake.¶
Each endpoint MUST have an active ML-DSA identity and a trust path or equivalent authenticated binding. The verifier MUST bind the identity to the expected role and to the WireGuard static public key carried in the bootstrap transcript. A valid signature under an unexpected identity or for a different WireGuard key MUST be rejected.¶
Implementations MUST support an authenticated local binding containing the exact identity octets, Client or Server role, selected ML-DSA parameter set, exact FIPS 204 public-key octets, and authorized WireGuard public key. The binding MUST be provisioned and updated through an authorized configuration channel; neither a bootstrap record nor successful TLS certificate validation alone may create or replace it. A separately specified certificate mechanism MAY additionally supply that binding.¶
Signatures use ML-DSA, rather than HashML-DSA, with the exact ASCII context string wireguard-pq-bootstrap-v2. The context has no trailing zero octet, and the protocol message MUST NOT be prehashed through an implementation-specific signing API. The PKI provider MAY be local or remote, but private signing keys and authorization tokens MUST be protected. A remote signing or status failure MUST cause provisioning to fail closed.¶
Each transaction uses a new TLS connection and the ordered records ClientInit, ServerHello, ClientProof, ServerFinished, and ClientAck. Each endpoint checks the configured suite, peer identity, role, WireGuard public keys, and tunnel name. The Client generates a fresh 32-octet nonce CN. The Server generates a fresh 32-octet SID and ML-KEM-768 pair (PK_S, SK_S).¶
D = ASCII("WireGuard-PQ-PSK-v2") || 0x00
H = D || ASCII("SERVER") || 0x00 || SHA-256(I) || SID || PK_S
P = D || ASCII("CLIENT") || 0x00 || SHA-256(H) || CT
X = SHA-256(I || encoded-ServerHello || encoded-ClientProof)
server-MAC = HMAC-SHA-256(K_SF, D || ASCII("SERVER") || X)
client-MAC = HMAC-SHA-256(K_CF, D || ASCII("CLIENT") || X)¶
ML-DSA uses context wireguard-pq-bootstrap-v2. All concatenations and ASCII labels are exact; the zero octets above are part of the inputs. The ClientInit hash binds both identities, both WireGuard keys, the suite in its header, tunnel name, and fresh Client nonce into both signatures and the key schedule.¶
The control connection MUST use TCP [RFC9293] with TLS 1.3 [RFC8446]. Both endpoints MUST validate the peer TLS certificate and its authorization for the configured control service. The Client MUST verify the expected server name. The inner ML-DSA identity checks are additionally required. TLS 1.2 and earlier, plaintext, TLS early data (0-RTT), and application records before handshake completion MUST be rejected. No PSK, shared secret, signing key, or KEM private key is transmitted in an application record.¶
The proposed ALPN value is the six-octet ASCII string wgpq/2, selected using [RFC7301]. Failure to select this exact value MUST abort the connection. Its registration is requested in Section 14 and remains pending. Until allocation is confirmed, its use is restricted to explicitly configured development deployments; it MUST NOT be represented as an assigned identifier. The TCP port is explicitly configured independently of the WireGuard UDP port; no default or service-port allocation is specified.¶
Record = ASCII("WGPQ") || version(1) || type(1) || suite(1) ||
flags(1) || BE32(body_length) || Body
version = 2
flags = 0
suite = 44 / 65 / 87 (decimal)¶
The fixed header is 12 octets. Body length is between 1 and 8192 inclusive and excludes the header. All multi-octet integers in this carrier are unsigned big-endian. Suite values identify ML-DSA-44, -65, or -87 with signature lengths Lsig of 2420, 3309, or 4627 octets. The suite MUST match configured trust policy; there is no algorithm negotiation. Unknown versions, message types, suite values, or flags terminate the exchange.¶
| Type | Body fields, in order | Body length |
|---|---|---|
| 1 ClientInit | CN(32); name-length(1); tunnel; W_C(32); W_S(32); client-id-length(2); client-id; server-id-length(2); server-id | 101 + name length + identity lengths |
| 2 ServerHello | SHA-256(I)(32); SID(32); PK_S(1184); signature | 1248 + Lsig |
| 3 ClientProof | SID(32); CT(1088); signature | 1120 + Lsig |
| 4 ServerFinished | SID(32); server-MAC(32) | 64 |
| 5 ClientAck | SID(32); client-MAC(32) | 64 |
Tunnel names contain 1 to 32 ASCII characters from A-Z, a-z, 0-9, dot, underscore, and hyphen. Each identity contains 1 to 255 UTF-8 octets, has no ASCII control characters or DEL, and is compared byte-for-byte to configured identity text without Unicode normalization. The two identities MUST differ. Each WireGuard public key is exactly 32 octets and MUST match the authorized configured key; an all-zero key is rejected. The ClientInit fields have no separators or terminators beyond the specified lengths.¶
TLS records and TCP reads need not align to bootstrap records. A receiver first reads exactly 12 header octets, validates the type, suite, flags, and length before allocating the body, then reads exactly body_length octets and rejects any internal length mismatch or surplus field. It processes exactly the five ordered messages of one transaction and closes the connection after completion or failure. TLS resumption MUST NOT reuse a bootstrap SID, KEM key pair, or pending state.¶
The complete bootstrap transaction and any pending key material MUST expire within 30 seconds, measured locally from sending or receiving ClientInit. A receiver MUST enforce this deadline even if no further bytes arrive; a blocking read MUST NOT extend it. Resource policy MUST bound concurrent connections. On timeout or cryptographic failure, the endpoint MUST discard pending state and close the connection. Detailed credential or KEM failure causes MUST NOT be exposed to an unauthenticated application peer.¶
After the authenticated KEM exchange, derive three independent 32-octet values using HKDF-SHA-256 [RFC5869]. SS is the local KEM shared secret. H is the exact Server signature input above.¶
salt = SHA-256(D || SID || CT)
T = SHA-256(H || CT)
PRK = HKDF-Extract(salt, SS)
PSK = HKDF-Expand(PRK, D || T, 32)
K_SF = HKDF-Expand(PRK,
D || ASCII("SERVER-FINISHED") || 0x00 || T, 32)
K_CF = HKDF-Expand(PRK,
D || ASCII("CLIENT-FINISHED") || 0x00 || T, 32)¶
D includes its terminating zero octet in every formula, including the PSK info. Confirmation keys are not used as WireGuard keys. The PSK is returned only after the corresponding peer confirmation succeeds. Invalid KEM ciphertexts can cause implicit rejection and an unrelated secret; a confirmation-MAC mismatch MUST abort provisioning.¶
Install the resulting 32-octet PSK in the configured peer's PresharedKey field using standard Base64. Interface private keys remain local. Both WireGuard public keys MUST match those in the signed ClientInit binding. Configuration updates MUST be authorized and atomic within each endpoint. The carrier does not provide a distributed atomic configuration commit; loss during completion requires recovery through a fresh bootstrap and explicit status reconciliation before declaring the tunnel ready.¶
An endpoint MUST NOT declare the tunnel ready solely because bootstrap completed. It MUST also verify successful native WireGuard handshake operation for the configured peer after the PSK was installed. A failed or interrupted update MUST be reported as a provisioning failure until the endpoints are reconciled. This check does not make the two configuration writes an atomic distributed operation.¶
Provisioned PSKs and authenticated bindings MUST be stored and installed through authorized local interfaces. An implementation MUST NOT log the raw PSK or return it from an unauthenticated diagnostic API. Secret-bearing configuration files require the same access restrictions.¶
Once the PSK is provisioned, the endpoints run the native WireGuard handshake. The profile does not add an ML-KEM field to the initiation or response packets and does not change the Noise construction. The native protocol combines its usual Curve25519 handshake state with the configured PSK according to NoiseIKpsk2 and then protects transport packets with WireGuard's standard ChaCha20-Poly1305 construction.¶
The PSK MUST be installed before the first handshake that is intended to use this profile. A configuration that omits the PSK, uses a different PSK, or associates it with the wrong peer MUST be treated as a provisioning failure. Native WireGuard rekey and cookie behavior remain applicable.¶
Each transaction requires a fresh CN, SID, and ML-KEM pair. The Client accepts only a ServerHello tied to its current encoded ClientInit. The Server accepts only one ClientProof and ClientAck for its current SID. The one-use state machine, signed Client nonce, two confirmation MACs, and 30-second lifetime prevent reuse of completed records as a new provisioning result. A retry creates a new transaction; a record MUST NOT reset or reopen completed state.¶
PSK rotation SHOULD occur before operational limits, after a credential change, or after suspected compromise. Installation is atomic per endpoint; a coordinated recovery procedure is required if the other endpoint has not completed installation. Superseded PSKs and KEM private keys MUST be removed from protected stores. Implementations SHOULD minimize secret lifetime and avoid retaining complete secret-bearing configurations.¶
Invalid signatures, identity bindings, ML-KEM lengths, ciphertexts, transcript hashes, parameter sets, or configuration key relationships MUST abort provisioning. An implementation supporting a classical provisioning path MUST NOT silently choose that path after a post-quantum failure. Any fallback MUST be an explicit, authenticated local policy decision.¶
Detailed error diagnostics MAY be logged locally, but unauthenticated control-plane responses SHOULD NOT distinguish signature, KEM, authorization, and transcript failures. Logs MUST NOT contain private keys, ML-KEM secret keys, shared secrets, PSKs, bearer tokens, or complete secret-bearing configurations.¶
Implementations MUST implement the common suite, exact encodings and signature contexts, peer and WireGuard key bindings, five-message state machine, key confirmation, transaction deadlines, and provisioning failure rules in this document. Conformance requires authenticated TLS transport, authorized PSK installation, and the native-handshake readiness check; completing the bootstrap exchange alone is insufficient.¶
This document requests the following entry in the "Application-Layer Protocol Negotiation (ALPN) Protocol IDs" registry established by [RFC7301]:¶
| Field | Requested value |
|---|---|
| Protocol | Post-Quantum Bootstrap for WireGuard, version 2 |
| Identification Sequence | 0x77 0x67 0x70 0x71 0x2f 0x32 ("wgpq/2") |
| Reference | This document |
This is a proposed registration subject to the registry's Expert Review procedure, not a completed assignment. The value and reference must be confirmed during review. No TCP service port, native WireGuard identifier, or separate registry for the local profile name is requested. Record types and suite values are scoped to version 2 of this bootstrap protocol.¶
This section records unresolved specification and review work for this Standards Track proposal. It does not relax the requirements above. The issues are to be resolved or otherwise explicitly addressed before Proposed Standard publication.¶
The post-quantum contribution depends on ML-KEM-768, ML-DSA, fresh randomness, key confidentiality, and authorized identity bindings. Ordinary TLS certificates or TLS key exchange MUST NOT be described as post-quantum merely because this carrier uses them. The signed inner exchange and confirmation keys authenticate and confirm the post-quantum provisioning material.¶
All record headers and lengths are checked before expensive processing. The signed ClientInit hash prevents substitution of endpoint identities, WireGuard keys, suite, tunnel, or Client nonce. Fresh SID and KEM state, one-use transitions, finite deadlines, and confirmation MACs prevent stale records or a different KEM secret from producing an accepted PSK. Credential failures and post-quantum failures MUST NOT trigger a silent classical fallback.¶
The native WireGuard handshake combines its existing Curve25519 state with the PSK according to NoiseIKpsk2. This draft does not provide a new hybrid security proof or alter the native anti-replay, cookie, rekey, and transport mechanisms. Endpoint compromise, leakage of secret-bearing configurations, traffic analysis, and denial of service remain outside the cryptographic guarantees of the bootstrap.¶