alee/stegasoo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
12929bf32657ab1a8ec3117628a45545fb5862b3
stegasoo/frontends/WEB_UI.md
Aaron D. Lee 12929bf326 Release checklist and updated test scripts.
2026-01-01 14:04:55 -05:00

29 KiB
Raw Blame History

Stegasoo Web UI Documentation (v3.2.0)

Complete guide for the Stegasoo web-based steganography interface.

Table of Contents

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
  • ✅ Native sharing (Web Share API)
  • ✅ Responsive design (mobile-friendly)
  • ✅ Password-protected RSA key downloads
  • ✅ Real-time entropy calculations
  • ✅ Automatic file cleanup
  • ✅ DCT steganography mode - Frequency domain embedding
  • ✅ Color mode selection - Preserve carrier colors
  • ✅ File embedding - Hide files, not just text
  • ✅ v3.2.0: No date tracking - Simplified workflow

What's New in v3.2.0

Version 3.2.0 simplifies the user experience significantly:

Change Before (v3.1) After (v3.2.0)
Credentials 7 daily phrases Single passphrase
Encode form Date selection required No date field
Decode form Date detection/input No date needed
Default words 3 words 4 words
Field label "Day Phrase" "Passphrase"

Key benefits:

  • ✅ No need to remember which day a message was encoded
  • ✅ Simpler forms with fewer fields
  • ✅ True asynchronous communication
  • ✅ Stronger default security (4 words = ~44 bits entropy)

Breaking Change: v3.2.0 cannot decode images created with v3.1.x.

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 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/4096 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.

Input Fields

Field Type Required Description
Reference Photo Image file ✓ Your shared secret photo
Carrier Image Image file ✓ Image to hide message in
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 (v3.2.0)
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.

Advanced Options

Expand "Advanced Options" to access embedding mode settings:

Option Values Default Description
Embedding Mode LSB / DCT LSB Steganography algorithm
Output Format PNG / JPEG PNG Output image format (DCT only)
Color Mode Color / Grayscale Color Carrier color handling (DCT only)

See Embedding Modes for detailed explanations.

Drag-and-Drop Upload

Both image upload zones support:

  • Click to browse
  • Drag and drop files
  • Instant image preview
  • File name display

Character Counter

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

Shows warning at 80% capacity.

Encoding Process

  1. Fill in all required fields
  2. (Optional) Expand "Advanced Options" for DCT mode
  3. Click "Encode Message"
  4. Wait for processing (shows spinner)
  5. 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)

About Page

URL: /about

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

Includes:

  • Version information (v3.2.0)
  • v3.2.0 changes explanation
  • Security model overview
  • Dependency status (Argon2, QR code support)

Embedding Modes

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

LSB Mode (Default)

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

Aspect Details
Capacity ~3 bits/pixel (~375 KB for 1920×1080)
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)
  • Maximum message capacity needed
  • Recipient won't modify the image

DCT Mode

Discrete Cosine Transform embedding hides data in frequency domain coefficients.

Aspect Details
Capacity ~0.25 bits/pixel (~65 KB for 1920×1080 PNG, ~50 KB JPEG)
Output Formats PNG or JPEG
Resilience ✅ Better resistance to analysis
Best For Stealth requirements, frequency domain hiding

When to use DCT:

  • When stealth is important
  • Smaller messages that fit in reduced capacity
  • When you want JPEG output for natural appearance

DCT Output Formats

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

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

Capacity Comparison

For a 1920×1080 image:

Mode Approximate Capacity
LSB (PNG) ~375 KB
DCT (PNG, Color) ~65 KB
DCT (JPEG) ~50 KB

Choosing the Right Mode

┌─────────────────────────────────────────────────────────────┐
│                    Mode Selection Guide                      │
├─────────────────────────────────────────────────────────────┤
│                                                             │
│  Need maximum capacity?                                     │
│              │                                              │
│      ┌───────┴───────┐                                      │
│      ▼               ▼                                      │
│     YES             NO                                      │
│      │               │                                      │
│      ▼               ▼                                      │
│  Use LSB        Need stealth?                               │
│  (default)           │                                      │
│              ┌───────┴───────┐                              │
│              ▼               ▼                              │
│             YES             NO                              │
│              │               │                              │
│              ▼               ▼                              │
│          Use DCT        Use LSB                             │
│                                                             │
└─────────────────────────────────────────────────────────────┘

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

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"
    deploy:
      resources:
        limits:
          memory: 768M
        reservations:
          memory: 384M

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 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

Reference in New Issue View Git Blame Copy Permalink