QuMail - Quantum Secure Email Client

A secure email client that implements multiple layers of encryption including AES-256-GCM, One-Time Pad (OTP), and Post-Quantum Cryptography (PQC) using CRYSTALS-Kyber to protect against both classical and quantum computer attacks.

Architecture Overview

This application consists of multiple components working together to provide end-to-end encryption:

• Frontend: Flutter desktop application for Windows
• Backend: .NET 8 Web API handling authentication and email management
• Database: PostgreSQL for user authentication and email storage
• Crypto Services: Multiple Python services for different encryption layers
  • Key Manager: Manages quantum cryptographic keys
  • OTP API: One-Time Pad encryption/decryption
  • AES Server: AES-256-GCM encryption/decryption
  • PQC Server: Post-Quantum Cryptography operations
  • Main Backend API: Handles all email functionality and authentication

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 Qunatum-Secure-Email-Client

2. Database Setup

Install PostgreSQL

• Download and install PostgreSQL 17+ from postgresql.org
• During installation, remember the password you set for the postgres user

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=5432
DB_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
cd Key_Manager/km
python server.py

# Terminal 2 - OTP API
cd level1
python otp_api_test.py

# Terminal 3 - AES Server
cd level2new
python server2.py

# Terminal 4 - PQC Server
cd level3
python pqc_server.py

Step 2: Start Backend API

# Terminal 5 - Backend API
cd Email_client/QuMail.EmailProtocol
dotnet run

Step 3: Start Frontend

# Terminal 6 - Flutter Frontend
cd frontend
flutter pub get
flutter run -d windows

Detailed Setup Instructions

Database Setup (Detailed)

Windows PostgreSQL Setup

1. Download PostgreSQL installer from postgresql.org
2. Run the installer and follow the setup wizard
3. Set a strong password for the postgres superuser
4. Add PostgreSQL to your PATH environment variable
5. 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

1. Download .NET 8 SDK from dotnet.microsoft.com
2. Run the installer
3. Verify installation:

   dotnet --version

Configure Backend

1. Navigate to the backend directory:

   cd Email_client/QuMail.EmailProtocol

2. Restore dependencies:

   dotnet restore

3. Build the project:

   dotnet build

4. Run the backend:

   dotnet run

Frontend Setup (Detailed)

Install Flutter SDK

1. Download Flutter SDK from flutter.dev
2. Extract to a directory (e.g., C:\flutter)
3. Add Flutter to your PATH environment variable
4. Verify installation:

   flutter doctor

Configure Frontend

1. Navigate to the frontend directory:

   cd frontend

2. Install dependencies:

   flutter pub get

3. 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

• Manages quantum keys for encryption
• Stores keys in key_store.json

OTP API Service

cd level1
python otp_api_test.py

• Provides One-Time Pad encryption/decryption
• Requires encoder.exe in the same directory

AES Server Service

cd level2new
python server2.py

• Provides AES-256-GCM encryption/decryption
• Integrates with Key Manager for key exchange

PQC Server Service

cd level3
python pqc_server.py

• Provides Post-Quantum Cryptography operations
• Uses CRYSTALS-Kyber algorithm

Backend API Service

cd Email_client/QuMail.EmailProtocol
dotnet run

• Handles all email functionality and authentication
• Integrates with all crypto services

Verification & Testing

Check Service Health

# Check if all services are running
# Replace with actual URLs shown in service startup logs
curl http://localhost:2020/health
curl http://localhost:2021/api/otp/health
curl http://localhost:2022/api/health
curl http://localhost:2023/health

Test User Credentials

• Email: test@example.com
• Password: password123

Create New User

You can create new users through the registration endpoint:

# Replace with the actual backend URL shown in startup logs
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 - check for port usage
netstat -ano | findstr :2020
netstat -ano | findstr :2021
netstat -ano | findstr :2022
netstat -ano | findstr :2023
netstat -ano | findstr :500

# 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

Qunatum-Secure-Email-Client/
├── 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
├── level3/                  # PQC encryption service
│   ├── pqc_server.py        # PQC API server
│   └── pqc_server_backup.py # Backup PQC server
├── 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 .env files 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

1. Use environment variables for all sensitive configuration
2. Set up proper logging and monitoring
3. Configure reverse proxy (nginx/Apache)
4. Enable SSL/TLS certificates
5. Set up database replication and backups

Performance Optimization

1. Configure connection pooling
2. Implement caching strategies
3. Optimize database queries
4. Use CDN for static assets
5. Monitor resource usage

Support

If you encounter issues during setup:

1. Check the troubleshooting section above
2. Review log files in the logs/ directory
3. Verify all services are running on correct ports
4. Ensure all dependencies are properly installed
5. Check database connectivity and schema

License

This project is licensed under the MIT License - see the LICENSE file for details.

---

For additional help or questions, please refer to the project documentation or create an issue in the repository.