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:

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

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

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