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.

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