Commit 4d3390f

~~Quantum Secure Email Client - Complete Setup Guide~~

QuMail - Quantum Secure Email Client

A ~~comprehensive quantum-resistant~~secure email client ~~with multi-layer~~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~~together to provide end-to-end encryption:

Frontend: Flutter desktop application for Windows)
Backend: .NET 8 Web API ~~with~~handling 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
- Key Manager: Manages quantum cryptographic 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
- 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
cd quantum

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
# Terminal 1 - Key Manager (Port 2020)
cd Key_Manager/km
python server.py

# Terminal 2 - OTP API
# Terminal 2 - OTP API (Port 2021)
cd level1
python otp_api_test.py

# Terminal 3 - AES Server
# Terminal 3 - AES Server (Port 2022)
cd level2new
python server2.py

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

Step 2: Start Backend API

# Terminal 5 - Backend API
# Terminal 4 - Backend API (Port 5001)
cd Email_client/QuMail.EmailProtocol
dotnet run
dotnet run --urls "http://localhost:5001"

Step 3: Start Frontend

# Terminal 6 - Flutter 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 postgres superuser
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"

Run the backend:
```
dotnet run
```

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.exe in 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)~~

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
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
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:5001/api/health
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
# Windows
netstat -ano | findstr :5001
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/
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
├── 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

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~~

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~~

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.

File tree

‎README.md‎

Quantum Secure Email Client - Complete Setup Guide

QuMail - Quantum Secure Email Client

🏗️ Architecture Overview

📋 Prerequisites

Required Software

Python Dependencies

🚀 Quick Start

1. Clone the Repository

2. Database Setup

Install PostgreSQL

Create Database and User

Alternative: Use provided SQL files

3. Environment Configuration

Generate Secure Secrets

4. Build and Start Services

Option A: Automated Setup (Windows)

Option B: Manual Setup

🔧 Detailed Setup Instructions

Database Setup (Detailed)

Windows PostgreSQL Setup

Create Database Schema

Backend Setup (Detailed)

Install .NET 8 SDK

Configure Backend

Frontend Setup (Detailed)

Install Flutter SDK

Configure Frontend

Crypto Services Setup (Detailed)

Python Dependencies

Key Manager Service

OTP API Service

AES Server Service

Backend API Service (Handles PQC Operations)

PQC Server Service

Backend API Service

🔍 Verification & Testing

Check Service Health

Test User Credentials

Create New User

🚨 Troubleshooting

Common Issues

Database Connection Issues

Port Conflicts

Flutter Build Issues

.NET Build Issues

Log Files

📁 Project Structure

🔐 Security Considerations

Environment Variables

.gitignore File

Database Security

Application Security

🚀 Production Deployment

Environment Setup

Performance Optimization

📞 Support

Support

📄 License

License

0 commit comments

`‎README.md‎`