quantumgo

README

Quantum-Go

Quantum-Resistant VPN Encryption using Cascaded Hybrid KEM (CH-KEM)

---

Overview

Quantum-Go is a production-ready, quantum-resistant VPN encryption library implementing a novel Cascaded Hybrid Key Encapsulation Mechanism (CH-KEM). It provides defense-in-depth security by combining:

• ML-KEM-1024 (NIST FIPS 203) - Post-quantum lattice-based cryptography
• X25519 (RFC 7748) - Classical elliptic curve Diffie-Hellman
• SHAKE-256 (NIST FIPS 202) - Cryptographic key derivation

Security Properties

Property	Status
Post-Quantum Security	ML-KEM-1024 (NIST Category 5)
Classical Security	X25519 (128-bit)
Hybrid Guarantee	Secure if EITHER algorithm is secure
Forward Secrecy	Ephemeral keys per session (and per rekey)
Session Resumption	Encrypted tickets with secure abbreviated handshake
FIPS 140-3	Build mode with POST/CST self-tests (docs)

Features

Core Cryptography

• Hybrid CH-KEM key exchange (ML-KEM-1024 + X25519)
• AES-256-GCM and ChaCha20-Poly1305 cipher suites
• Automatic session rekeying with replay protection

FIPS 140-3 Compliance

• FIPS build mode via -tags fips (AES-GCM only)
• Power-On Self-Tests (POST) - KAT verification at module load
• Conditional Self-Tests (CST) - Pairwise consistency and RNG health checks
• Runtime compliance verification with crypto.FIPSMode()

Production Hardening

• Connection pooling with health checking
• Buffer pooling (75%+ allocation reduction)
• Per-IP rate limiting and DoS protection
• Prometheus metrics and OpenTelemetry tracing

Quick Start

go get github.com/pzverkov/quantum-go

import "github.com/pzverkov/quantum-go/pkg/tunnel"

// Server
listener, _ := tunnel.Listen("tcp", ":8443", nil)
conn, _ := listener.Accept()

// Client
conn, _ := tunnel.Dial("tcp", "server:8443", nil)

For FIPS mode, build with:

go build -tags fips ./...

See Quick Start Guide for detailed examples.

Documentation

Guide	Description
Quick Start	Installation and basic usage
FIPS Compliance	FIPS 140-3 build mode and self-tests
Configuration	Tuning timeouts, rate limiting, and sessions
CLI Reference	Using quantum-vpn for demos and benchmarks
Architecture	CH-KEM protocol and security design
Roadmap	Development roadmap and compliance plans

Performance

Optimized with SIMD/Assembly (AES-NI, AVX2/AVX-512, hardware SHA3). Benchmarked with Go 1.26 (Green Tea GC, ~18% faster ML-KEM).

Platform	Handshakes/sec	Throughput (AES-GCM)
Apple Silicon (M1 Pro, early generation)	~2,050	~2.5 GB/s
Cloud instance (c6i.xlarge)	2,000-2,800	3-5 GB/s
Mid-range server (Xeon Silver)	2,800-3,800	4-7 GB/s
Enterprise (Xeon Platinum / EPYC)	3,800-5,500	8-12 GB/s

Run quantum-vpn benchmark on your target hardware. See CLI Reference.

Contributing

Contributions welcome! See CONTRIBUTING.md for:

• Development setup
• Test suite (unit, integration, fuzz)
• PR process

License

MIT License - see LICENSE.

---

Compliance & Liability

IMPORTANT: By using, cloning, or forking this repository, you acknowledge and agree to the following:

Export Controls

This software implements ECCN 5D002 dual-use cryptographic technology. Users are solely responsible for compliance with:

• US: Export Administration Regulations (EAR). Access by foreign nationals may constitute a "deemed export."
• EU: Dual-Use Regulation (EU 2021/821). Open-source exemptions may apply.
• Other: Local import/export regulations (e.g., French ANSSI declaration, UK SPIRE licensing).

FIPS Validation Status

This library implements FIPS 203/202 parameters with Power-On and Conditional Self-Tests. However, it is NOT a FIPS 140-3 validated cryptographic module. Federal agencies and regulated industries requiring FIPS validation must treat this as research-grade software.

Jurisdiction Restrictions

Strong encryption is restricted or regulated in certain jurisdictions (e.g., China, Russia, UAE, Saudi Arabia). This software must not be used to bypass telecommunications regulations. Users deploying in restricted regions assume full responsibility for legal compliance.

No Warranty

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY ARISING FROM THE USE OF THIS SOFTWARE.

No Legal Advice

Nothing in this repository - including documentation, compliance references, FIPS implementation details, and regulatory guidance - constitutes legal, regulatory, or compliance advice. Users should consult qualified legal counsel for guidance on applicable laws and regulations in their jurisdiction.

User Responsibility

By using, cloning, forking, or incorporating this software, you acknowledge that you are solely responsible for determining its legality in your jurisdiction and for compliance with all applicable laws, regulations, and standards. The authors and copyright holders bear no responsibility for how this software is used or deployed.

See ROADMAP.md for regulatory references covering 15+ jurisdictions.

Documentation

Overview

Package quantumgo provides quantum-resistant VPN encryption using Cascaded Hybrid KEM (CH-KEM).

Quantum-Go combines ML-KEM-1024 (NIST FIPS 203) post-quantum cryptography with X25519 classical cryptography for defense-in-depth security against both classical and quantum attacks.

Quick Start

For a complete VPN tunnel with handshake:

import "github.com/pzverkov/quantum-go/pkg/tunnel"

// Server
listener, _ := tunnel.Listen("tcp", ":8443")
conn, _ := listener.Accept()
data, _ := conn.Receive()

// Client
client, _ := tunnel.Dial("tcp", "localhost:8443")
client.Send([]byte("Hello!"))

For low-level CH-KEM key encapsulation:

import "github.com/pzverkov/quantum-go/pkg/chkem"

keyPair, _ := chkem.GenerateKeyPair()
ciphertext, sharedSecret, _ := chkem.Encapsulate(keyPair.PublicKey())
recoveredSecret, _ := chkem.Decapsulate(ciphertext, keyPair)

Package Structure

The library is organized into several packages:

• pkg/chkem: High-level CH-KEM key encapsulation API
• pkg/crypto: Low-level cryptographic primitives (ML-KEM, X25519, KDF, AEAD)
• pkg/tunnel: VPN tunnel with handshake protocol and encrypted transport
• pkg/protocol: Wire protocol message definitions and encoding
• internal/constants: Security parameters and protocol constants
• internal/errors: Custom error types for detailed error handling

Security Properties

The CH-KEM construction provides:

• Post-quantum security: ML-KEM-1024 (NIST Category 5, ~256-bit security)
• Classical security: X25519 ECDH (128-bit security)
• Hybrid guarantee: Secure if EITHER algorithm is secure
• Forward secrecy: Ephemeral keys generated for each session
• Authenticated encryption: AES-256-GCM or ChaCha20-Poly1305
• Replay protection: Sliding window with sequence numbers

Testing

The library includes comprehensive tests:

go test ./...                                    # All tests
go test -fuzz=FuzzParsePublicKey ./test/fuzz/  # Fuzz tests
go test -run TestKAT ./pkg/crypto              # Known Answer Tests
go test -bench=. ./test/benchmark              # Benchmarks

Performance

Typical performance on modern hardware (AMD64):

• CH-KEM key generation: ~800 µs
• CH-KEM encapsulation: ~900 µs
• CH-KEM decapsulation: ~1000 µs
• AES-256-GCM encryption: ~2 GB/s (hardware-accelerated)
• ChaCha20-Poly1305: ~800 MB/s (software)

References

• NIST FIPS 203: Module-Lattice-Based Key-Encapsulation Mechanism Standard
• RFC 7748: Elliptic Curves for Security
• NIST FIPS 202: SHA-3 Standard (SHAKE-256)

For more information, see: https://github.com/pzverkov/quantum-go