v3.0-final

🔐 CryptGuard v3.0-final — "SecretStream + KeyGuard"

(September 2025)

Version 3.0 introduces a unified cryptographic approach and integrated password management:

• Single algorithm: XChaCha20-Poly1305 SecretStream with streaming AEAD and per-frame authentication.
• Header as AAD commitment — stream header and KDF parameters are authenticated, preventing tampering.
• Authenticated TAG_FINAL with metadata carrying original name, extension, true size, and padding info.
• Integrated KeyGuard — secure password generator with entropy calculation and dedicated vault.
• Enhanced Vault with AAD binding, secure logging, and atomic operations.
• Simplified KDF profiles — Interactive (fast) and Sensitive (robust) with auto-calibration.

---

🚀 What's New (since v2.7.0)

CG2 Format & Crypto

Area	Update & Benefit
Unified SecretStream (v5)	All new files use XChaCha20-Poly1305 SecretStream exclusively — streaming AEAD with per-frame authentication and authenticated end-marker.
Header as AAD	Stream header + KDF parameters are bound as Associated Data, providing commitment and preventing parameter tampering or downgrade attacks.
TAG_FINAL metadata	Final chunk carries authenticated JSON with orig_name, orig_ext, pt_size, chunks, pad — automatic extension restore and exact size verification.
Reduced padding ceiling	Padding reduced from 1 MiB to 16 KiB maximum for better size privacy vs bloat trade-off.
Simplified KDF profiles	Two profiles: Interactive (everyday use) and Sensitive (high-security) with auto-calibrated, authenticated parameters.

KeyGuard Integration

Area	Update & Benefit
Password generator	Cryptographically secure generator using secrets module with real-time entropy calculation and pattern rejection.
Multiple character sets	Support for Numbers (10), Letters (52), Alphanumeric (62), and Full punctuation (94) character sets with customizable length.
KeyGuard Vault	Dedicated vault for password entries with atomic storage, compression, rate limiting, and secure entry management.
Sidebar UI integration	Non-intrusive side panel with Qt/Tk support and graceful fallback if modules are unavailable.
Entropy visualization	Real-time entropy calculation showing password strength in bits with minimum threshold warnings.

Vault & App Enhancements

Area	Update & Benefit
AAD-bound vault	Main vault now binds headers via AAD for stronger tampering detection, with secure logging that masks secrets.
Atomic operations	Robust file operations with automatic backup recovery and better SQLite PRAGMAs where applicable.
Dual vault system	Separate KeyGuard vault for passwords and main vault for encrypted files — independent backup and recovery.
Enhanced security	Improved process protection, secure memory handling, and defensive file I/O throughout the application.

---

🔑 KeyGuard: Integrated Password Management

Version 3.0 introduces KeyGuard, a comprehensive password management solution built directly into CryptGuard:

Secure Generation

• Cryptographically secure: Uses Python's secrets module for strong randomness
• Real-time entropy calculation: Shows password strength in bits with visual feedback
• Pattern rejection: Automatically discards weak patterns during generation
• Customizable length: Generate passwords from 1 to 128+ characters

Character Set Options

• Numbers (10 chars): 0-9
• Letters (52 chars): a-z, A-Z
• Alphanumeric (62 chars): Letters + Numbers
• Full (94 chars): Letters + Numbers + Punctuation

KeyGuard Vault

• Secure storage: Dedicated vault for password entries with NaCl SecretBox encryption
• Atomic operations: Safe file operations with automatic backup and recovery
• Compression: Transparent gzip compression before encryption
• Rate limiting: Built-in protection against brute-force attacks
• Entry management: Add, edit, delete, and reorder password entries

Integration

• Sidebar UI: Non-intrusive side panel that doesn't interfere with main workflow
• Dynamic loading: Graceful fallback if KeyGuard modules are unavailable
• Multi-framework: Works with both Qt (PySide6) and Tk interfaces
• Independent operation: KeyGuard vault is separate from main CryptGuard vault

---

🔄 Compatibility & Upgrade Notes

• New files are CG2 v5 (XChaCha20-Poly1305 SecretStream with header as AAD and TAG_FINAL metadata).
• Legacy compatibility: v1–v4 files still decrypt normally with backward-compatible readers.
• Write-only v5: All new encryptions use the unified SecretStream format exclusively.
• Automatic extension restore: v5 files automatically restore original filename and extension on decrypt.
• Reduced padding: Maximum padding reduced from 1 MiB to 16 KiB for better size privacy trade-off.
• KDF profile migration: Old files retain their original KDF parameters; new profiles apply only to v5 files.

---

🏦 Dual Vault System (v3.0)

Version 3.0 features a dual vault system for different types of secure storage:

Main CryptGuard Vault (Enhanced)

• Purpose: Stores your already-encrypted .cg2 files for organization and additional protection.
• AAD binding: Headers are now bound via Associated Authenticated Data for stronger tampering detection.
• Secure logging: Uses SecureFormatter to mask secrets in log files.
• Atomic operations: Robust file handling with automatic backup and recovery.
• Workflow: Tick "Store encrypted file in Vault" during encryption; use Vault button to manage entries.

KeyGuard Vault (New)

• Purpose: Dedicated storage for password entries generated by the KeyGuard system.
• Independent security: Separate passphrase and encryption from main vault.
• Entry management: Store, organize, and retrieve generated passwords with metadata.
• Compression: Transparent gzip compression before NaCl SecretBox encryption.
• Rate limiting: Built-in protection against brute-force attempts.

Security Model

• Defense in depth: Both vaults add layers of protection beyond the base encryption.
• Local storage: Everything stays on your machine — no cloud dependencies.
• Separate passphrases: Each vault can have its own independent passphrase.
• Privacy hygiene: Keeps sensitive files organized and prevents scattered .cg2 files.

---

🛠 Build / Install

Slim Windows build (recommended)

# Include PyNaCl for SecretStream support (required in v3.0):
pyinstaller --onefile --windowed --name "CryptGuard" --icon .\cryptguard.ico main_app.py

# For minimal build without KeyGuard (if modules/keyguard is not needed):
# pyinstaller --onefile --windowed --name "CryptGuard" --icon .\cryptguard.ico --exclude-module modules.keyguard main_app.py

Avoid --collect-all (bloats to >200 MB). If Qt complains about a missing plugin, add only what’s needed via --collect-data/--collect-binaries or --hidden-import.

From source (Python 3.11+)

git clone https://github.com/<your-user>/CryptGuardv2.git
cd CryptGuardv2
python -m venv .venv
# Windows:
.venv\Scripts\activate
# Linux/macOS:
source .venv/bin/activate
pip install -r requirements.txt
python main_app.py

---

🧪 Verify the Hardening

pip install -r dev-requirements.txt
pytest -n auto

---

⚠️ Notes & Limitations

• Do not run as Administrator if you need drag-and-drop on Windows (UAC restriction).
• Size padding (max 16 KiB) hides exact size but not coarse traffic analysis.
• Malware/OS compromise can capture passphrases or plaintext.
• Both vaults strengthen hygiene and privacy but depend on their passphrases and OS protections.
• KeyGuard requires the modules/keyguard package; falls back gracefully if unavailable.
• SecretStream (PyNaCl/libsodium) is required for v3.0 — older crypto backends remain for legacy decr...