singboxer/references/ref-tls-transport.md

sing-box TLS & Transport Reference

TLS Outbound (Client)

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

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

sing-box generate reality-keypair
# Output:
# PrivateKey: xxxx
# PublicKey: xxxx

V2Ray Transport Layer

Supported by: VMess, VLESS, Trojan

HTTP Transport

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

WebSocket Transport

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

gRPC Transport

{
  "transport": {
    "type": "grpc",
    "service_name": "GunService",
    "idle_timeout": "15s",
    "ping_timeout": "15s",
    "permit_without_stream": false
  }
}

QUIC Transport

{
  "transport": {
    "type": "quic"
  }
}

HTTPUpgrade Transport

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

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

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

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

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

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

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