Start here. Installation, usage, file format, troubleshooting and security notes. For a step-by-step walkthrough see QUICKSTART.md; for architecture and development details see GUIDE.md.
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.
- 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
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. To verify a download:
certutil -hashfile cipherbox-windows-x64.zip SHA256Requires Python 3.10+ on Windows, macOS or Linux:
git clone https://github.com/aquaxs1/CipherBox.git
cd CipherBox
pip install -r requirements.txt
python main.pyThis installs:
- customtkinter (v5.2.0): Modern GUI framework
- cryptography (v41.0.7): Strong cryptographic primitives
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.
When you launch CipherBox for the first time:
- Master Password Generation: A 32-character cryptographically-random password is auto-generated
- Critical Warning Screen: Read the warning carefully—this is your ONLY password
- Copy & Confirm: Copy the password to clipboard and confirm you've saved it
- Setup Complete: Your encryption key is derived and secured
-
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
Double-click cipherbox.exe, or from source:
python main.py- Open the "📝 Encrypt Files" tab
- Click "➕ Add Files" and select one or more files
- (Optional) Check "🔒 Encrypt filenames" to hide original filenames
- Click "🔐 Encrypt Files"
- Wait for completion message
- Original files are securely deleted; encrypted
.cipherboxfiles 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
- Open the "🔓 Decrypt Files" tab
- Click "➕ Add Files" and select
.cipherboxfiles to decrypt - Click "🔓 Decrypt Files"
- Enter your Master Password when prompted
- Wait for completion message
- Original files are restored with original names and extensions
What happens:
- Encrypted
.cipherboxfiles are decrypted - Original filenames are restored (if they were encrypted)
- Original files are reconstructed
- Encrypted
.cipherboxfiles are securely deleted - If a file with the same name exists, a number is appended (e.g.,
document_1.pdf)
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) │
└─────────────────────────────────────────────────────┘
- 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
| 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 |
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
Problem: File is in use by another application (e.g., open in editor)
Solution: Close the file in all applications and try again
Problem: Master Password is incorrect or file is damaged
Solution:
- Verify you've entered the correct Master Password
- Check that the
.cipherboxfile hasn't been corrupted or modified
Problem: Dependencies not installed
Solution:
pip install --upgrade -r requirements.txtProblem: ~/.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.
Problem: Cannot decrypt files
Solution: There is no recovery. Your encrypted files are permanently inaccessible. This is intentional for security.
- 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
- 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.
- Use on a clean system: Run on a trusted computer without malware
- Keep backups: Maintain backups of encrypted files in multiple locations
- Test recovery: Regularly test decryption to ensure files aren't corrupted
- Update Python: Keep Python and libraries updated for security patches
You can import CipherBox modules for programmatic use:
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)-
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
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.
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.
- 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! 🔐