stegasoo/WEB_UI.md

Stegasoo Web UI Documentation (v4.1.0)

Complete guide for the Stegasoo web-based steganography interface.

Table of Contents

• Overview
• What's New in v4.1.0
• Authentication & HTTPS
• Admin Recovery
• Multi-User Support
• Installation & Setup
• Pages & Features
  • Home Page
  • Generate Credentials
  • Encode Message
  • Decode Message
  • Tools Page
  • Account Page
  • About Page
• Embedding Modes
  • DCT Mode (Default)
  • LSB Mode
• User Interface Guide
• Workflow Examples
• Security Features
• Configuration
• Troubleshooting
• Mobile Support

---

Overview

The Stegasoo Web UI provides a user-friendly browser-based interface for:

• Generating secure credentials (passphrase, PINs, RSA keys)
• Encoding secret messages or files into images
• Decoding hidden messages or files from images
• Learning about the security model

Built with Flask, Bootstrap 5, and a modern dark theme.

Features

• ✅ Drag-and-drop file uploads
• ✅ Image previews with scan animations
• ✅ Native sharing (Web Share API)
• ✅ Responsive design (mobile-friendly)
• ✅ Password-protected RSA key downloads
• ✅ Real-time entropy calculations
• ✅ Automatic file cleanup
• ✅ DCT steganography mode - Now the default for social media resilience
• ✅ Color mode selection - Preserve carrier colors
• ✅ File embedding - Hide files, not just text
• ✅ QR code RSA keys - Scan to import keys
• ✅ v3.3.0: Streamlined UI - Compact mode selection, improved form flow

---

What's New in v4.1.0

Version 4.1.0 adds admin recovery, multi-user support, and new tools:

Feature	Description
Admin Recovery	Password reset using secure recovery key
Multi-User Support	Up to 16 users with role-based access
EXIF Editor	View, edit, and strip image metadata
Saved Channel Keys	Users can save/manage channel keys in account
Toast Improvements	Auto-dismiss after 20 seconds with fade

Key benefits:

• ✅ Never get locked out - recovery key backup options
• ✅ Share access with team members (admin/user roles)
• ✅ Full EXIF metadata control in Tools page
• ✅ Persistent channel key storage per user

---

What's New in v4.0.2

Version 4.0.2 added authentication and HTTPS support:

Feature	Description
Authentication	Single-admin login with SQLite3 user storage
First-run setup	Wizard to create admin account on first access
Account management	Change password page
Optional HTTPS	Auto-generated self-signed certificates

---

Authentication & HTTPS

Overview

v4.0.2 adds optional authentication and HTTPS for secure home network deployment.

First-Run Setup

On first access, you'll be prompted to create an admin account:

1. Navigate to http://localhost:5000
2. You'll be redirected to /setup
3. Enter a username (e.g., "admin")
4. Enter a password (minimum 8 characters)
5. Confirm the password
6. Click "Create Admin Account"

The admin account is stored in frontends/web/instance/stegasoo.db (SQLite).

Login

After setup, protected pages require login:

• Protected routes: /encode, /decode, /generate, /account, /api/*
• Public routes: /, /about, /login, /setup

Account Management

Access /account to:

• View current username
• Change your password
• Logout

Environment Variables

Variable	Default	Description
STEGASOO_AUTH_ENABLED	true	Enable/disable authentication
STEGASOO_HTTPS_ENABLED	false	Enable HTTPS with self-signed certs
STEGASOO_HOSTNAME	localhost	Hostname for certificate generation

Enabling HTTPS

# Enable HTTPS
export STEGASOO_HTTPS_ENABLED=true
export STEGASOO_HOSTNAME=stegasoo.local  # Optional: your hostname

cd frontends/web
python app.py

On first run with HTTPS enabled:

• Generates RSA 2048-bit private key
• Creates self-signed X.509 certificate (365 days validity)
• Stores in frontends/web/certs/
• Server starts on https://localhost:5000

Note: Browsers will show a security warning for self-signed certificates. This is expected for home network use.

Tip: To avoid browser warnings, use mkcert to generate locally-trusted certificates:

# Install mkcert and create local CA (one-time)
mkcert -install

# Generate trusted certs for your Pi
mkcert -key-file key.pem -cert-file cert.pem stegasoo.local localhost 127.0.0.1 YOUR_PI_IP

# Copy to certs directory
mv key.pem cert.pem frontends/web/certs/

Disabling Authentication

For development or trusted networks:

export STEGASOO_AUTH_ENABLED=false
cd frontends/web
python app.py

Docker Configuration

# docker/docker-compose.yml
services:
  web:
    environment:
      STEGASOO_AUTH_ENABLED: "true"
      STEGASOO_HTTPS_ENABLED: "true"
      STEGASOO_HOSTNAME: "stegasoo.local"
    volumes:
      - ./instance:/app/frontends/web/instance  # Persist user database
      - ./certs:/app/frontends/web/certs        # Persist SSL certs

Security Notes

• Passwords are hashed with Argon2id (time_cost=3, memory_cost=64MB)
• Single admin user only (no registration)
• Session-based authentication using Flask sessions
• Database stored in instance/stegasoo.db (add to .gitignore)

---

Admin Recovery

Overview

If you forget your admin password, the recovery key is the ONLY way to reset it. Generate and save your recovery key immediately after setup.

Recovery Key Format

XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX-XXXX
└──────────────────────────────────────┘
  32 alphanumeric characters (8 groups of 4)

Backup Options

The recovery key can be saved in multiple ways:

Method	Description	Security Level
Text file	Plain text download	Low - store securely
QR code	Obfuscated PNG image	Medium - XOR'd with magic hash
Stego image	Hidden in carrier image	High - requires original image

Generating a Recovery Key

During first-run setup:

1. Complete the admin account wizard
2. You'll be prompted to save your recovery key
3. Choose backup method(s)
4. Confirm you've saved the key

From Account page (admin only):

1. Navigate to /account
2. Click "Generate Recovery Key" (or "Regenerate" if one exists)
3. Save using your preferred method
4. Check the confirmation box
5. Click "Save New Key"

QR Code Obfuscation

QR codes are not plain text - they're XOR'd with a fixed obfuscation key derived from Stegasoo's magic headers. This prevents casual scanning from revealing the key.

Stego Backup

Hide your recovery key inside an image using Stegasoo itself:

1. Upload a carrier image (JPG/PNG, 50KB-2MB)
2. Click the "Stego" button
3. Download the stego image
4. Important: Keep the original carrier image - you'll need it for extraction

Recovering Your Password

URL: /recover

1. Navigate to the login page
2. Click "Forgot password?"
3. Option A: Enter recovery key directly
4. Option B: Extract from stego backup:
   • Expand "Extract from stego backup"
   • Upload your stego backup image
   • Upload the original carrier/reference image
   • Click "Extract Key"
5. Enter and confirm your new password
6. Click "Reset Password"

CLI Recovery

For locked-out scenarios where you can't access the web UI:

stegasoo admin recover --db frontends/web/instance/stegasoo.db

You'll be prompted for your recovery key and new password.

Important Notes

• Recovery keys are instance-bound (tied to the specific database)
• Regenerating a key invalidates the previous one
• Store backups in a secure, separate location
• Without a recovery key, the only option is to delete the database and reconfigure

---

Multi-User Support

Overview

Admins can create up to 16 additional users with role-based access control.

Roles

Role	Permissions
Admin	Full access: encode, decode, generate, tools, user management, recovery
User	Standard access: encode, decode, generate, account settings

User Management

URL: /admin/users (admin only)

Creating Users

1. Click "Add User"
2. Enter username
3. Select role (admin/user)
4. A temporary password is generated
5. Share the temporary password securely with the new user
6. User must change password on first login

Managing Users

• View all users and their roles
• Reset user passwords (generates new temp password)
• Change user roles
• Delete users (except yourself)

User Limits

• Maximum 16 users total (including admin)
• At least one admin must exist
• Users can't delete or demote the last admin

---

Installation & Setup

From PyPI

pip install stegasoo[web]

This automatically installs DCT dependencies (scipy) for full functionality.

From Source

git clone https://github.com/example/stegasoo.git
cd stegasoo
pip install -e ".[web]"

Running the Server

Development:

cd frontends/web
python app.py

Server starts at http://localhost:5000

Production with Gunicorn:

cd frontends/web
gunicorn --bind 0.0.0.0:5000 --workers 2 --threads 4 --timeout 60 app:app

Docker:

docker-compose -f docker/docker-compose.yml up web

First-Time Setup

1. Navigate to http://localhost:5000
2. Click "Generate" to create your credentials
3. Memorize your passphrase and PIN
4. Share credentials securely with your communication partner

---

Pages & Features

Home Page

URL: /

The landing page introduces Stegasoo and provides quick access to all features.

Main Actions

Card	Description	Link
Encode Message	Hide a secret in an image	/encode
Decode Message	Extract a hidden message	/decode
Generate Keys	Create new credentials	/generate

"How It Works" Section

Explains the three key components:

1. Reference Photo - Shared secret image
2. Passphrase - Your secret phrase (v3.2.0: same every time!)
3. Static PIN - Same every day

---

Generate Credentials

URL: /generate

Create a new set of credentials for steganography operations.

Configuration Options

Option	Range	Default	Description
Words per passphrase	3-12	4	BIP-39 words in passphrase
Use PIN	on/off	on	Generate a numeric PIN
PIN length	6-9	6	Digits in the PIN
Use RSA Key	on/off	off	Generate an RSA key pair
RSA key size	2048/3072	2048	Key size in bits

Entropy Calculator

The UI displays real-time entropy calculations:

Estimated entropy: ~63 bits
[=============>                 ] Good for most use cases
• Reference photo adds ~80-256 bits more

Generated Output (v3.2.0)

After clicking "Generate Credentials":

Static PIN (if enabled):

┌─────────────────────┐
│      8 4 7 2 9 3    │
└─────────────────────┘
Use this 6-digit PIN every time

Passphrase (v3.2.0: single passphrase, no daily rotation):

┌─────────────────────────────────────────┐
│  abandon ability able about             │
│                                         │
│  Use this passphrase to encode and      │
│  decode messages - no date needed!      │
└─────────────────────────────────────────┘

RSA Key (if enabled):

• Copy to clipboard button
• Download as password-protected .pem file
• Download as QR code image

Security Summary:

Passphrase entropy: 44 bits (4 words)
PIN entropy:        19 bits
RSA entropy:        128 bits
─────────────────────────────
Total:              191 bits
+ reference photo (~80-256 bits) = 271+ bits combined

RSA Key Download

1. Click "Download as .pem"
2. Enter a password (minimum 8 characters)
3. Click "Download Protected Key"
4. Save the file securely
5. Share with your communication partner through a secure channel

RSA Key QR Code

For easier sharing, you can also:

1. Click "Download QR Code"
2. Save the QR code image
3. Your partner can scan it to import the key

---

Encode Message

URL: /encode

Hide a secret message or file inside an image.

Form Flow (v3.3.0)

The encode form follows a logical flow:

1. Load Images - Reference photo and carrier image
2. View Capacity - Shows available capacity for DCT and LSB modes
3. Select Mode - DCT (default) or LSB with inline tooltips
4. Enter Payload - Text message or file
5. Add Security - Passphrase, PIN, and/or RSA key

Input Fields

Field	Type	Required	Description
Reference Photo	Image file	✓	Your shared secret photo
Carrier Image	Image file	✓	Image to hide message in
Embedding Mode	Toggle	✓	DCT (default) or LSB
Payload Type	Toggle	✓	Text message or file
Secret Message	Text	*	Message to hide (max 50KB)
File to Embed	File	*	File to hide (max 2MB)
Passphrase	Text	✓	Your passphrase
PIN	Number	**	Your static PIN
RSA Key	.pem file	**	Your shared RSA key
RSA Key QR	Image file	**	QR code containing RSA key
RSA Key Password	Password		Password for encrypted key

* One of message or file required. ** At least one security factor (PIN or RSA Key) required.

Embedding Mode Selection (v3.3.0)

The mode selector is now a compact inline toggle:

┌────────────────────────────────────────────────────────────┐
│  ◉ 🔊 DCT · Social Media ⓘ  │  ○ ⊞ LSB · Email & Files ⓘ │
└────────────────────────────────────────────────────────────┘

• DCT - Default, best for social media sharing
• LSB - Higher capacity, for lossless channels
• ⓘ - Hover for details (capacity, output format, etc.)

DCT Options

When DCT mode is selected, additional options appear:

Option	Values	Default	Description
Output Format	PNG / JPEG	JPEG	Output image format
Color Mode	Color / Grayscale	Color	Carrier color handling

Drag-and-Drop Upload

Both image upload zones support:

• Click to browse
• Drag and drop files
• Instant image preview with scan animation
• Status indicators ("Hash Acquired", "Carrier Loaded")

Capacity Info Panel

After loading a carrier image, a capacity panel appears:

┌─────────────────────────────────────────────────────────┐
│ 📏 Carrier: 1920 × 1080 (2.1 MP)   DCT: 150 KB  LSB: 750 KB │
└─────────────────────────────────────────────────────────┘

Character Counter

Message: [                                              ]
         1,234 / 50,000 characters                  2%

Shows warning at 80% capacity.

Encoding Process

1. Upload reference photo and carrier image
2. View capacity info panel
3. Select embedding mode (DCT default)
4. Choose payload type and enter content
5. Enter passphrase and security factors
6. Click "Encode Message"
7. Wait for processing (shows spinner)
8. Redirected to result page

Result Page

URL: /encode/result/<file_id>

After successful encoding:

┌────────────────────────────────────────┐
│  ✓ Message Encoded Successfully!       │
│                                        │
│     📄 a1b2c3d4.png                    │
│     Your secret is hidden              │
│     in this image                      │
│                                        │
│     Mode: DCT (Color, JPEG)            │
│     Capacity used: 45.2%               │
│                                        │
│     [    Download Image    ]           │
│     [      Share Image     ]           │
│                                        │
│  ⚠️ File expires in 5 minutes.         │
│     Download or share now.             │
│                                        │
│     [ Encode Another Message ]         │
└────────────────────────────────────────┘

Share Options:

1. Native Share (mobile/supported browsers):

   • Uses Web Share API
   • Opens system share sheet
   • Can share directly to apps

2. Fallback Share (desktop):

   • Email link
   • Telegram link
   • WhatsApp link
   • Copy link to clipboard

---

Decode Message

URL: /decode

Extract a hidden message or file from a stego image.

Input Fields

Field	Type	Required	Description
Reference Photo	Image file	✓	Same photo used for encoding
Stego Image	Image file	✓	Image containing hidden message
Passphrase	Text	✓	Same passphrase used for encoding
PIN	Number	*	Same PIN used for encoding
RSA Key	.pem file	*	Same RSA key used for encoding
RSA Key QR	Image file	*	QR code containing RSA key
RSA Key Password	Password		Password for encrypted key

* Must match security factors used during encoding.

Automatic Mode Detection

The decoder automatically detects whether a stego image uses LSB or DCT mode. You don't need to specify the mode manually—it just works!

Decoding Process (v3.2.0 Simplified)

1. Upload the same reference photo
2. Upload the received stego image
3. Enter your passphrase (no date needed!)
4. Enter your PIN and/or RSA key
5. Click "Decode Message"
6. View decoded message or download decoded file

Successful Decode (Text)

┌────────────────────────────────────────┐
│  ✓ Message Decrypted Successfully!     │
│                                        │
│  Decoded Message:                      │
│  ┌──────────────────────────────────┐  │
│  │ Meet at midnight. The package    │  │
│  │ will be under the bridge.        │  │
│  └──────────────────────────────────┘  │
│                                        │
│     [ Decode Another Message ]         │
└────────────────────────────────────────┘

Successful Decode (File)

┌────────────────────────────────────────┐
│  ✓ File Extracted Successfully!        │
│                                        │
│     📄 secret_document.pdf             │
│     Size: 245 KB                       │
│     Type: application/pdf              │
│                                        │
│     [    Download File    ]            │
│                                        │
│  ⚠️ File expires in 5 minutes.         │
│                                        │
│     [ Decode Another Message ]         │
└────────────────────────────────────────┘

Troubleshooting Tips

If decryption fails:

1. Check passphrase - Must be exact match (case-sensitive)
2. Same reference photo - Must be identical file
3. Correct PIN/RSA - Match what was used for encoding
4. Image integrity - Ensure no resizing/recompression (LSB mode)

---

Tools Page

URL: /tools

The Tools page provides utilities for image analysis and manipulation.

EXIF Editor

View and edit image metadata (EXIF data).

Features:

• View all EXIF fields from uploaded image
• Inline editing of individual fields
• Clear all metadata with one click
• Download cleaned image

Usage:

1. Upload an image (JPG recommended - richest EXIF data)
2. View all metadata fields in a table
3. Click any field to edit its value
4. Click "Save" to apply changes
5. Use "Clear All" to strip all metadata
6. Download the modified image

Common EXIF fields:

Field	Description
Make/Model	Camera manufacturer and model
DateTime	When the photo was taken
GPSLatitude/GPSLongitude	Location coordinates
Software	Editing software used
Artist	Photographer name

Privacy tip: Always strip EXIF data before sharing images publicly to remove location and device information.

Peek (Stego Detection)

Quickly check if an image contains hidden data.

Strip Metadata

Remove all metadata from an image in one click.

---

Account Page

URL: /account

Manage your account settings and preferences.

Password Change

1. Enter current password
2. Enter new password (minimum 8 characters)
3. Confirm new password
4. Click "Change Password"

Saved Channel Keys (v4.1.0)

Users can save frequently-used channel keys for quick access:

1. Click "Add Channel Key"
2. Enter a name/label for the key
3. Paste the channel key
4. Click "Save"

Saved keys appear in a dropdown during encode/decode operations.

Recovery Key Management (Admin only)

• View recovery key status (configured/not configured)
• Generate or regenerate recovery key
• Download backup options (text, QR, stego)

---

About Page

URL: /about

Information about the Stegasoo project, security model, and credits.

Includes:

• Version information (v4.1.0)
• Feature highlights
• Security model overview
• Dependency status (Argon2, scipy/DCT, QR code support)

---

Embedding Modes

Stegasoo offers two steganography algorithms, each with different trade-offs.

DCT Mode (Default)

Discrete Cosine Transform embedding hides data in frequency domain coefficients. This is now the default mode when scipy is available.

Aspect	Details
Capacity	~0.5 bits/pixel (~75 KB/MP)
Output Formats	PNG or JPEG
Resilience	✅ Survives JPEG recompression
Best For	Social media, messaging apps

When to use DCT:

• Sharing via social media (Instagram, WhatsApp, Telegram)
• When image may be recompressed
• When stealth is important
• Smaller messages that fit in reduced capacity

DCT Output Formats

Format	Pros	Cons
JPEG	Native format, natural, smaller, resilient	Slightly lower capacity
PNG	Lossless, predictable	Larger file

DCT Color Modes

Mode	Description	Use Case
Color	Embeds in luminance (Y), preserves chrominance	Most images, photos
Grayscale	Converts to grayscale before embedding	Black & white images

LSB Mode

Least Significant Bit embedding modifies the least significant bits of pixel values.

Aspect	Details
Capacity	~3 bits/pixel (~375 KB/MP)
Output Format	PNG only (lossless required)
Resilience	❌ Destroyed by JPEG compression
Best For	Maximum capacity, controlled sharing

When to use LSB:

• Sharing via lossless channels (email attachment, file transfer, cloud storage)
• Maximum message capacity needed
• Recipient won't modify/recompress the image

Capacity Comparison

For a 1920×1080 image (~2 MP):

Mode	Approximate Capacity
LSB (PNG)	~750 KB
DCT (PNG, Color)	~150 KB
DCT (JPEG)	~150 KB

Choosing the Right Mode

┌─────────────────────────────────────────────────────────────┐
│                    Mode Selection Guide                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Sharing via social media / messaging app?                  │
│              │                                              │
│      ┌───────┴───────┐                                      │
│      ▼               ▼                                      │
│     YES             NO                                      │
│      │               │                                      │
│      ▼               ▼                                      │
│  Use DCT        Need maximum capacity?                      │
│  (default)           │                                      │
│              ┌───────┴───────┐                              │
│              ▼               ▼                              │
│             YES             NO                              │
│              │               │                              │
│              ▼               ▼                              │
│          Use LSB        Use DCT                             │
│                        (default)                            │
│                                                             │
└─────────────────────────────────────────────────────────────┘

---

User Interface Guide

Layout Structure

┌──────────────────────────────────────────────────────────────┐
│  🦕 Stegasoo                    [Encode] [Decode] [Generate] │
├──────────────────────────────────────────────────────────────┤
│                                                              │
│   ┌────────────────────────────────────────────────────┐     │
│   │                    Page Content                     │     │
│   │                                                    │     │
│   │   ┌──────────────┐    ┌──────────────┐            │     │
│   │   │  Upload Zone  │    │  Upload Zone  │            │     │
│   │   │  (Reference)  │    │  (Carrier)    │            │     │
│   │   └──────────────┘    └──────────────┘            │     │
│   │                                                    │     │
│   │   Passphrase: [________________________]           │     │
│   │   PIN:        [____________]                       │     │
│   │                                                    │     │
│   │   [Advanced Options ▼]                             │     │
│   │   ┌────────────────────────────────────────────┐  │     │
│   │   │ Embedding Mode: [LSB ▼]                    │  │     │
│   │   │ Output Format:  [PNG ▼]  (DCT only)        │  │     │
│   │   │ Color Mode:     [Color ▼] (DCT only)       │  │     │
│   │   └────────────────────────────────────────────┘  │     │
│   │                                                    │     │
│   │   [        Encode Message        ]                │     │
│   │                                                    │     │
│   └────────────────────────────────────────────────────┘     │
│                                                              │
├──────────────────────────────────────────────────────────────┤
│                         Footer                               │
└──────────────────────────────────────────────────────────────┘

Color Scheme

Element	Color	Purpose
Background	Dark gradient	Reduce eye strain
Cards	Semi-transparent	Visual hierarchy
Headers	Purple gradient	Brand identity
Success	Green	Positive actions
Warning	Yellow	Caution messages
Error	Red	Error states

Form Validation

• Real-time validation feedback
• Clear error messages in alerts
• Required field indicators
• Input constraints (max length, format)
• Passphrase word count validation (v3.2.0)

Loading States

During long operations:

• Button shows spinner
• Button text changes (e.g., "Encoding...")
• Button is disabled to prevent double-submit

Flash Messages

┌──────────────────────────────────────────────┐
│ ✓ Credentials Generated!              [×]   │
└──────────────────────────────────────────────┘

Types:

• Success (green) - Operation completed
• Error (red) - Operation failed
• Warning (yellow) - Caution needed (e.g., short passphrase)

---

Workflow Examples

First-Time Setup (Both Parties)

Party A:

1. Go to /generate
2. Configure: PIN ✓, 4 words, 6 digits
3. Click "Generate Credentials"
4. Write down passphrase and PIN on paper
5. Memorize over the next few days
6. Destroy the paper

Share with Party B (in person or secure channel):

• The passphrase (just one phrase now!)
• The PIN
• The reference photo file (if not already shared)

Sending a Secret Message (LSB - Default)

1. Go to /encode
2. Upload your shared reference photo
3. Upload any carrier image (meme, vacation photo, etc.)
4. Type your secret message
5. Enter your passphrase
6. Enter your PIN
7. Click "Encode Message"
8. Download or share the resulting image
9. Send via any channel (email, file transfer)

Sending with DCT Mode

1. Go to /encode
2. Upload your shared reference photo
3. Upload carrier image
4. Type your secret message
5. Enter your passphrase and PIN
6. Expand "Advanced Options"
7. Select "DCT" embedding mode
8. Select "JPEG" output format (optional)
9. Click "Encode Message"
10. Download and share

Receiving a Secret Message (v3.2.0 Simplified)

1. Receive the stego image through any channel
2. Go to /decode
3. Upload the same reference photo
4. Upload the received stego image
5. Enter your passphrase (no date needed!)
6. Enter your PIN
7. Click "Decode Message"
8. Read the secret message or download the file

Embedding a File

1. Go to /encode
2. Upload reference photo and carrier image
3. Select "File" as payload type
4. Upload the file to embed (max 2MB)
5. Enter passphrase and PIN
6. Click "Encode Message"
7. Download the stego image

Extracting a File

1. Go to /decode
2. Upload reference photo and stego image
3. Enter passphrase and PIN
4. Click "Decode Message"
5. Click "Download File" to save the extracted file

Changing Credentials

To rotate to new credentials:

1. Both parties generate new credentials together
2. Agree on a cutover date
3. Messages encoded before cutover use old credentials
4. Messages encoded after cutover use new credentials

---

Security Features

Client-Side Security

Feature	Implementation
No credential storage	Nothing saved in browser
Automatic cleanup	Files deleted after 5 minutes
HTTPS support	Configure at server level

Server-Side Security

Feature	Implementation
Memory-hard KDF	Argon2id (256MB RAM)
Authenticated encryption	AES-256-GCM
Random salt	Per-message salt
Temporary storage	In-memory, auto-expiring
Input validation	All inputs validated
File size limits	5MB max upload

File Security

Aspect	Protection
Upload location	/tmp/stego_uploads (Docker)
Storage duration	5 minutes maximum
Access control	Random 16-byte file ID
Cleanup	Automatic + manual

Embedding Mode Security

Mode	Security Consideration
LSB	Full capacity, but fragile to modification
DCT	Lower capacity, frequency domain hiding

Both modes use the same strong encryption (AES-256-GCM with Argon2id key derivation).

---

Configuration

Environment Variables

Variable	Default	Description
FLASK_ENV	production	Flask environment
PYTHONPATH	-	Include src/ for development
STEGASOO_AUTH_ENABLED	true	Enable/disable authentication (v4.0.2)
STEGASOO_HTTPS_ENABLED	false	Enable HTTPS with self-signed certs (v4.0.2)
STEGASOO_HOSTNAME	localhost	Hostname for certificate CN (v4.0.2)
STEGASOO_CHANNEL_KEY	-	Channel key for deployment isolation

Application Limits

Limit	Value	Config Location
Max file upload	5 MB	app.config['MAX_CONTENT_LENGTH']
File expiry	5 minutes	TEMP_FILE_EXPIRY
Max image pixels	4 MP	stegasoo.constants
Max message size	50 KB	stegasoo.constants
Max file payload	2 MB	stegasoo.constants
PIN length	6-9 digits	stegasoo.constants
Passphrase words	3-12	stegasoo.constants

Production Deployment

With Gunicorn:

gunicorn \
  --bind 0.0.0.0:5000 \
  --workers 2 \
  --threads 4 \
  --timeout 60 \
  app:app

Worker Calculation:

• Each encode/decode uses ~256MB RAM (Argon2) + ~100MB for scipy (DCT mode)
• Formula: workers = (available_RAM - 512MB) / 350MB

With Nginx (reverse proxy):

server {
    listen 80;
    server_name stegasoo.example.com;

    client_max_body_size 10M;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_read_timeout 120s;
    }
}

With Docker Compose:

services:
  web:
    build:
      context: .
      target: web
    ports:
      - "5000:5000"
    environment:
      STEGASOO_AUTH_ENABLED: "true"
      STEGASOO_HTTPS_ENABLED: "false"
      STEGASOO_CHANNEL_KEY: ${STEGASOO_CHANNEL_KEY:-}
    volumes:
      - stegasoo-web-data:/app/frontends/web/instance
      - stegasoo-web-certs:/app/frontends/web/certs
    deploy:
      resources:
        limits:
          memory: 768M
        reservations:
          memory: 384M

volumes:
  stegasoo-web-data:
  stegasoo-web-certs:

---

Troubleshooting

Common Issues

"Decryption failed"

Causes:

• Wrong passphrase
• Wrong PIN
• Different reference photo
• Stego image was modified

Solutions:

1. Verify exact passphrase (case-sensitive)
2. Verify you're using the original reference photo
3. Ensure the stego image wasn't resized/recompressed (LSB mode)

"Invalid or missing Stegasoo header"

Causes:

• Image was heavily recompressed
• Wrong credentials
• Corrupted during transfer

Solutions:

1. Verify credentials match
2. Try obtaining original file
3. If using DCT mode, some modification is expected to work

"Carrier image too small"

Cause: Message too large for carrier capacity

Solutions:

1. Use a larger carrier image (more pixels)
2. Shorten the message
3. Use LSB mode for more capacity

"Passphrase should have at least 4 words"

Cause: Passphrase too short (v3.2.0 warning)

Solutions:

1. Use a longer passphrase for better security
2. Can still proceed with shorter passphrase (warning only)

"You must provide at least a PIN or RSA Key"

Cause: No security factor selected

Solution: Enter a PIN and/or upload an RSA key

Upload fails silently

Causes:

• File too large (>5MB)
• Invalid file type
• Browser issue

Solutions:

1. Reduce file size
2. Use PNG, JPG, or BMP formats
3. Try a different browser

RSA key password error

Causes:

• Wrong password
• Unencrypted key with password provided
• Corrupted key file

Solutions:

1. Verify the correct password
2. If key is unencrypted, leave password blank
3. Re-download or regenerate the key

DCT mode shows "requires scipy"

Cause: scipy library not installed

Solution:

pip install scipy
# Or rebuild Docker image
docker-compose -f docker/docker-compose.yml build --no-cache

Browser Compatibility

Browser	Status	Notes
Chrome 80+	✓ Full	Web Share API supported
Firefox 80+	✓ Full	Limited Web Share
Safari 14+	✓ Full	Web Share on iOS
Edge 80+	✓ Full	Web Share API supported
IE 11	✗ None	Not supported

Performance Issues

Slow encoding/decoding:

• Normal: Argon2 is intentionally slow (security feature)
• DCT mode adds ~1-2 seconds for transform operations
• Expected time: 3-7 seconds per operation

High memory usage:

• Normal: Argon2 requires 256MB RAM
• DCT mode adds scipy memory overhead (~100MB)
• Configure worker count based on available RAM

---

Mobile Support

Responsive Design

The UI adapts to mobile screens:

• Single-column layout on small screens
• Touch-friendly buttons (48px minimum)
• Readable text without zooming
• Scrollable tables
• Collapsible "Advanced Options" for cleaner mobile view

Mobile-Specific Features

Native Sharing: On supported mobile browsers, the "Share Image" button opens the native share sheet, allowing you to share directly to:

• Messaging apps (iMessage, WhatsApp, Telegram)
• Social media (Instagram, Twitter)
• Email
• Other installed apps

Camera Upload: File input accepts camera capture:

• Take a new photo as reference
• Capture carrier image directly

PWA Support (Future)

The web app can be added to home screen on mobile devices for quick access.

---

Keyboard Shortcuts

Shortcut	Action
Tab	Navigate between fields
Enter	Submit form (when focused)
Esc	Close modal/alert

---

Accessibility

Feature	Implementation
Screen readers	ARIA labels on interactive elements
Keyboard navigation	Full tab support
Color contrast	WCAG AA compliant
Focus indicators	Visible focus rings
Form labels	All inputs labeled

---

See Also

• CLI Documentation - Command-line interface
• API Documentation - REST API reference
• Web Frontend Update Summary - Migration details
• README - Project overview