Post-Quantum Noise handshake for py-libp2p (XXhfs + X-Wing KEM)

[paschal533]

Hi everyone,

I have been doing research on integrating post-quantum cryptography into the libp2p Noise handshake, and I wanted to bring it to this community and get your thoughts.

What was done on the JS side

I recently implemented the Noise_XXhfs_25519+XWing_ChaChaPoly_SHA256 handshake in js-libp2p-noise at Chainsafe. The XXhfs pattern is the Noise HFS extension that adds two extra tokens, e1 and ekem1, which perform a KEM operation alongside the classical X25519 DH. The KEM used is X-Wing, a hybrid of ML-KEM-768 and X25519, so the session key is secure as long as either algorithm holds.

The protocol ID is /noise-pq/1.0.0.

A working demo that runs in both Node.js and the browser is here: https://github.com/paschal533/pqc-libp2p-example

Benchmark results on a pure-JS runtime (Windows, Node.js v22):

• Classical Noise_XX: 9.07 ms per handshake
• Hybrid Noise_XXhfs: 44.16 ms per handshake (+4.9x overhead, dominated by the X-Wing KEM at ~20 ms)
• Wire overhead: +2,352 bytes per handshake (192 B classical vs 2,544 B hybrid)

The overhead is significant but manageable. For long-lived connections it is negligible. The main benefit is protecting against Store-Now-Decrypt-Later attacks on recorded traffic, which is a real threat today regardless of when quantum computers arrive.

Proposal for py-libp2p

I would like to research and implement the same handshake in py-libp2p so we can do interoperability testing between a Python node and a JS node over /noise-pq/1.0.0. I have written a detailed migration roadmap covering 7 phases, from the architecture decision (whether noiseprotocol is extensible enough to add custom tokens) all the way to live interop tests and benchmarks.

The key design questions for Python are:

1. Can noiseprotocol.PatternXX be subclassed to inject e1/ekem1 handlers, or do we need a standalone state machine?
2. For ML-KEM-768: liboqs-python (C bindings, most audited) vs pymlkem (pure Python, no C dependency)?
3. Does the combiner need to be extracted as a shared utility for future reuse?

I am happy to do this work as part of my ongoing PQC research across libp2p implementations. Would love to hear if there are already plans for this or if there are any constraints I should know about before starting.

cc @seetadev @acul71 @pacrob

Related:

• js-libp2p-noise: feat: add post-quantum hybrid Noise handshake ChainSafe/js-libp2p-noise#665
• dozyio's ML-DSA identity: feat: Post quantum identities with ML-DSA js-libp2p#3432

[acul71]

The key design questions for Python are:

1. Can noiseprotocol.PatternXX be subclassed to inject e1/ekem1 handlers, or do we need a standalone state machine?
2. For ML-KEM-768: liboqs-python (C bindings, most audited) vs pymlkem (pure Python, no C dependency)?
3. Does the combiner need to be extracted as a shared utility for future reuse?

Hi @paschal533 @seetadev @pacrob some thoughts about Noise-quantum
Are there already some specs about this ?

Post-Quantum Noise for py-libp2p: Answers to the Python Design Questions

Context

This document answers the three design questions raised in the py-libp2p discussion about adding a post-quantum hybrid Noise handshake (XXhfs with X-Wing KEM, protocol id /noise-pq/1.0.0), using:

• the discussion thread: Post-Quantum Noise handshake for py-libp2p (XXhfs + X-Wing KEM) #1306
• the linked js-libp2p-noise PR: feat: add post-quantum hybrid Noise handshake ChainSafe/js-libp2p-noise#665
• the current local py-libp2p Noise implementation in this repository.

The JS reference implementation introduces two new tokens (e1, ekem1) and keeps classical XX identity/auth structure, while mixing a KEM shared secret into the handshake key schedule.

What the current py-libp2p implementation implies

Current architecture summary (local codebase):

• libp2p/security/noise/transport.py always returns PatternXX.
• PatternXX in libp2p/security/noise/patterns.py uses NoiseConnection.from_name(...) with b"Noise_XX_25519_ChaChaPoly_SHA256".
• Handshake message crypto is delegated to noiseprotocol via noise_state.write_message(...) and noise_state.read_message(...) in libp2p/security/noise/io.py.
• Token semantics are not implemented in py-libp2p code; they are implicit in the protocol name handled by noiseprotocol.
• Static DH is currently constrained to X25519 (KeyType.X25519 checks in BasePattern._validate_noise_static_key).

This means py-libp2p currently acts as an orchestrator around noiseprotocol, not as a token-level handshake engine.

---

1) Can noiseprotocol.PatternXX be subclassed to inject e1/ekem1, or do we need a standalone state machine?

Short answer

For practical implementation velocity and correctness: build a dedicated XXhfs handshake state machine in py-libp2p (parallel to current PatternXX orchestration), instead of trying to subclass/inject token handlers into current noiseprotocol usage.

Why

1. No token injection seam in current py-libp2p path

   • py-libp2p does not parse or dispatch Noise tokens directly.
   • write_message/read_message are black-box calls into noiseprotocol.

2. Protocol name binds semantics

   • Current code uses Noise_XX_25519_ChaChaPoly_SHA256.
   • XXhfs introduces new tokens and transcript behavior not represented by existing classical pattern strings.

3. Lower risk than patching internals blindly

   • Depending on undocumented internal extension points in noiseprotocol would be brittle.
   • A local explicit handshake machine keeps behavior reviewable and testable in py-libp2p.

Recommended architecture

Implement a new path, for example:

• PatternXXHFS (or PatternNoisePQ) in libp2p/security/noise/patterns_pq.py
• TransportPQ (or protocol-selectable Transport) using /noise-pq/1.0.0
• explicit message A/B/C encode/decode logic with:
  • classical X25519 steps (XX-compatible identity checks),
  • KEM keygen/encap/decap for e1/ekem1,
  • explicit mix steps for KEM shared secret into chaining key.

Keep PatternXX unchanged for backward compatibility on /noise.

Optional future path

If noiseprotocol later gains first-class XXhfs support, py-libp2p can switch to it behind the same transport interface. The custom state machine can then be retired or kept as fallback.

---

2) For ML-KEM-768, liboqs-python (C bindings) vs pymlkem (pure Python)?

Short answer

Use a pluggable backend interface and ship with this policy:

• Primary production backend: liboqs-python (better maturity/performance/audit posture)
• Secondary fallback/backend for constrained environments: pure-Python implementation (pymlkem-class backend) behind explicit opt-in

Why this split is best

1. Security/perf reality

   • KEM is on the handshake critical path; pure Python is likely to be much slower and more variable.
   • Native/C-backed implementations are typically better tested for constant-time behavior.

2. Packaging and portability reality

   • Some users cannot or will not compile/install native crypto dependencies.
   • A pure Python fallback keeps development and CI unblockable.

3. Interop and testability

   • A backend abstraction allows deterministic vectors and interop tests independent of provider.

Concrete API shape

Create a narrow adapter, e.g.:

• IKem interface:
  • keygen() -> (pk, sk)
  • encapsulate(pk) -> (ct, ss)
  • decapsulate(ct, sk) -> ss
  • optional name/version metadata
• Backends:
  • kem_oqs.py
  • kem_py.py
• Selector:
  • default prefers oqs if present
  • env/config override for explicit backend

Dependency strategy

Do not hard-require PQ deps in core install initially. Use extras, e.g.:

• libp2p[pq-oqs]
• libp2p[pq-py]

This avoids breaking current users while enabling gradual adoption.

---

3) Does the combiner need to be extracted as a shared utility for future reuse?

Short answer

Yes. Extract the combiner (and related “mix into key schedule” primitives) into a standalone utility module from day one.

Why

1. Avoid embedding crypto glue in handshake flow

   • Keeps handshake control flow readable.
   • Reduces copy/paste if additional hybrid handshakes appear later.

2. Future-proofing

   • py-libp2p may later add other KEMs, different hybrids, or identity-level PQ transitions.
   • A reusable combiner module makes such evolution less risky.

3. Testability

   • Standalone deterministic tests for combiner correctness are easy to write and keep stable.

Suggested extraction boundaries

Create something like libp2p/security/noise/pq/ with:

• combiner.py
  • canonical combiner functions (domain-separated labels, strict input lengths/types, clear error handling)
• kdf.py (if needed)
  • explicit “mix secret into chaining key” helpers
• kem_interface.py
  • backend-agnostic KEM API
• transcript.py (optional)
  • transcript helpers and context-tag constants

Important: keep these modules independent from transport I/O to maximize reuse.

---

Practical migration plan for py-libp2p

1. Phase 1: Scaffolding

   • Add /noise-pq/1.0.0 transport entrypoint and feature flag.
   • Add IKem interface + dummy backend + tests.

2. Phase 2: Crypto core

   • Implement combiner utility and unit tests with fixed vectors.
   • Add first real backend (prefer oqs).

3. Phase 3: XXhfs state machine

   • Implement explicit A/B/C message flow and transcript updates.
   • Preserve existing libp2p identity signature verification semantics.

4. Phase 4: Interop

   • Add python<->js interop tests against js-libp2p-noise noiseHFS().
   • Validate wire format compatibility and failure modes.

5. Phase 5: Performance and hardening

   • Benchmark handshake latency and wire overhead against classical /noise.
   • Add strict limits/validation for large KEM payload components.

6. Phase 6: Release posture

   • Keep classical /noise default initially.
   • Document PQ mode as opt-in until interoperability and operational confidence are mature.

---

Risks and mitigations

• Risk: protocol drift from JS implementation

  • Mitigation: shared test vectors, mandatory interop CI.

• Risk: large handshake packets stress transports

  • Mitigation: explicit size checks and resource limits before allocation/decrypt.

• Risk: backend variability and supply-chain complexity

  • Mitigation: strict backend interface, pinned compatibility ranges, startup self-check logs.

• Risk: accidental security claims overreach

  • Mitigation: clear docs that hybrid security depends on correct implementation and backend quality.

---

Final recommendations (direct answers)

1. Pattern extensibility: Treat current noiseprotocol integration as non-extensible for custom tokens in practice; implement a dedicated XXhfs state machine path in py-libp2p.
2. ML-KEM backend choice: Use a pluggable backend; default to liboqs-python for production posture, with pure-Python backend as opt-in/fallback.
3. Combiner extraction: Yes, extract now into shared utilities (pq/combiner, pq/kem_interface, related helpers) to reduce risk and enable future hybrid/PQ reuse.

[paschal533]

Hi @acul71, yes Dozyio submitted RFC 710 to the libp2p specs repo two days ago covering ML-DSA peer identity: libp2p/specs#710. It is already getting detailed review from lidel and MarcoPolo. For the handshake side (XXhfs + X-Wing KEM), the Noise HFS extension spec is at https://github.com/noiseprotocol/noise_hfs_spec and the JS implementation is at ChainSafe/js-libp2p-noise 665.

[paschal533]

Thanks for the thorough analysis @acul71 The recommendation to build a dedicated XXhfs state machine rather than try to extend noiseprotocol aligns with what I mapped out in the roadmap. The pluggable IKem backend design makes sense too, especially with the optional extras approach to avoid breaking existing users. Happy to start on the implementation. Would it be useful to open a tracking issue here first?

[acul71]

yes thanks

[acul71]

@paschal533 Hold on on the traking issue, let's discuss more and wait for specs, so don't go right on just yet

[paschal533]

Hey @acul71, understood, no rush on the tracking issue. I'm just doing exploratory research and prototyping to figure out what could work while we wait for the spec to land. Nothing being merged yet.
I'll open a draft PR of the progress so far, Python and JS implementations passing the same test vectors byte-for-byte, plus a live TCP interop test, so people can poke at it, give feedback, or contribute if they're interested. All still very much WIP.

[paschal533]

Quick update for anyone following this thread. I have opened a draft PR with everything built so far so people can look at the code, run the tests, and give feedback without waiting for the spec discussion to fully resolve.

PR: #1310

What is in it:

• Full Noise XXhfs state machine in Python (PatternXXhfs, three-message A/B/C flow)
• X-Wing hybrid KEM (ML-KEM-768 + X25519) with a pluggable IKem interface
• 92 tests passing, including 47 cross-implementation vector tests that verify every byte of the handshake against deterministic vectors from js-libp2p-noise
• A live TCP interop script that completes a real handshake between a Python initiator and a JS responder
• Benchmarks showing 40.7 ms per handshake vs 4 ms classical (10x overhead at this stage, dominated by the pure-Python KEM)

One thing worth flagging for the broader discussion: the spec debate around libp2p/specs#710 and libp2p/specs#711 is about post-quantum peer identity keys and PeerID encoding. That is a separate concern from what this PR implements. The XXhfs handshake is about forward secrecy at the key exchange layer and keeps Ed25519 for identity exactly as it is today. When ML-DSA identity eventually lands it will be absorbed transparently because the signature step sits behind the existing privkey.sign() abstraction. The two tracks do not block each other.

All marked as draft and WIP. Happy to hear any thoughts on the design, the IKem interface, or anything else.