Quantum Secure Email Client - Complete Setup Guide
A comprehensive quantum-resistant email client with multi-layer encryption including AES-256-GCM, One-Time Pad (OTP), and Post-Quantum Cryptography (PQC) using CRYSTALS-Kyber.
🏗️ Architecture Overview
This application consists of multiple components working together:
- Frontend: Flutter desktop application (Windows)
- Backend: .NET 8 Web API with authentication and email management
- Database: PostgreSQL for user authentication and email storage
-
Crypto Services: Multiple Python services for different encryption layers
- Key Manager (Port 2020): Manages quantum keys
- OTP API (Port 2021): One-Time Pad encryption/decryption
- AES Server (Port 2022): AES-256-GCM encryption/decryption
- Main Backend API (Port 5001): Handles PQC operations and all email functionality
📋 Prerequisites
Before setting up the application, ensure you have the following installed:
Required Software
- PostgreSQL 17+ - Database server
- .NET 8 SDK - Backend API runtime
- Flutter SDK 3.8.1+ - Frontend development framework
- Python 3.8+ - Crypto services runtime
- Git - Version control (for cloning the repository)
Python Dependencies
pip install flask flask-cors requests cryptography
🚀 Quick Start
1. Clone the Repository
git clone <repository-url> cd quantum
2. Database Setup
Install PostgreSQL
- Download and install PostgreSQL 17+ from postgresql.org
- During installation, remember the password you set for the
postgresuser
Create Database and User
-- Connect to PostgreSQL as superuser psql -U postgres -- Create database CREATE DATABASE quantum_auth; -- Create user (optional, you can use postgres user) CREATE USER quantum_user WITH PASSWORD 'your_password_here'; -- Grant privileges GRANT ALL PRIVILEGES ON DATABASE quantum_auth TO quantum_user; -- Connect to the database \c quantum_auth -- Run the schema files \i database/schema.sql \i database/email_schema.sql
Alternative: Use provided SQL files
# Windows (PowerShell) psql -U postgres -d quantum_auth -f database/schema.sql psql -U postgres -d quantum_auth -f database/email_schema.sql # Linux/Mac psql -U postgres -d quantum_auth -f database/schema.sql psql -U postgres -d quantum_auth -f database/email_schema.sql
3. Environment Configuration
Generate Secure Secrets
Before creating the .env file, generate secure secrets:
# Generate a secure JWT secret key (32+ characters) # You can use online tools or generate one with: openssl rand -base64 32 # Generate an application secret key (32 characters, base64 encoded) openssl rand -base64 24
Copy the example environment file and configure it:
# Copy the example file copy env.example .env # Edit the .env file with your actual credentials notepad .env
Create a .env file in the root directory:
# Database Configuration DB_HOST=localhost DB_PORT=5432DB_PORT=5437DB_NAME=quantum_auth DB_USERNAME=postgres DB_PASSWORD=your_postgres_password_here # JWT Configuration JWT_SECRET_KEY=your-super-secret-jwt-key-here-must-be-at-least-32-characters-long-for-security JWT_ISSUER=QuMail JWT_AUDIENCE=QuMail-Users JWT_EXPIRES_MINUTES=60 # Application Secret (Generate a new 32-character base64 key) APP_SECRET_KEY=your-base64-encoded-secret-key-here
4. Build and Start Services
Option A: Automated Setup (Windows)
# Start all services automatically
start_server.bat
Option B: Manual Setup
Step 1: Start Crypto Services
# Terminal 1 - Key Manager (Port 2020) cd Key_Manager/km python server.py # Terminal 2 - OTP API (Port 2021) cd level1 python otp_api_test.py # Terminal 3 - AES Server (Port 2022) cd level2new python server2.py
Step 2: Start Backend API
# Terminal 4 - Backend API (Port 5001) cd Email_client/QuMail.EmailProtocol dotnet run --urls "http://localhost:5001"
Step 3: Start Frontend
# Terminal 5 - Flutter Frontend cd frontend flutter pub get flutter run -d windows
🔧 Detailed Setup Instructions
Database Setup (Detailed)
Windows PostgreSQL Setup
- Download PostgreSQL installer from postgresql.org
- Run the installer and follow the setup wizard
- Set a strong password for the
postgressuperuser - Add PostgreSQL to your PATH environment variable
- Verify installation:
psql --version
Create Database Schema
-- Connect to PostgreSQL psql -U postgres -- Create the application database CREATE DATABASE quantum_auth; -- Connect to the new database \c quantum_auth -- Create tables for authentication CREATE TABLE IF NOT EXISTS users ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), email VARCHAR(255) UNIQUE NOT NULL, password_hash VARCHAR(255) NOT NULL, name VARCHAR(255) NOT NULL, avatar_url TEXT, is_active BOOLEAN DEFAULT true, email_verified BOOLEAN DEFAULT false, created_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, updated_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP, last_login_at TIMESTAMP WITH TIME ZONE ); -- Create emails table CREATE TABLE IF NOT EXISTS emails ( id UUID PRIMARY KEY DEFAULT gen_random_uuid(), sender_email VARCHAR(255) NOT NULL, recipient_email VARCHAR(255) NOT NULL, subject VARCHAR(500) NOT NULL, body TEXT NOT NULL, sent_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP, is_read BOOLEAN DEFAULT FALSE ); -- Create indexes for performance CREATE INDEX IF NOT EXISTS idx_users_email ON users(email); CREATE INDEX IF NOT EXISTS idx_emails_recipient ON emails(recipient_email); CREATE INDEX IF NOT EXISTS idx_emails_sender ON emails(sender_email); -- Insert test user (password: 'password123') INSERT INTO users (email, password_hash, name, email_verified) VALUES ( 'test@example.com', '$2b$12$LQv3c1yqBWVHxkd0LHAkCOYz6TtxMQJqhN8/LewdBPj4o4tQ8.7C.', 'Test User', true ) ON CONFLICT (email) DO NOTHING;
Backend Setup (Detailed)
Install .NET 8 SDK
- Download .NET 8 SDK from dotnet.microsoft.com
- Run the installer
- Verify installation:
dotnet --version
Configure Backend
-
Navigate to the backend directory:
cd Email_client/QuMail.EmailProtocol -
Restore dependencies:
dotnet restore
-
Build the project:
dotnet build
-
Run the backend:
dotnet run --urls "http://localhost:5001"
Frontend Setup (Detailed)
Install Flutter SDK
- Download Flutter SDK from flutter.dev
- Extract to a directory (e.g.,
C:\flutter) - Add Flutter to your PATH environment variable
- Verify installation:
flutter doctor
Configure Frontend
-
Navigate to the frontend directory:
cd frontend -
Install dependencies:
flutter pub get
-
Run the application:
flutter run -d windows
Crypto Services Setup (Detailed)
Python Dependencies
Install required Python packages:
pip install flask flask-cors requests cryptography
Key Manager Service
cd Key_Manager/km
python server.py
- Runs on:
http://localhost:2020 - Manages quantum keys for encryption
- Stores keys in
key_store.json
OTP API Service
cd level1
python otp_api_test.py
- Runs on:
http://localhost:2021 - Provides One-Time Pad encryption/decryption
- Requires
encoder.exein the same directory
AES Server Service
cd level2new
python server2.py
- Runs on:
http://localhost:2022 - Provides AES-256-GCM encryption/decryption
- Integrates with Key Manager for key exchange
Backend API Service (Handles PQC Operations)
cd Email_client/QuMail.EmailProtocol dotnet run --urls "http://localhost:5001"
- Runs on:
http://localhost:5001 - Provides Post-Quantum Cryptography operations via PQCController
- Uses CRYSTALS-Kyber algorithm
- Handles all email functionality and authentication
🔍 Verification & Testing
Check Service Health
# Check if all services are running
curl http://localhost:5001/api/health
curl http://localhost:2020/health
curl http://localhost:2021/api/otp/health
curl http://localhost:2022/api/health
Test User Credentials
-
Email:
test@example.com -
Password:
password123
Create New User
You can create new users through the registration endpoint:
curl -X POST http://localhost:5001/api/auth/register \ -H "Content-Type: application/json" \ -d '{ "email": "newuser@example.com", "password": "newpassword123", "name": "New User" }'
🚨 Troubleshooting
Common Issues
Database Connection Issues
# Check if PostgreSQL is running pg_ctl status # Restart PostgreSQL service (Windows) net stop postgresql-x64-17 net start postgresql-x64-17 # Check database connection psql -U postgres -d quantum_auth -c "SELECT version();"
Port Conflicts
If you encounter port conflicts, check what's using the ports:
# Windows netstat -ano | findstr :5001 netstat -ano | findstr :2020 netstat -ano | findstr :2021 netstat -ano | findstr :2022 netstat -ano | findstr :2023 # Kill process by PID taskkill /F /PID <process_id>
Flutter Build Issues
# Clean Flutter cache flutter clean flutter pub get # Check Flutter doctor flutter doctor # Rebuild flutter build windows
.NET Build Issues
# Clean .NET cache dotnet clean dotnet restore dotnet build # Check .NET version dotnet --list-sdks dotnet --list-runtimes
Log Files
Check log files in the logs/ directory for detailed error information:
-
key_manager.log- Key Manager service logs -
otp_api.log- OTP API service logs -
aes_server.log- AES Server logs -
pqc_server.log- PQC Server logs
📁 Project Structure
quantum/
├── database/ # Database schema files
│ ├── schema.sql # Authentication tables
│ └── email_schema.sql # Email tables
├── Email_client/ # .NET Backend API
│ └── QuMail.EmailProtocol/
│ ├── Controllers/ # API controllers
│ ├── Services/ # Business logic services
│ ├── Models/ # Data models
│ └── appsettings.json # Configuration
├── frontend/ # Flutter frontend application
│ ├── lib/ # Dart source code
│ ├── pubspec.yaml # Flutter dependencies
│ └── ...
├── Key_Manager/ # Key management service
│ └── km/
│ └── server.py # Key Manager API
├── level1/ # OTP encryption service
│ ├── otp_api_test.py # OTP API server
│ └── encoder.exe # OTP encoder binary
├── level2new/ # AES encryption service
│ ├── server2.py # AES API server
│ └── aes_gcm_demo.exe # AES GCM binary
├── logs/ # Service log files
├── start_server.bat # Windows startup script
├── start_backend.bat # Backend startup script
└── README.md # This file
🔐 Security Considerations
Environment Variables
- NEVER commit
.envfiles to version control - Use strong, unique passwords for database access
- Generate secure JWT secret keys (minimum 32 characters)
- Generate unique application secret keys for each deployment
- Rotate secrets regularly in production
- Use environment-specific configurations
- Consider using secret management services in production
.gitignore File
A .gitignore file has been created in the root directory to prevent committing sensitive files. It includes:
- Environment files (
.env,.env.local, etc.) - Database files and logs
- Key stores and temporary files
- Build outputs and IDE files
The .gitignore file is already included in the repository.
Database Security
- Use strong PostgreSQL passwords
- Limit database user privileges
- Enable SSL connections in production
- Regular database backups
Application Security
- Keep all dependencies updated
- Use HTTPS in production environments
- Implement proper input validation
- Monitor logs for suspicious activity
🚀 Production Deployment
Environment Setup
- Use environment variables for all sensitive configuration
- Set up proper logging and monitoring
- Configure reverse proxy (nginx/Apache)
- Enable SSL/TLS certificates
- Set up database replication and backups
Performance Optimization
- Configure connection pooling
- Implement caching strategies
- Optimize database queries
- Use CDN for static assets
- Monitor resource usage
📞 Support
If you encounter issues during setup:
- Check the troubleshooting section above
- Review log files in the
logs/directory - Verify all services are running on correct ports
- Ensure all dependencies are properly installed
- Check database connectivity and schema
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
Happy Coding! 🚀
For additional help or questions, please refer to the project documentation or create an issue in the repository.
0 commit comments