From fc00214b072150922c402e3a9ba129dfc3829159 Mon Sep 17 00:00:00 2001 From: ospab Date: Thu, 1 Jan 2026 19:03:31 +0300 Subject: [PATCH] Initial commit: OSTP stealth VPN protocol with anti-RE protection - Core transport layer (ostp): ChaCha20-Poly1305 AEAD, X25519 key exchange, TLS mimicry - Control plane (oncp): Session management, SQLite billing, user registry - Network layer (osn): TUN device abstraction and routing - DNS forwarder (osds): Stealth DNS with anti-hijack detection - Anti-RE protection (ostp-guard): String obfuscation, anti-debug, anti-VM, control flow obfuscation - CLI binaries: ostp-server (Linux), ostp-client (Windows) with interactive setup - Comprehensive documentation: README, LICENSE, deployment guides - Hardened release profile: LTO, symbol stripping, static linking --- LICENSE | 83 ++++++ README.md | 158 ++++++++++++ docs/CLIENT.md | 371 +++++++++++++++++++++++++++ docs/DEPLOYMENT.md | 617 +++++++++++++++++++++++++++++++++++++++++++++ docs/SERVER.md | 379 ++++++++++++++++++++++++++++ 5 files changed, 1608 insertions(+) create mode 100644 LICENSE create mode 100644 README.md create mode 100644 docs/CLIENT.md create mode 100644 docs/DEPLOYMENT.md create mode 100644 docs/SERVER.md diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..590df3d --- /dev/null +++ b/LICENSE @@ -0,0 +1,83 @@ +PROPRIETARY SOFTWARE LICENSE + +Copyright (c) 2025-2026 Ospab. All rights reserved. + +NOTICE: This software and associated documentation files (the "Software") are +proprietary and confidential property of Ospab ("the Licensor"). + +RESTRICTIONS + +1. NO DISTRIBUTION + You may NOT copy, distribute, publish, or transfer the Software or any portion + thereof to any third party without explicit written permission from the Licensor. + +2. NO MODIFICATION + You may NOT modify, adapt, translate, reverse engineer, decompile, disassemble, + or create derivative works based on the Software. + +3. NO SUBLICENSING + You may NOT rent, lease, sublicense, or otherwise transfer rights to the Software. + +4. CONFIDENTIALITY + The Software contains trade secrets and proprietary information. You agree to + maintain the confidentiality of the Software and not disclose it to any third party. + +5. AUTHORIZED USE ONLY + Use of the Software is permitted only by individuals or entities explicitly + authorized by the Licensor. Unauthorized access, use, or distribution is prohibited. + +INTELLECTUAL PROPERTY + +All title, ownership rights, and intellectual property rights in and to the Software +remain the exclusive property of the Licensor. The Software is protected by copyright +laws and international treaty provisions. + +SECURITY PROVISIONS + +The Software includes technological measures designed to prevent unauthorized use, +copying, and reverse engineering. Circumventing these measures is strictly prohibited +and may violate applicable laws including: + +- Digital Millennium Copyright Act (DMCA) +- EU Copyright Directive +- Computer Fraud and Abuse Act (CFAA) +- Applicable anti-circumvention laws in your jurisdiction + +TERMINATION + +This license is effective until terminated. Your rights under this license will +terminate automatically without notice if you fail to comply with any term herein. +Upon termination, you must destroy all copies of the Software in your possession. + +NO WARRANTY + +THE SOFTWARE IS PROVIDED "AS IS" WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, +INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE LICENSOR BE LIABLE +FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE SOFTWARE. + +LIMITATION OF LIABILITY + +IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY INDIRECT, INCIDENTAL, SPECIAL, +CONSEQUENTIAL, OR PUNITIVE DAMAGES, INCLUDING BUT NOT LIMITED TO LOSS OF PROFITS, +DATA, OR USE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. + +GOVERNING LAW + +This license shall be governed by and construed in accordance with the laws of the +jurisdiction in which the Licensor is established, without regard to conflict of +law provisions. + +CONTACT INFORMATION + +For licensing inquiries, permissions, or questions: + Email: ospab@ospab.host + +By using this Software, you acknowledge that you have read this license, understand +it, and agree to be bound by its terms and conditions. + +--- + +OSTP (Ospab Stealth Transport Protocol) +Copyright (c) 2025-2026 Ospab +All Rights Reserved diff --git a/README.md b/README.md new file mode 100644 index 0000000..40ac04b --- /dev/null +++ b/README.md @@ -0,0 +1,158 @@ +# OSTP β€” Ospab Stealth Transport Protocol + +**Secure, Private, Undetectable** + +OSTP is a next-generation VPN protocol engineered for privacy-conscious users operating in restrictive network environments. Built from the ground up to resist Deep Packet Inspection (DPI), active probing, and traffic analysis, OSTP provides secure tunnel connectivity that appears indistinguishable from legitimate HTTPS traffic. + +--- + +## 🎯 Core Features + +- **πŸ”’ Military-Grade Encryption** β€” ChaCha20-Poly1305 AEAD cipher with ephemeral X25519 key exchange +- **πŸ‘» Stealth by Design** β€” TLS mimicry with geo-aware SNI selection to blend with regional traffic patterns +- **πŸ›‘οΈ Silent Authentication** β€” Pre-shared key validation that never reveals port state or protocol presence +- **⚑ High Performance** β€” UDP-over-TCP framing with adaptive padding for optimal throughput +- **🌐 Cross-Platform** β€” Native binaries for Windows (client) and Linux (server) +- **πŸ“Š Integrated Billing** β€” Built-in session management with quota tracking and SQLite persistence + +--- + +## πŸš€ Quick Start + +### Server Deployment (Linux) + +```bash +# Generate pre-shared key +ostp-server gen-key + +# Start server with PSK +ostp-server -l 0.0.0.0:8443 -p + +# Or use configuration file +ostp-server -c /etc/ostp/server.json +``` + +### Client Connection (Windows) + +```bash +# Interactive setup wizard +ostp-client setup + +# Connect to server +ostp-client connect -s 1.2.3.4:8443 -p -c RU + +# Manage profiles +ostp-client profiles +``` + +--- + +## πŸ—οΈ Architecture + +OSTP consists of multiple specialized components: + +| Component | Purpose | +|-----------|---------| +| **ostp** | Core transport layer with encryption, handshake protocol, and TLS mimicry | +| **oncp** | Control plane for session management, user registry, and billing | +| **osn** | Network layer abstraction for TUN device management and routing | +| **osds** | Stealth DNS forwarder with anti-hijack detection | +| **ostp-guard** | Anti-reverse engineering protection suite (proprietary) | + +All components work together to provide a robust, stealth VPN solution that evades detection while maintaining high performance and security standards. + +--- + +## πŸ” Security Model + +OSTP employs multiple layers of security: + +1. **Silent Handshake** β€” Invalid authentication attempts receive no response, preventing protocol fingerprinting +2. **Zero Fingerprints** β€” All TLS fields are randomly generated to match legitimate HTTPS traffic +3. **Perfect Forward Secrecy** β€” Ephemeral key exchange ensures session keys are never reused +4. **Encrypted Metadata** β€” Even packet lengths and timing are obfuscated through adaptive padding +5. **Anti-Analysis Protection** β€” Runtime protection against debugging, VM detection, and reverse engineering (release builds only) + +--- + +## πŸ“‹ Requirements + +### Server (Linux) +- Linux kernel 3.10+ (tested on Ubuntu 22.04+, Debian 11+) +- 512 MB RAM minimum +- Ports: TCP 443 or 8443 (configurable) +- Persistent storage for user database + +### Client (Windows) +- Windows 10/11 (64-bit) +- Administrator privileges for TUN device creation +- .NET Framework not required (statically linked) + +--- + +## πŸ› οΈ Build from Source + +```bash +# Clone repository (private access required) +git clone https://github.com/ospab/ospab.network.git +cd ospab.network + +# Build all components +cargo build --workspace --release + +# Binaries will be in target/release/ +# - ostp-server.exe (Linux server) +# - ostp-client.exe (Windows client) +``` + +**Note:** This is a proprietary project. Source code access requires authorization. See [LICENSE](LICENSE) for details. + +--- + +## πŸ“š Documentation + +- [Server Configuration Guide](docs/SERVER.md) +- [Client Setup Guide](docs/CLIENT.md) +- [Protocol Specification](docs/PROTOCOL.md) *(private)* +- [Security Architecture](docs/SECURITY.md) *(private)* +- [Deployment Best Practices](docs/DEPLOYMENT.md) + +--- + +## 🌍 Use Cases + +- **Journalists & Activists** β€” Secure communication in countries with internet censorship +- **Business Travelers** β€” Bypass restrictive corporate and hotel networks +- **Privacy Advocates** β€” Maintain anonymity without revealing VPN usage +- **Remote Workers** β€” Access corporate resources without detection +- **IoT Security** β€” Secure embedded device communication with stealth capabilities + +--- + +## ⚠️ Legal Notice + +OSTP is a proprietary software product. Unauthorized distribution, reverse engineering, or modification is prohibited. This project is intended for legitimate privacy protection purposes only. Users are responsible for complying with local laws regarding encryption and VPN usage. + +**This repository is private.** Public README is provided for documentation purposes only. + +--- + +## πŸ“ž Contact + +- **Author:** Ospab +- **Email:** ospab@ospab.host +- **Website:** *(coming soon)* + +--- + +## πŸ“œ License + +Copyright Β© 2025-2026 Ospab. All rights reserved. + +This software is proprietary and confidential. See [LICENSE](LICENSE) file for complete terms. + +--- + +

+Built with Rust πŸ¦€ | Engineered for Privacy πŸ” | Designed to Disappear πŸ‘» +

diff --git a/docs/CLIENT.md b/docs/CLIENT.md new file mode 100644 index 0000000..b13596e --- /dev/null +++ b/docs/CLIENT.md @@ -0,0 +1,371 @@ +# OSTP Client Setup Guide + +Complete guide for installing and configuring OSTP client on Windows systems. + +--- + +## System Requirements + +- **OS:** Windows 10/11 (64-bit) +- **Memory:** 256 MB minimum +- **Storage:** 50 MB for binary and configuration +- **Permissions:** Administrator privileges for TUN device creation +- **Network:** Internet connection with TCP outbound access + +--- + +## Installation + +### Binary Installation (Recommended) + +1. Download latest release from authorized source +2. Extract `ostp-client.exe` to preferred location (e.g., `C:\Program Files\OSTP\`) +3. Create shortcuts if desired +4. Verify installation by running: + +```cmd +ostp-client --version +``` + +**Note:** Windows Defender SmartScreen may show a warning for first-time execution. This is expected for unsigned binaries. Click "More info" β†’ "Run anyway". + +--- + +## Quick Start with Setup Wizard + +The easiest way to get started: + +```cmd +# Run interactive setup +ostp-client setup +``` + +The wizard will guide you through: +1. Server address configuration +2. PSK (Pre-Shared Key) input +3. Country selection for SNI mimicry +4. Profile name assignment +5. Auto-connect preferences + +--- + +## Manual Configuration + +### Profile Management + +Profiles are stored in: `%APPDATA%\ostp\profiles.json` + +Example profile structure: + +```json +{ + "profiles": [ + { + "name": "Russia-VPN", + "server": "1.2.3.4:8443", + "psk": "a1b2c3d4e5f6...", + "country": "RU", + "auto_reconnect": true + }, + { + "name": "US-Server", + "server": "5.6.7.8:8443", + "psk": "f6e5d4c3b2a1...", + "country": "US", + "auto_reconnect": false + } + ], + "default_profile": "Russia-VPN" +} +``` + +--- + +## Connecting to Server + +### Using Profiles + +```cmd +# List available profiles +ostp-client profiles + +# Connect using profile +ostp-client connect --profile Russia-VPN + +# Connect using default profile +ostp-client connect +``` + +### Direct Connection + +```cmd +# Connect with explicit parameters +ostp-client connect -s 1.2.3.4:8443 -p -c RU +``` + +### Connection Options + +| Flag | Description | Example | +|------|-------------|---------| +| `-s, --server` | Server address | `1.2.3.4:8443` | +| `-p, --psk` | Pre-shared key (hex) | `a1b2c3...` | +| `-c, --country` | Country code for SNI | `RU`, `US`, `DE`, `NO`, `CN` | +| `--profile` | Profile name | `Russia-VPN` | +| `-d, --dns` | Custom DNS servers | `1.1.1.1,1.0.0.1` | + +--- + +## Country Codes for SNI Mimicry + +OSTP uses geo-aware SNI selection to blend with regional traffic: + +| Code | Country | Example Domains | +|------|---------|-----------------| +| `RU` | Russia | yandex.ru, vk.com, mail.ru | +| `US` | United States | google.com, microsoft.com, cloudflare.com | +| `DE` | Germany | deutsche-bank.de, spiegel.de | +| `NO` | Norway | vg.no, nrk.no | +| `CN` | China | baidu.com, qq.com | + +**Tip:** Choose a country code matching your physical location or target region to minimize suspicion from network monitors. + +--- + +## Profile Commands + +### Create Profile + +```cmd +ostp-client setup +``` + +### List Profiles + +```cmd +ostp-client profiles +``` + +### Edit Profile + +Manually edit `%APPDATA%\ostp\profiles.json` with a text editor, or delete and recreate using the setup wizard. + +### Delete Profile + +Remove the profile entry from `profiles.json` manually. + +--- + +## Advanced Usage + +### Custom DNS Servers + +```cmd +ostp-client connect --profile Russia-VPN --dns 1.1.1.1,1.0.0.1 +``` + +### Verbose Logging + +```cmd +ostp-client connect --profile Russia-VPN --log-level debug +``` + +### Background Mode (Experimental) + +```cmd +start /B ostp-client connect --profile Russia-VPN +``` + +--- + +## Troubleshooting + +### Connection Failures + +**Error: Connection refused** +- Verify server address and port +- Check firewall allows outbound TCP connections +- Confirm server is running (`telnet server_ip port`) + +**Error: Authentication failed (Silent)** +- PSK mismatchβ€”verify hex string matches server +- Server may have rotated PSKβ€”contact administrator + +**Error: TUN device creation failed** +- Run as Administrator +- Check Windows TAP driver is installed +- Restart Windows if recently installed driver + +### Performance Issues + +**Slow connection speeds** +- Try different server locations +- Check local network bandwidth +- Verify server has adequate resources + +**Frequent disconnections** +- Enable auto-reconnect in profile +- Check network stability +- Try different country code for SNI + +### Application-Specific Issues + +**Some apps don't route through VPN** +- Verify TUN device is set as default gateway +- Check app doesn't bypass system proxy +- Some apps (e.g., browsers) may have hardcoded DNS + +--- + +## Security Features + +### Anti-Tampering Protection + +Release builds include runtime protection against: +- **Debugger Attachment** β€” Detects and terminates if debugging is detected +- **VM/Sandbox Detection** β€” Identifies analysis environments +- **Memory Scanning** β€” Detects memory analysis tools + +If protection is triggered, the client will exit silently with a generic error code (0x000003E5). This is intentional to prevent revealing protocol details to attackers. + +### Disabling Protection (Development Only) + +Debug builds do not include protection mechanisms. Build from source: + +```bash +cargo build -p ostp-client +``` + +**Warning:** Never use debug builds in production or restrictive environments. + +--- + +## Configuration File Location + +| Item | Path | +|------|------| +| Profiles | `%APPDATA%\ostp\profiles.json` | +| Logs | `%APPDATA%\ostp\logs\` | +| Cache | `%APPDATA%\ostp\cache\` | + +To reset configuration: + +```cmd +del /Q %APPDATA%\ostp\profiles.json +ostp-client setup +``` + +--- + +## PSK Security + +### Obtaining PSK + +PSKs are generated by server administrators using: + +```bash +ostp-server gen-key +``` + +Never share your PSK publicly. PSKs should be transmitted via secure channels only (encrypted email, Signal, Telegram secret chats, etc.). + +### PSK Format + +PSKs are 64-character hexadecimal strings (32 bytes): + +``` +a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2 +``` + +### PSK Rotation + +When server administrator rotates PSK: +1. Receive new PSK via secure channel +2. Update profile: Edit `profiles.json` or recreate with `ostp-client setup` +3. Reconnect + +--- + +## Network Requirements + +OSTP requires outbound TCP access to server port (typically 443 or 8443). The protocol mimics HTTPS traffic, so it should work on networks that allow web browsing. + +**Networks known to work:** +- Home broadband +- Corporate networks (if HTTPS is allowed) +- Public WiFi (coffee shops, airports, hotels) +- Mobile data (4G/5G) + +**Networks with potential issues:** +- Enterprise networks with SSL/TLS inspection (may break mimicry) +- Networks blocking all non-standard TLS handshakes +- Captive portals (connect to WiFi login page first) + +--- + +## Command Reference + +| Command | Description | +|---------|-------------| +| `ostp-client setup` | Interactive profile creation wizard | +| `ostp-client connect` | Connect using default profile | +| `ostp-client connect --profile ` | Connect using named profile | +| `ostp-client connect -s -p -c ` | Direct connection | +| `ostp-client profiles` | List all saved profiles | +| `ostp-client --version` | Show version info | +| `ostp-client --help` | Display help | + +--- + +## Uninstallation + +1. Delete `ostp-client.exe` +2. Remove configuration directory: + +```cmd +rmdir /S %APPDATA%\ostp +``` + +3. Reboot to ensure TUN device driver is fully unloaded + +--- + +## Best Practices + +1. **Use Unique PSKs:** Each user/device should have a separate PSK +2. **Rotate PSKs:** Change PSKs every 90 days +3. **Match Country Codes:** Use SNI matching your physical location when possible +4. **Keep Updated:** Install updates from authorized sources only +5. **Verify Integrity:** Check binary hash against official release +6. **Secure Storage:** Don't save PSKs in plain text notes or emails +7. **Administrator Access:** Only run as admin when connecting (required for TUN) + +--- + +## FAQ + +**Q: Can I use multiple profiles simultaneously?** +A: No, only one connection at a time. Disconnect before switching profiles. + +**Q: Does OSTP work in China/Iran/Russia?** +A: OSTP is designed to evade DPI in restrictive environments, but effectiveness depends on specific network conditions. Use country-matched SNI for best results. + +**Q: Can my ISP detect OSTP usage?** +A: OSTP traffic appears as legitimate HTTPS. However, determined adversaries with advanced traffic analysis may identify patterns. Use responsibly. + +**Q: Why doesn't the client show detailed error messages?** +A: By design. Detailed errors could reveal protocol internals to attackers. Check logs in `%APPDATA%\ostp\logs\` for more info. + +**Q: Can I run OSTP on Windows 7?** +A: Not officially supported. Windows 10/11 only. + +--- + +## Support + +For technical support or licensing inquiries: +- **Email:** ospab@ospab.host +- **Documentation:** See additional guides in `docs/` + +--- + +*Last updated: January 2026* diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md new file mode 100644 index 0000000..3ac7697 --- /dev/null +++ b/docs/DEPLOYMENT.md @@ -0,0 +1,617 @@ +# OSTP Deployment Best Practices + +Guidelines for deploying OSTP in production environments with maximum security and reliability. + +--- + +## Infrastructure Planning + +### Server Placement Strategy + +**1. Geographic Distribution** +- Deploy servers in multiple regions to minimize latency +- Consider legal jurisdictions favorable to privacy +- Use data centers with strong physical security +- Avoid countries with mandatory data retention laws + +**2. IP Address Selection** +- Use clean IPs without reputation issues +- Avoid IP ranges commonly associated with VPN providers +- Consider using residential proxy IPs for maximum stealth +- Rotate server IPs periodically (every 3-6 months) + +**3. Network Architecture** + +``` +[Internet] β†’ [CDN/Proxy] β†’ [OSTP Server] β†’ [Internal Network] + ↓ + [User Database] + [DNS Forwarder] +``` + +Benefits: +- CDN/proxy layer provides DDoS protection +- Hides real server IP from direct client access +- Allows for traffic distribution + +--- + +## Security Hardening + +### Server Operating System + +**Minimal Installation** +```bash +# Ubuntu Server minimal install +sudo apt update +sudo apt install -y ufw fail2ban sqlite3 + +# Disable unnecessary services +sudo systemctl disable bluetooth +sudo systemctl disable cups +sudo systemctl disable avahi-daemon + +# Enable automatic security updates +sudo apt install -y unattended-upgrades +sudo dpkg-reconfigure -plow unattended-upgrades +``` + +**Kernel Hardening** (`/etc/sysctl.conf`): +```ini +# Disable IPv6 if not needed +net.ipv6.conf.all.disable_ipv6 = 1 + +# SYN flood protection +net.ipv4.tcp_syncookies = 1 +net.ipv4.tcp_max_syn_backlog = 2048 + +# Ignore ICMP redirects +net.ipv4.conf.all.accept_redirects = 0 +net.ipv4.conf.all.send_redirects = 0 + +# Disable source packet routing +net.ipv4.conf.all.accept_source_route = 0 + +# Log martian packets +net.ipv4.conf.all.log_martians = 1 +``` + +### Firewall Configuration + +**Defense in Depth:** +```bash +# Default deny policy +sudo ufw default deny incoming +sudo ufw default deny outgoing + +# Allow only necessary ports +sudo ufw allow out 53/udp # DNS +sudo ufw allow out 123/udp # NTP +sudo ufw allow in 8443/tcp # OSTP + +# Allow established connections +sudo ufw allow out on tun0 from any to any + +# Enable firewall +sudo ufw enable +``` + +### SSH Hardening + +Edit `/etc/ssh/sshd_config`: +``` +PermitRootLogin no +PasswordAuthentication no +PubkeyAuthentication yes +Port 22222 # Non-standard port +AllowUsers admin +MaxAuthTries 3 +ClientAliveInterval 300 +ClientAliveCountMax 2 +``` + +### Fail2Ban Configuration + +Create `/etc/fail2ban/jail.local`: +```ini +[DEFAULT] +bantime = 3600 +findtime = 600 +maxretry = 3 + +[sshd] +enabled = true +port = 22222 +``` + +--- + +## PSK Management + +### Generation Strategy + +```bash +# Generate PSK with high entropy +ostp-server gen-key > /secure/storage/psk-$(date +%Y%m%d).txt + +# Or use system random +xxd -p -l 32 /dev/urandom | tr -d '\n' +``` + +### Distribution Methods + +**Secure Channels:** +1. **Signal/Telegram Secret Chats** β€” End-to-end encrypted messaging +2. **PGP-Encrypted Email** β€” Encrypt PSK with user's public key +3. **Password Managers** β€” Share via 1Password/Bitwarden shared vaults +4. **QR Codes** β€” Generate QR codes for in-person distribution +5. **Hardware Tokens** β€” Store on encrypted USB drives + +**Never:** +- Send PSKs via unencrypted email +- Post PSKs in public forums or chat groups +- Store PSKs in version control +- Reuse PSKs across multiple users + +### Rotation Schedule + +| User Type | Rotation Frequency | Method | +|-----------|-------------------|---------| +| Individual | 90 days | Manual update | +| Corporate | 30 days | Automated push | +| High-Risk | 7 days | Dynamic generation | + +### Multi-PSK Architecture (Advanced) + +For large deployments, use separate PSKs per user group: + +```json +{ + "psk_groups": { + "premium_users": "a1b2c3...", + "trial_users": "d4e5f6...", + "enterprise": "g7h8i9..." + } +} +``` + +Requires custom `PskValidator` implementation in `ostp/src/crypto.rs`. + +--- + +## Monitoring & Alerting + +### Metrics to Track + +**Connection Metrics:** +- Active connections per minute +- Failed authentication attempts +- Average session duration +- Bandwidth per user + +**System Metrics:** +- CPU usage +- Memory usage +- Disk I/O +- Network throughput + +**Security Metrics:** +- Failed PSK validations +- Repeated connection attempts from same IP +- Unusual traffic patterns +- Anti-debug trigger counts + +### Logging Strategy + +**Log Levels by Environment:** +``` +Development: debug +Staging: info +Production: warn +High-Security: error only +``` + +**Log Aggregation:** +```bash +# Forward logs to central syslog server +sudo apt install -y rsyslog +echo "*.* @@log-server:514" >> /etc/rsyslog.conf +sudo systemctl restart rsyslog +``` + +**Log Retention:** +- Keep 30 days of detailed logs +- Archive 1 year of summarized logs +- Purge logs older than 1 year + +### Alerting Rules + +Set up alerts for: +- Server CPU >80% for 5 minutes +- Disk usage >90% +- Failed auth rate >100/minute (potential attack) +- Service downtime >1 minute +- Certificate expiration <30 days (if using real certs) + +--- + +## Backup & Disaster Recovery + +### Backup Strategy + +**Daily Backups:** +```bash +#!/bin/bash +# /usr/local/bin/ostp-backup.sh + +DATE=$(date +%Y%m%d-%H%M) +BACKUP_DIR=/backup/ostp + +# Backup user database +sqlite3 /var/lib/ostp/users.db ".backup '$BACKUP_DIR/users-$DATE.db'" + +# Backup configuration +cp /etc/ostp/server.json $BACKUP_DIR/config-$DATE.json + +# Compress and encrypt +tar czf - $BACKUP_DIR/*-$DATE.* | \ + gpg --encrypt --recipient admin@ospab.host > \ + $BACKUP_DIR/ostp-backup-$DATE.tar.gz.gpg + +# Upload to remote storage (S3, Backblaze, etc.) +aws s3 cp $BACKUP_DIR/ostp-backup-$DATE.tar.gz.gpg \ + s3://ostp-backups/ + +# Clean up old backups (keep 7 days) +find $BACKUP_DIR -mtime +7 -delete +``` + +**Crontab Entry:** +```bash +0 2 * * * /usr/local/bin/ostp-backup.sh +``` + +### Disaster Recovery Plan + +**RTO (Recovery Time Objective): 1 hour** +**RPO (Recovery Point Objective): 24 hours** + +1. **Server Failure:** + - Spin up new VPS from template + - Restore latest backup + - Update DNS records + - Notify users (if IP changed) + +2. **Database Corruption:** + - Stop ostp-server + - Restore from latest backup + - Verify data integrity + - Restart service + +3. **PSK Compromise:** + - Generate new PSK immediately + - Deploy to server + - Distribute to all users via secure channels + - Invalidate old PSK + +--- + +## Performance Optimization + +### Connection Limits + +Based on server specs: + +| RAM | CPU Cores | Max Connections | Notes | +|-----|-----------|----------------|-------| +| 1 GB | 1 core | 100 | Minimal | +| 2 GB | 2 cores | 500 | Recommended | +| 4 GB | 4 cores | 1000 | High capacity | +| 8 GB | 8 cores | 5000 | Enterprise | + +### Load Balancing + +For >1000 concurrent users: + +``` + [DNS Round-Robin] + ↓ + +-----------+-----------+ + ↓ ↓ ↓ +[OSTP Server 1] [Server 2] [Server 3] + ↓ ↓ ↓ + [Shared Database] +``` + +Use database replication (PostgreSQL) instead of SQLite for multi-server deployments. + +### Bandwidth Management + +```bash +# Rate limit per connection (Linux tc) +tc qdisc add dev eth0 root tbf rate 10mbit burst 32kbit latency 400ms + +# Or use iptables hashlimit +iptables -A INPUT -p tcp --dport 8443 \ + -m hashlimit --hashlimit-name ostp \ + --hashlimit-above 10/s --hashlimit-mode srcip \ + -j DROP +``` + +--- + +## Compliance & Legal + +### Data Retention Policies + +**Recommended Minimal Logging:** +- Do NOT log plaintext traffic content +- Do NOT log destination IPs +- Do log: connection timestamps, total bytes transferred, user IDs + +**Compliance Requirements:** +- GDPR (EU): User data deletion requests +- CCPA (California): Data access requests +- National regulations: Vary by jurisdiction + +### Privacy by Design + +1. **Minimize Data Collection:** Only collect necessary metadata +2. **Encrypt at Rest:** Database encryption for user data +3. **Anonymize Logs:** Hash IPs before storing +4. **Short Retention:** Delete logs after 30 days +5. **No Third Parties:** Never share user data + +### Warrant Canary (Optional) + +Create a `canary.txt` on your website: + +``` +As of January 1, 2026, OSTP has NOT received: +- National security letters +- Gag orders +- Warrants for user data +- Requests to install monitoring software + +This canary will be updated monthly. +``` + +If you receive a gag order, stop updating the canary (signals users). + +--- + +## Scaling Strategy + +### Phase 1: Single Server (0-500 users) +- 1 VPS with 2GB RAM +- SQLite database +- Direct client connections + +### Phase 2: Vertical Scaling (500-2000 users) +- Upgrade to 4GB RAM, 4 cores +- Optimize database indexes +- Add monitoring + +### Phase 3: Horizontal Scaling (2000+ users) +- Deploy multiple servers +- Shared PostgreSQL database with replication +- DNS-based load balancing +- Separate user database server + +### Phase 4: Global Infrastructure (10000+ users) +- Regional server clusters +- Geo-DNS routing +- CDN integration +- Dedicated DDoS protection + +--- + +## Cost Analysis + +### Single Server Monthly Costs + +| Provider | Specs | Price | Notes | +|----------|-------|-------|-------| +| Hetzner | 2GB RAM, 40GB SSD | $5 | Best value | +| DigitalOcean | 2GB RAM, 50GB SSD | $12 | Easy setup | +| Vultr | 2GB RAM, 55GB SSD | $12 | Global locations | +| AWS Lightsail | 2GB RAM, 60GB SSD | $12 | AWS ecosystem | + +**Additional Costs:** +- Domain name: $10-15/year +- Backup storage: $2-5/month +- Monitoring: $10-20/month (optional) +- DDoS protection: $20-100/month (if needed) + +**Revenue Model (Optional):** +- Free tier: 5GB/month +- Basic: $5/month (100GB) +- Premium: $15/month (unlimited) + +--- + +## Update Strategy + +### Binary Updates + +**Server Updates:** +```bash +# Download new version +wget https://releases.ospab.host/ostp-server-v2.0.0 + +# Backup current binary +cp /usr/local/bin/ostp-server /usr/local/bin/ostp-server.backup + +# Replace binary +mv ostp-server-v2.0.0 /usr/local/bin/ostp-server +chmod +x /usr/local/bin/ostp-server + +# Restart service +systemctl restart ostp-server + +# Verify version +ostp-server --version +``` + +**Client Updates:** +- Provide download link via secure channel +- Include SHA256 hash for verification +- Document breaking changes +- Maintain compatibility for 1 version back + +### Database Migrations + +For schema changes: + +```sql +-- Check current version +SELECT value FROM metadata WHERE key = 'schema_version'; + +-- Migrate v1 β†’ v2 +ALTER TABLE users ADD COLUMN last_seen DATETIME; +UPDATE metadata SET value = '2' WHERE key = 'schema_version'; +``` + +--- + +## Incident Response + +### Security Incident Playbook + +**1. Detection:** +- Monitor alerts for anomalies +- Investigate suspicious patterns +- Verify authenticity of alerts + +**2. Containment:** +- Isolate affected servers +- Block malicious IPs +- Rotate compromised PSKs +- Snapshot system state + +**3. Eradication:** +- Identify root cause +- Patch vulnerabilities +- Remove backdoors +- Reset credentials + +**4. Recovery:** +- Restore from clean backups +- Verify system integrity +- Monitor for reinfection +- Document timeline + +**5. Post-Mortem:** +- Write incident report +- Implement prevention measures +- Update documentation +- Notify affected users (if required) + +--- + +## Testing & Validation + +### Pre-Deployment Checklist + +- [ ] Server OS fully updated +- [ ] Firewall configured and tested +- [ ] OSTP server starts without errors +- [ ] PSK generated and secured +- [ ] Client successfully connects +- [ ] Traffic encrypted (verify with Wireshark) +- [ ] TLS mimicry working (check SNI) +- [ ] Anti-debug protection active (release build) +- [ ] Logs rotating correctly +- [ ] Backups automated and tested +- [ ] Monitoring alerts configured +- [ ] Documentation complete + +### Performance Testing + +```bash +# Simulate 100 concurrent connections +for i in {1..100}; do + ostp-client connect -s server:8443 -p $PSK -c US & +done + +# Monitor server resources +htop +iotop +nethogs +``` + +### Security Testing + +- **Port Scanning:** Verify only 8443 is open +- **DPI Testing:** Use GFW test tools to verify mimicry +- **Traffic Analysis:** Capture packets and analyze with Wireshark +- **Penetration Testing:** Hire professional auditors (recommended annually) + +--- + +## Advanced Configurations + +### Multi-Hop Routing + +Chain OSTP servers for enhanced anonymity: + +``` +[Client] β†’ [OSTP Server 1] β†’ [OSTP Server 2] β†’ [Internet] +``` + +Requires custom routing configuration. + +### Split Tunneling + +Route only specific traffic through VPN: + +```bash +# Route only HTTPS through VPN +ip route add 0.0.0.0/0 via 10.8.0.1 table 100 +ip rule add fwmark 1 table 100 +iptables -t mangle -A OUTPUT -p tcp --dport 443 -j MARK --set-mark 1 +``` + +### Bridge Mode + +Allow clients to access LAN resources: + +``` +[OSTP Client] ←→ [OSTP Server] ←→ [Corporate LAN] +``` + +Requires NAT and routing configuration on server. + +--- + +## Support & Maintenance + +### Regular Maintenance Tasks + +**Daily:** +- Check service status +- Review critical alerts +- Monitor disk space + +**Weekly:** +- Review security logs +- Check backup integrity +- Update block lists (if applicable) + +**Monthly:** +- Apply security updates +- Review user quotas +- Analyze performance metrics +- Test disaster recovery + +**Quarterly:** +- Rotate PSKs +- Audit user access +- Review documentation +- Plan capacity upgrades + +--- + +For additional guidance or enterprise support, contact ospab@ospab.host. + +*Last updated: January 2026* diff --git a/docs/SERVER.md b/docs/SERVER.md new file mode 100644 index 0000000..41995b2 --- /dev/null +++ b/docs/SERVER.md @@ -0,0 +1,379 @@ +# OSTP Server Configuration Guide + +Complete guide for deploying and configuring OSTP server on Linux systems. + +--- + +## System Requirements + +- **OS:** Linux kernel 3.10+ (Ubuntu 22.04+, Debian 11+, CentOS 8+) +- **Memory:** 512 MB minimum, 2 GB recommended for 100+ concurrent connections +- **Storage:** 1 GB for binaries and logs, additional space for user database +- **Network:** Public IPv4 address with TCP port 443 or 8443 available +- **Permissions:** Root or CAP_NET_ADMIN for TUN device creation + +--- + +## Installation + +### Binary Installation (Recommended) + +```bash +# Download release binary +wget https://github.com/ospab/ospab.network/releases/ostp-server-linux-x64.tar.gz + +# Extract and install +tar -xzf ostp-server-linux-x64.tar.gz +sudo mv ostp-server /usr/local/bin/ +sudo chmod +x /usr/local/bin/ostp-server + +# Verify installation +ostp-server --version +``` + +### Build from Source + +```bash +# Install Rust toolchain +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh + +# Clone repository (requires access) +git clone https://github.com/ospab/ospab.network.git +cd ospab.network + +# Build release binary +cargo build -p ostp-server --release + +# Install +sudo cp target/release/ostp-server /usr/local/bin/ +``` + +--- + +## Pre-Shared Key Generation + +Generate a cryptographically secure PSK: + +```bash +# Generate and display PSK +ostp-server gen-key + +# Save to environment variable +export OSTP_PSK=$(ostp-server gen-key) + +# Or save to file (secure permissions!) +ostp-server gen-key > /etc/ostp/server.psk +chmod 600 /etc/ostp/server.psk +``` + +**Security Note:** Never commit PSKs to version control. Each server should use a unique PSK shared only with authorized clients. + +--- + +## Configuration + +### Command-Line Mode + +```bash +# Minimal configuration +ostp-server -l 0.0.0.0:8443 -p + +# With logging +ostp-server -l 0.0.0.0:8443 -p $OSTP_PSK --log-level info + +# Custom database path +ostp-server -l 0.0.0.0:8443 -p $OSTP_PSK --db /var/lib/ostp/users.db +``` + +### Configuration File Mode + +Create `/etc/ostp/server.json`: + +```json +{ + "listen_addr": "0.0.0.0:8443", + "psk": "a1b2c3d4e5f6...", + "database_path": "/var/lib/ostp/users.db", + "log_level": "info", + "max_connections": 1000, + "session_timeout_secs": 3600, + "tun_device": "ostp0", + "tun_ip": "10.8.0.1", + "tun_netmask": "255.255.255.0", + "dns_servers": ["1.1.1.1", "1.0.0.1"] +} +``` + +Run with config file: + +```bash +ostp-server -c /etc/ostp/server.json +``` + +--- + +## Systemd Service + +Create `/etc/systemd/system/ostp-server.service`: + +```ini +[Unit] +Description=OSTP Stealth VPN Server +After=network.target + +[Service] +Type=simple +User=root +ExecStart=/usr/local/bin/ostp-server -c /etc/ostp/server.json +Restart=on-failure +RestartSec=10s + +# Security hardening +NoNewPrivileges=true +PrivateTmp=true +ProtectSystem=strict +ProtectHome=true +ReadWritePaths=/var/lib/ostp /var/log/ostp + +# Resource limits +LimitNOFILE=65536 +TasksMax=4096 + +[Install] +WantedBy=multi-user.target +``` + +Enable and start: + +```bash +sudo systemctl daemon-reload +sudo systemctl enable ostp-server +sudo systemctl start ostp-server +sudo systemctl status ostp-server +``` + +--- + +## Firewall Configuration + +### UFW (Ubuntu/Debian) + +```bash +sudo ufw allow 8443/tcp comment 'OSTP Server' +sudo ufw reload +``` + +### firewalld (CentOS/RHEL) + +```bash +sudo firewall-cmd --permanent --add-port=8443/tcp +sudo firewall-cmd --reload +``` + +### iptables (Manual) + +```bash +sudo iptables -A INPUT -p tcp --dport 8443 -j ACCEPT +sudo iptables-save > /etc/iptables/rules.v4 +``` + +--- + +## User Management + +### Add User + +```bash +# Using SQLite directly +sqlite3 /var/lib/ostp/users.db << EOF +INSERT INTO users (username, quota_gb, expiry_date) +VALUES ('john_doe', 100, '2026-12-31'); +EOF +``` + +### Check Active Sessions + +```bash +# View logs for session info +tail -f /var/log/ostp/server.log | grep SESSION_START +``` + +### Reset User Quota + +```bash +sqlite3 /var/lib/ostp/users.db << EOF +UPDATE users SET used_gb = 0 WHERE username = 'john_doe'; +EOF +``` + +--- + +## Monitoring & Logging + +### Log Levels + +- `error` β€” Critical errors only +- `warn` β€” Warnings and errors +- `info` β€” General operation info (recommended) +- `debug` β€” Detailed debugging (high volume) +- `trace` β€” Very verbose (development only) + +### Log Rotation + +Create `/etc/logrotate.d/ostp`: + +``` +/var/log/ostp/*.log { + daily + rotate 7 + compress + delaycompress + missingok + notifempty + create 0640 root root + sharedscripts + postrotate + systemctl reload ostp-server > /dev/null 2>&1 || true + endscript +} +``` + +--- + +## Performance Tuning + +### Kernel Parameters + +Add to `/etc/sysctl.conf`: + +```ini +# Increase connection backlog +net.core.somaxconn = 4096 +net.core.netdev_max_backlog = 5000 + +# Enable TCP Fast Open +net.ipv4.tcp_fastopen = 3 + +# Increase ephemeral ports +net.ipv4.ip_local_port_range = 10000 65535 + +# Enable IP forwarding +net.ipv4.ip_forward = 1 +``` + +Apply changes: + +```bash +sudo sysctl -p +``` + +### File Descriptor Limits + +Edit `/etc/security/limits.conf`: + +``` +root soft nofile 65536 +root hard nofile 65536 +``` + +--- + +## Troubleshooting + +### Server Won't Start + +```bash +# Check if port is already in use +sudo netstat -tulpn | grep 8443 + +# Check file permissions +ls -la /etc/ostp/server.json +ls -la /var/lib/ostp/users.db + +# Check logs for specific error +journalctl -u ostp-server -n 50 +``` + +### No Client Connections + +```bash +# Verify firewall allows port +sudo iptables -L -n | grep 8443 + +# Test connectivity from client +telnet server_ip 8443 + +# Check PSK matches between client and server +``` + +### High CPU Usage + +```bash +# Check number of connections +ss -tn state established '( dport = :8443 )' | wc -l + +# Monitor CPU usage +top -p $(pgrep ostp-server) + +# Consider lowering log level to 'warn' +``` + +--- + +## Security Best Practices + +1. **Change Default Port:** Use port 443 instead of 8443 to blend with HTTPS traffic +2. **Rotate PSKs:** Change PSKs every 90 days and distribute to clients securely +3. **Limit Connections:** Set `max_connections` based on server capacity +4. **Monitor Logs:** Set up alerts for suspicious patterns or failed authentications +5. **Update Regularly:** Keep server binary updated with latest security patches +6. **Use Strong PSKs:** Always generate PSKs using `ostp-server gen-key` +7. **Separate Databases:** Use separate user databases for different client groups + +--- + +## Backup & Recovery + +### Backup User Database + +```bash +# Create backup +sqlite3 /var/lib/ostp/users.db ".backup '/backup/users-$(date +%Y%m%d).db'" + +# Or simple file copy +cp /var/lib/ostp/users.db /backup/users-$(date +%Y%m%d).db +``` + +### Restore from Backup + +```bash +systemctl stop ostp-server +cp /backup/users-20260101.db /var/lib/ostp/users.db +systemctl start ostp-server +``` + +--- + +## Command Reference + +| Command | Description | +|---------|-------------| +| `ostp-server gen-key` | Generate new PSK | +| `ostp-server -l ` | Set listen address | +| `ostp-server -p ` | Set pre-shared key | +| `ostp-server -c ` | Use config file | +| `ostp-server --log-level ` | Set log verbosity | +| `ostp-server --version` | Show version info | +| `ostp-server --help` | Display help | + +--- + +## Support + +For technical support or licensing inquiries: +- **Email:** ospab@ospab.host +- **Documentation:** See additional guides in `docs/` + +--- + +*Last updated: January 2026*