ospab.network/docs/CLIENT.md

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:

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:

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

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

# List available profiles
ostp-client profiles

# Connect using profile
ostp-client connect --profile Russia-VPN

# Connect using default profile
ostp-client connect

Direct Connection

# Connect with explicit parameters
ostp-client connect -s 1.2.3.4:8443 -p <hex-psk> -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

ostp-client setup

List Profiles

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

ostp-client connect --profile Russia-VPN --dns 1.1.1.1,1.0.0.1

Verbose Logging

ostp-client connect --profile Russia-VPN --log-level debug

Background Mode (Experimental)

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:

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:

del /Q %APPDATA%\ostp\profiles.json
ostp-client setup

---

PSK Security

Obtaining PSK

PSKs are generated by server administrators using:

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 <name>	Connect using named profile
ostp-client connect -s <addr> -p <psk> -c <country>	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:

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