Quantum Encryptor

A post-quantum cryptography tool for file encryption. New files combine ML-KEM-768 and X25519 key establishment with AES-256-GCM so confidentiality does not depend on either key-establishment component alone.

Monochrome local web interface for ML-KEM-768 + X25519 key generation, file encryption, decryption, and PEM key inspection.

Features

• Post-Quantum/Traditional Security: Combines ML-KEM-768 with X25519 so confidentiality does not depend on one key-establishment algorithm
• Authenticated File Encryption: Derives AES-256-GCM keys from both ML-KEM and X25519 shared secrets
• Password-Protected Keys: Private keys are always encrypted with scrypt-derived AES-256-GCM keys
• User-Friendly Interface: Custom local web UI with progressive technical details and a Python ASGI API
• PEM Key Format: Keys stored in PEM-like format with quantum algorithm extensions

Screenshots

The current browser smoke captures show the responsive Encrypt and Inspect key workflows. Click either image to open the full screenshot page.

See docs/SCREENSHOTS.md for the dedicated screenshot page.

Project Documentation

• Security policy
• Security design notes
• Threat model
• Release checklist
• Changelog

Requirements

• Python 3.10 through 3.13
• Open Quantum Safe native liboqs shared library
• Open Quantum Safe liboqs-python wrapper, which imports as oqs
• Python dependencies listed in requirements.txt
• Node.js 20.19+ or 22.12+ and npm for building the custom web UI
• Optional hash-locked installs from requirements-lock.txt or requirements-dev-lock.txt

Installation

1. Clone the repository:

   git clone https://github.com/brainx/Quantum-Encryptor.git
   cd Quantum-Encryptor

2. Create a virtual environment (recommended):

   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install dependencies:

   pip install -r requirements.txt
   npm install

   For a reproducible runtime install with pinned hashes:

   pip install --require-hashes -r requirements-lock.txt

4. Install or expose native liboqs.

   The app checks for a native liboqs shared library before importing liboqs-python, so startup and tests do not trigger wrapper auto-install side effects. If liboqs is not installed in a standard library path, set OQS_INSTALL_PATH to the install prefix that contains lib/, lib64/, or bin/.

   export OQS_INSTALL_PATH=/path/to/liboqs/install

Usage

1. Start the application:

   ./start.sh

   The custom web app builds the frontend and listens on 127.0.0.1:4000 by default. Set PORT to override the local development port:

   PORT=4001 ./start.sh

   Set PYTHON if you want the wrapper scripts to use a specific interpreter:

   PYTHON=.venv/bin/python ./start.sh
   PYTHON=.venv/bin/python ./test.sh

   Frontend development can run Vite separately on 127.0.0.1:4001:

   npm run dev

2. Open the web interface in your browser. Choose the intent that matches your task:

   • Encrypt: protect a file for the holder of a recipient public key.
   • Decrypt: recover a file with the matching encrypted private key and password.
   • Generate keys: create a new public key and password-protected private key.
   • Inspect key: check supported key metadata without exposing key material.

   Each workflow starts with plain-language guidance. Expand Technical details only when you need suite, format, or key-policy information.

Local-only interface privacy

The custom interface processes selected files through the local Python service at 127.0.0.1. It does not use browser persistence, telemetry, remote fonts, or remote application assets. The UI does not display plaintext previews, passwords, private-key content, or the local API token.

Verification

Run the Python test suite:

./test.sh

Run the custom frontend checks:

npm run test:unit
npm run check
npm run build

With the app already running on 127.0.0.1:4000, run the browser smoke test:

npm run ui-smoke

The UI smoke test writes ignored screenshots under tmp/ui-smoke/.

When a native liboqs installation is available to the running app, also run the real browser encryption round trip:

npm run ui-native

Do not treat the browser smoke test as proof that the native cryptographic backend is installed; it verifies the built interface against the local API contract. npm run ui-native verifies key generation, encryption, and decryption through the available native backend.

Key Generation

1. Select "Generate keys" from the workflow navigation
2. Enter and confirm a strong private-key password
3. Generate the keys and download both public and private key files
4. Share your public key with others who want to send you encrypted files

File Encryption

1. Select "Encrypt" from the workflow navigation
2. Upload the file you want to encrypt
3. Upload the recipient's public key (.pem file)
4. Specify the output filename
5. Download the encrypted file

File Decryption

1. Select "Decrypt" from the workflow navigation
2. Upload the encrypted file (.pqc file)
3. Upload your private key (.pem file)
4. Enter your private-key password
5. Download the decrypted file

Automation Usage

Automation tools can use the deterministic JSON CLI instead of driving the browser interface. Run commands from the repository workspace and pass only workspace-relative paths. Absolute paths, .. traversal, symlink escapes, and accidental output overwrites are rejected.

mkdir -p keys data

python -m pqc_agent_tools health --json

export PQC_PRIVATE_KEY_PASSWORD='<strong-private-key-password>'
python -m pqc_agent_tools generate-keys \
  --public-out keys/agent-public.pem \
  --private-out keys/agent-private.pem

python -m pqc_agent_tools inspect-key --key keys/agent-public.pem
python -m pqc_agent_tools inspect-key --key keys/agent-private.pem

python -m pqc_agent_tools encrypt \
  --input data/message.txt \
  --public-key keys/agent-public.pem \
  --output data/message.pqc

python -m pqc_agent_tools inspect-file --input data/message.pqc
python -m pqc_agent_tools verify-file \
  --input data/message.pqc \
  --private-key keys/agent-private.pem

python -m pqc_agent_tools decrypt \
  --input data/message.pqc \
  --private-key keys/agent-private.pem \
  --output data/message.decrypted.txt

The installed console entry point is equivalent:

quantum-encryptor-agent health --json

The CLI prints JSON only and never includes plaintext, private keys, passwords, raw file bytes, or absolute local paths in its output. Private-key operations read passwords from the environment variable named by --password-env, defaulting to PQC_PRIVATE_KEY_PASSWORD.

Security Considerations

• New encrypted files use format version 4 with the ML-KEM-768+X25519-v2 suite and authenticate the complete file header as AES-GCM associated data
• New encrypted private-key PEM files require PQC-Key-Format: 3; private-key metadata, hybrid suite, KDF parameters, salt, and nonce are authenticated as AES-GCM associated data
• Authenticated format-v3 files and PQC-Key-Format: 2 ML-KEM private keys remain decrypt-only for migration; encryption never silently downgrades
• Private keys must be password protected with scrypt-derived AES-256-GCM keys; unencrypted private keys and legacy encrypted private-key PEM metadata are rejected by default
• Private-key passwords require at least 16 characters, at least 5 unique characters, and must not match known weak values
• Decryption requires an exact private-key/container suite match. The ambiguous legacy ML-KEM-768+X25519 suite is decrypt-only and selects ML-KEM or Kyber only after AES-GCM authentication succeeds; v3 uses its exact stored KEM identity
• Existing v2 ML-KEM private keys can decrypt authenticated v3 files, but creating new encrypted files requires generating a new composite key pair; re-encrypt migrated data with that new public key
• Legacy hybrid public keys must be regenerated before encryption; they are never relabeled or reused as current-suite keys
• PEM/key reads are capped at 128 KiB before parsing; POSIX workspace inputs use descriptor-anchored, no-follow reads, and reads remain bounded even if a file changes during the operation
• The web UI enforces a 100 MiB plaintext processing limit because files are handled in memory; encrypted containers allow bounded header and authentication overhead above that plaintext limit
• State-changing local web API requests require a per-process API token and reject non-local browser origins when an Origin header is present
• The local agent CLI accepts only workspace-relative paths, returns machine-readable JSON without secret material, and writes private keys plus decrypted outputs with owner-only permissions on POSIX systems; non-overwrite output creation uses exclusive file creation
• Native liboqs is loaded lazily and missing backend support disables key generation/encryption instead of crashing the app
• CI runs Python formatting, linting, type checks, unit tests, custom web UI build/type checks, API client tests, browser UI smoke, isolated installed-wheel checks, Python/npm dependency audits, locked runtime install, and a native liboqs integration test job pinned to the matching 0.16.0 release commit; repository CodeQL default setup provides static analysis
• See docs/THREAT_MODEL.md for repository trust boundaries, assets, abuse cases, and invariants
• Disclaimer: This software has not undergone an independent security audit and should be reviewed before production use

Project Structure

• crypto_config.py - Configuration parameters for cryptographic operations
• crypto_core.py - Core cryptographic functions (key generation, encryption, decryption)
• api_app.py - Local ASGI API and static web UI server
• pqc_agent_tools.py - Local JSON CLI for automation workflows
• web/ - React frontend source for the custom UI
• package.json / vite.config.ts - Frontend build configuration
• ui_helpers.py - UI-safe filename helpers
• start.sh - Local application startup script
• test.sh - Test runner
• requirements-lock.txt / requirements-dev-lock.txt - Hash-locked runtime and development dependency sets
• pyproject.toml / setup.py - Packaging metadata

License

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

Acknowledgments

• Open Quantum Safe for liboqs implementation
• NIST for leading the post-quantum cryptography standardization effort