PCQ Messenger - Post-Quantum Secure Chat

A quantum-resistant messaging application with real-time encryption comparison dashboard.

🌟 Features

• 🔐 Real Kyber-512 Post-Quantum Encryption - Production-grade quantum-resistant cryptography
• 🛡️ Hybrid Encryption - Combines classical (X25519) + quantum-resistant (Kyber) for maximum security
• 💬 Multi-User Chat - Unlimited clients across different networks
• 🎨 Modern Web UI - Premium dark theme with real-time updates
• 📊 Live Monitoring Dashboard - Grafana dashboard comparing Classical vs PQ vs Hybrid encryption
• ⚡ Real-Time Metrics - Performance, security, and throughput comparison

🏗️ Architecture

┌─────────────┐         ┌─────────────┐         ┌─────────────┐
│   Client 1  │         │   Client 2  │         │   Client N  │
│  (Any Net)  │         │  (Any Net)  │         │  (Any Net)  │
└──────┬──────┘         └──────┬──────┘         └──────┬──────┘
       │                       │                       │
       └───────────────────────┼───────────────────────┘
                               │
                        ┌──────▼──────┐
                        │ Chat Server │
                        │  (Port 8080)│
                        └──────┬──────┘
                               │
                        ┌──────▼──────┐
                        │ Prometheus  │
                        │  (Port 9090)│
                        └──────┬──────┘
                               │
                        ┌──────▼──────┐
                        │   Grafana   │
                        │  (Port 3000)│
                        └─────────────┘
                        (Admin Only)

🚀 Quick Start

Prerequisites

• Python 3.8+
• Docker & Docker Compose (for admin monitoring)
• pip

1. Install Dependencies

pip install -r requirements.txt

2. Start the Server

On the server machine (or admin machine):

./run_server.sh

The server will start on 0.0.0.0:8080 (accessible from any network).

3. Start Admin Monitoring (Optional - Admin Only)

On the admin machine:

./run_admin.sh

This starts:

• Grafana at http://localhost:3000 (admin/admin)
• Prometheus at http://localhost:9090

The dashboard automatically loads with encryption comparison metrics.

4. Connect Clients

On any client machine:

./run_client.sh <server-ip>

Or simply:

./run_client.sh

Then enter:

• Server IP (e.g., 192.168.1.100 or your-server.com)
• Your username
• Encryption mode (Hybrid recommended)

The web interface will open automatically in your browser.

📊 Grafana Dashboard Metrics

The admin dashboard displays real-time comparisons:

Metric	Classical	Post-Quantum	Hybrid
Encryption Speed	⚡ Fastest	🐌 Slower	⚖️ Balanced
Security Level	🔑 128-bit classical	🔐 128-bit quantum	🛡️ 128-bit both
Key Size	📦 32 bytes	📦 1184 bytes	📦 Combined
Ciphertext Overhead	✅ Minimal	⚠️ Larger	⚖️ Moderate

🔒 Security Guarantees

Classical Encryption (X25519 + AES-256-GCM)

• ✅ Secure against classical computers
• ❌ Vulnerable to quantum computers (Shor's algorithm)
• 🎯 128-bit classical security

Post-Quantum Encryption (Kyber-512)

• ✅ Secure against quantum computers
• ✅ NIST-standardized (FIPS 203)
• 🎯 128-bit quantum security

Hybrid Encryption (Recommended)

• ✅ Secure if EITHER algorithm remains unbroken
• ✅ Defense-in-depth approach
• 🎯 Maximum security: max(classical, quantum)

🌐 Cross-Network Setup

Option 1: Public Server

1. Deploy server on a cloud VM (AWS, DigitalOcean, etc.)
2. Note the public IP
3. Clients connect using: ./run_client.sh <public-ip>

Option 2: Port Forwarding

1. Forward port 8080 on your router to server machine
2. Find your public IP: curl ifconfig.me
3. Clients connect using your public IP

Option 3: Tunneling (ngrok)

# On server machine
ngrok tcp 8080

# Use the ngrok URL in clients
./run_client.sh <ngrok-url>

📁 Project Structure

PCQ-messenger-backup/
├── app/
│   ├── crypto_classical.py    # X25519 + AES-GCM
│   ├── crypto_kyber.py         # Real Kyber-512 implementation
│   ├── crypto_hybrid.py        # Hybrid encryption
│   ├── server.py               # WebSocket chat server
│   ├── client.py               # CLI client
│   ├── web_ui.py               # Flask web interface
│   ├── metrics.py              # Prometheus metrics
│   └── networking.py           # Network utilities
├── static/
│   ├── style.css               # Premium dark theme
│   └── app.js                  # WebSocket client
├── templates/
│   └── chat.html               # Chat interface
├── monitoring/
│   ├── docker-compose.yml      # Monitoring stack
│   ├── prometheus.yml          # Prometheus config
│   ├── grafana-dashboard.json  # Pre-configured dashboard
│   └── grafana-provisioning/   # Auto-provisioning
├── run_server.sh               # Server launcher
├── run_client.sh               # Client launcher
├── run_admin.sh                # Admin monitoring launcher
└── requirements.txt            # Python dependencies

🛠️ Advanced Usage

CLI Client (No Browser)

python -m app.client ws://<server-ip>:8080 --username YourName --mode hybrid

Custom Ports

# Server
./run_server.sh 0.0.0.0 8080 9090

# Client web UI
python -m app.web_ui --port 5001

View Metrics Directly

# Server metrics
curl http://<server-ip>:9090/metrics

# Client metrics (if running)
curl http://localhost:8001/metrics

🔧 Troubleshooting

"Connection refused" error

• Check server is running: netstat -tulpn | grep 8080
• Check firewall: sudo ufw allow 8080
• Verify server IP is correct

Dependencies installation fails

# Install system dependencies for liboqs
sudo apt-get update
sudo apt-get install -y cmake ninja-build libssl-dev

# Then retry
pip install -r requirements.txt

Grafana dashboard not loading

# Restart monitoring stack
cd monitoring
docker-compose down
docker-compose up -d

📈 Performance Benchmarks

Typical performance on modern hardware:

Operation	Classical	Post-Quantum	Hybrid
Key Generation	~0.1ms	~0.5ms	~0.6ms
Encryption (1KB)	~0.05ms	~0.08ms	~0.09ms
Decryption (1KB)	~0.05ms	~0.08ms	~0.09ms
Handshake	~0.2ms	~1.0ms	~1.2ms

🤝 Contributing

This is a demonstration project showcasing post-quantum cryptography integration.

📄 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• liboqs - Open Quantum Safe project for Kyber implementation
• NIST - Post-Quantum Cryptography Standardization
• Grafana & Prometheus - Monitoring infrastructure

📞 Support

For issues or questions, please open an issue on the repository.

---

⚠️ Security Note: While this implementation uses production-grade cryptography libraries, it's designed for educational and demonstration purposes. For production deployments, conduct a thorough security audit.