singboxer/references/ref-tls-transport.md

# sing-box TLS & Transport Reference

## TLS Outbound (Client)

```json
{
  "tls": {
    "enabled": true,
    "disable_sni": false,
    "server_name": "example.com",
    "insecure": false,
    "alpn": ["h2", "http/1.1"],
    "min_version": "1.2",
    "max_version": "1.3",
    "cipher_suites": [],
    "certificate": [],
    "certificate_path": "",

    // uTLS fingerprinting
    "utls": {
      "enabled": true,
      "fingerprint": "chrome"
    },

    // Reality protocol
    "reality": {
      "enabled": true,
      "public_key": "public-key",
      "short_id": "short-id"
    },

    // Encrypted Client Hello
    "ech": {
      "enabled": true,
      "pq_signature_schemes_enabled": false,
      "dynamic_record_sizing_disabled": false,
      "config": [],
      "config_path": ""
    }
  }
}
```

### uTLS Fingerprints

| Fingerprint | Description |
|-------------|-------------|
| `chrome` | Latest Chrome (recommended) |
| `firefox` | Latest Firefox |
| `safari` | Latest Safari |
| `edge` | Latest Edge |
| `ios` | iOS Safari |
| `android` | Android Chrome |
| `random` | Random from all |
| `randomized` | Randomized parameters |
| `chrome_auto` | Auto-update Chrome |
| `360_auto` | 360 Browser |
| `qq_auto` | QQ Browser |

## TLS Inbound (Server)

```json
{
  "tls": {
    "enabled": true,
    "server_name": "example.com",
    "alpn": ["h2", "http/1.1"],
    "min_version": "1.2",
    "max_version": "1.3",
    "cipher_suites": [],
    "certificate": [],
    "certificate_path": "/path/to/cert.pem",
    "key": [],
    "key_path": "/path/to/key.pem",

    // Client certificate auth
    "client_auth": {
      "enabled": true,
      "mode": "require-and-verify",
      "certificate": [],
      "certificate_path": ""
    },

    // Reality server
    "reality": {
      "enabled": true,
      "private_key": "private-key",
      "short_id": ["short-id"],
      "handshake": {
        "server": "www.microsoft.com",
        "server_port": 443
      },
      "max_time_difference": "1m"
    },

    // ECH server
    "ech": {
      "enabled": true,
      "pq_signature_schemes_enabled": false,
      "dynamic_record_sizing_disabled": false,
      "key": [],
      "key_path": ""
    },

    // Kernel TLS (Linux 5.1+)
    "kernel_tx": false,
    "kernel_rx": false
  }
}
```

### Client Auth Modes
- `no` — No client certificate required
- `request` — Request but don't require
- `require-any` — Require any client certificate
- `verify-if-given` — Verify only if provided
- `require-and-verify` — Require and verify against CA

### Reality Key Generation
```bash
sing-box generate reality-keypair
# Output:
# PrivateKey: xxxx
# PublicKey: xxxx
```

## V2Ray Transport Layer

Supported by: VMess, VLESS, Trojan

### HTTP Transport
```json
{
  "transport": {
    "type": "http",
    "host": ["example.com"],
    "path": "/",
    "method": "PUT",
    "headers": {
      "X-Custom": ["value"]
    },
    "idle_timeout": "15s",
    "ping_timeout": "15s"
  }
}
```

### WebSocket Transport
```json
{
  "transport": {
    "type": "ws",
    "path": "/ws-path",
    "headers": {
      "Host": "example.com"
    },
    "max_early_data": 2048,
    "early_data_header_name": "Sec-WebSocket-Protocol"
  }
}
```

### gRPC Transport
```json
{
  "transport": {
    "type": "grpc",
    "service_name": "GunService",
    "idle_timeout": "15s",
    "ping_timeout": "15s",
    "permit_without_stream": false
  }
}
```

### QUIC Transport
```json
{
  "transport": {
    "type": "quic"
  }
}
```

### HTTPUpgrade Transport
```json
{
  "transport": {
    "type": "httpupgrade",
    "host": "example.com",
    "path": "/upgrade-path",
    "headers": {
      "X-Custom": ["value"]
    }
  }
}
```

## Anti-Censorship Techniques

### TLS Fragment (in route rule action)
Splits TLS ClientHello into small fragments to evade DPI:
```json
{
  "action": "route",
  "outbound": "direct",
  "tls_fragment": {
    "enabled": true,
    "size": "1-5",
    "sleep": "10-20",
    "fallback_delay": "300ms"
  }
}
```
- `size`: Fragment size range (bytes)
- `sleep`: Delay between fragments (ms)
- Only works with TCP, mutually exclusive with `tls_record_fragment`

### TLS Record Fragment (in route rule action)
Splits TLS records into smaller records:
```json
{
  "action": "route",
  "outbound": "direct",
  "tls_record_fragment": {
    "enabled": true,
    "size": "100-200"
  }
}
```
- Lower overhead than TLS fragment
- Mutually exclusive with `tls_fragment`

### VLESS + Reality (anti-probing)
Makes the server look like a legitimate website:
```json
{
  "inbounds": [{
    "type": "vless",
    "listen_port": 443,
    "users": [{ "uuid": "...", "flow": "xtls-rprx-vision" }],
    "tls": {
      "enabled": true,
      "reality": {
        "enabled": true,
        "private_key": "...",
        "short_id": ["abcd1234"],
        "handshake": {
          "server": "www.microsoft.com",
          "server_port": 443
        }
      }
    }
  }]
}
```

### ShadowTLS v3 + Shadowsocks (stealth)
Traffic looks like normal TLS to a legitimate site:
```json
{
  "inbounds": [{
    "type": "shadowtls",
    "listen_port": 443,
    "version": 3,
    "users": [{ "name": "user1", "password": "stls-pass" }],
    "handshake": {
      "server": "www.google.com",
      "server_port": 443
    },
    "handshake_for_server_name": {
      "www.google.com": {
        "server": "www.google.com",
        "server_port": 443
      }
    },
    "detour": "ss-in"
  }],
  "outbounds": [...]
}
```

### Hysteria2 + Salamander Obfuscation
```json
{
  "type": "hysteria2",
  "obfs": {
    "type": "salamander",
    "password": "obfs-password"
  }
}
```

## CDN-Compatible Transports

For routing through CDN (Cloudflare, etc.):
- **WebSocket** (`ws`) — most widely supported
- **gRPC** — good CDN support, efficient
- **HTTPUpgrade** — lightweight alternative to WebSocket

Example: VLESS + WebSocket behind CDN:
```json
{
  "type": "vless",
  "server": "cdn-domain.example.com",
  "server_port": 443,
  "uuid": "...",
  "tls": {
    "enabled": true,
    "server_name": "cdn-domain.example.com"
  },
  "transport": {
    "type": "ws",
    "path": "/vless-ws",
    "headers": {
      "Host": "cdn-domain.example.com"
    }
  }
}
```