A secure, anonymous messaging application that uses Tor hidden services and end-to-end encryption to provide private communication channels.
demo.mp4
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ ANONYMOUS MESSAGING SYSTEM │
└─────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ SERVER SIDE │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────────────────────┐ │
│ │ Python App │ │ Tor Process │ │ Hidden Service │ │
│ │ (Server Mode) │ │ │ │ abc123def456.onion │ │
│ │ │ │ ┌─────────────┐ │ │ │ │
│ │ • TorManager │◄──►│ │ Hidden Svc │ │◄──►│ • Generated .onion addr │ │
│ │ • SecureMsg │ │ │ Controller │ │ │ • Private key stored │ │
│ │ • AnonymousServ │ │ └─────────────┘ │ │ • Port mapping: 80→8080 │ │
│ │ │ │ │ │ │ │
│ │ Listens on: │ │ SOCKS: 9050 │ └─────────────────────────────────┘ │
│ │ localhost:8080 │ │ Control: 9051 │ │
│ └─────────────────┘ └──────────────────┘ │
│ │ │ │
│ │ ┌────────▼────────┐ │
│ │ │ Tor Network │ │
│ │ │ │ │
│ │ │ ┌─────────────┐ │ │
│ │ │ │Entry Relay │ │ │
│ │ │ └─────┬───────┘ │ │
│ │ │ │ │ │
│ │ │ ┌─────▼───────┐ │ │
│ │ │ │Middle Relay │ │ │
│ │ │ └─────┬───────┘ │ │
│ │ │ │ │ │
│ │ │ ┌─────▼───────┐ │ │
│ │ │ │Exit/Rendez. │ │ │
│ │ │ │ Point │ │ │
│ │ │ └─────────────┘ │ │
│ │ └─────────────────┘ │
│ │ │ │
└───────────┼───────────────────────┼────────────────────────────────────────────────┘
│ │
│ ┌────────▼────────┐
│ │ Tor Network │
│ │ (3-hop path) │
│ └────────┬────────┘
│ │
┌───────────┼───────────────────────┼────────────────────────────────────────────────┐
│ │ │ CLIENT SIDE │
├───────────┼───────────────────────┼────────────────────────────────────────────────┤
│ │ │ │
│ ┌────────▼────────┐ ┌────────▼────────┐ ┌─────────────────────────────────┐ │
│ │ Python App │ │ Tor Process │ │ Connection String │ │
│ │ (Client Mode) │ │ (SOCKS Proxy) │ │ │ │
│ │ │ │ │ │ abc123def456.onion: │ │
│ │ • TorManager │◄──►│ SOCKS: 9050 │ │ base64_encryption_key_here │ │
│ │ • SecureMsg │ │ (or 9051-9054) │ │ │ │
│ │ • AnonymousClnt │ │ │ │ • Onion address for connection │ │
│ │ │ │ Routes all │ │ • Fernet encryption key │ │
│ │ Connects via: │ │ traffic through │ │ • Shared out-of-band securely │ │
│ │ SOCKS proxy │ │ Tor network │ │ │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ MESSAGE FLOW │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Client A Tor Network Server │
│ │ │ │ │
│ │ 1. Encrypt message │ │ │
│ │ with Fernet key │ │ │
│ │ │ │ │
│ │ 2. Add padding to │ │ │
│ │ 512B/1KB/2KB/4KB │ │ │
│ │ │ │ │
│ │ 3. Send via SOCKS │ │ │
│ │ proxy to Tor │ │ │
│ │ │ │ │
│ ├──────────────────────────►│ 4. Route through 3 hops │ │
│ │ │ (Entry→Middle→Exit) │ │
│ │ │ │ │
│ │ ├────────────────────────────►│ 5. Deliver to │
│ │ │ │ hidden service │
│ │ │ │ │
│ │ │ │ 6. Relay encrypted │
│ │ │ │ message to all │
│ │ │ │ connected clients│
│ │ │ │ │
│ │ │ 7. Route back through ◄┤ │
│ │ │ different 3-hop path │ │
│ │ │ │ │
│ ◄───────────────────────────┤ 8. Deliver to Client B │ │
│ │ │ via SOCKS proxy │ │
│ │ │ │ │
│ │ 9. Decrypt with │ │ │
│ │ shared Fernet key │ │ │
│ │ │ │ │
│ │ 10. Remove padding & │ │ │
│ │ display message │ │ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ SECURITY LAYERS │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Layer 1: Network Anonymity │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ • Tor Hidden Services (.onion addresses) │ │
│ │ • 3-hop onion routing (Entry → Middle → Exit/Rendezvous) │ │
│ │ • No IP address exposure for server or clients │ │
│ │ • Circuit refresh every 5 minutes │ │
│ │ • Traffic routed through different paths │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Layer 2: Message Encryption │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ • Fernet symmetric encryption (AES-128 + HMAC-SHA256) │ │
│ │ • Cryptographically secure key generation │ │
│ │ • Base64-encoded keys for sharing │ │
│ │ • Server never sees plaintext (zero-knowledge relay) │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Layer 3: Traffic Analysis Protection │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ • Message padding to fixed sizes (512B, 1KB, 2KB, 4KB) │ │
│ │ • Random timing delays (0.5-3 seconds between messages) │ │
│ │ • Dummy traffic generation (every 30-60 seconds) │ │
│ │ • No message size or timing correlation possible │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Layer 4: Memory & Data Protection │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ • Secure memory zeroing (3-pass overwrite) │ │
│ │ • Memory locking (prevents swap to disk) │ │
│ │ • Temporary file cleanup │ │
│ │ • All logging disabled │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ ONION SERVICE CREATION PROCESS │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Step 1: Key Generation │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ • Tor generates ED25519 private/public key pair │ │
│ │ • Public key hashed to create .onion address │ │
│ │ • Format: [16-char-hash].onion (v2) or [56-char-hash].onion (v3) │ │
│ │ • Private key stored securely in Tor data directory │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 2: Service Registration │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ • Tor creates hidden service descriptor │ │
│ │ • Descriptor contains: public key, service info, introduction points │ │
│ │ • Published to distributed hash table (DHT) in Tor network │ │
│ │ • Rendezvous points selected for client connections │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Step 3: Connection Establishment │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ • Client looks up .onion address in Tor DHT │ │
│ │ • Retrieves service descriptor and introduction points │ │
│ │ • Establishes circuit to rendezvous point │ │
│ │ • Server and client meet at rendezvous point │ │
│ │ • Direct encrypted tunnel established (no exit node needed) │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
┌─────────────────────────────────────────────────────────────────────────────────────┐
│ TRAFFIC CHARACTERISTICS │
├─────────────────────────────────────────────────────────────────────────────────────┤
│ │
│ Protocol Stack: │
│ ┌─────────────────────────────────────────────────────────────────────────────────┐ │
│ │ Application Layer: Encrypted Messages (Fernet) │ │
│ │ Transport Layer: TCP (reliable delivery) │ │
│ │ Network Layer: Tor Onion Routing (3 layers of encryption) │ │
│ │ Physical Layer: Standard Internet (but anonymized) │ │
│ └─────────────────────────────────────────────────────────────────────────────────┘ │
│ │
│ Traffic Flow: │
│ • NOT HTTPS: Direct TCP connection through Tor │
│ • Each Tor hop adds/removes one layer of encryption │
│ • Final connection to hidden service is direct (no exit node) │
│ • All traffic appears as Tor traffic to ISP/network observers │
│ • Message content encrypted separately with Fernet (double encryption) │
│ │
└─────────────────────────────────────────────────────────────────────────────────────┘
This implementation is based on research documented at: Research Document - Anonymous Messaging Systems
This application creates an anonymous messaging system where users can communicate without revealing their IP addresses or identities. It combines Tor's anonymity network with strong encryption to protect both message content and metadata.
The system operates in two modes:
- Server Mode: Creates a Tor hidden service (.onion address) that others can connect to
- Client Mode: Connects to existing hidden services using connection strings
- TorManager: Manages Tor process and hidden service creation
- SecureMessenger: Handles encryption/decryption and traffic obfuscation
- AnonymousServer: Manages client connections and message relay
- AnonymousClient: Handles client-side connection and UI
- Tor Hidden Services: All communication routed through Tor's onion routing
- No IP Address Exposure: Server and clients never reveal real IP addresses
- Circuit Refresh: Automatic Tor circuit renewal every 5 minutes
- Enhanced Tor Configuration:
- New circuits every 30 seconds
- Distinct subnet enforcement
- IPv6 disabled to prevent leaks
- Minimal disk writes
- Fernet Encryption: Symmetric encryption using cryptographically secure keys
- Message Padding: Fixed-size message padding (512B, 1KB, 2KB, 4KB) to prevent size analysis
- Timing Obfuscation: Random delays (0.5-3 seconds) between messages
- Dummy Traffic: Periodic fake messages to obscure communication patterns
- Perfect Forward Secrecy: Prepared for ECDH key exchange (currently uses Fernet for compatibility)
- Secure Memory Zeroing: Multiple-pass memory clearing for sensitive data
- Memory Locking: Prevents sensitive data from being swapped to disk (when available)
- Temporary File Cleanup: Automatic cleanup of Tor data directories
- Logging Disabled: All Python logging disabled to prevent metadata leakage
- Fixed Message Sizes: Messages padded to standard sizes
- Dummy Traffic Generation: Regular fake messages every 30-60 seconds
- Timing Randomization: Variable delays to prevent timing correlation
- Connection Obfuscation: Multiple retry attempts with delays
# Install Tor
# Ubuntu/Debian:
sudo apt-get install tor
# macOS:
brew install tor
# Install Python dependencies for messenger
pip install -r requirements.txt
# Install additional dependencies for security testing
pip install -r pentest_requirements.txtFor Messenger:
stem>=1.8.0
cryptography>=3.0.0
rich>=10.0.0
PySocks>=1.7.0
requests>=2.25.0
For Security Testing:
scapy>=2.4.0
matplotlib>=3.0.0
seaborn>=0.11.0
numpy>=1.19.0
pandas>=1.3.0
psutil>=5.8.0
# Interactive mode
python anon_messenger.py
# Direct server mode
python anon_messenger.py --serverThe server will:
- Start Tor and create a hidden service
- Generate an encryption key
- Display a connection string like:
abc123def456.onion:encryption_key_here
# Interactive mode
python anon_messenger.py
# Direct client mode
python anon_messenger.py --client "onion_address:encryption_key"- Type messages and press Enter to send
- Type
quit,exit,/quit, or/exitto disconnect - Ctrl+C to force exit
The project includes a comprehensive penetration testing tool (pentest_anon_messenger.py) that demonstrates the security and anonymity of the messenger by analyzing what data can and cannot be observed through various network analysis techniques.
The penetration testing tool serves as proof-of-concept to demonstrate:
- What network traffic is visible to observers
- How the messenger's security measures protect against common attacks
- Traffic analysis resistance and correlation attack prevention
- Tor infrastructure security assessment
The tool requires root/administrator privileges for packet capture:
# Linux/macOS - Install system dependencies
sudo apt-get install python3-dev libpcap-dev # Ubuntu/Debian
brew install libpcap # macOS# Run comprehensive security test (60 seconds)
sudo python3 pentest_anon_messenger.py
# Quick test (30 seconds)
sudo python3 pentest_anon_messenger.py --quick
# Custom duration
sudo python3 pentest_anon_messenger.py --duration 120
# Specify network interface
sudo python3 pentest_anon_messenger.py --interface eth0
# Generate detailed report and visualizations
sudo python3 pentest_anon_messenger.py --report security_analysis.json --plots-
Start the Anonymous Messenger (in separate terminal):
python3 anon_messenger.py --server
-
Run the Pentest Tool (requires root):
sudo python3 pentest_anon_messenger.py --duration 60 --plots
-
Connect Clients (in separate terminals):
python3 anon_messenger.py --client "onion_address:key" -
Send Messages to generate traffic for analysis
-
Review Results in the pentest tool output and generated plots
- Packet Capture: Real-time network packet interception
- Traffic Pattern Analysis: Timing, size, and flow analysis
- Tor Traffic Detection: Identification of Tor-related communications
- Connection Mapping: Analysis of network connections and patterns
- Tor Infrastructure Analysis: Detection and configuration assessment
- Correlation Attack Simulation: Traffic correlation vulnerability testing
- Timing Analysis: Detection of regular patterns that could aid attacks
- Padding Detection: Verification of message padding effectiveness
- Real-time Display: Live security analysis with Rich UI
- Security Scoring: Numerical security assessment (0-100)
- Detailed Reports: JSON export of all findings
- Recommendations: Specific security improvement suggestions
The pentest tool generates three comprehensive security visualizations that provide critical insights for research into anonymous messaging security:
What it shows:
- Packet Size Distribution: Color-coded fingerprinting risk analysis
- Timing Pattern Analysis: Inter-packet timing with correlation risk assessment
- Traffic Volume Timeline: Burst detection and volume pattern analysis
- Tor Coverage Analysis: Percentage of traffic protected by anonymization
- Comprehensive Summary: Metrics including entropy, metadata leakage, and fingerprinting risk
Research Value: Quantifies what network attackers can observe and demonstrates effectiveness of anonymity protections.
What it shows:
- Overall Security Score: 0-100 gauge with letter grade (A-F)
- Component Breakdown: Tor Infrastructure, Traffic Analysis, Correlation Resistance
- Anonymity Radar: Multi-dimensional security assessment across 6 categories
- Protection vs Attack Success: Defense effectiveness against specific attack types
- Recommendations: Prioritized security improvements with urgency levels
Research Value: Comprehensive assessment of security measures effectiveness and overall protection quality.
What it shows:
- Risk Matrix: Likelihood vs Impact analysis for different attack vectors
- Attack Timeline: Success probability over time for various attack scenarios
- Defense Analysis: Theoretical vs actual implementation effectiveness
- Adversary Assessment: Protection levels against different threat actors
- Vulnerability Heatmap: Systematic assessment across network layers
- Mitigation Roadmap: Priority-based action items for security improvements
Research Value: Comprehensive threat modeling and vulnerability assessment with actionable mitigation strategies.
What it checks:
- Tor process detection and configuration
- Port analysis (SOCKS, Control ports)
- Tor connectivity testing
- Security configuration assessment
Expected Results:
- ✓ Tor processes running
- ✓ SOCKS proxy functional
- ✓ Secure configuration detected
What it captures:
- All TCP packets on specified interface
- Packet timing and size patterns
- Connection establishment and teardown
- Tor-specific traffic identification
What it analyzes:
- Traffic volume and patterns
- Message size distribution
- Timing regularity
- Padding effectiveness
Scoring Criteria:
- Tor Infrastructure (30 points): Proper Tor setup and connectivity
- Traffic Analysis (40 points): Padding, timing obfuscation, Tor usage
- Correlation Risk (30 points): Resistance to traffic correlation attacks
Grade Scale:
- A (90-100): Excellent security
- B (80-89): Good security
- C (70-79): Adequate security
- D (60-69): Poor security
- F (0-59): Inadequate security
-
Network Metadata:
- Connection timestamps
- Packet sizes and timing
- Traffic volume
- Tor usage (but not destinations)
-
Traffic Patterns:
- Communication frequency
- Burst patterns
- Connection durations
-
Message Content:
- All messages are encrypted end-to-end
- No plaintext content visible
-
Real IP Addresses:
- All traffic routed through Tor
- Only localhost connections visible
-
Message Recipients:
- Hidden service addresses not exposed
- No correlation between users
-
Message Sizes:
- Padding obscures actual message lengths
- Fixed-size packets prevent size analysis
- Padding Detection: Verifies messages are padded to fixed sizes (512B, 1KB, 2KB, 4KB)
- Timing Obfuscation: Detects random delays between messages (0.5-3 seconds)
- Dummy Traffic: Identifies fake messages sent periodically
- Tor Integration: Verifies all traffic routes through Tor network
- Circuit Management: Detects automatic circuit refresh (every 5 minutes)
- Pattern Analysis: Tests for regular timing patterns
- Traffic Bursts: Identifies bursts that could aid correlation
- Risk Assessment: Overall correlation risk (LOW/MEDIUM/HIGH)
- ✓ Tor processes running and configured securely
- ✓ Padding detected in traffic analysis
- ✓ No regular timing patterns
- ✓ Low correlation attack risk
- ✓ Security score 80+ (Grade B or better)
- ✗ Regular timing patterns detected
- ✗ No padding in messages
- ✗ High correlation attack risk
- ✗ Tor connectivity issues
- ✗ Security score below 70 (Grade C or worse)
Permission Denied:
# Solution: Run with sudo
sudo python3 pentest_anon_messenger.pyNo Packets Captured:
# Check interface name
ip addr show # Linux
ifconfig # macOS
# Use correct interface
sudo python3 pentest_anon_messenger.py --interface eth0Tor Not Detected:
# Start Tor manually
tor &
# Or use system Tor
sudo systemctl start tor # Linux
brew services start tor # macOS- Risk: Traffic pattern analysis could correlate users
- Mitigation: Enhanced dummy traffic, variable timing
- Severity: High
- Risk: Sensitive data in memory could be extracted
- Mitigation: Better memory protection, secure enclaves
- Severity: High
- Risk: Tor network compromise or traffic analysis
- Mitigation: Use bridges, guard node selection
- Severity: High
- Risk: Timing, power, or electromagnetic analysis
- Mitigation: Constant-time operations, hardware security
- Severity: Medium
- Risk: Cryptographic implementation flaws
- Mitigation: Code audits, formal verification
- Severity: Medium
- Risk: Vulnerabilities in third-party libraries
- Mitigation: Regular updates, dependency scanning
- Severity: Medium
- Risk: Malware or system-level attacks
- Mitigation: System hardening, sandboxing
- Severity: Low (requires local access)
- Risk: Users revealing connection strings
- Mitigation: User education, secure sharing methods
- Severity: Low (user error)
- Global Passive Adversary: Could correlate traffic patterns
- Tor Node Compromise: Malicious entry/exit nodes
- ISP Monitoring: Deep packet inspection and timing analysis
- DNS Leaks: Potential DNS resolution outside Tor
- Fingerprinting: Unique usage patterns or behaviors
- Metadata Analysis: Message timing and size correlation
- Key Compromise: If encryption keys are exposed
- Protocol Attacks: Exploitation of implementation flaws
- Use VPN + Tor for additional layers
- Regular circuit refresh and key rotation
- Consistent dummy traffic patterns
- Avoid revealing personal information in messages
- Use from isolated, hardened systems
This system assumes:
- Tor network is functioning and not completely compromised
- Local system is secure and not compromised
- Users follow operational security practices
- Cryptographic libraries are implemented correctly
- No global passive adversary with unlimited resources
- Perfect Forward Secrecy: Implement full ECDH key exchange
- Post-Quantum Cryptography: Add quantum-resistant algorithms
- Message Authentication: Add HMAC for message integrity
- Key Rotation: Automatic periodic key rotation
- Secure Key Exchange: Implement secure initial key exchange protocol
- Bridge Support: Add Tor bridge configuration for censored networks
- Pluggable Transports: Support for obfs4 and other transports
- Guard Node Selection: Custom guard node configuration
- Exit Node Avoidance: Ensure all traffic stays within Tor network
- Sandboxing: Run in isolated containers or VMs
- Memory Protection: Enhanced memory protection mechanisms
- Secure Boot: Verify system integrity
- Network Isolation: Prevent non-Tor network access
- Group Chat: Multi-user chat rooms
- File Transfer: Secure file sharing capabilities
- Message History: Encrypted local message storage
- User Authentication: Optional user verification
- Mobile Support: Cross-platform compatibility
secure_zero_memory(data): Overwrites sensitive data in memory 3 times with zeros to prevent recoverylock_memory(data): Uses mlock to prevent memory pages from being swapped to disk- Logging Disabled: All Python logging and urllib3 warnings disabled to prevent metadata leakage
Manages Tor process lifecycle, hidden service creation, and circuit management for anonymity.
find_free_port(start_port=9050)
- Scans ports sequentially to find available SOCKS/control ports
- Prevents port conflicts when multiple instances run
check_existing_tor()
- Attempts to connect to existing Tor instance on default ports (9050/9051)
- Tests SOCKS proxy functionality before proceeding
- Applies security configurations to existing instance
start_tor()
- Creates temporary data directory with secure permissions
- Launches Tor with hardened configuration:
NewCircuitPeriod: 30s- Forces frequent circuit changesEnforceDistinctSubnets: 1- Prevents same-subnet relay usageClientUseIPv6: 0- Disables IPv6 to prevent leaksAvoidDiskWrites: 1- Minimizes forensic traces
- Establishes controller connection for circuit management
create_hidden_service(port)
- Creates ephemeral hidden service in temporary directory
- Handles different stem API versions for compatibility
- Returns .onion address for client connections
- Waits 5 seconds for service propagation
_start_circuit_refresh()
- Spawns daemon thread for automatic circuit renewal every 5 minutes
- Sends NEWNYM signal to force new circuits
- Prevents long-term traffic correlation
Handles end-to-end encryption, message padding, timing obfuscation, and dummy traffic generation.
generate_key()
- Creates Fernet symmetric key using cryptographically secure random generator
- Returns base64-encoded key for sharing
set_key(key_str)
- Validates and sets encryption key from connection string
- Handles base64 padding correction
- Initializes Fernet cipher suite
_derive_message_key(message_id)
- Prepared for ECDH implementation using HKDF key derivation
- Would derive unique keys per message for perfect forward secrecy
- Currently unused (Fernet compatibility mode)
_pad_message(message)
- Adds random padding (16-80 bytes) to obscure message length
- Selects target size from fixed MESSAGE_SIZES array
- Format:
[4-byte length][message][random padding] - Prevents traffic analysis based on message size
_unpad_message(padded_data)
- Extracts original message from padded data
- Reads 4-byte length prefix to determine message boundaries
- Handles legacy unpadded messages for backward compatibility
_apply_timing_obfuscation()
- Enforces random delays (0.5-3 seconds) between messages
- Prevents timing correlation attacks
- Tracks last send time to ensure minimum intervals
encrypt_message(message)
- Applies timing obfuscation before encryption
- Pads message to fixed size
- Uses Fernet authenticated encryption
- Returns base64-encoded ciphertext
decrypt_message(encrypted_message)
- Decrypts Fernet token
- Removes padding to recover original message
- Handles both padded and legacy message formats
generate_dummy_message()
- Creates fake messages with random content
- Prefixed with "DUMMY:" for identification
- Used for traffic analysis protection
is_dummy_message(decrypted_message)
- Identifies dummy traffic by "DUMMY:" prefix
- Prevents dummy messages from being displayed
Manages server-side operations including client connections, message relay, and dummy traffic generation.
start()
- Initializes TorManager and creates hidden service
- Binds TCP socket to localhost:8080
- Generates encryption key and displays connection string
- Starts dummy traffic generation thread
- Accepts client connections in main loop
_start_dummy_traffic()
- Spawns daemon thread for periodic dummy message generation
- Sends fake messages every 30-60 seconds (randomized)
- Broadcasts dummy traffic to all connected clients
- Maintains traffic flow even during idle periods
handle_client(client_socket)
- Manages individual client connections in separate threads
- Relays encrypted messages between clients without decryption
- Removes failed clients from connection pool
- No message content inspection (zero-knowledge relay)
stop()
- Gracefully shuts down server and cleans up resources
- Closes all client connections
- Triggers TorManager and SecureMessenger cleanup
Handles client-side connection establishment, message sending/receiving, and user interface.
connect(connection_string)
- Parses connection string format:
onion_address:encryption_key - Sets up encryption using provided key
- Discovers working Tor SOCKS proxy (ports 9050-9054)
- Establishes connection through Tor to hidden service
- Implements retry logic with exponential backoff
receive_messages()
- Runs in separate thread to handle incoming messages
- Decrypts received messages using SecureMessenger
- Filters out dummy traffic before display
- Continues on decryption errors (resilient to malformed data)
send_message(message)
- Encrypts message using SecureMessenger
- Sends over established Tor connection
- Displays sent message to user
- Handles connection failures gracefully
input_handler()
- Processes user input in separate thread
- Handles quit commands (
quit,exit,/quit,/exit) - Sends non-empty messages through encrypted channel
- Manages graceful disconnection
start_chat_ui()
- Initializes interactive chat interface using Rich library
- Starts input handler thread
- Maintains main loop until disconnection
- Handles keyboard interrupts (Ctrl+C)
disconnect()
- Closes socket connection
- Triggers SecureMessenger cleanup
- Sets connection flag to false
Provides command-line interface and orchestrates server/client modes.
Argument Parsing
--server: Starts in server mode--client <connection_string>: Connects as client- No arguments: Interactive mode selection
Interactive Mode
- Prompts user to choose server or client mode
- Handles connection string input for client mode
- Provides clean exit on keyboard interrupt
Error Handling
- Graceful cleanup on exceptions
- Proper resource deallocation
- Silent failure handling for security
MESSAGE_SIZES = [512, 1024, 2048, 4096] # Fixed message sizes for padding
DUMMY_TRAFFIC_INTERVAL = 30 # Send dummy traffic every 30 seconds
MIN_MESSAGE_DELAY = 0.5 # Minimum delay between messages
MAX_MESSAGE_DELAY = 3.0 # Maximum delay between messages
CIRCUIT_REFRESH_INTERVAL = 300 # Refresh Tor circuit every 5 minutes- Main Thread: UI/connection management
- Receive Thread: Message reception and decryption
- Input Thread: User input processing
- Dummy Traffic Thread: Periodic fake message generation
- Circuit Refresh Thread: Tor circuit renewal
- Traffic Analysis Studies: Use visibility analysis to quantify what attackers can observe
- Anonymity Metrics: Radar charts provide multi-dimensional anonymity assessment
- Threat Modeling: Risk matrices enable systematic threat analysis
- Defense Evaluation: Compare theoretical vs actual protection effectiveness
- Penetration Testing: Comprehensive vulnerability identification
- Risk Management: Prioritized mitigation roadmaps
- Compliance: Quantified security scoring for audits
- Monitoring: Track security improvements over time
- Design Validation: Verify anonymity protections work as intended
- Performance Tuning: Balance security vs performance trade-offs
- Feature Prioritization: Focus development on highest-impact security improvements
For detailed research methodology, threat modeling, and implementation decisions, see the complete research documentation: Research Document
This software is for educational and research purposes. Users are responsible for compliance with local laws and regulations. The authors make no guarantees about the security or anonymity provided by this system.
Security improvements and bug reports are welcome. Please follow responsible disclosure for security vulnerabilities.
MIT License - See LICENSE file for details