Encrypted Vault

Overview

Encrypted Vault is a portable, GitHub-friendly encrypted file storage solution. Every file you add is individually encrypted with a unique random 256-bit key. All metadata is stored in an opaque binary format — no readable JSON or plain-text headers that could expose sensitive information.

The application supports a full-featured graphical interface built with PyQt6 and a powerful CLI for scripting and automation. Built-in viewers let you preview images, PDFs, videos, audio, and text files directly from within the vault without writing anything to disk.

Features

Prerequisites

• Python 3.8 or higher — Download Python
• pip — Python package manager (bundled with Python 3.4+)
• virtualenv (recommended) — for isolated environments

Dependencies

Installation

1. Clone the repository

   copygit clone https://github.com/AadithyanRaju/Encrypted-Vault.git
   cd Encrypted-Vault

2. Create a virtual environment (recommended)

   Linux / macOS Windows (PowerShell) Windows (CMD)

   copypython3 -m venv .venv
   source .venv/bin/activate

   copypython -m venv .venv
   .venv\Scripts\Activate.ps1

   copypython -m venv .venv
   .venv\Scripts\activate.bat

3. Install dependencies

   copypip install -r requirements.txt

GUI Mode

The graphical interface provides a full file-manager-like experience for your encrypted vault.

Launch the GUI

copy# Open the GUI without specifying a vault
python src/efs.py gui

# Open the GUI with a vault pre-loaded
python src/efs.py gui /path/to/vault

GUI Capabilities

• 🔓 Unlock / lock vault — enter your master passphrase to decrypt the metadata index
• ➕ Add files & folders — drag-and-drop or use the file browser, with optional relative path
• 📂 Tree view with search — browse your encrypted files hierarchically and filter by name
• 👁️ In-vault preview — images, PDFs, videos, audio, and text without extracting to disk
• 💾 Extract files — save individual files or bulk-export the entire vault
• ✏️ Rename & delete — manage files without decrypting them
• 🔑 Change master password — rotate your passphrase and optionally adjust Argon2 parameters

CLI Mode

The command-line interface is designed for scripting, automation, and headless environments.

Initialize a New Vault

copy# Default Argon2 parameters
python src/efs.py init /path/to/vault --passphrase "your-secure-passphrase"

# Custom Argon2 parameters for higher security
python src/efs.py init /path/to/vault --passphrase "your-passphrase" -t 8 -m 524288 -p 4

Add Files

copy# Add a single file
python src/efs.py add /path/to/vault /path/to/file.txt --passphrase "your-passphrase"

# Preserve the original folder path inside the vault
python src/efs.py add /path/to/vault /path/to/file.txt \
  --relpath "documents/file.txt" --passphrase "your-passphrase"

List Encrypted Files

copypython src/efs.py ls /path/to/vault --passphrase "your-passphrase"

Extract Files

copypython src/efs.py extract /path/to/vault <file-id> /output/path.txt \
  --passphrase "your-passphrase"

Remove a File

copypython src/efs.py rm /path/to/vault <file-id> --passphrase "your-passphrase"

Rename a File

copypython src/efs.py rename /path/to/vault <file-id> "new-name.txt" \
  --passphrase "your-passphrase"

Rotate Master Key

copy# Change passphrase only
python src/efs.py rotate-master /path/to/vault \
  --passphrase "old-passphrase" --new-passphrase "new-passphrase"

# Change passphrase and update Argon2 parameters
python src/efs.py rotate-master /path/to/vault \
  --passphrase "old-passphrase" --new-passphrase "new-passphrase" \
  -t 8 -m 524288 -p 4

CLI Reference

Global Options

Vault Structure

When you initialize a vault at /path/to/vault, the following directory structure is created on disk:

• vault.enc — holds the encrypted metadata index (filenames, UUIDs, per-file keys). Nothing is readable without the correct passphrase.
• blobs/<uuid>.bin — each blob is the raw nonce followed by the AES-256-GCM ciphertext of a single file. The UUID is meaningless without the metadata.

Binary Format

The vault.enc header is a fixed-size 45-byte binary structure followed by the encrypted metadata ciphertext.

File Blob Format

Each blobs/<uuid>.bin file has a minimal format:

Project Structure

Security Details

Encryption

• Algorithm: AES-256-GCM — authenticated encryption; ciphertext integrity is cryptographically verified on every read.
• Key size: 256-bit (32 bytes) per-file random key, independently generated for every file.
• Nonce: 96-bit random nonce per encryption operation — never reused.
• Key wrapping: Per-file keys are encrypted with the master key before being stored in vault.enc.

Key Derivation

• Algorithm: Argon2id — memory-hard, resists GPU/ASIC brute-force and side-channel attacks.
• Pre-hashing: The passphrase is pre-hashed with SHA3-512 before being passed to Argon2id for additional length-normalisation.
• Salt: 128-bit random salt stored in vault.enc — unique per vault, regenerated on master key rotation.
• Configurable parameters: Time cost, memory cost, and parallelism are tunable to match your hardware.

Threat Model

Encrypted Vault protects files at rest. It does not protect:

• Files while they are unlocked in memory
• Against malware or keyloggers running on your system
• Against an adversary with physical access to an unlocked vault
• Network transmission (use HTTPS/SSH for transfers)

Secure Storage Recommendations

• Never commit passphrases or unencrypted secrets to version control.
• Set restrictive filesystem permissions on your vault directory (chmod 700 on Linux/macOS).
• Store vault.enc and blobs/ in a location with appropriate access controls.
• Keep all dependencies up to date to patch security vulnerabilities.

Best Practices

• Use a strong, unique passphrase — 20+ characters, mixed case, numbers, and symbols.
• Enable full-disk encryption on your system (BitLocker / FileVault / LUKS) as a complementary layer.
• Keep your operating system and dependencies updated to patch security vulnerabilities.
• Use higher Argon2 parameters (-t, -m) on powerful machines for better brute-force resistance.
• Back up your encrypted vault to multiple locations (local + cloud) to protect against hardware failure.
• Rotate your master key periodically or immediately after any suspected passphrase exposure.

Building a Standalone Executable

You can bundle Encrypted Vault into a self-contained .exe (or binary on Linux/macOS) that doesn't require Python to be installed on the target machine.

copypyinstaller vault.exe.spec

The packaged application will be created in the dist/ directory as vault.exe. You can distribute this file as a standalone application.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository

   Click Fork on GitHub to create your own copy.

2. Create a feature branch

   copygit checkout -b feature/your-amazing-feature

3. Make your changes

   Keep changes focused, minimal, and well-tested.

4. Commit with a descriptive message

   copygit commit -m "feat: add support for XYZ"

5. Open a Pull Request

   Push your branch and open a PR against the main branch describing your changes.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Copyright © 2025 Aadithyan Raju

Built with cryptography, PyQt6, and argon2-cffi.