From a8ed8ce31bf5e5a5700f63e71ebff37ce9f030ed Mon Sep 17 00:00:00 2001 From: aquaxs1 Date: Sat, 29 Aug 2026 14:19:35 +0000 Subject: [PATCH] Ship the Windows build as a zip, and split out download and setup pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The release published a bare CipherBox.exe next to the archives and the site linked straight to it. An unsigned executable downloaded directly is what browsers and antivirus engines flag hardest, and the zip of the same binary was already being built β€” so the bare .exe is dropped and everything points at cipherbox-windows-x64.zip instead. The site followed the same shape as the other projects' sites: - download.html takes over the install section, now linking the archive and explaining why it is one - setup.html takes over "How to use it", so the guide has a name that matches the other sites - index.html keeps the hero and the feature list and links out to both - the nav carries Download, Setup, Features and GitHub; Terms stay in the footer terms.html was missing scope, liability, third-party components, trademarks and contact. It now covers all of them, numbered, and the nav and footer links that pointed at the moved sections are repointed. README, QUICKSTART and GUIDE describe the unzip step. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01QvaJuvQfxgNSxrWjxNaXTd --- .github/workflows/release.yml | 40 +- GUIDE.md | 1298 ++++++++++++++++----------------- QUICKSTART.md | 805 ++++++++++---------- README.md | 720 +++++++++--------- site/download.html | 106 +++ site/index.html | 71 +- site/setup.html | 74 ++ site/sitemap.xml | 2 + site/terms.html | 72 +- 9 files changed, 1669 insertions(+), 1519 deletions(-) create mode 100644 site/download.html create mode 100644 site/setup.html diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 3ce44fb..9974d9d 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -7,11 +7,11 @@ name: Build & release binaries # customtkinter GUI you get from `python main.py`, with no Python install # required on the target machine. # -# The Windows build is additionally published under the fixed name -# CipherBox.exe. The website links straight to -# releases/latest/download/CipherBox.exe, so that name must stay stable across -# releases -- renaming it breaks the download button on every page that points -# at it. +# Every build is published as an archive, never as a bare executable: browsers +# and antivirus engines flag a freshly downloaded, unsigned .exe far more often +# than the same binary inside a .zip. The website links to +# releases/latest/download/cipherbox-windows-x64.zip, so that name must stay +# stable across releases -- renaming it breaks the download button. on: push: @@ -37,8 +37,6 @@ jobs: name: windows-x64 asset_ext: zip binary: cipherbox.exe - # Stable, human-facing name the website downloads directly. - standalone: CipherBox.exe - os: macos-14 name: macos-arm64 asset_ext: zip @@ -115,13 +113,6 @@ jobs: chmod +x "dist/${{ matrix.binary }}" tar -C dist -czf "cipherbox-${{ matrix.name }}.tar.gz" "${{ matrix.binary }}" - # Published alongside the archive so the website can link to a single, - # unchanging URL that hands the user a runnable file with no unzip step. - - name: Stage standalone executable - if: matrix.standalone != '' - shell: bash - run: cp "dist/${{ matrix.binary }}" "${{ matrix.standalone }}" - - name: Checksum shell: bash run: | @@ -132,13 +123,6 @@ jobs: shasum -a 256 "$FILE" > "$FILE.sha256" fi - - name: Checksum (standalone) - if: matrix.standalone != '' - shell: bash - run: | - FILE="${{ matrix.standalone }}" - certutil -hashfile "$FILE" SHA256 | sed -n '2p' | tr -d '\r' | awk -v f="$FILE" '{print $0" "f}' > "$FILE.sha256" - - uses: actions/upload-artifact@v4 with: name: cipherbox-${{ matrix.name }} @@ -147,14 +131,6 @@ jobs: cipherbox-${{ matrix.name }}.${{ matrix.asset_ext }}.sha256 if-no-files-found: error - - uses: actions/upload-artifact@v4 - if: matrix.standalone != '' - with: - name: cipherbox-${{ matrix.name }}-standalone - path: | - ${{ matrix.standalone }} - ${{ matrix.standalone }}.sha256 - if-no-files-found: error release: name: Publish release @@ -188,7 +164,6 @@ jobs: name: CipherBox ${{ steps.version.outputs.version }} generate_release_notes: true files: | - artifacts/CipherBox.exe artifacts/*.zip artifacts/*.tar.gz artifacts/SHA256SUMS.txt @@ -196,8 +171,9 @@ jobs: Desktop builds of CipherBox ${{ steps.version.outputs.version }}. No Python installation required β€” download and run. - **Windows:** grab `CipherBox.exe` and double-click it. The `.zip` - archives are the same binary for anyone who prefers them. + **Windows:** download `cipherbox-windows-x64.zip`, unzip it and run + `cipherbox.exe`. Shipping the binary inside an archive keeps browsers + and antivirus engines from flagging the unsigned download. These binaries are **not code-signed**, so Windows SmartScreen and macOS Gatekeeper will warn on first launch. On Windows choose diff --git a/GUIDE.md b/GUIDE.md index 4ff7fe6..e0f5037 100644 --- a/GUIDE.md +++ b/GUIDE.md @@ -1,649 +1,649 @@ -# CipherBox - Developer Guide - -> **For developers.** Architecture, module responsibilities, build and deployment. -> If you just want to use CipherBox, read [QUICKSTART.md](QUICKSTART.md) or -> [README.md](README.md) instead. - -## πŸ“‹ Table of Contents - -1. [Project Overview](#project-overview) -2. [Architecture](#architecture) -3. [Installation](#installation) -4. [Usage Guide](#usage-guide) -5. [Security Implementation](#security-implementation) -6. [Code Quality](#code-quality) -7. [Troubleshooting](#troubleshooting) -8. [File Reference](#file-reference) - ---- - -## Project Overview - -**CipherBox** is a production-ready, secure desktop application for encrypting and decrypting local files. It combines enterprise-grade cryptography with a modern, user-friendly interface. - -### Key Features - -βœ“ **Auto-generated Master Password** (32 alphanumeric characters) -βœ“ **PBKDF2-HMAC-SHA256 Key Derivation** (480,000 iterations) -βœ“ **Fernet AES Encryption** with authentication -βœ“ **Secure File Deletion** (3-pass overwrite + zero fill, flushed to disk) -βœ“ **Optional Filename Encryption** (UUID + .cipherbox) -βœ“ **Modern customtkinter GUI** (dark mode) -βœ“ **Multi-file Support** (batch operations) -βœ“ **Comprehensive Error Handling** - -### Technology Stack - -- **Python 3.10+**: Core language -- **customtkinter 5.2.0**: Modern GUI framework -- **cryptography 41.0.7**: Industry-standard crypto library -- **No external services**: All operations local, no cloud - ---- - -## Architecture - -### Module Structure - -``` -CipherBox/ -β”œβ”€β”€ main.py # GUI & application orchestration -β”œβ”€β”€ crypto_utils.py # Cryptographic operations -β”œβ”€β”€ config_manager.py # Configuration & salt management -β”œβ”€β”€ test_cipherbox.py # Test suite -β”œβ”€β”€ requirements.txt # Python dependencies -β”œβ”€β”€ packaging/ -β”‚ └── cipherbox.spec # PyInstaller build spec -β”œβ”€β”€ site/ # Documentation website -β”œβ”€β”€ .github/workflows/ -β”‚ β”œβ”€β”€ tests.yml # Test suite on every push and PR -β”‚ └── release.yml # Builds and publishes desktop binaries -β”œβ”€β”€ LICENSE # MIT -β”œβ”€β”€ README.md # Full documentation -β”œβ”€β”€ QUICKSTART.md # Quick start guide -└── GUIDE.md # This file -``` - -### Module Responsibilities - -#### `crypto_utils.py` - Cryptographic Engine -**Responsibility**: All encryption/decryption operations - -**Key Classes**: -- `CryptoManager`: Central class for all crypto operations - -**Key Methods**: -- `generate_master_password(length)`: Generate secure random password -- `generate_salt()`: Generate cryptographic salt -- `derive_key(password, salt, iterations)`: PBKDF2 key derivation -- `encrypt_file(path, key, encrypt_filename)`: File encryption -- `decrypt_file(path, key)`: File decryption -- `_secure_delete(path, passes)`: Multi-pass file deletion - -**Security Features**: -- PBKDF2-HMAC-SHA256 with 480,000 iterations -- Fernet for authenticated encryption -- Metadata handling for filename storage -- Secure deletion with random overwrite - -#### `config_manager.py` - Configuration Handler -**Responsibility**: Persistent storage of encryption salt - -**Key Classes**: -- `ConfigManager`: Configuration file operations - -**Key Methods**: -- `is_first_launch()`: Detect first-time use -- `save_salt(salt)`: Securely store salt -- `load_salt()`: Retrieve salt -- `_load_config()`: Load JSON config - -**Storage**: -- Location: `~/.cipherbox/config.json` -- Format: JSON with base64-encoded salt -- Permissions: `0o600` (owner read/write only) - -#### `main.py` - GUI Application -**Responsibility**: User interface & orchestration - -**Key Classes**: -- `CipherBoxApp`: Main application window (CTk-based) - -**Key Features**: -- First-launch wizard with password generation -- Password verification screen -- Encrypt/Decrypt tabs with file dialogs -- Multi-threaded file operations -- Real-time status updates -- Error handling with user-friendly messages - -**UI Elements**: -- Master password setup wizard -- File selection dialogs -- File list displays -- Encryption/Decryption buttons -- Lock/Unlock functionality - ---- - -## Installation - -### End users - -Download **[CipherBox.exe](https://github.com/aquaxs1/CipherBox/releases/latest/download/CipherBox.exe)** -and run it. No Python required. See QUICKSTART.md for the details. - -### Development setup - -#### Prerequisites - -- **Python 3.10+**: Download from [python.org](https://www.python.org/downloads/) -- **Tk bindings**: bundled with Python on Windows and macOS; on Debian/Ubuntu - install `python3-tk` separately, or customtkinter fails at import -- **~500 MB disk space**: For Python + dependencies - -#### From source -```bash -git clone https://github.com/aquaxs1/CipherBox.git -cd CipherBox -pip install -r requirements.txt -python test_cipherbox.py # Verify installation -python main.py # Launch application -``` - -#### Building a binary -```bash -pip install pyinstaller -pyinstaller packaging/cipherbox.spec --noconfirm --clean -``` - -Delete `build/` and `dist/` first so nothing from an earlier build survives -into the new one; `--clean` handles PyInstaller's own cache. The result is a -single executable in `dist/`. - -### Verification - -Test the installation: -```bash -python test_cipherbox.py -``` - -Expected output: -``` -============================================================ - CipherBox Test Suite -============================================================ - -[Tests running...] - -============================================================ - ALL TESTS PASSED βœ“ -============================================================ -``` - ---- - -## Usage Guide - -### First Launch Workflow - -``` -1. Run: python main.py -2. See first-launch wizard -3. Master password auto-generated (32 chars) -4. BIG RED WARNING: "Save this password or lose all files!" -5. Copy to clipboard -6. Check: "I have saved it" -7. Click: "Proceed to Main Application" -8. Ready to encrypt/decrypt files! -``` - -### Encrypt Files Workflow - -``` -1. Click: "πŸ“ Encrypt Files" tab -2. Click: "βž• Add Files" -3. Select: one or multiple files -4. Optional: Check "πŸ”’ Encrypt filenames" -5. Click: "πŸ” Encrypt Files" -6. Wait: Progress completes -7. Result: .cipherbox files created, originals deleted -``` - -### Decrypt Files Workflow - -``` -1. Click: "πŸ”“ Decrypt Files" tab -2. Click: "βž• Add Files" -3. Select: .cipherbox files -4. Click: "πŸ”“ Decrypt Files" -5. Wait: Progress completes -6. Result: Original files restored, .cipherbox deleted -``` - -### Lock/Unlock Workflow - -``` -1. Click: "πŸ”’ Lock" button (top-right) -2. Confirm: "Lock application?" -3. Back to: Password prompt screen -4. Enter: Master password -5. Click: "πŸ”“ Unlock" -6. Back to: Main application interface -``` - ---- - -## Security Implementation - -### Cryptographic Specifications - -#### Key Derivation - -| Parameter | Value | Rationale | -|-----------|-------|-----------| -| Algorithm | PBKDF2-HMAC-SHA256 | OWASP approved, proven secure | -| Iterations | 480,000 | OWASP 2024 recommendation | -| Salt Length | 32 bytes (256 bits) | Sufficient entropy | -| Output Length | 32 bytes (256 bits) | Full Fernet key size | -| Encoding | Base64 URL-safe | JSON-compatible storage | - -#### Encryption - -| Parameter | Value | Rationale | -|-----------|-------|-----------| -| Cipher | Fernet (AES-128-CBC) | Built-in authentication | -| Authentication | HMAC-SHA256 | Detects tampering | -| Key Encoding | Base64 URL-safe | Fernet requirement | -| Metadata | JSON + Length | Allows filename recovery | - -#### File Deletion - -| Parameter | Value | Rationale | -|-----------|-------|-----------| -| Passes | 3 | Practical security | -| Pattern | Random data (2 passes) + Zeros (1 pass) | Military standard | -| Fallback | Regular deletion if secure fails | Ensures file removal | - -### Threat Model - -#### What CipherBox Protects Against - -βœ“ Unauthorized file access (encryption) -βœ“ File tampering (authenticated encryption) -βœ“ Data recovery after deletion (secure deletion) -βœ“ Rainbow tables/dictionary attacks (PBKDF2 iterations) -βœ“ Filename disclosure (optional filename encryption) - -#### What CipherBox Does NOT Protect Against - -βœ— Malware on your computer (can intercept password) -βœ— Physical access to RAM (could extract key in memory) -βœ— Keyloggers/screensharing software -βœ— Network interception (all operations are local) -βœ— Weak master passwords (auto-generated, so not an issue) - -### Security Best Practices Implemented - -βœ“ **Cryptographically strong randomness**: `os.urandom()` -βœ“ **No hardcoded secrets**: All derived or user-provided -βœ“ **No password logging**: Passwords only in memory during session -βœ“ **Metadata integrity**: Stored securely inside encrypted file -βœ“ **Separation of concerns**: GUI, crypto, and config are separate modules -βœ“ **Error handling**: Graceful failures, no information leakage -βœ“ **File permissions**: Config file `0o600` (owner only) - ---- - -## Code Quality - -### Code Organization - -#### Separation of Concerns - -- **GUI Logic** (main.py): User interface only -- **Crypto Logic** (crypto_utils.py): No UI dependencies -- **Config Logic** (config_manager.py): File I/O only - -**Benefit**: Easy to test, maintain, and extend - -#### Error Handling - -Every operation returns structured results: - -```python -# Encryption returns: (success: bool, message: str) -success, msg = crypto.encrypt_file(path, key) - -# Decryption returns: (success: bool, message: str, output_path: str | None) -success, msg, output_path = crypto.decrypt_file(path, key) -``` - -#### Threading - -Long operations run in separate threads to keep UI responsive: - -```python -def start_encryption(): - threading.Thread(target=self.perform_encryption, daemon=True).start() -``` - -### Code Comments - -- Heavily commented for clarity -- Docstrings for all public methods -- Inline comments for complex logic -- Security-relevant comments highlighted - -### Code Style - -- **PEP 8 compliant**: Standard Python style -- **Type hints**: Where applicable (Python 3.10+) -- **Meaningful names**: Variables and functions are self-documenting -- **DRY principle**: No code duplication - ---- - -## Troubleshooting - -### Installation Issues - -#### "Python not found" -```bash -# Windows: Check Python in PATH -python --version - -# If not found, reinstall Python and check: -# β˜‘ Add Python to PATH (during installation) -``` - -#### "ModuleNotFoundError: No module named 'customtkinter'" -```bash -pip install -r requirements.txt -``` - -### Runtime Issues - -#### "Permission denied" on Windows -- Close the file in all applications -- Close any file explorer windows -- Try again - -#### "Permission denied" on macOS/Linux -```bash -# Add execution permission if needed -chmod +x main.py - -# Run with proper permissions -python3 main.py -``` - -#### GUI doesn't appear (Linux) -```bash -# Some Linux systems need specific graphics setup -sudo apt-get install python3-tk -pip install -r requirements.txt -python3 main.py -``` - -### Cryptographic Issues - -#### "Wrong password or corrupted file" -- Verify Master Password is exactly correct -- Check `.cipherbox` file hasn't been modified -- Try a different file to confirm password - -#### Lost Master Password -- Check password manager (if you saved it there) -- Check physical backups (if you wrote it down) -- If truly lost: files are permanently inaccessible - -### Performance Issues - -#### Encryption/Decryption slow -- Normal: Key derivation (PBKDF2) takes 1-2 seconds -- For large files: Speed depends on file size and disk I/O -- Check disk space: Ensure plenty of free space available - ---- - -## File Reference - -### requirements.txt -``` -customtkinter==5.2.0 -cryptography==41.0.7 -``` - -### Configuration File: ~/.cipherbox/config.json -```json -{ - "version": 1, - "salt": "base64-encoded-salt-string" -} -``` - -### Encrypted File Format: *.cipherbox - -``` -[Fernet Encrypted Payload] -β”œβ”€ [4 bytes] Metadata Length (big-endian) -β”œβ”€ [variable] JSON Metadata -β”‚ β”œβ”€ version: 1 -β”‚ β”œβ”€ original_filename: "document.pdf" -β”‚ └─ encrypted_filename: true/false -└─ [variable] Original File Content (binary) -``` - ---- - -## Advanced Customization - -### Changing Key Derivation Parameters - -**File**: `crypto_utils.py` - -```python -class CryptoManager: - PBKDF2_ITERATIONS = 480000 # Increase for more security (slower) - PBKDF2_SALT_LENGTH = 32 # Already optimal -``` - -**Recommendations**: -- Increasing iterations makes it slower but more secure -- OWASP 2024 recommends 480,000 minimum -- For modern CPUs, up to 1,000,000 is reasonable - -### Changing Appearance - -**File**: `main.py` - -```python -# Change theme -ctk.set_appearance_mode("light") # or "dark" - -# Change color scheme -ctk.set_default_color_theme("green") # or "blue", "dark-blue" -``` - -### Adding New Features - -Examples of potential additions: - -1. **Compression before encryption**: Add ZIP compression step -2. **Cloud sync**: Integrate with OneDrive/Google Drive -3. **Batch scheduling**: Encrypt files on a schedule -4. **Password change**: Allow password rotation -5. **File archiving**: Create encrypted backups - ---- - -## Performance Metrics - -### Benchmarks - -Measured on an x86-64 Linux container. Absolute times vary a lot with CPU and -disk; the peak-memory column does not -- it is inherent to how files are -processed. - -| Operation | File Size | Time | Peak RAM | -|-----------|-----------|------|----------| -| Master Password Generation | N/A | < 1 ms | N/A | -| Salt Generation | N/A | < 1 ms | N/A | -| Key Derivation (480k iterations) | N/A | ~0.1–0.5 s | N/A | -| Encrypt | 1 MB | ~30 ms | ~34 MB | -| Encrypt | 10 MB | ~0.4 s | ~124 MB | -| Encrypt | 50 MB | ~3 s | ~461 MB | -| Decrypt | 1 MB | ~30 ms | comparable | -| Decrypt | 50 MB | ~1.4 s | comparable | -| Secure Delete (3 passes + zero, fsync'd) | 1 MB | ~15 ms | ~4 MB | - -**Files are not streamed.** Each one is held in memory whole, together with the -payload built around it and Fernet's base64 ciphertext, so peak memory runs at -roughly **9x the file size**. That scales linearly: a 1 GB file needs several GB -free and fails with a `MemoryError` on most machines. CipherBox warns before it -starts on anything above 256 MB (`CryptoManager.LARGE_FILE_THRESHOLD`). - -Note that timings degrade faster than linearly once memory pressure sets in -- -50 MB takes roughly 8x as long as 10 MB, not 5x. - ---- - -## Testing - -### Test Coverage - -Run comprehensive tests: - -```bash -python test_cipherbox.py -``` - -### Test Categories - -1. **Master Password Generation**: Strength and randomness -2. **Salt Generation**: Uniqueness and entropy -3. **Key Derivation**: Consistency and correctness -4. **Config Management**: Storage and retrieval -5. **File Encryption/Decryption**: Content integrity -6. **Filename Encryption**: UUID generation and restoration -7. **Wrong Password**: Error handling -8. **Large Files**: Multi-MB file handling - -### Test Results - -Expected: **8/8 tests pass βœ“** - ---- - -## Security Audit Checklist - -- βœ“ Passwords are never stored -- βœ“ Encryption keys are derived securely (PBKDF2) -- βœ“ Encryption uses authenticated cipher (Fernet) -- βœ“ Files are securely deleted (multi-pass overwrite) -- βœ“ Configuration files have restricted permissions (0o600) -- βœ“ Error messages don't leak sensitive information -- βœ“ No hardcoded secrets in code -- βœ“ Thread-safe operations where needed -- βœ“ Input validation on file paths -- βœ“ Comprehensive error handling - ---- - -## Deployment Considerations - -### For Personal Use - -- Run locally on your computer -- Store salt file in `~/.cipherbox/` -- Back up Master Password in password manager - -### For Team Use - -- Each user has their own Master Password -- Share encrypted files via secure channel -- Share password via separate secure channel (NOT the same channel as files) -- Each user maintains their own config/salt - -### For Backup/Archival - -- Encrypt important files -- Store `.cipherbox` files in multiple locations -- Store Master Password separately (password manager + physical backup) -- Test decryption periodically - ---- - -## Maintenance - -### Regular Maintenance Tasks - -- [ ] Update Python when new versions released -- [ ] Update dependencies: `pip install --upgrade -r requirements.txt` -- [ ] Test decryption monthly on archived files -- [ ] Back up Master Password in multiple locations -- [ ] Review config directory permissions - -### Monitoring - -- Check logs for errors: Python error messages during operation -- Monitor disk space: Large files need 2x their size free (encryption + original) -- Test recovery: Regularly decrypt sample files - ---- - -## Version History - -- **v1.0** (2026-05-02): Initial production release - - Master password auto-generation - - PBKDF2-HMAC-SHA256 key derivation (480,000 iterations) - - Fernet AES encryption - - Optional filename encryption - - Secure file deletion - - customtkinter GUI - - Comprehensive error handling - - Full test suite - ---- - -## Support Resources - -- **README.md**: Full documentation -- **QUICKSTART.md**: Quick start guide -- **test_cipherbox.py**: Diagnostic tests -- **Code comments**: Inline documentation - ---- - -## Contributing Improvements - -Feel free to enhance CipherBox by: - -1. Improving performance -2. Adding features (compression, scheduling, etc.) -3. Enhancing UI/UX -4. Expanding test coverage -5. Improving documentation - ---- - -## License - -CipherBox is provided for personal use. Modify and improve as needed. - ---- - -## Acknowledgments - -- **cryptography.io**: Excellent cryptographic library -- **customtkinter**: Modern Python GUI library -- **OWASP**: Security best practices and recommendations - ---- - -**Last Updated**: May 2, 2026 -**Status**: Production Ready βœ“ -**Author**: Security-focused Development - -For questions or improvements, review the code and make enhancements locally. πŸ” +# CipherBox - Developer Guide + +> **For developers.** Architecture, module responsibilities, build and deployment. +> If you just want to use CipherBox, read [QUICKSTART.md](QUICKSTART.md) or +> [README.md](README.md) instead. + +## πŸ“‹ Table of Contents + +1. [Project Overview](#project-overview) +2. [Architecture](#architecture) +3. [Installation](#installation) +4. [Usage Guide](#usage-guide) +5. [Security Implementation](#security-implementation) +6. [Code Quality](#code-quality) +7. [Troubleshooting](#troubleshooting) +8. [File Reference](#file-reference) + +--- + +## Project Overview + +**CipherBox** is a production-ready, secure desktop application for encrypting and decrypting local files. It combines enterprise-grade cryptography with a modern, user-friendly interface. + +### Key Features + +βœ“ **Auto-generated Master Password** (32 alphanumeric characters) +βœ“ **PBKDF2-HMAC-SHA256 Key Derivation** (480,000 iterations) +βœ“ **Fernet AES Encryption** with authentication +βœ“ **Secure File Deletion** (3-pass overwrite + zero fill, flushed to disk) +βœ“ **Optional Filename Encryption** (UUID + .cipherbox) +βœ“ **Modern customtkinter GUI** (dark mode) +βœ“ **Multi-file Support** (batch operations) +βœ“ **Comprehensive Error Handling** + +### Technology Stack + +- **Python 3.10+**: Core language +- **customtkinter 5.2.0**: Modern GUI framework +- **cryptography 41.0.7**: Industry-standard crypto library +- **No external services**: All operations local, no cloud + +--- + +## Architecture + +### Module Structure + +``` +CipherBox/ +β”œβ”€β”€ main.py # GUI & application orchestration +β”œβ”€β”€ crypto_utils.py # Cryptographic operations +β”œβ”€β”€ config_manager.py # Configuration & salt management +β”œβ”€β”€ test_cipherbox.py # Test suite +β”œβ”€β”€ requirements.txt # Python dependencies +β”œβ”€β”€ packaging/ +β”‚ └── cipherbox.spec # PyInstaller build spec +β”œβ”€β”€ site/ # Documentation website +β”œβ”€β”€ .github/workflows/ +β”‚ β”œβ”€β”€ tests.yml # Test suite on every push and PR +β”‚ └── release.yml # Builds and publishes desktop binaries +β”œβ”€β”€ LICENSE # MIT +β”œβ”€β”€ README.md # Full documentation +β”œβ”€β”€ QUICKSTART.md # Quick start guide +└── GUIDE.md # This file +``` + +### Module Responsibilities + +#### `crypto_utils.py` - Cryptographic Engine +**Responsibility**: All encryption/decryption operations + +**Key Classes**: +- `CryptoManager`: Central class for all crypto operations + +**Key Methods**: +- `generate_master_password(length)`: Generate secure random password +- `generate_salt()`: Generate cryptographic salt +- `derive_key(password, salt, iterations)`: PBKDF2 key derivation +- `encrypt_file(path, key, encrypt_filename)`: File encryption +- `decrypt_file(path, key)`: File decryption +- `_secure_delete(path, passes)`: Multi-pass file deletion + +**Security Features**: +- PBKDF2-HMAC-SHA256 with 480,000 iterations +- Fernet for authenticated encryption +- Metadata handling for filename storage +- Secure deletion with random overwrite + +#### `config_manager.py` - Configuration Handler +**Responsibility**: Persistent storage of encryption salt + +**Key Classes**: +- `ConfigManager`: Configuration file operations + +**Key Methods**: +- `is_first_launch()`: Detect first-time use +- `save_salt(salt)`: Securely store salt +- `load_salt()`: Retrieve salt +- `_load_config()`: Load JSON config + +**Storage**: +- Location: `~/.cipherbox/config.json` +- Format: JSON with base64-encoded salt +- Permissions: `0o600` (owner read/write only) + +#### `main.py` - GUI Application +**Responsibility**: User interface & orchestration + +**Key Classes**: +- `CipherBoxApp`: Main application window (CTk-based) + +**Key Features**: +- First-launch wizard with password generation +- Password verification screen +- Encrypt/Decrypt tabs with file dialogs +- Multi-threaded file operations +- Real-time status updates +- Error handling with user-friendly messages + +**UI Elements**: +- Master password setup wizard +- File selection dialogs +- File list displays +- Encryption/Decryption buttons +- Lock/Unlock functionality + +--- + +## Installation + +### End users + +Download **[cipherbox-windows-x64.zip](https://github.com/aquaxs1/CipherBox/releases/latest/download/cipherbox-windows-x64.zip)**, unzip it and run +`cipherbox.exe`. No Python required. See QUICKSTART.md for the details. + +### Development setup + +#### Prerequisites + +- **Python 3.10+**: Download from [python.org](https://www.python.org/downloads/) +- **Tk bindings**: bundled with Python on Windows and macOS; on Debian/Ubuntu + install `python3-tk` separately, or customtkinter fails at import +- **~500 MB disk space**: For Python + dependencies + +#### From source +```bash +git clone https://github.com/aquaxs1/CipherBox.git +cd CipherBox +pip install -r requirements.txt +python test_cipherbox.py # Verify installation +python main.py # Launch application +``` + +#### Building a binary +```bash +pip install pyinstaller +pyinstaller packaging/cipherbox.spec --noconfirm --clean +``` + +Delete `build/` and `dist/` first so nothing from an earlier build survives +into the new one; `--clean` handles PyInstaller's own cache. The result is a +single executable in `dist/`. + +### Verification + +Test the installation: +```bash +python test_cipherbox.py +``` + +Expected output: +``` +============================================================ + CipherBox Test Suite +============================================================ + +[Tests running...] + +============================================================ + ALL TESTS PASSED βœ“ +============================================================ +``` + +--- + +## Usage Guide + +### First Launch Workflow + +``` +1. Run: python main.py +2. See first-launch wizard +3. Master password auto-generated (32 chars) +4. BIG RED WARNING: "Save this password or lose all files!" +5. Copy to clipboard +6. Check: "I have saved it" +7. Click: "Proceed to Main Application" +8. Ready to encrypt/decrypt files! +``` + +### Encrypt Files Workflow + +``` +1. Click: "πŸ“ Encrypt Files" tab +2. Click: "βž• Add Files" +3. Select: one or multiple files +4. Optional: Check "πŸ”’ Encrypt filenames" +5. Click: "πŸ” Encrypt Files" +6. Wait: Progress completes +7. Result: .cipherbox files created, originals deleted +``` + +### Decrypt Files Workflow + +``` +1. Click: "πŸ”“ Decrypt Files" tab +2. Click: "βž• Add Files" +3. Select: .cipherbox files +4. Click: "πŸ”“ Decrypt Files" +5. Wait: Progress completes +6. Result: Original files restored, .cipherbox deleted +``` + +### Lock/Unlock Workflow + +``` +1. Click: "πŸ”’ Lock" button (top-right) +2. Confirm: "Lock application?" +3. Back to: Password prompt screen +4. Enter: Master password +5. Click: "πŸ”“ Unlock" +6. Back to: Main application interface +``` + +--- + +## Security Implementation + +### Cryptographic Specifications + +#### Key Derivation + +| Parameter | Value | Rationale | +|-----------|-------|-----------| +| Algorithm | PBKDF2-HMAC-SHA256 | OWASP approved, proven secure | +| Iterations | 480,000 | OWASP 2024 recommendation | +| Salt Length | 32 bytes (256 bits) | Sufficient entropy | +| Output Length | 32 bytes (256 bits) | Full Fernet key size | +| Encoding | Base64 URL-safe | JSON-compatible storage | + +#### Encryption + +| Parameter | Value | Rationale | +|-----------|-------|-----------| +| Cipher | Fernet (AES-128-CBC) | Built-in authentication | +| Authentication | HMAC-SHA256 | Detects tampering | +| Key Encoding | Base64 URL-safe | Fernet requirement | +| Metadata | JSON + Length | Allows filename recovery | + +#### File Deletion + +| Parameter | Value | Rationale | +|-----------|-------|-----------| +| Passes | 3 | Practical security | +| Pattern | Random data (2 passes) + Zeros (1 pass) | Military standard | +| Fallback | Regular deletion if secure fails | Ensures file removal | + +### Threat Model + +#### What CipherBox Protects Against + +βœ“ Unauthorized file access (encryption) +βœ“ File tampering (authenticated encryption) +βœ“ Data recovery after deletion (secure deletion) +βœ“ Rainbow tables/dictionary attacks (PBKDF2 iterations) +βœ“ Filename disclosure (optional filename encryption) + +#### What CipherBox Does NOT Protect Against + +βœ— Malware on your computer (can intercept password) +βœ— Physical access to RAM (could extract key in memory) +βœ— Keyloggers/screensharing software +βœ— Network interception (all operations are local) +βœ— Weak master passwords (auto-generated, so not an issue) + +### Security Best Practices Implemented + +βœ“ **Cryptographically strong randomness**: `os.urandom()` +βœ“ **No hardcoded secrets**: All derived or user-provided +βœ“ **No password logging**: Passwords only in memory during session +βœ“ **Metadata integrity**: Stored securely inside encrypted file +βœ“ **Separation of concerns**: GUI, crypto, and config are separate modules +βœ“ **Error handling**: Graceful failures, no information leakage +βœ“ **File permissions**: Config file `0o600` (owner only) + +--- + +## Code Quality + +### Code Organization + +#### Separation of Concerns + +- **GUI Logic** (main.py): User interface only +- **Crypto Logic** (crypto_utils.py): No UI dependencies +- **Config Logic** (config_manager.py): File I/O only + +**Benefit**: Easy to test, maintain, and extend + +#### Error Handling + +Every operation returns structured results: + +```python +# Encryption returns: (success: bool, message: str) +success, msg = crypto.encrypt_file(path, key) + +# Decryption returns: (success: bool, message: str, output_path: str | None) +success, msg, output_path = crypto.decrypt_file(path, key) +``` + +#### Threading + +Long operations run in separate threads to keep UI responsive: + +```python +def start_encryption(): + threading.Thread(target=self.perform_encryption, daemon=True).start() +``` + +### Code Comments + +- Heavily commented for clarity +- Docstrings for all public methods +- Inline comments for complex logic +- Security-relevant comments highlighted + +### Code Style + +- **PEP 8 compliant**: Standard Python style +- **Type hints**: Where applicable (Python 3.10+) +- **Meaningful names**: Variables and functions are self-documenting +- **DRY principle**: No code duplication + +--- + +## Troubleshooting + +### Installation Issues + +#### "Python not found" +```bash +# Windows: Check Python in PATH +python --version + +# If not found, reinstall Python and check: +# β˜‘ Add Python to PATH (during installation) +``` + +#### "ModuleNotFoundError: No module named 'customtkinter'" +```bash +pip install -r requirements.txt +``` + +### Runtime Issues + +#### "Permission denied" on Windows +- Close the file in all applications +- Close any file explorer windows +- Try again + +#### "Permission denied" on macOS/Linux +```bash +# Add execution permission if needed +chmod +x main.py + +# Run with proper permissions +python3 main.py +``` + +#### GUI doesn't appear (Linux) +```bash +# Some Linux systems need specific graphics setup +sudo apt-get install python3-tk +pip install -r requirements.txt +python3 main.py +``` + +### Cryptographic Issues + +#### "Wrong password or corrupted file" +- Verify Master Password is exactly correct +- Check `.cipherbox` file hasn't been modified +- Try a different file to confirm password + +#### Lost Master Password +- Check password manager (if you saved it there) +- Check physical backups (if you wrote it down) +- If truly lost: files are permanently inaccessible + +### Performance Issues + +#### Encryption/Decryption slow +- Normal: Key derivation (PBKDF2) takes 1-2 seconds +- For large files: Speed depends on file size and disk I/O +- Check disk space: Ensure plenty of free space available + +--- + +## File Reference + +### requirements.txt +``` +customtkinter==5.2.0 +cryptography==41.0.7 +``` + +### Configuration File: ~/.cipherbox/config.json +```json +{ + "version": 1, + "salt": "base64-encoded-salt-string" +} +``` + +### Encrypted File Format: *.cipherbox + +``` +[Fernet Encrypted Payload] +β”œβ”€ [4 bytes] Metadata Length (big-endian) +β”œβ”€ [variable] JSON Metadata +β”‚ β”œβ”€ version: 1 +β”‚ β”œβ”€ original_filename: "document.pdf" +β”‚ └─ encrypted_filename: true/false +└─ [variable] Original File Content (binary) +``` + +--- + +## Advanced Customization + +### Changing Key Derivation Parameters + +**File**: `crypto_utils.py` + +```python +class CryptoManager: + PBKDF2_ITERATIONS = 480000 # Increase for more security (slower) + PBKDF2_SALT_LENGTH = 32 # Already optimal +``` + +**Recommendations**: +- Increasing iterations makes it slower but more secure +- OWASP 2024 recommends 480,000 minimum +- For modern CPUs, up to 1,000,000 is reasonable + +### Changing Appearance + +**File**: `main.py` + +```python +# Change theme +ctk.set_appearance_mode("light") # or "dark" + +# Change color scheme +ctk.set_default_color_theme("green") # or "blue", "dark-blue" +``` + +### Adding New Features + +Examples of potential additions: + +1. **Compression before encryption**: Add ZIP compression step +2. **Cloud sync**: Integrate with OneDrive/Google Drive +3. **Batch scheduling**: Encrypt files on a schedule +4. **Password change**: Allow password rotation +5. **File archiving**: Create encrypted backups + +--- + +## Performance Metrics + +### Benchmarks + +Measured on an x86-64 Linux container. Absolute times vary a lot with CPU and +disk; the peak-memory column does not -- it is inherent to how files are +processed. + +| Operation | File Size | Time | Peak RAM | +|-----------|-----------|------|----------| +| Master Password Generation | N/A | < 1 ms | N/A | +| Salt Generation | N/A | < 1 ms | N/A | +| Key Derivation (480k iterations) | N/A | ~0.1–0.5 s | N/A | +| Encrypt | 1 MB | ~30 ms | ~34 MB | +| Encrypt | 10 MB | ~0.4 s | ~124 MB | +| Encrypt | 50 MB | ~3 s | ~461 MB | +| Decrypt | 1 MB | ~30 ms | comparable | +| Decrypt | 50 MB | ~1.4 s | comparable | +| Secure Delete (3 passes + zero, fsync'd) | 1 MB | ~15 ms | ~4 MB | + +**Files are not streamed.** Each one is held in memory whole, together with the +payload built around it and Fernet's base64 ciphertext, so peak memory runs at +roughly **9x the file size**. That scales linearly: a 1 GB file needs several GB +free and fails with a `MemoryError` on most machines. CipherBox warns before it +starts on anything above 256 MB (`CryptoManager.LARGE_FILE_THRESHOLD`). + +Note that timings degrade faster than linearly once memory pressure sets in -- +50 MB takes roughly 8x as long as 10 MB, not 5x. + +--- + +## Testing + +### Test Coverage + +Run comprehensive tests: + +```bash +python test_cipherbox.py +``` + +### Test Categories + +1. **Master Password Generation**: Strength and randomness +2. **Salt Generation**: Uniqueness and entropy +3. **Key Derivation**: Consistency and correctness +4. **Config Management**: Storage and retrieval +5. **File Encryption/Decryption**: Content integrity +6. **Filename Encryption**: UUID generation and restoration +7. **Wrong Password**: Error handling +8. **Large Files**: Multi-MB file handling + +### Test Results + +Expected: **8/8 tests pass βœ“** + +--- + +## Security Audit Checklist + +- βœ“ Passwords are never stored +- βœ“ Encryption keys are derived securely (PBKDF2) +- βœ“ Encryption uses authenticated cipher (Fernet) +- βœ“ Files are securely deleted (multi-pass overwrite) +- βœ“ Configuration files have restricted permissions (0o600) +- βœ“ Error messages don't leak sensitive information +- βœ“ No hardcoded secrets in code +- βœ“ Thread-safe operations where needed +- βœ“ Input validation on file paths +- βœ“ Comprehensive error handling + +--- + +## Deployment Considerations + +### For Personal Use + +- Run locally on your computer +- Store salt file in `~/.cipherbox/` +- Back up Master Password in password manager + +### For Team Use + +- Each user has their own Master Password +- Share encrypted files via secure channel +- Share password via separate secure channel (NOT the same channel as files) +- Each user maintains their own config/salt + +### For Backup/Archival + +- Encrypt important files +- Store `.cipherbox` files in multiple locations +- Store Master Password separately (password manager + physical backup) +- Test decryption periodically + +--- + +## Maintenance + +### Regular Maintenance Tasks + +- [ ] Update Python when new versions released +- [ ] Update dependencies: `pip install --upgrade -r requirements.txt` +- [ ] Test decryption monthly on archived files +- [ ] Back up Master Password in multiple locations +- [ ] Review config directory permissions + +### Monitoring + +- Check logs for errors: Python error messages during operation +- Monitor disk space: Large files need 2x their size free (encryption + original) +- Test recovery: Regularly decrypt sample files + +--- + +## Version History + +- **v1.0** (2026-05-02): Initial production release + - Master password auto-generation + - PBKDF2-HMAC-SHA256 key derivation (480,000 iterations) + - Fernet AES encryption + - Optional filename encryption + - Secure file deletion + - customtkinter GUI + - Comprehensive error handling + - Full test suite + +--- + +## Support Resources + +- **README.md**: Full documentation +- **QUICKSTART.md**: Quick start guide +- **test_cipherbox.py**: Diagnostic tests +- **Code comments**: Inline documentation + +--- + +## Contributing Improvements + +Feel free to enhance CipherBox by: + +1. Improving performance +2. Adding features (compression, scheduling, etc.) +3. Enhancing UI/UX +4. Expanding test coverage +5. Improving documentation + +--- + +## License + +CipherBox is provided for personal use. Modify and improve as needed. + +--- + +## Acknowledgments + +- **cryptography.io**: Excellent cryptographic library +- **customtkinter**: Modern Python GUI library +- **OWASP**: Security best practices and recommendations + +--- + +**Last Updated**: May 2, 2026 +**Status**: Production Ready βœ“ +**Author**: Security-focused Development + +For questions or improvements, review the code and make enhancements locally. πŸ” diff --git a/QUICKSTART.md b/QUICKSTART.md index 6e772ff..1ec3c7c 100644 --- a/QUICKSTART.md +++ b/QUICKSTART.md @@ -1,401 +1,404 @@ -# CipherBox Quick Start Guide - -> **For users.** Get running and encrypt your first file, step by step. -> Reference documentation lives in [README.md](README.md); architecture and -> development notes in [GUIDE.md](GUIDE.md). - -## πŸš€ Installation (2 minutes) - -### Option 1: Windows β€” download the app (Recommended) - -1. Download **[CipherBox.exe](https://github.com/aquaxs1/CipherBox/releases/latest/download/CipherBox.exe)** -2. Double-click it - -That is the whole installation. No Python, no dependencies, no unpacking. - -On first launch Windows SmartScreen shows a blue warning, because the build is -not code-signed. Choose **More info β†’ Run anyway**. - -To check the download against the published hash first: -```powershell -certutil -hashfile CipherBox.exe SHA256 -``` -Compare the result with `SHA256SUMS.txt` on the -[releases page](https://github.com/aquaxs1/CipherBox/releases/latest). - -### Option 2: Run from source (any platform) - -Needs **Python 3.10+**. On macOS/Linux this is currently the way to run -CipherBox unless a release ships a binary for your platform. - -```bash -git clone https://github.com/aquaxs1/CipherBox.git -cd CipherBox -pip install -r requirements.txt -python main.py -``` - -To confirm everything works before you trust it with real files: -```bash -python test_cipherbox.py -``` - ---- - -## πŸ“ First Launch Walkthrough - -### Step 1: Security Warning -When you launch CipherBox for the first time, you'll see a bright red warning screen. - -**Why?** Your Master Password is being generated. This is your ONLY password. - -### Step 2: Master Password Display -A 32-character cryptographically-random password appears: -- **Example**: `aBc123XyZ9kL7mN0pQrS4tUvW5xYz8aB` - -### Step 3: Save Your Password -1. Click **"πŸ“‹ Copy to Clipboard"** -2. Paste it in a SECURE location: - - Password manager (Bitwarden, 1Password, KeePass) - - Paper stored in a safe - - Encrypted note on an external drive - - **NOT** in a plain text file on your computer - -### Step 4: Confirmation -Check the box: "βœ“ I have saved this password in a safe location" - -### Step 5: Proceed -Click **"Proceed to Main Application"** - -You're now ready to encrypt/decrypt files! - ---- - -## πŸ” How to Encrypt Files - -### Basic Encryption (Keep filename) - -1. Open the **"πŸ“ Encrypt Files"** tab -2. Click **"βž• Add Files"** -3. Select one or more files to encrypt -4. Click **"πŸ” Encrypt Files"** -5. Wait for completion -6. Original files are securely deleted -7. `.cipherbox` encrypted files remain - -**Example:** -``` -Before: document.pdf (1.5 MB) -After: document.pdf.cipherbox (1.5 MB) -``` - -### Advanced: Hide Filenames - -1. Open the **"πŸ“ Encrypt Files"** tab -2. Click **"βž• Add Files"** -3. Select files -4. βœ“ Check **"πŸ”’ Encrypt filenames"** -5. Click **"πŸ” Encrypt Files"** - -**What happens:** -- Filename becomes a random UUID -- Original filename stored securely inside the encrypted file -- Restoring filename during decryption is automatic - -**Example:** -``` -Before: confidential_report.xlsx (2.1 MB) -After: a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6.cipherbox (2.1 MB) -``` - -**Benefits:** -- Files can't be identified by name -- Plausible deniability (could be any file type) -- Extra privacy layer - ---- - -## πŸ”“ How to Decrypt Files - -1. Open the **"πŸ”“ Decrypt Files"** tab -2. Click **"βž• Add Files"** -3. Select `.cipherbox` files to decrypt -4. Click **"πŸ”“ Decrypt Files"** -5. Original files are restored with original names and extensions -6. `.cipherbox` files are securely deleted - -**Example:** -``` -Before: a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6.cipherbox -After: confidential_report.xlsx -``` - -**File Naming:** -- If a file with the same name already exists, a number is appended -- Example: `document_1.pdf`, `document_2.pdf` - ---- - -## πŸ”’ Master Password Management - -### What You Need to Know - -- βœ“ Your Master Password is **YOUR ONLY PASSWORD** -- βœ“ It CANNOT be recovered if lost -- βœ“ It is NEVER stored anywhere -- βœ— No recovery options exist -- βœ— No "forgot password" reset -- βœ— Losing it means losing ALL encrypted files forever - -### Where to Store Your Master Password - -**SECURE Locations:** -1. **Password Manager** (Recommended) - - Bitwarden (open-source, free) - - 1Password (commercial) - - KeePass (open-source) - - LastPass - -2. **Physical Backup** (Recommended) - - Written on paper in a safe - - Safety deposit box - - Home safe - -3. **Redundancy** (Best Practice) - - Store in password manager + write down - - Store in multiple physical locations - - Share with trusted family member (in case of emergency) - -**INSECURE Locations:** -- βœ— Plain text files on your computer -- βœ— Sticky notes on your monitor -- βœ— Email drafts -- βœ— Cloud storage (unless encrypted) -- βœ— Text messages -- βœ— Slack/Teams messages - ---- - -## πŸ’‘ Common Scenarios - -### Scenario 1: Backup Important Files - -**Goal**: Encrypt files for secure backup - -``` -1. Select important files (documents, photos, etc.) -2. Encrypt with filename encryption enabled -3. Copy encrypted .cipherbox files to external drive -4. Store in multiple locations -5. Original files are securely deleted from computer -6. Decrypt on external drive when needed -``` - -### Scenario 2: Protect Sensitive Documents - -**Goal**: Protect documents from prying eyes - -``` -1. Select sensitive PDFs/spreadsheets -2. Encrypt with standard filename (keeps .pdf/.xlsx visible) -3. Move encrypted files to protected folder -4. Delete original files permanently -5. Only you can decrypt them -``` - -### Scenario 3: Secure File Transfer - -**Goal**: Send encrypted files to someone else - -``` -1. Encrypt files with filename encryption -2. Share encrypted .cipherbox files via any channel (email, cloud, USB) -3. Share Master Password separately (NOT via same channel) -4. Recipient installs CipherBox -5. Recipient decrypts files with your password -``` - ---- - -## ⚠️ Important Reminders - -### Before You Start - -- [ ] I have saved my Master Password in a secure location -- [ ] I understand that losing my password means losing all files -- [ ] I understand that there is NO recovery mechanism -- [ ] I have read and understand the security warnings - -### During Use - -- [ ] Close files before encrypting (don't encrypt open files) -- [ ] Keep backups of important encrypted files -- [ ] Test decryption periodically to ensure files aren't corrupted -- [ ] Keep Python and libraries updated - -### Best Practices - -- [ ] Use a password manager to store your Master Password -- [ ] Write your Master Password on paper in a secure location -- [ ] Never share your Master Password with anyone -- [ ] Test decryption on a small file before encrypting large files -- [ ] Keep the `~/.cipherbox/config.json` file safe (contains the salt) - ---- - -## πŸ› Troubleshooting - -### CipherBox won't start - -**Problem**: "ModuleNotFoundError: No module named 'customtkinter'" - -**Solution**: -```bash -pip install -r requirements.txt -``` - -### "Permission denied" error - -**Problem**: Can't encrypt/decrypt file - -**Solution**: -- Close the file in all applications -- Close any file explorer/finder windows showing the file -- Try again - -### "Wrong password or corrupted file" error - -**Problem**: Can't decrypt even with correct password - -**Solutions**: -- Double-check that you've entered the correct Master Password exactly -- Verify the `.cipherbox` file hasn't been corrupted or modified -- Try decrypting a different file to confirm password is correct -- If multiple files fail, your password may be wrong - -### Lost Master Password - -**Problem**: Can't decrypt files - -**Solution**: -- If you saved it in a password manager, retrieve it there -- If you wrote it down, look for it in your safe -- If you truly lost it: YOUR FILES ARE PERMANENTLY INACCESSIBLE - - There is no recovery - - This is by design for maximum security - ---- - -## πŸ”§ Advanced Tips - -### Batch Encryption - -You can select multiple files at once: -1. Click "βž• Add Files" -2. Hold **Ctrl** (Windows/Linux) or **Cmd** (macOS) -3. Click each file you want to encrypt -4. Click "Open" -5. All files will be encrypted together - -### Folder Encryption Workaround - -CipherBox encrypts individual files. To encrypt a folder: -1. Compress folder to ZIP file -2. Encrypt the ZIP file -3. To recover: Decrypt ZIP file, then extract - -### Multiple Encryption - -You can encrypt an encrypted file again: -1. Encrypt `document.pdf` β†’ creates `document.pdf.cipherbox` -2. Encrypt `document.pdf.cipherbox` again (yes, it works!) -3. Result: `document.pdf.cipherbox.cipherbox` -4. To decrypt: decrypt once, then decrypt again - ---- - -## πŸ“Š Performance Expectations - -### Key Derivation -- **Time**: roughly 0.1–0.5 seconds on a modern CPU, once per unlock -- **Why**: PBKDF2 with 480,000 iterations (deliberately slow, to make guessing - your master password expensive) - -### Encryption -- **1 MB**: well under a second -- **10 MB**: under half a second -- **50 MB**: a few seconds -- **Above 256 MB**: CipherBox warns first β€” see the memory note below -- **Factors**: file size, CPU speed, disk I/O - -### Memory use β€” the real limit -Files are loaded into memory whole rather than streamed, so encrypting or -decrypting needs roughly **9x the file size** in free RAM. A 100 MB file wants -about 900 MB free; a 1 GB file needs several GB and will fail on most machines. -Split very large archives before encrypting them. - -### Decryption -- Similar speed to encryption -- Key derivation (1-2 seconds) + decryption time - ---- - -## πŸŽ“ Security Concepts Explained - -### Why PBKDF2? -- **PBKDF2** (Password-Based Key Derivation Function 2) is a standard way to convert passwords into encryption keys -- **480,000 iterations** means it takes time to derive the key, making brute-force attacks infeasible -- **HMAC-SHA256** uses a cryptographically secure hash function - -### Why Fernet? -- **Fernet** combines AES (Advanced Encryption Standard) with authentication -- **Authentication** ensures encrypted files haven't been tampered with -- If someone modifies the encrypted file, decryption will fail safely - -### Why Secure Deletion? -- Simply deleting a file only removes the directory entry -- The actual data remains on disk -- **3-pass overwriting** + **zero fill**, each pass flushed to the device, makes - recovery very difficult on a magnetic disk. On an SSD, USB stick or SD card, wear - levelling writes each pass to a fresh block and the original data survives out of - reach β€” full-disk encryption is the dependable answer there. - ---- - -## πŸ“ž Support & Contact - -### Having Issues? - -1. **Check README.md** for detailed troubleshooting -2. **Review test results** from `test_cipherbox.py` -3. **Check Python version**: `python --version` (must be 3.10+) -4. **Check dependencies**: `pip list | grep customtkinter` - -### Reporting Issues - -When reporting issues, include: -- Your operating system (Windows 10/11, macOS version, Linux distro) -- Python version (`python --version`) -- Error message (exact text) -- Steps to reproduce the issue - ---- - -## πŸ“š Further Learning - -### Cryptography Concepts -- [OWASP Password Storage](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) -- [Fernet (cryptography.io)](https://cryptography.io/en/latest/fernet/) -- [PBKDF2 RFC 8018](https://tools.ietf.org/html/rfc8018) - -### Python Security -- [Official cryptography Library Docs](https://cryptography.io/) -- [Python Security Best Practices](https://python.readthedocs.io/en/latest/library/security_warnings.html) - ---- - -**Last Updated**: May 2, 2026 -**Version**: 1.0 -**Status**: Production Ready βœ“ - -Enjoy secure file encryption with CipherBox! πŸ” +# CipherBox Quick Start Guide + +> **For users.** Get running and encrypt your first file, step by step. +> Reference documentation lives in [README.md](README.md); architecture and +> development notes in [GUIDE.md](GUIDE.md). + +## πŸš€ Installation (2 minutes) + +### Option 1: Windows β€” download the app (Recommended) + +1. Download **[cipherbox-windows-x64.zip](https://github.com/aquaxs1/CipherBox/releases/latest/download/cipherbox-windows-x64.zip)** +2. Unzip it and double-click `cipherbox.exe` + +That is the whole installation. No Python, no dependencies. + +The binary ships inside an archive because browsers and antivirus engines flag a +freshly downloaded, unsigned `.exe` far more readily than the same file in a zip. + +On first launch Windows SmartScreen shows a blue warning, because the build is +not code-signed. Choose **More info β†’ Run anyway**. + +To check the download against the published hash first: +```powershell +certutil -hashfile cipherbox-windows-x64.zip SHA256 +``` +Compare the result with `SHA256SUMS.txt` on the +[releases page](https://github.com/aquaxs1/CipherBox/releases/latest). + +### Option 2: Run from source (any platform) + +Needs **Python 3.10+**. On macOS/Linux this is currently the way to run +CipherBox unless a release ships a binary for your platform. + +```bash +git clone https://github.com/aquaxs1/CipherBox.git +cd CipherBox +pip install -r requirements.txt +python main.py +``` + +To confirm everything works before you trust it with real files: +```bash +python test_cipherbox.py +``` + +--- + +## πŸ“ First Launch Walkthrough + +### Step 1: Security Warning +When you launch CipherBox for the first time, you'll see a bright red warning screen. + +**Why?** Your Master Password is being generated. This is your ONLY password. + +### Step 2: Master Password Display +A 32-character cryptographically-random password appears: +- **Example**: `aBc123XyZ9kL7mN0pQrS4tUvW5xYz8aB` + +### Step 3: Save Your Password +1. Click **"πŸ“‹ Copy to Clipboard"** +2. Paste it in a SECURE location: + - Password manager (Bitwarden, 1Password, KeePass) + - Paper stored in a safe + - Encrypted note on an external drive + - **NOT** in a plain text file on your computer + +### Step 4: Confirmation +Check the box: "βœ“ I have saved this password in a safe location" + +### Step 5: Proceed +Click **"Proceed to Main Application"** + +You're now ready to encrypt/decrypt files! + +--- + +## πŸ” How to Encrypt Files + +### Basic Encryption (Keep filename) + +1. Open the **"πŸ“ Encrypt Files"** tab +2. Click **"βž• Add Files"** +3. Select one or more files to encrypt +4. Click **"πŸ” Encrypt Files"** +5. Wait for completion +6. Original files are securely deleted +7. `.cipherbox` encrypted files remain + +**Example:** +``` +Before: document.pdf (1.5 MB) +After: document.pdf.cipherbox (1.5 MB) +``` + +### Advanced: Hide Filenames + +1. Open the **"πŸ“ Encrypt Files"** tab +2. Click **"βž• Add Files"** +3. Select files +4. βœ“ Check **"πŸ”’ Encrypt filenames"** +5. Click **"πŸ” Encrypt Files"** + +**What happens:** +- Filename becomes a random UUID +- Original filename stored securely inside the encrypted file +- Restoring filename during decryption is automatic + +**Example:** +``` +Before: confidential_report.xlsx (2.1 MB) +After: a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6.cipherbox (2.1 MB) +``` + +**Benefits:** +- Files can't be identified by name +- Plausible deniability (could be any file type) +- Extra privacy layer + +--- + +## πŸ”“ How to Decrypt Files + +1. Open the **"πŸ”“ Decrypt Files"** tab +2. Click **"βž• Add Files"** +3. Select `.cipherbox` files to decrypt +4. Click **"πŸ”“ Decrypt Files"** +5. Original files are restored with original names and extensions +6. `.cipherbox` files are securely deleted + +**Example:** +``` +Before: a1b2c3d4-e5f6-47g8-h9i0-j1k2l3m4n5o6.cipherbox +After: confidential_report.xlsx +``` + +**File Naming:** +- If a file with the same name already exists, a number is appended +- Example: `document_1.pdf`, `document_2.pdf` + +--- + +## πŸ”’ Master Password Management + +### What You Need to Know + +- βœ“ Your Master Password is **YOUR ONLY PASSWORD** +- βœ“ It CANNOT be recovered if lost +- βœ“ It is NEVER stored anywhere +- βœ— No recovery options exist +- βœ— No "forgot password" reset +- βœ— Losing it means losing ALL encrypted files forever + +### Where to Store Your Master Password + +**SECURE Locations:** +1. **Password Manager** (Recommended) + - Bitwarden (open-source, free) + - 1Password (commercial) + - KeePass (open-source) + - LastPass + +2. **Physical Backup** (Recommended) + - Written on paper in a safe + - Safety deposit box + - Home safe + +3. **Redundancy** (Best Practice) + - Store in password manager + write down + - Store in multiple physical locations + - Share with trusted family member (in case of emergency) + +**INSECURE Locations:** +- βœ— Plain text files on your computer +- βœ— Sticky notes on your monitor +- βœ— Email drafts +- βœ— Cloud storage (unless encrypted) +- βœ— Text messages +- βœ— Slack/Teams messages + +--- + +## πŸ’‘ Common Scenarios + +### Scenario 1: Backup Important Files + +**Goal**: Encrypt files for secure backup + +``` +1. Select important files (documents, photos, etc.) +2. Encrypt with filename encryption enabled +3. Copy encrypted .cipherbox files to external drive +4. Store in multiple locations +5. Original files are securely deleted from computer +6. Decrypt on external drive when needed +``` + +### Scenario 2: Protect Sensitive Documents + +**Goal**: Protect documents from prying eyes + +``` +1. Select sensitive PDFs/spreadsheets +2. Encrypt with standard filename (keeps .pdf/.xlsx visible) +3. Move encrypted files to protected folder +4. Delete original files permanently +5. Only you can decrypt them +``` + +### Scenario 3: Secure File Transfer + +**Goal**: Send encrypted files to someone else + +``` +1. Encrypt files with filename encryption +2. Share encrypted .cipherbox files via any channel (email, cloud, USB) +3. Share Master Password separately (NOT via same channel) +4. Recipient installs CipherBox +5. Recipient decrypts files with your password +``` + +--- + +## ⚠️ Important Reminders + +### Before You Start + +- [ ] I have saved my Master Password in a secure location +- [ ] I understand that losing my password means losing all files +- [ ] I understand that there is NO recovery mechanism +- [ ] I have read and understand the security warnings + +### During Use + +- [ ] Close files before encrypting (don't encrypt open files) +- [ ] Keep backups of important encrypted files +- [ ] Test decryption periodically to ensure files aren't corrupted +- [ ] Keep Python and libraries updated + +### Best Practices + +- [ ] Use a password manager to store your Master Password +- [ ] Write your Master Password on paper in a secure location +- [ ] Never share your Master Password with anyone +- [ ] Test decryption on a small file before encrypting large files +- [ ] Keep the `~/.cipherbox/config.json` file safe (contains the salt) + +--- + +## πŸ› Troubleshooting + +### CipherBox won't start + +**Problem**: "ModuleNotFoundError: No module named 'customtkinter'" + +**Solution**: +```bash +pip install -r requirements.txt +``` + +### "Permission denied" error + +**Problem**: Can't encrypt/decrypt file + +**Solution**: +- Close the file in all applications +- Close any file explorer/finder windows showing the file +- Try again + +### "Wrong password or corrupted file" error + +**Problem**: Can't decrypt even with correct password + +**Solutions**: +- Double-check that you've entered the correct Master Password exactly +- Verify the `.cipherbox` file hasn't been corrupted or modified +- Try decrypting a different file to confirm password is correct +- If multiple files fail, your password may be wrong + +### Lost Master Password + +**Problem**: Can't decrypt files + +**Solution**: +- If you saved it in a password manager, retrieve it there +- If you wrote it down, look for it in your safe +- If you truly lost it: YOUR FILES ARE PERMANENTLY INACCESSIBLE + - There is no recovery + - This is by design for maximum security + +--- + +## πŸ”§ Advanced Tips + +### Batch Encryption + +You can select multiple files at once: +1. Click "βž• Add Files" +2. Hold **Ctrl** (Windows/Linux) or **Cmd** (macOS) +3. Click each file you want to encrypt +4. Click "Open" +5. All files will be encrypted together + +### Folder Encryption Workaround + +CipherBox encrypts individual files. To encrypt a folder: +1. Compress folder to ZIP file +2. Encrypt the ZIP file +3. To recover: Decrypt ZIP file, then extract + +### Multiple Encryption + +You can encrypt an encrypted file again: +1. Encrypt `document.pdf` β†’ creates `document.pdf.cipherbox` +2. Encrypt `document.pdf.cipherbox` again (yes, it works!) +3. Result: `document.pdf.cipherbox.cipherbox` +4. To decrypt: decrypt once, then decrypt again + +--- + +## πŸ“Š Performance Expectations + +### Key Derivation +- **Time**: roughly 0.1–0.5 seconds on a modern CPU, once per unlock +- **Why**: PBKDF2 with 480,000 iterations (deliberately slow, to make guessing + your master password expensive) + +### Encryption +- **1 MB**: well under a second +- **10 MB**: under half a second +- **50 MB**: a few seconds +- **Above 256 MB**: CipherBox warns first β€” see the memory note below +- **Factors**: file size, CPU speed, disk I/O + +### Memory use β€” the real limit +Files are loaded into memory whole rather than streamed, so encrypting or +decrypting needs roughly **9x the file size** in free RAM. A 100 MB file wants +about 900 MB free; a 1 GB file needs several GB and will fail on most machines. +Split very large archives before encrypting them. + +### Decryption +- Similar speed to encryption +- Key derivation (1-2 seconds) + decryption time + +--- + +## πŸŽ“ Security Concepts Explained + +### Why PBKDF2? +- **PBKDF2** (Password-Based Key Derivation Function 2) is a standard way to convert passwords into encryption keys +- **480,000 iterations** means it takes time to derive the key, making brute-force attacks infeasible +- **HMAC-SHA256** uses a cryptographically secure hash function + +### Why Fernet? +- **Fernet** combines AES (Advanced Encryption Standard) with authentication +- **Authentication** ensures encrypted files haven't been tampered with +- If someone modifies the encrypted file, decryption will fail safely + +### Why Secure Deletion? +- Simply deleting a file only removes the directory entry +- The actual data remains on disk +- **3-pass overwriting** + **zero fill**, each pass flushed to the device, makes + recovery very difficult on a magnetic disk. On an SSD, USB stick or SD card, wear + levelling writes each pass to a fresh block and the original data survives out of + reach β€” full-disk encryption is the dependable answer there. + +--- + +## πŸ“ž Support & Contact + +### Having Issues? + +1. **Check README.md** for detailed troubleshooting +2. **Review test results** from `test_cipherbox.py` +3. **Check Python version**: `python --version` (must be 3.10+) +4. **Check dependencies**: `pip list | grep customtkinter` + +### Reporting Issues + +When reporting issues, include: +- Your operating system (Windows 10/11, macOS version, Linux distro) +- Python version (`python --version`) +- Error message (exact text) +- Steps to reproduce the issue + +--- + +## πŸ“š Further Learning + +### Cryptography Concepts +- [OWASP Password Storage](https://cheatsheetseries.owasp.org/cheatsheets/Password_Storage_Cheat_Sheet.html) +- [Fernet (cryptography.io)](https://cryptography.io/en/latest/fernet/) +- [PBKDF2 RFC 8018](https://tools.ietf.org/html/rfc8018) + +### Python Security +- [Official cryptography Library Docs](https://cryptography.io/) +- [Python Security Best Practices](https://python.readthedocs.io/en/latest/library/security_warnings.html) + +--- + +**Last Updated**: May 2, 2026 +**Version**: 1.0 +**Status**: Production Ready βœ“ + +Enjoy secure file encryption with CipherBox! πŸ” diff --git a/README.md b/README.md index 7da42a5..8b7aad1 100644 --- a/README.md +++ b/README.md @@ -1,359 +1,361 @@ -# CipherBox - Secure File Encryption Application - -> **Start here.** Installation, usage, file format, troubleshooting and security notes. -> For a step-by-step walkthrough see [QUICKSTART.md](QUICKSTART.md); for architecture -> and development details see [GUIDE.md](GUIDE.md). - -## Overview - -**CipherBox** is a modern, secure desktop application for encrypting and decrypting local files. Built with a sleek GUI and enterprise-grade cryptography, it ensures your sensitive files remain protected. - -### Key Security Features - -- **PBKDF2-HMAC-SHA256 Key Derivation**: 480,000 iterations (OWASP 2024 recommendation) -- **Fernet Encryption**: Symmetric AES encryption with authentication -- **Master Password Protection**: One secure password to encrypt/decrypt all files -- **Secure File Deletion**: Multi-pass overwriting, flushed to disk, before file removal - (effective on magnetic disks; see the note under Security Considerations for SSDs) -- **Optional Filename Encryption**: Hide original filenames using random UUIDs -- **No Plain Text Storage**: Password is never stored; only cryptographically-derived keys - ---- - -## Installation - -### Windows: download the executable (recommended) - -Download **[CipherBox.exe](https://github.com/aquaxs1/CipherBox/releases/latest/download/CipherBox.exe)** -and double-click it. The whole app is in that one file β€” no Python, no installer, -nothing to unzip. - -The build is not code-signed, so SmartScreen warns on first launch. Choose -**More info β†’ Run anyway**. - -All builds and their SHA-256 checksums are on the -[releases page](https://github.com/aquaxs1/CipherBox/releases/latest). To verify a -download: - -```powershell -certutil -hashfile CipherBox.exe SHA256 -``` - -### Run from source (any platform) - -Requires **Python 3.10+** on Windows, macOS or Linux: - -```bash -git clone https://github.com/aquaxs1/CipherBox.git -cd CipherBox -pip install -r requirements.txt -python main.py -``` - -This installs: -- **customtkinter** (v5.2.0): Modern GUI framework -- **cryptography** (v41.0.7): Strong cryptographic primitives - -### Build the executable yourself - -```bash -pip install pyinstaller -pyinstaller packaging/cipherbox.spec --noconfirm --clean -``` - -`--clean` discards PyInstaller's cache, and the spec keeps test files out of the -bundle. The binary lands in `dist/`. Delete `build/` and `dist/` before a release -build so nothing from an earlier build survives into it. - ---- - -## First-Time Setup - -When you launch CipherBox for the first time: - -1. **Master Password Generation**: A 32-character cryptographically-random password is auto-generated -2. **Critical Warning Screen**: Read the warning carefullyβ€”this is your ONLY password -3. **Copy & Confirm**: Copy the password to clipboard and confirm you've saved it -4. **Setup Complete**: Your encryption key is derived and secured - -### ⚠️ IMPORTANT SECURITY NOTES - -- **Save your Master Password securely**: - - Write it down on paper and store in a safe - - Use a password manager (Bitwarden, 1Password, KeePass) - - **NEVER** store it in plain text files on your computer - - **NEVER** share it with anyone - -- **If you lose your Master Password**: - - All encrypted files are **permanently inaccessible** - - There is NO recovery method - - This is by design for maximum security - ---- - -## Usage - -### Launching the Application - -Double-click `CipherBox.exe`, or from source: - -```bash -python main.py -``` - -### Encrypting Files - -1. Open the **"πŸ“ Encrypt Files"** tab -2. Click **"βž• Add Files"** and select one or more files -3. (Optional) Check **"πŸ”’ Encrypt filenames"** to hide original filenames -4. Click **"πŸ” Encrypt Files"** -5. Wait for completion message -6. Original files are securely deleted; encrypted `.cipherbox` files remain - -**What happens:** -- Files are encrypted with your Master Password -- If filenames are encrypted, original names are stored securely inside -- Original files are overwritten 3 times and zero-filled before deletion, with each - pass flushed to the device -- Encrypted files can be moved/copied safely - -### Decrypting Files - -1. Open the **"πŸ”“ Decrypt Files"** tab -2. Click **"βž• Add Files"** and select `.cipherbox` files to decrypt -3. Click **"πŸ”“ Decrypt Files"** -4. Enter your Master Password when prompted -5. Wait for completion message -6. Original files are restored with original names and extensions - -**What happens:** -- Encrypted `.cipherbox` files are decrypted -- Original filenames are restored (if they were encrypted) -- Original files are reconstructed -- Encrypted `.cipherbox` files are securely deleted -- If a file with the same name exists, a number is appended (e.g., `document_1.pdf`) - ---- - -## File Format & Structure - -### Encrypted File Format - -Each `.cipherbox` file contains: - -``` -β”Œβ”€ Fernet Encryption ─────────────────────────────────┐ -β”‚ β”Œβ”€ Plaintext Payload (before encryption) ─────────┐ β”‚ -β”‚ β”‚ [Metadata Length: 4 bytes] β”‚ β”‚ -β”‚ β”‚ [JSON Metadata (variable length)] β”‚ β”‚ -β”‚ β”‚ β”‚ β€’ version: 1 β”‚ β”‚ -β”‚ β”‚ β”‚ β€’ original_filename: "document.pdf" β”‚ β”‚ -β”‚ β”‚ β”‚ β€’ encrypted_filename: true/false β”‚ β”‚ -β”‚ β”‚ [Original File Content (binary)] β”‚ β”‚ -β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ ← Fernet-encrypted (includes authentication tag) β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ -``` - -### Configuration Storage - -- **Location**: `~/.cipherbox/config.json` (user's home directory) -- **Contents**: Salt for key derivation (never the password) -- **Permissions**: `0o600` (read/write by owner only) -- **Writes**: atomic β€” an interrupted write leaves the previous config intact - rather than a half-written one -- **Validation**: a config carrying no usable salt is treated as no install at - all and cleared, so residue from an old test run or build cannot lock you out - of a fresh install - ---- - -## Technical Specifications - -### Cryptography Details - -| Component | Specification | -|-----------|---| -| **Key Derivation** | PBKDF2-HMAC-SHA256 | -| **Iterations** | 480,000 (OWASP 2024) | -| **Salt Length** | 32 bytes (256 bits) | -| **Encryption Cipher** | Fernet (AES-128-CBC + HMAC-SHA256) | -| **Key Size** | 32 bytes (256 bits) | -| **Secure Deletion** | 3-pass overwrite + final zero fill, each pass fsync'd | - -### Code Architecture - -``` -CipherBox/ -β”œβ”€β”€ main.py # GUI application & orchestration -β”œβ”€β”€ crypto_utils.py # Encryption/decryption logic -β”œβ”€β”€ config_manager.py # Configuration & salt management -β”œβ”€β”€ test_cipherbox.py # Test suite -β”œβ”€β”€ packaging/ # PyInstaller build spec -β”œβ”€β”€ site/ # Documentation website -β”œβ”€β”€ requirements.txt # Python dependencies -└── README.md # This file -``` - -**Separation of Concerns:** -- **main.py**: User interface (customtkinter) -- **crypto_utils.py**: All cryptographic operations -- **config_manager.py**: Configuration file management - ---- - -## Troubleshooting - -### "Permission denied" Error - -**Problem**: File is in use by another application (e.g., open in editor) - -**Solution**: Close the file in all applications and try again - -### "Wrong password or corrupted file" - -**Problem**: Master Password is incorrect or file is damaged - -**Solution**: -- Verify you've entered the correct Master Password -- Check that the `.cipherbox` file hasn't been corrupted or modified - -### Application won't start - -**Problem**: Dependencies not installed - -**Solution**: -```bash -pip install --upgrade -r requirements.txt -``` - -### "Configuration Reset" on startup - -**Problem**: `~/.cipherbox/config.json` exists but holds no usable salt β€” residue -from an interrupted setup, an old test run or a previous build. - -**Solution**: Nothing to do. CipherBox detects this, removes the unusable file and -runs first-time setup again with a new master password. A config holding a real -salt is never removed automatically. - -Note that reinstalling does **not** clear this state: the config lives in your home -directory, not in the install. - -### Forgot Master Password - -**Problem**: Cannot decrypt files - -**Solution**: There is no recovery. Your encrypted files are permanently inaccessible. This is intentional for security. - ---- - -## Security Considerations - -### βœ“ What CipherBox Does Well - -- Uses industry-standard, audited cryptographic libraries -- Implements proper key derivation with high iteration count -- Securely deletes original files -- Never stores passwords in any form -- Uses Fernet for authenticated encryption (prevents tampering) -- Rejects a wrong master password at login instead of failing later on your files - -### ⚠️ What CipherBox Cannot Protect Against - -- **Malware**: If your computer is compromised, malware could intercept your password -- **Physical Access**: Someone with physical access and admin privileges could potentially intercept memory -- **Weak Master Passwords**: CipherBox auto-generates strong passwords, so this is not a concern -- **Data remanence on flash storage**: Secure deletion overwrites the original file in - place, which works on a magnetic disk. On an SSD, USB flash drive or SD card, wear - levelling writes each pass to a fresh physical block and leaves the original one - intact and unreachable through any file API. Copy-on-write and journalling - filesystems (Btrfs, ZFS, APFS), snapshots and backups keep old copies too. **Full-disk - encryption is the dependable protection against this**, not overwriting. - -### Best Practices - -1. **Use on a clean system**: Run on a trusted computer without malware -2. **Keep backups**: Maintain backups of encrypted files in multiple locations -3. **Test recovery**: Regularly test decryption to ensure files aren't corrupted -4. **Update Python**: Keep Python and libraries updated for security patches - ---- - -## Advanced Usage - -### Command-Line Usage (For Scripting) - -You can import CipherBox modules for programmatic use: - -```python -from crypto_utils import CryptoManager -from config_manager import ConfigManager - -crypto = CryptoManager() -config = ConfigManager() - -# Generate password -master_pwd = crypto.generate_master_password(32) - -# Load salt and derive key -salt = config.load_salt() -key = crypto.derive_key(master_pwd, salt) - -# Encrypt file -success, msg = crypto.encrypt_file("document.pdf", key, encrypt_filename=True) - -# Decrypt file -success, msg, output_path = crypto.decrypt_file("randomuuid.cipherbox", key) -``` - ---- - -## Performance - -- **Encryption/Decryption Speed**: Depends on file size and system - - Key derivation: ~1-2 seconds (PBKDF2 with 480,000 iterations) - - Typical file (1-100 MB): < 1 second - - Large files (> 1 GB): Proportional to size - -- **Memory Usage**: Minimal; files are read/written in chunks - ---- - -## License & Support - -This application is provided as-is for personal use. - -For security issues, please do NOT publicly disclose vulnerabilities. Instead, review the code and make improvements locally. - ---- - -## FAQ - -**Q: Can I change my Master Password?** -A: Not in the current version. If needed, you would need to decrypt all files with the old password and re-encrypt with a new one. - -**Q: Can I use this on external drives?** -A: Yes, but keep the `.cipherbox` config directory on your main system for easy access. - -**Q: How large can encrypted files be?** -A: Each file is loaded into memory whole rather than streamed, so peak RAM use is roughly **9x the file size** (measured across 8-96 MB inputs). A 100 MB file needs about 900 MB free; a 1 GB file needs several GB and will fail on most machines. CipherBox warns before starting on any file above 256 MB. For very large archives, split them first or use a tool that streams. - -**Q: Is CipherBox open-source?** -A: The code is provided in a straightforward format. Feel free to review, modify, and improve it. - -**Q: Can I use CipherBox on multiple devices?** -A: Yes, but you need to manually copy the `~/.cipherbox/config.json` salt file to other devices to decrypt files. Keep it in a safe location. - ---- - -## Version History - -- **v1.0** (2026-05-02): Initial release - - Master password auto-generation - - File encryption/decryption with Fernet - - Optional filename encryption - - Modern customtkinter GUI - ---- - -Enjoy secure file encryption with **CipherBox**! πŸ” +# CipherBox - Secure File Encryption Application + +> **Start here.** Installation, usage, file format, troubleshooting and security notes. +> For a step-by-step walkthrough see [QUICKSTART.md](QUICKSTART.md); for architecture +> and development details see [GUIDE.md](GUIDE.md). + +## Overview + +**CipherBox** is a modern, secure desktop application for encrypting and decrypting local files. Built with a sleek GUI and enterprise-grade cryptography, it ensures your sensitive files remain protected. + +### Key Security Features + +- **PBKDF2-HMAC-SHA256 Key Derivation**: 480,000 iterations (OWASP 2024 recommendation) +- **Fernet Encryption**: Symmetric AES encryption with authentication +- **Master Password Protection**: One secure password to encrypt/decrypt all files +- **Secure File Deletion**: Multi-pass overwriting, flushed to disk, before file removal + (effective on magnetic disks; see the note under Security Considerations for SSDs) +- **Optional Filename Encryption**: Hide original filenames using random UUIDs +- **No Plain Text Storage**: Password is never stored; only cryptographically-derived keys + +--- + +## Installation + +### Windows: download the executable (recommended) + +Download **[cipherbox-windows-x64.zip](https://github.com/aquaxs1/CipherBox/releases/latest/download/cipherbox-windows-x64.zip)**, unzip it and double-click +`cipherbox.exe`. The whole app is that one executable β€” no Python, no installer. + +It ships inside an archive on purpose: browsers and antivirus engines flag a +freshly downloaded, unsigned `.exe` far more readily than the same binary in a zip. + +The build is not code-signed, so SmartScreen warns on first launch. Choose +**More info β†’ Run anyway**. + +All builds and their SHA-256 checksums are on the +[releases page](https://github.com/aquaxs1/CipherBox/releases/latest). To verify a +download: + +```powershell +certutil -hashfile cipherbox-windows-x64.zip SHA256 +``` + +### Run from source (any platform) + +Requires **Python 3.10+** on Windows, macOS or Linux: + +```bash +git clone https://github.com/aquaxs1/CipherBox.git +cd CipherBox +pip install -r requirements.txt +python main.py +``` + +This installs: +- **customtkinter** (v5.2.0): Modern GUI framework +- **cryptography** (v41.0.7): Strong cryptographic primitives + +### Build the executable yourself + +```bash +pip install pyinstaller +pyinstaller packaging/cipherbox.spec --noconfirm --clean +``` + +`--clean` discards PyInstaller's cache, and the spec keeps test files out of the +bundle. The binary lands in `dist/`. Delete `build/` and `dist/` before a release +build so nothing from an earlier build survives into it. + +--- + +## First-Time Setup + +When you launch CipherBox for the first time: + +1. **Master Password Generation**: A 32-character cryptographically-random password is auto-generated +2. **Critical Warning Screen**: Read the warning carefullyβ€”this is your ONLY password +3. **Copy & Confirm**: Copy the password to clipboard and confirm you've saved it +4. **Setup Complete**: Your encryption key is derived and secured + +### ⚠️ IMPORTANT SECURITY NOTES + +- **Save your Master Password securely**: + - Write it down on paper and store in a safe + - Use a password manager (Bitwarden, 1Password, KeePass) + - **NEVER** store it in plain text files on your computer + - **NEVER** share it with anyone + +- **If you lose your Master Password**: + - All encrypted files are **permanently inaccessible** + - There is NO recovery method + - This is by design for maximum security + +--- + +## Usage + +### Launching the Application + +Double-click `cipherbox.exe`, or from source: + +```bash +python main.py +``` + +### Encrypting Files + +1. Open the **"πŸ“ Encrypt Files"** tab +2. Click **"βž• Add Files"** and select one or more files +3. (Optional) Check **"πŸ”’ Encrypt filenames"** to hide original filenames +4. Click **"πŸ” Encrypt Files"** +5. Wait for completion message +6. Original files are securely deleted; encrypted `.cipherbox` files remain + +**What happens:** +- Files are encrypted with your Master Password +- If filenames are encrypted, original names are stored securely inside +- Original files are overwritten 3 times and zero-filled before deletion, with each + pass flushed to the device +- Encrypted files can be moved/copied safely + +### Decrypting Files + +1. Open the **"πŸ”“ Decrypt Files"** tab +2. Click **"βž• Add Files"** and select `.cipherbox` files to decrypt +3. Click **"πŸ”“ Decrypt Files"** +4. Enter your Master Password when prompted +5. Wait for completion message +6. Original files are restored with original names and extensions + +**What happens:** +- Encrypted `.cipherbox` files are decrypted +- Original filenames are restored (if they were encrypted) +- Original files are reconstructed +- Encrypted `.cipherbox` files are securely deleted +- If a file with the same name exists, a number is appended (e.g., `document_1.pdf`) + +--- + +## File Format & Structure + +### Encrypted File Format + +Each `.cipherbox` file contains: + +``` +β”Œβ”€ Fernet Encryption ─────────────────────────────────┐ +β”‚ β”Œβ”€ Plaintext Payload (before encryption) ─────────┐ β”‚ +β”‚ β”‚ [Metadata Length: 4 bytes] β”‚ β”‚ +β”‚ β”‚ [JSON Metadata (variable length)] β”‚ β”‚ +β”‚ β”‚ β”‚ β€’ version: 1 β”‚ β”‚ +β”‚ β”‚ β”‚ β€’ original_filename: "document.pdf" β”‚ β”‚ +β”‚ β”‚ β”‚ β€’ encrypted_filename: true/false β”‚ β”‚ +β”‚ β”‚ [Original File Content (binary)] β”‚ β”‚ +β”‚ β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ +β”‚ ← Fernet-encrypted (includes authentication tag) β”‚ +β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +``` + +### Configuration Storage + +- **Location**: `~/.cipherbox/config.json` (user's home directory) +- **Contents**: Salt for key derivation (never the password) +- **Permissions**: `0o600` (read/write by owner only) +- **Writes**: atomic β€” an interrupted write leaves the previous config intact + rather than a half-written one +- **Validation**: a config carrying no usable salt is treated as no install at + all and cleared, so residue from an old test run or build cannot lock you out + of a fresh install + +--- + +## Technical Specifications + +### Cryptography Details + +| Component | Specification | +|-----------|---| +| **Key Derivation** | PBKDF2-HMAC-SHA256 | +| **Iterations** | 480,000 (OWASP 2024) | +| **Salt Length** | 32 bytes (256 bits) | +| **Encryption Cipher** | Fernet (AES-128-CBC + HMAC-SHA256) | +| **Key Size** | 32 bytes (256 bits) | +| **Secure Deletion** | 3-pass overwrite + final zero fill, each pass fsync'd | + +### Code Architecture + +``` +CipherBox/ +β”œβ”€β”€ main.py # GUI application & orchestration +β”œβ”€β”€ crypto_utils.py # Encryption/decryption logic +β”œβ”€β”€ config_manager.py # Configuration & salt management +β”œβ”€β”€ test_cipherbox.py # Test suite +β”œβ”€β”€ packaging/ # PyInstaller build spec +β”œβ”€β”€ site/ # Documentation website +β”œβ”€β”€ requirements.txt # Python dependencies +└── README.md # This file +``` + +**Separation of Concerns:** +- **main.py**: User interface (customtkinter) +- **crypto_utils.py**: All cryptographic operations +- **config_manager.py**: Configuration file management + +--- + +## Troubleshooting + +### "Permission denied" Error + +**Problem**: File is in use by another application (e.g., open in editor) + +**Solution**: Close the file in all applications and try again + +### "Wrong password or corrupted file" + +**Problem**: Master Password is incorrect or file is damaged + +**Solution**: +- Verify you've entered the correct Master Password +- Check that the `.cipherbox` file hasn't been corrupted or modified + +### Application won't start + +**Problem**: Dependencies not installed + +**Solution**: +```bash +pip install --upgrade -r requirements.txt +``` + +### "Configuration Reset" on startup + +**Problem**: `~/.cipherbox/config.json` exists but holds no usable salt β€” residue +from an interrupted setup, an old test run or a previous build. + +**Solution**: Nothing to do. CipherBox detects this, removes the unusable file and +runs first-time setup again with a new master password. A config holding a real +salt is never removed automatically. + +Note that reinstalling does **not** clear this state: the config lives in your home +directory, not in the install. + +### Forgot Master Password + +**Problem**: Cannot decrypt files + +**Solution**: There is no recovery. Your encrypted files are permanently inaccessible. This is intentional for security. + +--- + +## Security Considerations + +### βœ“ What CipherBox Does Well + +- Uses industry-standard, audited cryptographic libraries +- Implements proper key derivation with high iteration count +- Securely deletes original files +- Never stores passwords in any form +- Uses Fernet for authenticated encryption (prevents tampering) +- Rejects a wrong master password at login instead of failing later on your files + +### ⚠️ What CipherBox Cannot Protect Against + +- **Malware**: If your computer is compromised, malware could intercept your password +- **Physical Access**: Someone with physical access and admin privileges could potentially intercept memory +- **Weak Master Passwords**: CipherBox auto-generates strong passwords, so this is not a concern +- **Data remanence on flash storage**: Secure deletion overwrites the original file in + place, which works on a magnetic disk. On an SSD, USB flash drive or SD card, wear + levelling writes each pass to a fresh physical block and leaves the original one + intact and unreachable through any file API. Copy-on-write and journalling + filesystems (Btrfs, ZFS, APFS), snapshots and backups keep old copies too. **Full-disk + encryption is the dependable protection against this**, not overwriting. + +### Best Practices + +1. **Use on a clean system**: Run on a trusted computer without malware +2. **Keep backups**: Maintain backups of encrypted files in multiple locations +3. **Test recovery**: Regularly test decryption to ensure files aren't corrupted +4. **Update Python**: Keep Python and libraries updated for security patches + +--- + +## Advanced Usage + +### Command-Line Usage (For Scripting) + +You can import CipherBox modules for programmatic use: + +```python +from crypto_utils import CryptoManager +from config_manager import ConfigManager + +crypto = CryptoManager() +config = ConfigManager() + +# Generate password +master_pwd = crypto.generate_master_password(32) + +# Load salt and derive key +salt = config.load_salt() +key = crypto.derive_key(master_pwd, salt) + +# Encrypt file +success, msg = crypto.encrypt_file("document.pdf", key, encrypt_filename=True) + +# Decrypt file +success, msg, output_path = crypto.decrypt_file("randomuuid.cipherbox", key) +``` + +--- + +## Performance + +- **Encryption/Decryption Speed**: Depends on file size and system + - Key derivation: ~1-2 seconds (PBKDF2 with 480,000 iterations) + - Typical file (1-100 MB): < 1 second + - Large files (> 1 GB): Proportional to size + +- **Memory Usage**: Minimal; files are read/written in chunks + +--- + +## License & Support + +This application is provided as-is for personal use. + +For security issues, please do NOT publicly disclose vulnerabilities. Instead, review the code and make improvements locally. + +--- + +## FAQ + +**Q: Can I change my Master Password?** +A: Not in the current version. If needed, you would need to decrypt all files with the old password and re-encrypt with a new one. + +**Q: Can I use this on external drives?** +A: Yes, but keep the `.cipherbox` config directory on your main system for easy access. + +**Q: How large can encrypted files be?** +A: Each file is loaded into memory whole rather than streamed, so peak RAM use is roughly **9x the file size** (measured across 8-96 MB inputs). A 100 MB file needs about 900 MB free; a 1 GB file needs several GB and will fail on most machines. CipherBox warns before starting on any file above 256 MB. For very large archives, split them first or use a tool that streams. + +**Q: Is CipherBox open-source?** +A: The code is provided in a straightforward format. Feel free to review, modify, and improve it. + +**Q: Can I use CipherBox on multiple devices?** +A: Yes, but you need to manually copy the `~/.cipherbox/config.json` salt file to other devices to decrypt files. Keep it in a safe location. + +--- + +## Version History + +- **v1.0** (2026-05-02): Initial release + - Master password auto-generation + - File encryption/decryption with Fernet + - Optional filename encryption + - Modern customtkinter GUI + +--- + +Enjoy secure file encryption with **CipherBox**! πŸ” diff --git a/site/download.html b/site/download.html new file mode 100644 index 0000000..5d4860e --- /dev/null +++ b/site/download.html @@ -0,0 +1,106 @@ + + + + + + + +Download β€” CipherBox + + + + + + + + + + + + + + + +
+ +
+ +
+ +
+

Download

+

One archive, unzipped where you want it. Always the newest release.

+ +
+
+

Windows

+

cipherbox-windows-x64.zip

+

The whole app in one executable, shipped inside a zip. Unzip it, + double-click cipherbox.exe, done β€” nothing to install, no Python.

+ Download for Windows +

Windows 10 & 11 (64-bit) Β· + All downloads and checksums

+
+
+

First launch

+

Windows does not know this file yet, so SmartScreen shows a blue + warning. Choose More info β†’ Run anyway. It appears because + the build is not code-signed, not because anything is wrong with it. The + binary ships inside a zip for the same reason β€” antivirus engines flag a + freshly downloaded bare .exe far more readily.

+

Paranoid? Check the file against the published hash first:

+
certutil -hashfile cipherbox-windows-x64.zip SHA256
+
+
+ +
+ macOS, Linux, or running from source +
+

Prebuilt macOS and Linux binaries ship with tagged releases when they are + available β€” check the + latest release. + Otherwise run it from source on any platform. Needs Python 3.10+:

+
git clone https://github.com/aquaxs1/CipherBox.git
+cd CipherBox
+pip install -r requirements.txt
+python main.py
+

This pulls in customtkinter and cryptography, + and skips the unsigned-binary warning entirely.

+
+
+
+ +
+ +
+
+
+ Download + Setup + Features + GitHub + License (MIT) + Terms of Use +
+

+ No recovery: lose your master password and your encrypted files + are gone for good. Provided β€œas is”, without warranty β€” see the + terms. +

+

Β© 2026 AquaXS. All rights reserved. Released under the MIT License.

+
+
+ + + diff --git a/site/index.html b/site/index.html index 63b1a69..3338f52 100644 --- a/site/index.html +++ b/site/index.html @@ -23,14 +23,14 @@
@@ -43,8 +43,8 @@

Your files.
Readable only by you.

CipherBox is a desktop app that encrypts local files with AES (Fernet) and PBKDF2-HMAC-SHA256. One master password β€” no cloud, no account.

- Download for Windows - Other platforms + Download + Setup guide

Free Β· No installer Β· No Python required

@@ -53,57 +53,6 @@

Your files.
Readable only by you.

-
-

Download

- -
-
-

Windows

-

CipherBox.exe

-

The whole app in one file. Download it, double-click it, done β€” - nothing to install, no Python, no unzipping.

- Download CipherBox.exe -

β‰ˆ17 MB Β· Windows 10 & 11 (64-bit) Β· - All downloads and checksums

-
-
-

First launch

-

Windows does not know this file yet, so SmartScreen shows a blue - warning. Choose More info β†’ Run anyway. It appears because - the build is not code-signed, not because anything is wrong with it.

-

Paranoid? Check the file against the published hash first:

-
certutil -hashfile CipherBox.exe SHA256
-
-
- -
- macOS, Linux, or running from source -
-

Prebuilt macOS and Linux binaries ship with tagged releases when they are - available β€” check the - latest release. - Otherwise run it from source on any platform. Needs Python 3.10+:

-
git clone https://github.com/aquaxs1/CipherBox.git
-cd CipherBox
-pip install -r requirements.txt
-python main.py
-

This pulls in customtkinter and cryptography, - and skips the unsigned-binary warning entirely.

-
-
-
- -
-

How to use it

-

Double-click CipherBox.exe. From source it is python main.py.

-
    -
  1. First launch: CipherBox generates a 32-character master password. Store it somewhere safe β€” without it there is no recovery.
    2. -
  2. Encrypt: Open the β€œEncrypt Files” tab, add your files, optionally encrypt filenames, and run it. Originals are securely overwritten and deleted, leaving .cipherbox files behind.
    3. -
  3. Decrypt: Open the β€œDecrypt Files” tab, pick your .cipherbox files and enter the master password. Original names and contents are restored.
    4. -
-

For scripting you can import crypto_utils.CryptoManager and config_manager.ConfigManager directly.

-
-

What it can do

@@ -143,12 +92,12 @@

Batch processing