securevault-pqc 0.3.0.post1
Post-quantum file encryption using ML-KEM-768 + X25519
License: MIT
Requires Python: >=3.9

# SecureVault - Post-Quantum File Encryption
***Protect your files from future quantum computers.***

SecureVault is a cross-platform post-quantum encryption tool that protects files using NIST-standardized ML-KEM-768 combined with classical X25519 hybrid encryption.

![Python Version](https://img.shields.io/badge/python-3.9%2B-blue)
![License](https://img.shields.io/badge/license-MIT-green)
![Platform](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)
![Cryptography](https://img.shields.io/badge/crypto-ML--KEM--768-purple)
![NIST](https://img.shields.io/badge/NIST-Post--Quantum-orange)
![Status](https://img.shields.io/badge/status-active-success)


## The Problem
Quantum computers will break RSA/ECC encryption within 10-20 years. 
Attackers are stealing encrypted data NOW to decrypt LATER.

This is called "**harvest now, decrypt later**" attacks.

## The Solution
SecureVault uses:

- ML-KEM-768 (NIST standardized post-quantum KEM)  
- X25519 (classical elliptic-curve)  
- Hybrid encryption (both together)

Even if one system is broken in the future, the other still protects your data (I like to call this defense in depth²)


## Features

- **Hybrid encryption**: X25519 + ML-KEM-768 (defense in depth²)
- **Authenticated file encryption** using Fernet (AES-CBC + HMAC)
- **Password-protected keys**: PBKDF2 key derivation (100k iterations)
- **Cross-platform**: Works on Linux, macOS, and Windows
- **Post-quantum ready**: Uses NIST-standardized algorithms designed to resist known quantum attacks
- **Digital signatures**: Ed25519 + ML-DSA-65  
- **Easy CLI + Desktop GUI**: Simple commands, no crypto knowledge needed; very easy to navigate
- **No installation required for GUI**: Download and run - works out of the box
- **Educational**: Shows security info about your files
- **Designed for long-term security**

## Choose Your Version

| Version | Best For | Installation |
|---------|----------|--------------|
| **Desktop GUI** | Most users, drag-and-drop simplicity | [Download](https://meganealexis.net/securevault/) |
| **CLI** | Developers, automation, scripting | `pip install securevault-pqc` |

**Note:** GUI executables are version 0.3.0. CLI package may have newer versions with documentation updates.

## Installation

### Option 1: Desktop GUI (Recommended for most users)

Download the standalone application for your platform:

🔗 **[Download SecureVault GUI](https://meganealexis.net/securevault/)**

**Available for:**
- Windows (`.exe`)
- macOS (`.app`)
- Linux (executable)

**Security verification:**
Before running the downloaded file, verify its integrity using the checksums provided on the download page. This ensures your download wasn't modified or intercepted.
```bash
# macOS/Linux
shasum -a 256 SecureVault-macos

# Windows (PowerShell)
Get-FileHash SecureVault-windows.exe -Algorithm SHA256
```

Compare the output with the checksum at: https://meganealexis.net/securevault/

**No installation required** - just download, verify, and run!

---

### Option 2: Command-Line Interface (CLI)

For developers, automation, or advanced users who prefer the terminal.

#### Prerequisites
- Python 3.9 or higher
- pip

#### Platform-Specific Setup

### liboqs / liboqs-python Compatibility

SecureVault currently targets:

- liboqs-python >= 0.14.1 and < 0.15

In most cases, you do NOT need to build liboqs manually.
If installation succeeds with pip, you can skip manual setup.


##### macOS Setup

> Manual build instructions below are for advanced users.
> The liboqs version shown may differ from the liboqs-python wheel and can be adjusted if needed.

```bash
# 1. Install CMake (if not already installed)
brew install cmake

# 2. Build liboqs with shared library support
cd /tmp
git clone --branch 0.15.0 https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build && cd build
cmake -DBUILD_SHARED_LIBS=ON -DCMAKE_INSTALL_PREFIX=/opt/homebrew/opt/liboqs ..
make -j$(sysctl -n hw.ncpu)
sudo make install

# 3. Create symlinks where liboqs-python expects the library
mkdir -p ~/.oqs/lib ~/.oqs/lib64
ln -sf /opt/homebrew/opt/liboqs/lib/liboqs.dylib ~/.oqs/lib/liboqs.dylib
ln -sf /opt/homebrew/opt/liboqs/lib/liboqs.dylib ~/.oqs/lib64/liboqs.dylib

# 4. Create and activate virtual environment
cd ~/Documents/Testing_securevault
python3 -m venv venv
source venv/bin/activate

# 5. Install SecureVault
pip install securevault-pqc

# 6. Test it!
securevault --help
```

##### Windows Setup

> Manual build instructions below are for advanced users.
> The liboqs version shown may differ from the liboqs-python wheel and can be adjusted if needed.

```bash
# 1. Install Chocolatey build tools (if not already installed)
choco install visualstudio2022buildtools visualstudio2022-workload-vctools -y

# 2. Build liboqs
cd $env:TEMP
git clone --branch 0.15.0 https://github.com/open-quantum-safe/liboqs.git
cd liboqs
mkdir build
cd build

cmake -DBUILD_SHARED_LIBS=ON `
  -DCMAKE_INSTALL_PREFIX="$env:USERPROFILE\_oqs" `
  -G "Visual Studio 17 2022" -A x64 ..

cmake --build . --config Release
cmake --install . --config Release

# 3. Verify DLL was created 
ls "$env:USERPROFILE\_oqs\bin\oqs.dll"

# 4. Create and activate virtual environment
cd ~/Documents/Testing_securevault
python -m venv venv
.\venv\Scripts\Activate.ps1

# 5. Install SecureVault
pip install securevault-pqc

# 6. Test it!
securevault --help
```

##### Linux Setup
```bash
# 1. Install dependencies (Ubuntu/Debian)
sudo apt-get update
sudo apt-get install cmake build-essential

# 2. Create and activate virtual environment
cd ~/Documents/Testing_securevault
python3 -m venv venv
source venv/bin/activate

# 3. Install SecureVault
pip install securevault-pqc

# 4. Test it!
securevault --help
```

## Quick Start

### Basic Workflow
```
Alice generates keys → Shares alice_public.key with Bob
Bob encrypts file.txt using alice_public.key + bob.key → Sends file.txt.vault to Alice
Alice decrypts file.txt.vault using alice.key + bob_public.key
```

### CLI Example
```bash
# 1. Generate your keypair
securevault keygen --output my_keys.key
# You'll be asked to enter a password - remember it, you'll need it for encrypting/decrypting
# Creates: my_keys.key (private) and my_keys_public.key (public)

# 2. Share your public key
# Send my_keys_public.key to anyone who wants to send you encrypted files
# Get their public key (e.g., alice_public.key) for sending files to them

# 3. Create a test file
echo "Secret data" > secret.txt

# 4. Encrypt a file (sending to Alice)
securevault encrypt secret.txt alice_public.key my_keys.key
# You'll be asked to enter your password
# Output: secret.txt.vault

# 5. Check security info
securevault info secret.txt.vault

# 6. Decrypt a file (Alice received your file)
securevault decrypt secret.txt.vault alice.key my_keys_public.key
# Alice enters her password
# Output: secret.txt
```

### Real Example with Names

If your private key is `bob.key` and you're sending to Alice (`alice_public.key`):
```bash
securevault encrypt document.pdf alice_public.key bob.key
```

If your private key is `alice.key` and you're receiving from Bob (`bob_public.key`):
```bash
securevault decrypt document.pdf.vault alice.key bob_public.key
```

## Common Mistakes

- Using a private key when a public key is expected.
- Mixing keys generated by different tool versions.
- Using the wrong password when decrypting private keys.
- Modifying a `.vault` file manually — tampering will cause signature verification to fail.


### GUI Usage

The desktop GUI provides the same functionality with a visual interface:

1. **Generate Keys** - Create your keypair with password protection
2. **Encrypt Files** - Drag and drop files, select recipient's public key
3. **Decrypt Files** - Select .vault file and provide your private key
4. **View Info** - Check encryption details and security information

No command-line knowledge needed!

## Running the Desktop GUI

### Windows

1. Download `SecureVault-v0.3.0-Windows.exe`
2. Double-click the executable to launch SecureVault
3. **Security Warning**: Windows may show a SmartScreen warning because this is a new, unsigned application
   - Click "More info"
   - Click "Run anyway"
   - This is expected for early releases and does not indicate malicious software

### macOS

1. Download `SecureVault-v0.3.0-macOS.app.zip`
2. Unzip the downloaded file
3. Open Terminal and navigate to your Downloads folder:
   ```bash
   cd ~/Downloads
   ```
4. Make the application executable:
   ```bash
   chmod +x SecureVault-v0.3.0-macOS.app/Contents/MacOS/SecureVault
   ```
5. Run the application:
   ```bash
   ./SecureVault-v0.3.0-macOS.app/Contents/MacOS/SecureVault
   ```
6. **Security Warning**: macOS may block the application on first run
   - Go to System Settings → Privacy & Security
   - Scroll down to find "SecureVault was blocked"
   - Click "Open Anyway"
   - Run the application again

**Alternative (if the app bundle doesn't work):**
You can also double-click the unzipped `.app` file in Finder, then follow step 6 above if blocked.

### Linux

1. Download `SecureVault-v0.3.0-Linux`
2. Open Terminal and navigate to your Downloads folder:
   ```bash
   cd ~/Downloads
   ```
3. Make the file executable:
   ```bash
   chmod +x SecureVault-v0.3.0-Linux
   ```
4. Run the application:
   ```bash
   ./SecureVault-v0.3.0-Linux
   ```

### Verifying Your Download (Recommended)

Before running the application, verify the download integrity using SHA-256 checksums:

**Windows (PowerShell):**
```powershell
cd $HOME\Downloads
Get-FileHash .\SecureVault-v0.3.0-Windows.exe -Algorithm SHA256
```

**macOS:**
```bash
cd ~/Downloads
shasum -a 256 SecureVault-v0.3.0-macOS.app.zip
```

**Linux:**
```bash
cd ~/Downloads
sha256sum SecureVault-v0.3.0-Linux
```

Compare the output hash with the checksums published at:  
https://meganealexis.net/securevault/downloads/checksums.txt

If the hashes match exactly, your download is verified and safe to run.

## Technical Details

SecureVault uses a hybrid post-quantum + classical design:

- Key exchange:
  - ML-KEM-768 (post-quantum, NIST standardized)
  - X25519 (classical elliptic-curve key exchange)

- File encryption:
  - Fernet (AES-CBC + HMAC authentication)

- Key wrapping:
  - AES-256-GCM used to protect the generated file encryption key

- Key derivation: 
  - PBKDF2 (100k iterations)

- Signatures:
  - Ed25519 (classical)
  - ML-DSA-65 (post-quantum)

This design provides defense-in-depth by combining classical and post-quantum primitives.


## Security Model

SecureVault is designed to protect files against both classical and future quantum-capable attackers.

### What SecureVault Protects Against

- Passive interception of encrypted files ("harvest now, decrypt later" attacks)
- Tampering or modification of `.vault` files
- Forged sender identity through dual-signature verification
- Offline attacks against stored private keys through password-based encryption
- Single-primitive failure by using hybrid classical + post-quantum cryptography

### Security Guarantees

- Files are encrypted with a randomly generated symmetric key.
- The symmetric key is wrapped using both:
  - ML-KEM-768 (post-quantum)
  - X25519 (classical)
- Vault integrity is protected with two signatures:
  - Ed25519
  - ML-DSA-65
- Signature verification is fail-closed; modified or corrupted vaults will not decrypt.

### Out of Scope / Not Protected

SecureVault does NOT protect against:

- Malware or keyloggers running on your machine
- Weak user passwords
- Compromised operating systems
- Loss of private keys or passwords
- Side-channel attacks

### Threat Model Summary

SecureVault assumes:

- The attacker can fully access encrypted `.vault` files.
- The attacker may have future quantum capabilities.
- The attacker does NOT control your local machine during encryption/decryption.

> Security note: SecureVault is intended for educational and practical experimentation. Independent security review is recommended before relying on it for high-value or regulated data.

## Security Notice

⚠️ **SecureVault has not yet been independently audited.** 

This is an educational and experimental cryptography project. While it uses NIST-standardized algorithms (ML-KEM-768, ML-DSA-65) and follows best practices, it should not be used for critical security applications without a professional security audit.

## Project Status

Active development. 

Educational + experimental cryptography project.


## Changelog

### 0.3.0.post1
- Fixed README documentation error

### 0.3.0
### SECURITY FIXES
- Fixed ML-DSA-65 signature verification (was completely broken in 0.2.1.post1)
- Switched from dilithium_py to liboqs for correct signature implementation
- Implemented fail-closed verification (decryption now blocks if signatures fail)
- Added envelope signing (signs entire vault metadata, prevents tampering)
- format_version field for forward/backward compatibility
- tool_version field showing SecureVault version
- Proper signature algorithm identifier: "Ed25519+ML-DSA-65 (oqs)"
- Version checking in decrypt to prevent format incompatibilities

### 0.2.1.post1
- Improved CLI command structure for better readability and discoverability
- Clarified `--help` output and usage examples
- Minor documentation and UX improvements

### 0.2.1
- Added `securevault --version`
- Improved CLI help clarity
- Suppressed non-fatal liboqs version warnings for clean CLI output
- Minor UX polish

### 0.2.0.post3
- Packaging and metadata fixes
- README updates and clarifications

### 0.2.0
- Hybrid post-quantum + classical encryption (ML-KEM-768 + X25519)
- File signing and verification
- GUI test interface added

### 0.1.0
- Initial prototype release
- Basic key generation, encryption, and decryption

## License

MIT License

Copyright (c) 2026 Mégane Alexis

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

## Source Code Availability

SecureVault executables are currently available for download under the MIT License. 

The SecureVault CLI source code is distributed via PyPI.

Additional components (GUI and advanced tooling) may be released separately as development progresses.




## Bug Reports / Contact

GitHub issues are currently disabled.

If you find bugs or security concerns, contact:

📧 meganealexis12@gmail.com

🔗 LinkedIn: https://www.linkedin.com/in/megane-alexis/

## Author

Mégane Alexis  
Recent Grad in Computer Science · Cybersecurity · Cryptography