Skip to content

GUIDE.md

Latest commit

 

History

History
619 lines (453 loc) · 16.1 KB

GUIDE.md

File metadata and controls

619 lines (453 loc) · 16.1 KB
Raw

CipherBox - Complete Developer & User Guide

📋 Table of Contents

  1. Project Overview
  2. Architecture
  3. Installation
  4. Usage Guide
  5. Security Implementation
  6. Code Quality
  7. Troubleshooting
  8. 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)
✓ 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 (23 KB)
├── crypto_utils.py      # Cryptographic operations (10 KB)
├── config_manager.py    # Configuration & salt management (3 KB)
├── test_cipherbox.py    # Comprehensive test suite (11 KB)
├── requirements.txt     # Python dependencies
├── install.bat          # Windows installer
├── install.sh           # macOS/Linux installer
├── README.md            # Full documentation (9 KB)
├── QUICKSTART.md        # Quick start guide (11 KB)
└── 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

Prerequisites

  • Python 3.10+: Download from python.org
  • Admin/User access: For file operations
  • ~500 MB disk space: For Python + dependencies

Quick Install

Windows

install.bat

macOS/Linux

chmod +x install.sh
./install.sh

Manual

pip install -r requirements.txt
python test_cipherbox.py    # Verify installation
python main.py              # Launch application

Verification

Test the installation:

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:

# 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:

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"

# 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'"

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

# Add execution permission if needed
chmod +x main.py

# Run with proper permissions
python3 main.py

GUI doesn't appear (Linux)

# 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

{
  "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

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

# 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 (approximate, varies by system)

Operation Time File Size
Master Password Generation 100 ms N/A
Salt Generation 10 ms N/A
Key Derivation (480k iterations) 1.5 seconds N/A
Encrypt Small File 500 ms 1 MB
Encrypt Medium File 2 seconds 50 MB
Encrypt Large File 30 seconds 1 GB
Decrypt Small File 600 ms 1 MB
Secure Delete 50 ms 1 MB

Testing

Test Coverage

Run comprehensive tests:

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. 🔐