A desktop application for secure hybrid encryption, digital signatures, and file encryption — inspired by the Enigma machine but built with modern cryptography.
Author: Chaiphile
Version: 2.2
License: Polyform Noncommercial License 1.0.0
Ultimate Enigma Messenger is a local cryptographic tool that encrypts messages and files using a combination of:
- AES‑256‑GCM for symmetric encryption
- RSA‑OAEP (4096-bit) for key wrapping and friend‑specific encryption
- Argon2id for memory-hard key derivation
- Double Ratchet Protocol for forward secrecy and break-in recovery
- Post-Quantum Cryptography (X25519 + Kyber768 hybrid KEM) for quantum-safe encryption
- TOTP Authentication for secure unlock verification
- Hybrid Digital signatures (Ed25519 + Dilithium3) for authenticity and non‑repudiation
- Time‑based symmetric keys with NTP-synchronized sliding window (WINDOW_SIZE=2, ±60s)
- Self‑destruct messages with configurable expiration
All sensitive keys are encrypted at rest and stored in a SQLCipher-encrypted SQLite database (via sqlcipher3). When sqlcipher3 is unavailable, the app falls back to plain SQLite with a warning. The app provides an intuitive dark-themed GUI built with ttkbootstrap for encryption, decryption, contact management, and key exchange.
Detailed Documentation: See the docs/ directory for comprehensive guides:
- Setup Guide (Windows/macOS/Linux) – Multi-OS installation and configuration
- Services Reference – Every service, method, and parameter documented
- Models Reference – Data models, database schema, SecureString, constants
- Views & Controllers Reference – All UI tabs, controllers, dialogs
- Architecture – System design and component interaction
- Security Model – Threat model and security properties
- API Reference – API documentation
- Contributing Guidelines – Development guidelines and workflows
- Database Reference – Database schema and operations
- Hybrid Signature Implementation – Hybrid signature details
- Scientific Report – Cryptographic architecture and scientific foundations
- Hybrid Encryption – AES-GCM for speed, RSA-OAEP for friend-only confidentiality
- Time‑Based Keys – Every message encrypted with a key derived from shared secret + timestamp; valid within ±60-second window (WINDOW_SIZE=2)
- Hybrid Digital Signatures – Ed25519 + Dilithium3 for authenticity and non‑repudiation
- Self‑Destruct – Set messages to expire after configurable duration
- Friend Management – Store friends' public keys and ECDH-derived shared secrets
- ECDH Key Exchange – X25519 key exchange for unique per-friend secrets
- Global Shared Secret – Fallback symmetric key for group communication
- Double Ratchet – Signal Protocol implementation with XChaCha20-Poly1305 for forward secrecy
- Hybrid KEM – X25519 + Kyber768 for quantum-safe key encapsulation
- Hybrid Signatures – Ed25519 + Dilithium3 for quantum-safe authentication
- Hybrid Envelopes – Classical + PQC encryption for transition safety
- Future-Proof – Protects against quantum computer threats
- Master Password – Argon2id-derived key protects all secrets at rest (PBKDF2-to-Argon2id migration supported)
- TOTP Verification – RFC 6238 time-based one-time password for unlock
- Duress Password – Alternate password that triggers duress mode
- Emergency Lock – Instant key wipe with hotkey support (Ctrl+Shift+L)
- Lockout Protection – Exponential backoff on failed attempts
- Anti-Tamper – Debugger detection, binary integrity checks, hooking framework detection, and hardware breakpoint detection in compiled .exe
- File Encryption – Encrypt/decrypt any file with password (AES-GCM + Argon2id)
- Friend-Specific Files – Encrypt files for specific recipients
- Signature Verification – Verify file signatures on decrypt
- Chunked Processing – Handle large files efficiently
- Dark Theme – Modern ttkbootstrap "darkly" theme
- Clipboard Auto-Clear – Sensitive data cleared after configurable timeout
- NTP Synchronization – Multi-server NTP consensus with outlier rejection for accurate time-based key derivation
- Event-Driven UI – Decoupled components via EventBus with 22 event types
- SecureString – Memory-safe string handling with 3-pass wipe
For detailed OS-specific instructions (Windows, macOS, Linux), see the Setup Guide.
# Clone
git clone https://github.com/yourusername/ultimate-enigma.git
cd ultimate-enigma
# Virtual environment (recommended)
python -m venv venv
source venv/bin/activate # Linux/macOS
venv\Scripts\activate # Windows
# Install & run
pip install -r requirements.txt
python main.pyOn Windows, native Python extensions (like cryptography, argon2-cffi) and the Post-Quantum Cryptography library (liboqs) require a C/C++ compiler to build.
Required Components:
- Visual Studio Build Tools (or full Visual Studio 2022)
- MSVC v143 C++ Build Tools (x86/x64)
- Windows 11 SDK
We provide an automated PowerShell script to install all required C++ development components silently:
# Open PowerShell as Administrator, navigate to the project folder, and run:
.\setup_dev_env.ps1For manual installation instructions, see the Windows Setup Guide.
| Platform | Key Notes |
|---|---|
| Windows | Full support including global hotkeys (Ctrl+Shift+L/U). Use build_app.bat for executable. Requires C++ Build Tools (see Windows Prerequisites above). |
| macOS | Install via Homebrew (brew install python@3.12). No global hotkeys (use lock button). Apple Silicon supported. |
| Linux | Requires python3-tk package. No global hotkeys. X11 or Wayland with XWayland required. |
See docs/SETUP.md for complete installation steps, liboqs/PQC setup, troubleshooting, and building executables on each platform.
- You will be prompted to set a master password (minimum 16 characters required)
- The app generates a 4096-bit RSA key pair, PQC keys, hybrid signing keys, and 256-bit global shared secret
- TOTP setup is required for secure unlock capability
- All keys are encrypted with your master password and stored securely
- Set your display name (required for Double Ratchet): In the Friends tab, click "Set My Name" and enter the exact name your contacts use for you — this is embedded in ratchet envelopes so recipients can identify your session
The application is organized into tabs:
- Type your message, optionally sign it with your private key
- Choose from 4 encryption modes: Ratchet, Shared Secret, RSA, PQC
- Enable self‑destruct and select expiration time
- Click Encrypt & Send – Base64 ciphertext is displayed and copied
- Paste received Base64 message into input field
- Click Decrypt Message – plaintext and signature verification appear
- Mode indicator shows encryption type used
- Expired self-destruct messages show appropriate error
- Encrypt any file with 3 methods: password, global secret, friend secret
- Decrypt encrypted files with same method
- Support for friend-specific file encryption
- Signature verification on decrypt
- Add friends with name, public key (PEM), and optional shared secret
- Perform ECDH key exchange with selected friend
- Initialize Double Ratchet sessions
- Remove friends, view public key details and fingerprints
- Treeview-based friend management
- View fingerprint of current global shared secret
- Export/import global secret (Base64)
- Start ECDH key exchange for secure secret establishment
- View local system time and NTP server time
- Multi-server NTP consensus with outlier rejection
- Auto-refresh capability
- Choose from preset servers or enter custom hostname
- Displays time offset and last sync timestamp
- App version, author, and privacy statement
- Backup and restore functionality
- Security actions (key wipe, etc.)
- Click EMERGENCY LOCK button or use hotkey (Ctrl+Shift+L)
- Immediately wipes all keys from memory
- Requires master password + TOTP to unlock
- All services are rebuilt with restored keys
The project includes a comprehensive test suite using pytest with 550+ tests covering all modules.
pytest tests/ -vpytest tests/test_encryption_service.py -vpytest tests/ --cov=. --cov-report=htmlThe test suite covers:
- Cryptographic primitives (AES, RSA, ECDH, Argon2id, PQC)
- Double Ratchet protocol operations
- Time‑based key sliding window
- Self‑destruct logic
- Database encryption/decryption
- KeyStore operations (load, save, wipe)
- File encryption/decryption
- TOTP generation and verification
- EventBus publish/subscribe
- Clipboard service (copy, clear, auto-clear timer)
- NTP client (query, timeout, error handling, consensus)
- Anti-tamper and anti-debugger detection logic
- Concurrent operations and thread safety
- Edge cases (corrupt data, wrong passwords, timeouts)
- SecureString memory safety
- Constant-time decryption
Batch files are provided for common test scenarios:
run_tests.py– Main test runnerrun_specific_tests.bat– Run targeted testsrun_timeout_tests.bat– Test timeout handlingrun_concurrent_test.bat– Test concurrent operations
The project follows an MVC (Model-View-Controller) architecture with an event-driven service layer:
┌─────────────────────────────────────────────────────────────┐
│ EnigmaApp (main) │
│ ┌────────────────┐ ┌──────────────┐ ┌───────────────────┐ │
│ │ApplicationCtrl │ │AuthController│ │ServiceOrchestrator│ │
│ └────────────────┘ └──────────────┘ └───────────────────┘ │
│ │ │
│ ┌─────────┴─────────┐ │
│ │ EventBus │ │
│ │ (22 event types)│ │
│ └───────────────────┘ │
│ │ │
│ ┌───────────────────────────┼───────────────────────────┐ │
│ │ Services │ Views │ │
│ │ EncryptionSvc │ EncryptTab │ │
│ │ FileService │ DecryptTab │ │
│ │ FriendsService │ FriendsTab │ │
│ │ ClipboardService │ FileTab │ │
│ │ DoubleRatchet │ SecretTab │ │
│ │ PQCService │ NtpTab │ │
│ │ TOTPService │ AboutTab │ │
│ │ HotkeyService │ LockScreen │ │
│ │ ... (19 services) │ TrustTab │ │
│ └───────────────────────────┴───────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
| Directory/File | Purpose |
|---|---|
main.py |
Entry point (48 lines) - logging, anti-tamper, ttkbootstrap darkly theme |
app.py |
EnigmaApp class (373 lines) - composition root, 7 tabs, emergency lock/unlock, event subscriptions |
crypto.py |
Crypto operations (465 lines) - AES-256-GCM + RSA-OAEP, time-based keys, constant-time decryption, hybrid signing, self-destruct |
database.py |
Database layer (500 lines) - SQLite/SQLCipher, Argon2id KDF, schema init, integrity check, error classification, PBKDF2-to-Argon2id migration |
key_manager.py |
Key management (1182 lines) - RSA 4096-bit, PQC keys, hybrid sig keys, exponential backoff lockout, duress mode, password change |
ntp_client.py |
NTP client (145 lines) - Multi-server NTP consensus with outlier rejection |
controllers/ |
MVC controllers (3 files) - lifecycle, auth, service DI |
models/ |
Data models (3 files) - envelope (RatchetEnvelope, PQCEncvelope), friend profile, re-exports |
services/ |
Business logic (19 files, ~5214 lines) - encryption, files, friends, ratchet, PQC, TOTP, etc. |
views/ |
View layer (11 files, ~2747 lines) - tabs, dialogs, lock screen, utilities |
components/ |
Reusable UI components (5 files) - add friend, hybrid sig exchange, PQC exchange, TOTP dialogs |
src/ |
Core utilities (8 files, ~2014 lines) - constants, exceptions, secure string, crypto helpers, anti-tamper, timeout |
tests/ |
Test suite (23 files, 550+ tests) |
docs/ |
Documentation (11 reference files) |
For detailed architecture documentation, see docs/ARCHITECTURE.md.
- Master Password – Never stored; used only to derive encryption key via Argon2id. If lost, data cannot be recovered.
- Memory Safety – Keys are zeroed from memory on lock/close using
SecureStringwith 3-pass wipe. - Time‑Based Keys – Offers ±60-second replay protection window (WINDOW_SIZE=2); not a substitute for network security.
- Constant-Time Decryption – Decryption timing is constant regardless of failure mode to prevent timing attacks.
- Self‑Destruct – Client‑side feature only; does not guarantee deletion on recipient's machine.
- Key Storage – All secrets encrypted at rest (Argon2id + AES-GCM) in SQLite database.
- ECDH – Performed locally; users must verify fingerprints through secure channel to prevent MITM.
- TOTP – Required for unlock after emergency lock; prevents unauthorized access.
- Lockout – Exponential backoff and hard lockout protect against brute force.
- Duress Mode – Alternate password triggers duress mode for coercion scenarios.
- Post-Quantum – Hybrid KEM (X25519 + Kyber768) and hybrid signatures (Ed25519 + Dilithium3) for quantum-safe security.
- Anti-Tamper – Compiled .exe includes debugger detection, binary integrity checks, hooking framework detection, and hardware breakpoint detection. Process exits silently if tampering is detected.
- Hybrid Signatures – Combines classical (Ed25519) and post-quantum (Dilithium3) signatures for transition safety.
- Thread Safety – Per-friend RLock prevents deadlocks in concurrent ratchet operations.
- EventBus – Thread-safe singleton event system with 22 event types for decoupled communication.
For the complete security model, see docs/SECURITY.md.
| Package | Version | Purpose |
|---|---|---|
| ttkbootstrap | ≥1.10.0 | Modern themed Tkinter widgets |
| cryptography | ≥41.0.0 | Core cryptographic operations |
| argon2-cffi | ≥23.1.0 | Memory-hard key derivation |
| qrcode[pil] | ≥7.4 | QR code generation for TOTP |
| liboqs-python | ≥0.9.0 | Post-quantum cryptography (Kyber, Dilithium) |
| sqlcipher3 | ≥1.2.0 | Encrypted SQLite database |
| pytest | ≥7.0.0 | Testing framework (optional) |
| Document | Description |
|---|---|
| Setup Guide | Multi-OS installation (Windows/macOS/Linux), PQC setup, troubleshooting |
| Services Reference | All 19 services with every method, parameter, and return type |
| Models Reference | Envelopes (RatchetEnvelope, PQCEncvelope), FriendProfile, DB schema, SecureString, constants |
| Views & Controllers | All 12 view files, 3 controllers, 5 component dialogs, lock screen, utilities |
| Architecture | MVC design, event flow, threading model |
| Security Model | Cryptographic primitives, threat model, known limitations |
| API Reference | API documentation |
| Contributing | Code style, testing, PR process |
| Database Reference | Database schema and operations |
| Hybrid Signature Implementation | Hybrid signature implementation details |
| Scientific Report | Cryptographic architecture and scientific foundations |
This project is licensed under the Polyform Noncommercial License 1.0.0. See the LICENSE.txt file for details.
- Python Cryptography library for all cryptographic operations
- liboqs for post-quantum algorithms
- ttkbootstrap for modern UI theming
- Tkinter for the GUI framework
- The Enigma machine for historical inspiration
- Signal Protocol for Double Ratchet design
Privacy is a right, not a privilege.