Zero Knowledge Swarm — Post-Quantum Encryption with Built-in Anonymity

ZKS Protocol is a post-quantum secure networking protocol with a memory-safe architecture built on high-assurance foundations. It provides defense-in-depth encryption with multiple layers of security, including 256-bit post-quantum computational security.

• 🌟 Key Features
• 🚀 Quick Start
• 🔒 Security Architecture
• 📦 Crate Structure
• 🧅 Anonymous Routing
• 📱 Platform Support
• 📖 Examples
• 🛡️ Security
• 🤝 Contributing
• 📜 License

ZKS Protocol's security is proven by mathematics, not assumptions:

Hybrid Encryption (Network Mode):
  DEK ← CSPRNG(32 bytes)              // Data Encryption Key
  entropy ← drand ⊕ local_CSPRNG      // Computational security (256-bit)
  wrapped_DEK ← DEK ⊕ entropy         // Defense-in-depth

Security Level: 256-bit post-quantum computational (OTP-inspired, not true OTP)

∴ Secure against all known attacks including quantum computers ∎

⚠️ IMPORTANT: Network-mode entropy (drand + CSPRNG) provides 256-bit computational security, not information-theoretic security.

📄 Full Security Documentation

• Rust 1.70+ toolchain
• OpenSSL (for development)

Add to your Cargo.toml:

[dependencies]
zks_sdk = "0.1"
tokio = { version = "1", features = ["full"] }

use zks_sdk::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build a post-quantum secure connection
    let connection = ZkConnectionBuilder::new()
        .url("zk://secure-server.example.com:8443")
        .security(SecurityLevel::PostQuantum)
        .build()
        .await?;
    
    println!("✅ Connected with post-quantum encryption!");
    
    // Send encrypted data
    connection.send(b"Hello, quantum-proof world!").await?;
    
    // Receive response
    let response = connection.recv().await?;
    println!("📩 Received: {:?}", response);
    
    connection.close().await?;
    Ok(())
}

use zks_sdk::prelude::*;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Build an anonymous swarm-routed connection
    let connection = ZksConnectionBuilder::new()
        .url("zks://hidden-service.example.com:8443")
        .min_hops(3)  // Route through 3+ relay nodes
        .security(SecurityLevel::PostQuantum)
        .build()
        .await?;
    
    println!("🧅 Anonymous connection established!");
    println!("   Your IP is hidden from the destination server.");
    
    // Send anonymous message
    connection.send(b"Confidential message").await?;
    
    connection.close().await?;
    Ok(())
}

import init, { ZksWasmUtils } from 'zks-wasm';

await init();

// Generate post-quantum keypair
const keypair = ZksWasmUtils.generate_ml_dsa_keypair();
console.log("🔑 Generated ML-DSA keypair");

// Sign a message
const message = new TextEncoder().encode("Hello from the browser!");
const signature = ZksWasmUtils.ml_dsa_sign(message, keypair.signing_key);
console.log("✍️ Signature created");

// Verify signature
const isValid = ZksWasmUtils.ml_dsa_verify(message, signature, keypair.verifying_key);
console.log("✅ Signature valid:", isValid);

ZKS Protocol achieves 256-bit post-quantum security through defense-in-depth:

Hybrid Encryption Architecture

• Key wrapping: DEK XORed with drand ⊕ CSPRNG entropy
• Bulk encryption: Content encrypted with ChaCha20-Poly1305(DEK)
• Defense-in-depth: Multiple independent entropy sources
• Result: 256-bit computational security, quantum-resistant

Entropy Budget (Network Mode):

• ✅ All messages: 256-bit computational security via drand ⊕ CSPRNG (OTP-inspired)
• ℹ️ Entropy source: drand beacon + local CSPRNG provides 256-bit post-quantum computational security

Mathematical Foundation (Computational Security):

• Defense-in-depth: XOR of drand beacon and local CSPRNG provides 256-bit computational security
• No single point of failure: Secure if either entropy source is uncompromised
• Post-quantum: ML-KEM-1024 key exchange resists quantum attacks
• Important distinction: This provides computational security (OTP-inspired), not information-theoretic security

Protocol-Level Anonymity:

• Session rotation: Sessions become cryptographically unlinkable
• Per-message key derivation: Forward secrecy within sessions
• Cover traffic: Constant bandwidth prevents timing analysis

Fallback (if drand unavailable):

• 256-bit ChaCha20-Poly1305: Computationally secure, quantum-resistant
• Landauer limit: Brute-force energy requirements make attacks impractical

┌──────────────┐                           ┌──────────────┐
│   Initiator  │                           │  Responder   │
└──────┬───────┘                           └──────┬───────┘
       │                                          │
       │  1. HandshakeInit                        │
       │  ─────────────────────────────────────►  │
       │  [ephemeral_pk, nonce]                   │
       │                                          │
       │  2. HandshakeResponse                    │
       │  ◄─────────────────────────────────────  │
       │  [ephemeral_pk, ciphertext, signature]   │
       │                                          │
       │  3. HandshakeFinish                      │
       │  ─────────────────────────────────────►  │
       │  [confirmation_hash]                     │
       │                                          │
       ▼                                          ▼
   [shared_secret derived]                [shared_secret derived]

zks/
├── zks_sdk        # High-level SDK (start here!)
├── zks_crypt      # Wasif-Vernam cipher, drand integration
├── zks_pqcrypto   # ML-KEM-1024, ML-DSA-87 (NIST Level 5)
├── zks_proto      # Handshake protocol, URL parsing
├── zks_wire       # Swarm networking, NAT traversal
├── zks_types      # Common type definitions
├── zks_wasm       # WebAssembly bindings
├── zks_surb       # Single-Use Reply Blocks for anonymous replies

The zks:// protocol provides onion routing through a decentralized swarm network using the novel Faisal Swarm Topology:

┌────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌────────────┐
│ Client │───►│ Guard   │───►│ Middle  │───►│ Exit    │───►│ Destination│
│        │    │ (Entry) │    │ (Relay) │    │ (Exit)  │    │            │
└────────┘    └─────────┘    └─────────┘    └─────────┘    └────────────┘
     │              │              │              │               │
     └─Wasif-Vernam►└─Wasif-Vernam►└─Wasif-Vernam►└─plaintext────►│

• Multi-hop routing: Configurable number of relay hops (default: 3)
• Layered encryption: Each hop uses independent Wasif-Vernam cipher
• Persistent cipher state: Arc<RwLock<WasifVernam>> for proper nonce management
• Traffic analysis resistance: Fixed 512-byte cell sizes + random padding
• Anti-replay protection: Bitmap-based per-layer protection
• Peer discovery: Automatic swarm network formation via libp2p

The examples/ directory contains complete working examples:

# Basic encrypted connection
cargo run --example basic_connection

# Anonymous swarm-routed connection
cargo run --example anonymous_connection

# Secure file transfer
cargo run --example file_transfer

• Post-quantum resistance: All key exchanges use NIST-standardized ML-KEM-1024
• Defense-in-depth: DEK wrapped with drand ⊕ CSPRNG (256-bit computational)
• Forward secrecy: Session keys are derived per-connection with recursive key chains
• Zero trust: End-to-end encryption with mutual authentication
• Memory safety: Memory-safe architecture, leveraging Rust's ownership model with minimal, audit-friendly unsafe code for cryptographic primitives.

ZKS Protocol achieves 256-bit computational security through defense-in-depth:

Mathematical Foundation: XOR of independent entropy sources provides computational security.

Entropy Sources (Network Mode):

• Local CSPRNG: OS entropy pool (Windows BCrypt, Linux /dev/urandom)
• drand beacon: BLS12-381 verified randomness from 18+ distributed operators

These two sources are XORed together for defense-in-depth.

Entropy Grid (Hierarchical Distribution):

The Entropy Grid distributes drand rounds across the swarm to reduce API load:

Fetch Order:
1. Local Cache     → Fastest (in-memory)
2. Swarm Peers     → P2P via GossipSub
3. IPFS            → Decentralized storage
4. drand API       → Final fallback

Note: The Entropy Grid distributes drand data—it does not contribute additional entropy sources. The XOR combination is: drand ⊕ local_CSPRNG.

Security Properties:

• Hybrid key wrapping: DEK wrapped with drand ⊕ CSPRNG entropy, bulk data with ChaCha20
• Security chain: Breaking encryption requires compromising both entropy sources
• Session rotation: Auto-rotate every 10 min for cryptographic unlinkability
• Fallback: ChaCha20 if drand unavailable (still post-quantum secure)

Defense-in-Depth Operation: System combines multiple entropy sources (drand + local CSPRNG) for strong computational security.

Critical Distinction: Network mode provides 256-bit computational security - resistant to quantum computers but theoretically breakable with sufficient computational power

For messages >32 bytes, ZKS Protocol provides 256-bit computational security through ChaCha20-Poly1305, with security bounds derived from fundamental physical constraints:

The Physics Argument (Computational Security):

• Landauer Limit: Minimum energy required to erase 1 bit = kT ln(2) ≈ 3×10⁻²¹ J
• 256-bit key space: 2²⁵⁶ ≈ 1.16×10⁷⁷ possible keys
• Minimum brute-force energy: ~3.5×10⁵⁶ Joules

Cosmic Scale Comparison:

• Total energy output of Sun over its lifetime: ~1.2×10⁴⁴ J
• Total energy in observable universe: ~4×10⁶⁹ J
• Required energy exceeds universal energy by ~10¹³ times

Time Requirements (even at theoretical maximum efficiency):

• At Planck time per operation: ~6.3×10³³ seconds
• Age of universe: ~4.3×10¹⁷ seconds
• Would require ~10¹⁶ universe lifetimes

Quantum Computing Limitations:

• Grover's algorithm provides only √N speedup (2¹²⁸ operations instead of 2²⁵⁶)
• Still requires energy exceeding total cosmic output by billions of times
• Quantum decoherence and error correction make this practically impossible

Conclusion: Messages >32 bytes are computationally secure with security bounds that make brute-force attacks physically impractical, providing 256-bit post-quantum computational security (NOT information-theoretic security).

Please report security vulnerabilities to: security@zks-protocol.org

See SECURITY.md for our full security policy.

ZKS Protocol provides competitive performance while maintaining 256-bit post-quantum computational security:

For detailed benchmarks, see BENCHMARKS.md.

# Run performance benchmarks
cargo bench -p zks_crypt
cargo bench -p zks_wire --bench onion_routing_bench

# Run all tests
cargo test --workspace

# Run specific crate tests
cargo test -p zks_sdk
cargo test -p zks_crypt

# Run integration tests
cargo test --test integration_tests

Contributions are welcome! Here's how to get started:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please ensure your code:

• ✅ Follows Rust best practices
• ✅ Includes appropriate tests
• ✅ Has documentation for public APIs
• ✅ Passes all CI checks

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See LICENSE for the full license text.

• GitHub Issues: Report bugs and request features
• Security: md.wasif.faisal@g.bracu.ac.bd

Cloudflare Project Alexandria

_{🚀 Infrastructure support from Cloudflare Project Alexandria — Supporting open-source innovation}

The ZKS Protocol provides two security tiers:

1. Network Mode: 256-bit post-quantum computational security via ML-KEM + ChaCha20

Key Properties:

• No computational assumptions: Security relies on mathematical laws, not hardness assumptions
• Quantum-resistant: Immune to both classical and quantum attacks
• Forward secrecy: Recursive key chains prevent retrospective decryption
• Trustless design: No single point of failure or trusted third parties required

Built with ❤️ for a quantum-safe future

_{Protecting your privacy today, and tomorrow.}