🔐 ZKS Protocol

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

🌟 Why ZKS?

ZKS Protocol is the first post-quantum secure networking SDK with built-in anonymity through onion routing. Built with 100% safe Rust, it provides unbreakable encryption for the quantum computing era.

📑 Table of Contents

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

🌟 Key Features

🚀 Quick Start

📋 Prerequisites

• Rust 1.70+ toolchain
• OpenSSL (for development)

📥 Installation

Add to your Cargo.toml:

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

💻 Basic Connection (ZK://)

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(())
}

🧅 Anonymous Connection (ZKS://)

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::TrueVernam)
        .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(())
}

🌐 Browser (WebAssembly)

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);

🔒 Security Architecture

🔐 Cryptographic Primitives

🛡️ Security Levels

pub enum SecurityLevel {
    /// Classical cryptography (for testing only)
    Classical,
    
    /// Post-quantum secure (recommended for production)
    PostQuantum,
    
    /// Maximum security with TRUE random entropy
    TrueVernam,
}

🔄 3-Message Handshake

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

📦 Crate Structure

zks/
├── zks_sdk        # High-level SDK (start here!)
├── zks_crypt      # Wasif-Vernam cipher, drand integration
├── zks_pqcrypto   # ML-KEM-768, ML-DSA-65
├── zks_proto      # Handshake protocol, URL parsing
├── zks_wire       # Swarm networking, NAT traversal
├── zks_types      # Common type definitions
└── zks_wasm       # WebAssembly bindings

🧅 Anonymous Routing

The zks:// protocol provides onion routing through a decentralized swarm network:

┌────────┐    ┌─────────┐    ┌─────────┐    ┌─────────┐    ┌────────────┐
│ Client │───►│ Entry   │───►│ Middle  │───►│ Exit    │───►│ Destination│
│        │    │ Relay   │    │ Relay   │    │ Relay   │    │            │
└────────┘    └─────────┘    └─────────┘    └─────────┘    └────────────┘
     │              │              │              │               │
     └──encrypted──►└──encrypted──►└──encrypted──►└──plaintext───►│

Features

• Multi-hop routing: Configurable number of relay hops (default: 3)
• Layered encryption: Each hop can only decrypt its layer
• Traffic analysis resistance: Optional scrambling mode
• Peer discovery: Automatic swarm network formation

📱 Platform Support

📖 Examples

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

🌐 What Can You Build?

🛡️ Security

Security Model

• Post-quantum resistance: All key exchanges use NIST-standardized algorithms
• Forward secrecy: Session keys are derived per-connection
• Zero trust: End-to-end encryption with mutual authentication
• Memory safety: 100% safe Rust, no unsafe code in core crates

Responsible Disclosure

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

See SECURITY.md for our full security policy.

🧪 Testing

# 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

🤝 Contributing

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

📜 License

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

See LICENSE for the full license text.

📞 Contact

• GitHub Issues: Report bugs and request features
• Security: security@zks-protocol.org

Built with ❤️ for a quantum-safe future

_{Protecting your privacy today, and tomorrow.}