diff --git a/README.md b/README.md index 98d8edb..97f8829 100644 --- a/README.md +++ b/README.md @@ -5,428 +5,118 @@ A secure steganography system for hiding encrypted messages in images using hybr [![Tests](https://github.com/adlee-was-taken/stegasoo/actions/workflows/test.yml/badge.svg)](https://github.com/adlee-was-taken/stegasoo/actions/workflows/test.yml) [![Lint](https://github.com/adlee-was-taken/stegasoo/actions/workflows/lint.yml/badge.svg)](https://github.com/adlee-was-taken/stegasoo/actions/workflows/lint.yml) ![Python](https://img.shields.io/badge/Python-3.10--3.12-blue) -[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT) +[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE) ![Security](https://img.shields.io/badge/Security-AES--256--GCM-red) -![Version](https://img.shields.io/badge/Version-4.0.1-purple) ## Features -- πŸ” **AES-256-GCM** authenticated encryption -- 🧠 **Argon2id** memory-hard key derivation (256MB RAM requirement) -- 🎲 **Pseudo-random pixel selection** defeats steganalysis -- πŸ”‘ **Multi-factor authentication**: PIN, RSA key, or both -- πŸ–ΌοΈ **Reference photo** as "something you have" -- 🌐 **Multiple interfaces**: CLI, Web UI, REST API -- πŸ“ **File embedding** - Hide any file type (PDF, ZIP, documents) -- πŸ“± **QR code support** - Encode/decode RSA keys via QR codes -- πŸ†• **DCT steganography** - JPEG-resilient embedding for social media -- πŸ†• **Large image support** - Process images up to 14MB+ +- **AES-256-GCM** authenticated encryption +- **Argon2id** memory-hard key derivation (256MB RAM requirement) +- **Pseudo-random pixel selection** defeats steganalysis +- **Multi-factor authentication**: Reference photo + passphrase + PIN/RSA key +- **Multiple interfaces**: CLI, Web UI, REST API +- **File embedding**: Hide any file type (PDF, ZIP, documents) +- **DCT steganography**: JPEG-resilient embedding for social media +- **Channel keys**: Private group communication channels -## What's New in v4.0.0 - -| Feature | Description | -|---------|-------------| -| **Simplified Auth** | Removed date dependency - encode/decode anytime without tracking dates | -| **Passphrase** | Renamed from "day phrase" to "passphrase" (no more daily rotation) | -| **Python 3.12** | Requires Python 3.10-3.12 (jpegio incompatible with 3.13) | -| **Large Image Fix** | JPEG normalization prevents crashes with quality=100 images | -| **Subprocess Isolation** | WebUI runs encode/decode in subprocesses for stability | -| **4-Word Default** | Default passphrase increased from 3 to 4 words | - -### Breaking Changes from v3.x - -- `day_phrase` parameter renamed to `passphrase` in all APIs -- `date_str` parameter removed from encode/decode functions -- Python 3.13 not supported (jpegio C extension incompatibility) - -### Embedding Mode Comparison +## Embedding Modes | Mode | Capacity (1080p) | JPEG Resilient | Best For | |------|------------------|----------------|----------| -| **DCT** (default) | ~150 KB | βœ… Yes | Social media, messaging apps | -| **LSB** | ~750 KB | ❌ No | Email, file transfer | +| **DCT** (default) | ~150 KB | Yes | Social media, messaging apps | +| **LSB** | ~750 KB | No | Email, direct file transfer | -## WebUI Preview +## Web UI -| Front Page | Encode | Decode | Generate | -|:----------:|:------:|:------:|:--------:| -| ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Encode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Decode.webp) | ![Screenshot](https://github.com/adlee-was-taken/stegasoo/blob/main/data/WebUI_Generate.webp) | +| Home | Encode | Decode | Generate | +|:----:|:------:|:------:|:--------:| +| ![Home](data/WebUI.webp) | ![Encode](data/WebUI_Encode.webp) | ![Decode](data/WebUI_Decode.webp) | ![Generate](data/WebUI_Generate.webp) | ## Quick Start ```bash -# Install with all features (requires Python 3.10-3.12) +# Install (Python 3.10-3.12) pip install -e ".[all]" -# Generate credentials (memorize these!) +# Generate credentials stegasoo generate --pin --words 4 -# Encode a message (DCT mode - default, best for social media) +# Encode a message stegasoo encode \ - --ref photo.jpg \ + --ref my_photo.jpg \ --carrier meme.jpg \ --passphrase "apple forest thunder mountain" \ --pin 123456 \ --message "Secret message" -# Encode with LSB mode (higher capacity, for email/file transfer) -stegasoo encode \ - --ref photo.jpg \ - --carrier meme.png \ - --passphrase "apple forest thunder mountain" \ - --pin 123456 \ - --message "Secret message" \ - --mode lsb - -# Decode (auto-detects mode) +# Decode stegasoo decode \ - --ref photo.jpg \ - --stego stego.png \ + --ref my_photo.jpg \ + --stego stego_image.png \ --passphrase "apple forest thunder mountain" \ --pin 123456 ``` -For detailed installation instructions, see **[INSTALL.md](INSTALL.md)**. +## Interfaces ---- +| Interface | Start Command | Documentation | +|-----------|---------------|---------------| +| **CLI** | `stegasoo --help` | [CLI.md](CLI.md) | +| **Web UI** | `cd frontends/web && python app.py` | [WEB_UI.md](WEB_UI.md) | +| **REST API** | `cd frontends/api && uvicorn main:app` | [API.md](API.md) | ## Security Model -Stegasoo uses multiple authentication factors combined with strong cryptography: - ``` -β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β” -β”‚ AUTHENTICATION LAYERS β”‚ -β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€ -β”‚ β”‚ -β”‚ Reference Photo ──┐ β”‚ -β”‚ (~80-256 bits) β”‚ β”‚ -β”‚ β”œβ”€β”€β–Ί Argon2id KDF ──► AES-256-GCM Key β”‚ -β”‚ Passphrase ──────── (256MB RAM) β”‚ -β”‚ (~43-132 bits) β”‚ β”‚ -β”‚ β”‚ β”‚ -β”‚ Static PIN ──────── β”‚ -β”‚ (~20-30 bits) β”‚ β”‚ -β”‚ β”‚ β”‚ -β”‚ RSA Key β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ β”‚ -β”‚ (~128 bits) (optional, adds another factor) β”‚ -β”‚ β”‚ -β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +Reference Photo ──┐ +(~80-256 bits) β”‚ + β”œβ”€β”€β–Ί Argon2id KDF ──► AES-256-GCM Key +Passphrase ──────── (256MB RAM) +(~43-132 bits) β”‚ + β”‚ +PIN ─────────────── +(~20-30 bits) β”‚ + β”‚ +RSA Key β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜ +(optional) ``` -### Entropy Summary - -| Component | Entropy | Purpose | -|-----------|---------|---------| -| Reference Photo | ~80-256 bits | Something you have | -| Passphrase (3-12 words) | ~33-132 bits | Something you know | -| PIN (6-9 digits) | ~20-30 bits | Something you know | -| RSA Key (2048-4096 bit) | ~112-128 bits | Something you have (optional) | -| **Combined** | **133-400+ bits** | **Beyond brute force** | - -### Attack Resistance - -| Attack | Protection | -|--------|------------| -| Brute force | 2^133+ combinations minimum | -| Rainbow tables | Random 16-byte salt per message | -| Steganalysis | Pseudo-random pixel/coefficient selection | -| GPU cracking | Argon2id requires 256MB RAM per attempt | -| Side-channel | Constant-time operations in cryptography library | -| JPEG recompression | DCT mode embeds in frequency domain | - -### Security Configurations - | Configuration | Entropy | Use Case | |--------------|---------|----------| -| 3-word passphrase + 6-digit PIN | ~133 bits | Casual private messaging | -| 4-word passphrase + 9-digit PIN | ~176 bits | Standard security (recommended) | -| 4-word passphrase + RSA 2048 | ~241 bits | File-based authentication | -| 6-word passphrase + PIN + RSA 4096 | ~304 bits | Maximum security | - ---- - -## Interfaces - -### Command-Line Interface (CLI) - -Full-featured CLI with piping support: - -```bash -# Generate with RSA key -stegasoo generate --rsa --rsa-bits 4096 -o mykey.pem -p "password" - -# Encode (DCT mode is now default) -stegasoo encode -r ref.jpg -c carrier.jpg -p "passphrase words here" --pin 123456 -m "Message" - -# Encode with LSB mode for higher capacity -stegasoo encode -r ref.jpg -c carrier.png -p "passphrase words here" --pin 123456 \ - -m "Message" --mode lsb - -# Encode a file -stegasoo encode -r ref.jpg -c carrier.png -p "passphrase words here" --pin 123456 -f secret.txt - -# Decode to stdout (quiet mode) -stegasoo decode -r ref.jpg -s stego.png -p "passphrase words here" --pin 123456 -q - -# Compare LSB vs DCT capacity for an image -stegasoo compare carrier.png - -# Check available modes -stegasoo modes -``` - -πŸ“– Full documentation: **[CLI.md](CLI.md)** - -### Web UI - -Browser-based interface with drag-and-drop uploads: - -```bash -# Start the server -cd frontends/web -python app.py -# Visit http://localhost:5000 -``` - -Features: -- Drag-and-drop image uploads with scan animations -- Real-time entropy calculator -- Native mobile sharing (Web Share API) -- DCT mode default with compact mode selector -- Subprocess isolation for stability -- Large image support (14MB+ tested) -- Streamlined form flow (v3.3.0) - -πŸ“– Full documentation: **[WEB_UI.md](WEB_UI.md)** - -### REST API - -FastAPI-powered REST API with OpenAPI documentation: - -```bash -# Start the server -cd frontends/api -uvicorn main:app --host 0.0.0.0 --port 8000 -# Docs at http://localhost:8000/docs -``` - -Example API calls: - -```bash -# Generate credentials -curl -X POST http://localhost:8000/generate \ - -H "Content-Type: application/json" \ - -d '{"use_pin": true, "passphrase_words": 4}' - -# Encode (DCT mode is default) -curl -X POST http://localhost:8000/encode/multipart \ - -F "message=Secret" \ - -F "passphrase=apple forest thunder mountain" \ - -F "pin=123456" \ - -F "reference_photo=@photo.jpg" \ - -F "carrier=@meme.jpg" \ - --output stego.jpg - -# Encode with LSB mode -curl -X POST http://localhost:8000/encode/multipart \ - -F "message=Secret" \ - -F "passphrase=apple forest thunder mountain" \ - -F "pin=123456" \ - -F "embed_mode=lsb" \ - -F "reference_photo=@photo.jpg" \ - -F "carrier=@meme.png" \ - --output stego.png - -# Decode (auto-detects mode) -curl -X POST http://localhost:8000/decode/multipart \ - -F "passphrase=apple forest thunder mountain" \ - -F "pin=123456" \ - -F "reference_photo=@photo.jpg" \ - -F "stego_image=@stego.jpg" -``` - -πŸ“– Full documentation: **[API.md](API.md)** - ---- - -## Project Structure - -``` -stegasoo/ -β”œβ”€β”€ src/stegasoo/ # Core library -β”‚ β”œβ”€β”€ __init__.py # Public API -β”‚ β”œβ”€β”€ constants.py # Configuration -β”‚ β”œβ”€β”€ crypto.py # Encryption/decryption -β”‚ β”œβ”€β”€ steganography.py # LSB image embedding -β”‚ β”œβ”€β”€ dct_steganography.py # DCT embedding -β”‚ β”œβ”€β”€ keygen.py # Credential generation -β”‚ β”œβ”€β”€ validation.py # Input validation -β”‚ β”œβ”€β”€ models.py # Data classes -β”‚ β”œβ”€β”€ exceptions.py # Custom exceptions -β”‚ β”œβ”€β”€ qr_utils.py # QR code utilities -β”‚ └── utils.py # Utilities -β”‚ -β”œβ”€β”€ frontends/ -β”‚ β”œβ”€β”€ web/ # Flask web UI -β”‚ β”‚ β”œβ”€β”€ app.py -β”‚ β”‚ β”œβ”€β”€ subprocess_stego.py # Subprocess isolation -β”‚ β”‚ └── stego_worker.py # Worker script -β”‚ β”œβ”€β”€ cli/ # Command-line interface -β”‚ └── api/ # FastAPI REST API -β”‚ -β”œβ”€β”€ data/ -β”‚ └── bip39-words.txt # BIP-39 wordlist -β”‚ -β”œβ”€β”€ pyproject.toml # Package configuration -β”œβ”€β”€ requirements.txt # Dependencies -β”œβ”€β”€ Dockerfile # Multi-stage Docker build -β”œβ”€β”€ docker-compose.yml # Container orchestration -β”‚ -β”œβ”€β”€ README.md # This file -β”œβ”€β”€ INSTALL.md # Installation guide -β”œβ”€β”€ CLI.md # CLI documentation -β”œβ”€β”€ API.md # API documentation -β”œβ”€β”€ WEB_UI.md # Web UI documentation -β”œβ”€β”€ SECURITY.md # Security documentation -└── UNDER_THE_HOOD.md # Technical deep-dive -``` - ---- +| 4-word passphrase + 6-digit PIN | ~153 bits | Standard security | +| 4-word passphrase + PIN + RSA | ~280+ bits | Maximum security | ## Requirements -| Requirement | Version | Notes | -|-------------|---------|-------| -| Python | 3.10-3.12 | **3.13 not supported** (jpegio incompatibility) | -| RAM | 512 MB+ | 256MB for Argon2 operations | -| Disk | ~100 MB | | - -### Key Dependencies - -| Package | Purpose | -|---------|---------| -| `cryptography` | AES-256-GCM encryption | -| `Pillow` | Image processing | -| `argon2-cffi` | Memory-hard key derivation | -| `scipy` | DCT transforms | -| `jpegio` | JPEG coefficient manipulation | -| `numpy` | Array operations | - ---- - -## Configuration - -### Limits - -| Limit | Value | -|-------|-------| -| Max image size | Tested up to 14MB | -| Max message size | 50 KB | -| Max file upload | 5 MB | -| PIN length | 6-9 digits | -| Passphrase length | 3-12 words | -| RSA key sizes | 2048, 3072, 4096 bits | - -### Environment Variables - -| Variable | Default | Description | -|----------|---------|-------------| -| `FLASK_ENV` | production | Flask environment | -| `PYTHONPATH` | - | Include `src/` for development | - ---- +| Requirement | Version | +|-------------|---------| +| Python | 3.10-3.12 | +| RAM | 512 MB+ | ## Development ```bash -# Install dev dependencies pip install -e ".[dev]" - -# Run tests pytest - -# Format code -black src/ frontends/ -ruff check src/ frontends/ - -# Type checking -mypy src/ - -# Check DCT support -python -c "from stegasoo import has_dct_support; print(f'DCT: {has_dct_support()}')" -python -c "from stegasoo.dct_steganography import has_jpegio_support; print(f'jpegio: {has_jpegio_support()}')" +black src/ tests/ frontends/ +ruff check src/ tests/ frontends/ ``` ---- +## Documentation -## Version History - -| Version | Changes | -|---------|---------| -| **4.0.1** | Lint cleanup, test fixes, Web UI improvements (channel key dropdown, LED indicators) | -| **4.0.0** | Channel key support for deployment isolation, removed date dependency, renamed day_phraseβ†’passphrase, Python 3.12 requirement, JPEG normalization fix, subprocess isolation, large image support | -| **3.2.x** | DCT color mode, JPEG output fixes | -| **3.0.x** | Added DCT steganography mode | -| **2.2.x** | QR code support, file embedding | -| **2.0.x** | Web UI, REST API, RSA keys | -| **1.0.x** | Initial release, CLI only | - ---- - -## Upgrading from v3.x - -### Code Changes Required - -```python -# Old (v3.x) -result = encode( - message="secret", - day_phrase="apple forest thunder", - date_str="2024-01-15", - ... -) - -# New (v4.0) -result = encode( - message="secret", - passphrase="apple forest thunder mountain", - # No date_str needed! - ... -) -``` - -### CLI Changes - -```bash -# Old (v3.x) -stegasoo encode --phrase "words" --date 2024-01-15 ... - -# New (v4.0) -stegasoo encode --passphrase "words here more" ... -# or short form -stegasoo encode -p "words here more" ... -``` - ---- +- [INSTALL.md](INSTALL.md) - Installation guide +- [CLI.md](CLI.md) - Command-line reference +- [API.md](API.md) - REST API documentation +- [WEB_UI.md](WEB_UI.md) - Web interface guide +- [SECURITY.md](SECURITY.md) - Security model details +- [UNDER_THE_HOOD.md](UNDER_THE_HOOD.md) - Technical deep-dive +- [CHANGELOG.md](CHANGELOG.md) - Version history +- [CONTRIBUTING.md](CONTRIBUTING.md) - Contributor guide ## License -MIT License - Use responsibly. +MIT License - see [LICENSE](LICENSE). Use responsibly. --- -## ⚠️ Disclaimer - -This tool is for educational and legitimate privacy purposes only. Users are responsible for complying with applicable laws in their jurisdiction. - ---- - -## See Also - -- **[INSTALL.md](INSTALL.md)** - Detailed installation instructions -- **[CLI.md](CLI.md)** - Command-line interface reference -- **[API.md](API.md)** - REST API documentation -- **[WEB_UI.md](WEB_UI.md)** - Web interface guide -- **[SECURITY.md](SECURITY.md)** - Security model and threat analysis -- **[UNDER_THE_HOOD.md](UNDER_THE_HOOD.md)** - Technical implementation details +*This tool is for educational and legitimate privacy purposes. Users are responsible for complying with applicable laws.*