Post-Quantum Cryptography Migration Research for js-libp2p

[paschal533]

Post-Quantum Cryptography Migration Research for js-libp2p

Summary

With NIST's finalization of post-quantum cryptography standards in August 2024 (ML-KEM, ML-DSA, SLH-DSA) and the deprecation timeline targeting 2035, it's time to begin researching PQC migration paths for js-libp2p. This discussion initiates a structured research effort to assess quantum vulnerability, evaluate migration strategies, and develop a roadmap for PQC adoption.

Background

The Quantum Threat to libp2p

libp2p relies on cryptographic primitives that are vulnerable to quantum attacks:

Component	Current Algorithm	Quantum Status
Noise key exchange	X25519 (ECDH)	❌ Broken by Shor's algorithm
Peer identity	Ed25519	❌ Broken by Shor's algorithm
TLS key exchange	ECDHE	❌ Broken by Shor's algorithm
Symmetric encryption	ChaCha20-Poly1305	✅ Secure (Grover's provides limited speedup)

Why Act Now?

1. Store-Now-Decrypt-Later (SNDL): Adversaries can capture encrypted P2P traffic today and decrypt it when quantum computers become available. Data requiring long-term confidentiality is already at risk.

2. NIST Timeline: NIST IR 8547 establishes deprecation of quantum-vulnerable algorithms by 2035, with high-risk systems transitioning much earlier.

3. Migration Complexity: Based on historical migrations (SHA-1 → SHA-256), cryptographic transitions take 5+ years. Starting research now ensures readiness.

4. Ecosystem Dependencies: Ethereum, IPFS, Filecoin, and other major projects depend on libp2p. Their PQC requirements will flow through to us.

Research Scope

This research will follow an adapted version of the TNO PQC Migration Handbook methodology:

Phase 1: Cryptographic Inventory

• Map all cryptographic primitives across js-libp2p packages
• Identify extension points (e.g., ICryptoInterface in libp2p-noise)
• Survey cross-implementation status (go, rust, js, nim)

Phase 2: Quantum Risk Assessment

• Threat modeling for P2P-specific SNDL scenarios
• Impact analysis per component
• Priority matrix for migration order

Phase 3: Technical Feasibility

• Algorithm selection (ML-KEM-768, ML-DSA-65)
• Performance benchmarks using @noble/post-quantum
• Size constraints analysis (ENR limits, bandwidth impact)
• Browser/Node.js compatibility matrix

Phase 4: Migration Strategies

• Hybrid approaches (X25519 + ML-KEM)
• Phased rollout plan
• Interoperability coordination with other implementations
• Cryptographic agility design

Phase 5: Proof of Concept

• Reference implementation of hybrid Noise crypto provider
• Benchmark suite
• Interop test vectors
• Migration documentation

Key Questions for the Community

1. Priority: Which components should we prioritize? (Noise key exchange seems highest due to SNDL risk)

2. Hybrid vs Pure PQC: Should we target hybrid mode (classical + PQC) for backward compatibility, or plan for pure PQC?

3. Algorithm Choice: ML-KEM-768 is the NIST standard for key exchange. Are there concerns about using it in js-libp2p?

4. Cross-Implementation Coordination: How do we coordinate with go-libp2p and rust-libp2p teams?

5. Timeline: What's a reasonable timeline for opt-in PQC support?

Relevant Resources

• NIST PQC Standards - FIPS 203, 204, 205
• NIST IR 8547 - Transition to Post-Quantum Cryptography Standards
• TNO PQC Migration Handbook - Methodology reference
• Post Quantum Noise - Academic paper on PQC in Noise protocol
• PSE: Towards a Quantum-Safe P2P for Ethereum - P2P-specific constraints
• @noble/post-quantum - Pure JS implementation of ML-KEM, ML-DSA
• rust-libp2p#2168 - Related discussion

Prior Art

• Signal: PQXDH protocol (X25519 + Kyber)
• iMessage: PQ3 protocol (ongoing keying with ML-KEM)
• Chrome/Cloudflare: Hybrid TLS with X25519Kyber768
• WireGuard: PQ-WireGuard research

---

I welcome feedback, questions, and collaboration from the community. Let's work together to make js-libp2p quantum-safe!

[paschal533]

Research Update: Deep Dive Findings & Concrete Implementation Plan

Following the initial discussion post, I've completed an extensive literature review and codebase analysis. Here are the key findings and a concrete path forward.

---

🔬 Research Completed

I've surveyed 22 academic papers and NIST standards, analyzed the full js-libp2p-noise codebase, and studied all active IETF drafts. Here's what I found:

---

1. The Exact Attack Surface in js-libp2p-noise

After reading the full source of js-libp2p-noise, the quantum attack surface is precisely bounded to three lines of code in protocol.ts:

protected writeEE(): void {
  this.ss.mixKey(this.crypto.dh(this.e, this.re))    // ← Shor's can break this
}
protected writeES(): void {
  this.ss.mixKey(this.crypto.dh(this.e, this.rs))    // ← Shor's can break this
}
protected writeSE(): void {
  this.ss.mixKey(this.crypto.dh(this.s, this.re))    // ← Shor's can break this
}

The ICryptoInterface in src/crypto.ts has a crypto?: ICryptoInterface injection point in NoiseInit that is already designed for exactly this kind of extension. We can implement a PQC backend without modifying the library internals.

---

2. Algorithm Decision: ML-KEM-768 via X-Wing Hybrid

Selected approach: X-Wing (draft-connolly-cfrg-xwing-kem)

X-Wing is a composite KEM that fuses X25519 and ML-KEM-768:

SS = SHA3-256(SS_mlkem || SS_x25519 || CT_x25519 || PK_x25519 || label)

Why X-Wing:

• Industry consensus: Chrome, Firefox, Cloudflare (37% of human web traffic), Go stdlib all use X25519+ML-KEM-768
• Included in @noble/post-quantum v0.6.0 (the noble ecosystem already used by pureJsCrypto backend)
• 32-byte shared secret output, drop-in for X25519's output
• Formal security proof: secure if SHA3-256 is secure AND (X25519 OR ML-KEM-768 is secure)

Key sizes:

	Classical X25519	X-Wing Hybrid
Public key	32 bytes	1,216 bytes
Ciphertext	32 bytes	1,120 bytes
Shared secret	32 bytes	32 bytes ✅

---

3. Why Hybrid Over Pure PQNoise

Pure PQNoise (pqXX pattern from the ACM CCS 2022 paper) requires 4 message round trips instead of XX's 3, because KEMs are asymmetric (no equivalent of the symmetric dh(keypair, pubkey) call). This adds latency per connection, non-trivial in a P2P network with thousands of concurrent peers.

The Noise HFS extension (noise_hfs_spec) adds KEM tokens to the existing XX pattern without changing the message count:

Classical XX:          Hybrid XXhfs:
  -> e                   -> e, e1           // +1,216 byte KEM pubkey
  <- e, ee, s, es        <- e, ee, ekem1, s, es  // +1,120 byte KEM ciphertext
  -> s, se               -> s, se           // unchanged

Security: both classical DH AND quantum-safe KEM feed the chaining key. An adversary must break both to break the session.

---

4. JS Library: @noble/post-quantum

npm install @noble/post-quantum

@noble/post-quantum v0.6.0 (March 2026) by Paul Miller provides:

• ML-KEM-512/768/1024 (FIPS 203)
• X-Wing, KitchenSink, QSF hybrid KEMs
• ML-DSA-44/65/87 (FIPS 204) — for future peer identity migration
• Pure TypeScript, ESM-native, browser + Node.js + Deno + Cloudflare Workers

Performance on Apple M4:

Operation	Time
X-Wing keygen	~580 μs
X-Wing encapsulate	~350 μs
X-Wing decapsulate	~280 μs
Full XXhfs handshake	~1.5 ms
Classical XX handshake	~0.15 ms

The 10× handshake overhead in CPU time is well within acceptable bounds, network RTT (>10ms) dominates connection establishment.

Message overhead: +2,436 bytes across the 3 messages (all within TCP segment limits; no fragmentation needed).

---

5. Reference Implementations Found

The most directly relevant references:

• Katzenpost (Go), only production P2P system using PQNoise today. Uses pqXX with Kyber768+X25519 hybrid for its mix network wire protocol. Go library: katzenpost/noise
• Clatter (Rust), most complete PQNoise library, supports hybrid handshakes. jmlepisto/clatter
• Signal PQXDH, deployed to all Signal clients Sept 2023. Same hybrid X25519+ML-KEM pattern we're proposing.
• Go 1.24, uses X25519MLKEM768 in crypto/tls by default. Meaning go-libp2p's TLS transport already has PQC at key exchange.

---

6. Proposed Implementation Plan

I've written a detailed ROADMAP.md in the research repository. Summary:

Phase 0 (Week 1): Environment setup, baseline benchmarks
Phase 1 (Week 2): IKem interface + pqcCrypto backend with X-Wing
Phase 2 (Week 3): XXhfsHandshakeState, new handshake state machine
Phase 3 (Week 4): NoiseHFS class, new ConnectionEncrypter with protocol ID /noise-pq/1.0.0
Phase 4 (Week 5): Benchmarks Node.js + browser
Phase 5 (Week 6): Test vectors + Clatter interop
Phase 6 (Weeks 7–8): Specification + documentation + PR

The new protocol identifier would be /noise-pq/1.0.0, allowing both /noise and /noise-pq/1.0.0 to be offered during multistream negotiation. Backward compatible by design.

---

7. Answers to the Key Questions

Q1: Priority? Noise key exchange is definitely Priority 1 (SNDL risk; entire connection confidentiality). Peer identity (Ed25519 → ML-DSA) is Priority 2 but harder and out of scope for this phase.

Q2: Hybrid vs Pure PQC? Hybrid mode (XXhfs) is the right call: (a) 3 messages instead of 4, (b) security holds if either X25519 or ML-KEM-768 is unbroken, (c) it's what TLS, Signal, WireGuard, and Chrome all deployed in 2024-2025.

Q3: Algorithm choice? ML-KEM-768 via X-Wing hybrid. NIST FIPS 203 standard, Cat. 3 security, industry consensus, already in @noble/post-quantum.

Q4: Cross-implementation coordination? Katzenpost Go (pqXX) is already in production. For the js implementation, I'd propose coordinating via this discussion + a matching PR to libp2p/specs for /noise-pq/1.0.0.

Q5: Timeline? Opt-in PQC support (the NoiseHFS class) in ~8 weeks of active development. Making it the default in /noise is a bigger migration (protocol version bump + deprecation notice) and would be a separate discussion.

---

Next Steps

I'm starting implementation this week. I'll post updates here as each phase completes. Looking for feedback on:

1. The /noise-pq/1.0.0 protocol identifier, any naming conflicts or conventions to follow?
2. Whether the Noise HFS extension is preferred over a protocol-level redesign
3. Interest from go-libp2p/rust-libp2p teams in coordinating test vectors

cc @tabcat @achingbrain @dozyio @Faolain

[dozyio]

Also been thinking a bit about this - will need some spec changes, protobuf changes etc... Got a PR for ML-DSA support which might give you a starting point.

Hybrid is probably the way forward similar to TLS - IIRC there is some push back on pure PQ systems

In terms of JS - node has experimental support for ML-DSA & ML-KEM, @noble/post-quantum isn't audited, also there is no support in webcrypto.

[paschal533]

Also been thinking a bit about this - will need some spec changes, protobuf changes etc... Got a PR for ML-DSA support which might give you a starting point.

Hybrid is probably the way forward similar to TLS - IIRC there is some push back on pure PQ systems

In terms of JS - node has experimental support for ML-DSA & ML-KEM, @noble/post-quantum isn't audited, also there is no support in webcrypto.

Thank you @dozyio for the pointer to PR #3432. I have studied the implementation. The two bodies of work are complementary. The Noise protocol does both... it performs a KEM-based key exchange and authenticates static keys via signed payloads in Messages B and C (NoiseHandshakePayload). Your ML-DSA PR covers the identity layer and my Noise HFS work covers the key exchange layer. Neither is sufficient alone for full post-quantum security.

On the audit concern with @noble/post-quantum, You are right to flag this. PR #3432 handles it well: a dual-backend pattern (noble for browser/fallback, node:crypto.subtle for Node.js) that mirrors what pureJsCrypto already does. I plan to adopt the same pattern for ML-KEM

On WebCrypto... agreed, noble is the correct path
ML-KEM has no Web Crypto API support (neither does ML-DSA). The noble-only browser path and node-subtle Node.js path from PR #3432 is the right architecture for ML-KEM too. I will mirror that structure exactly.

While studying PR #3432, I found that MLDSA65 produces 3,309-byte signatures (vs 64 bytes for Ed25519). The NoiseHandshakePayload in Messages B and C carries the signed static key. This significantly changes the hybrid handshake size estimates:

Component	Classical	Hybrid (XXhfs + MLDSA65)
Message A	~32 B	~1,248 B (+1,216 B for KEM pubkey)
Message B	~96 B	~4,805 B (+1,088 B KEM ciphertext, +3,245 B MLDSA65 sig Δ)
Message C	~48 B	~3,389 B (+3,245 B MLDSA65 sig Δ)
Total overhead	baseline	+~9,000 B

The KEM component (X-Wing or plain ML-KEM-768) adds ~2,304 bytes across the handshake. The ML-DSA identity signatures dwarf that, they are the dominant size cost. This does not block the approach (TCP/QUIC have no 1500-byte packet limits for handshakes), but it is worth documenting for spec work.

I plan to build on top of PR #3432, by using KeyType.MLDSA = 4 and MLDSAPrivateKey/MLDSAPublicKey for static identity keys in the Noise handshake, add a new IKem interface in src/kem.ts (separate from ICryptoInterface) for the KEM tokens and Implement XXhfsHandshakeState that calls KEM encap/decap for the e1/ekem1 tokens and the existing three dh() calls for ee/es/se

Happy to sync on the spec changes and protobuf work, the e1 (1216 B KEM pubkey) and ekem1 (1088 B ciphertext) need to be appended to Messages A and B respectively, which may require updating NoiseHandshakePayload.proto.

Would a separate /noise-pq spec document alongside the existing Noise spec be the right home for the wire format, or should this go into a libp2p spec PR?

[paschal533]

Implementation Update: PR is up

After completing all the phases I outlined in the previous update, the PR is now open at ChainSafe/js-libp2p-noise#665.

Here is a quick summary of what got built:

Core implementation (Phases 1-3)

• IKem interface in src/kem.ts (separate from ICryptoInterface as discussed)
• pqcKem backend in src/crypto/pqc.ts using XWing from @noble/post-quantum v0.6.0
• XXhfsHandshakeState in src/protocol-pqc.ts that adds the e1 and ekem1 KEM tokens to the existing XX state machine without touching any of the classical DH paths
• noiseHFS() factory in src/noise-hfs.ts that implements ConnectionEncrypter with protocol ID /noise-pq/1.0.0

Both noise() and noiseHFS() are exported from the same package so they can coexist in the same libp2p node via multistream negotiation.

Tests (Phase 5)

99 new tests across 4 spec files:

• test/pqc-kem.spec.ts (17 tests covering the IKem backend)
• test/pqc-protocol.spec.ts (18 tests for the handshake state machine)
• test/pqc-noise.spec.ts (12 integration tests using real libp2p connections)
• test/pqc-vectors.spec.ts (52 tests verifying 5 deterministic test vectors)

The test vectors in test/fixtures/pqc-test-vectors.json were generated using seeded keys so they are reproducible and can be used to verify a compatible implementation in another language. I included a full wire format spec in NOISE_HFS_SPEC.md with the exact byte layout and token ordering.

Benchmarks (Phase 4)

Measured on Node.js v22.17.1, Windows 11 x64, pure JS:

	ops/s	ms/op
X-Wing keygen	293	3.42
X-Wing encapsulate	120	8.32
X-Wing decapsulate	136	7.33
Classical XX handshake	114	8.75
XXhfs handshake	23	44.18

The numbers are slower than the Apple M4 figures from the research phase since this is running on Windows x64 pure JS. A WASM-accelerated ML-KEM backend would close that gap significantly.

On the @dozyio PR #3432 findings

I incorporated the ML-DSA wire size analysis from our earlier exchange into benchmarks/results.md. The full-PQ scenario (XXhfs + MLDSA65 identity on both sides) comes out to roughly 9,400 bytes total. The identity cost (MLDSA65 pubkey + signature on each side) is about 2.7x larger than the KEM overhead alone which lines up with what I calculated in the previous comment. NoiseHFS is ready to support ML-DSA identity keys automatically once PR #3432 merges since privateKey.sign() is already key-type aware.

On the node:crypto.subtle backend

I created src/crypto/pqc.node.ts as a placeholder following the same dual-backend pattern from PR #3432. The reason it currently just re-exports the noble implementation is that Node.js v22 does not actually expose ML-KEM-768 via node:crypto.subtle yet. I tested this directly and every algorithm name I tried (MLKEM768, ML-KEM-768, X25519MLKEM768) throws "unrecognized algorithm". The Node.js issue tracker has an open ticket for this. When native support lands the swap is documented in the file comments. Even then, noble would still be needed for the X25519 step and the SHA3-256 combiner that X-Wing applies on top.

On the spec location question

Given this is a new handshake pattern with a new protocol ID, I think a NOISE_HFS_SPEC.md in the js-libp2p-noise repo is the right home for the JS reference, but a libp2p/specs PR for /noise-pq/1.0.0 makes sense if there is appetite for cross-implementation coordination. Happy to draft that once the core PR gets some review.

Would love any feedback from @dozyio @achingbrain @tabcat @Faolain on the implementation or the spec, especially on whether the protocol ID naming and the IKem interface design look reasonable for upstreaming.