TLS — sing-box

每个 sing-box 入站与出站都通过 InboundTLSOptionsContainer / OutboundTLSOptionsContainer 内嵌一个 tls: { ... } 块。同一个块以嵌套子块形式承载 REALITY、ECH 与 uTLS —— 它们不是独立的顶层功能。

入站 `tls`

字段	类型	默认值	允许值	描述
`enabled`	`bool`	`false`	`true \| false`	总开关。为 false 时块内其他字段被忽略。
`server_name`	`string`	`(inferred from SNI)`	`<hostname>`	ACME 签发使用的期望服务器名。若设置了 `acme` 则必填。
`insecure`	`bool`	`false`	`true \| false`	跳过 TLS 校验。仅供测试。
`alpn`	`badoption.Listable[string]`	`[]`	`<ALPN string>`	向客户端宣告的 ALPN 列表。
`min_version`	`string`	`1.2`	`1.0 \| 1.1 \| 1.2 \| 1.3`	可接受的最低 TLS 版本。
`max_version`	`string`	`1.3`	`1.0 \| 1.1 \| 1.2 \| 1.3`	可接受的最高 TLS 版本。
`cipher_suites`	`badoption.Listable[string]`	`(library default)`	`<cipher>`	覆盖加密套件列表（仅 TLS 1.2）。
`curve_preferences`	`badoption.Listable[CurvePreference]`	`(library default)`	`P256 \| P384 \| P521 \| X25519 \| X25519MLKEM768`	密钥交换曲线偏好列表。
`certificate`	`badoption.Listable[string]`	`[]`	`<PEM block>`	内联服务器证书 PEM。列表形式可承载完整证书链。
`certificate_path`	`string`	`(unset)`	`<PEM file path>`	服务端证书文件路径。
`client_authentication`	`ClientAuthType`	`no`	`no \| request \| require-any \| verify-if-given \| require-and-verify`	mTLS 客户端鉴权策略。映射到 crypto/tls 的 ClientAuthType 值。
`client_certificate`	`badoption.Listable[string]`	`[]`	`<PEM block>`	受信客户端证书根（mTLS）。
`client_certificate_path`	`badoption.Listable[string]`	`[]`	`<PEM file path>`	客户端受信根的路径形式。
`client_certificate_public_key_sha256`	`badoption.Listable[[]byte]`	`[]`	`<SHA-256 bytes>`	按公钥 SHA-256 锚定客户端证书。用于一次性发放客户端证书的场景。
`key`	`badoption.Listable[string]`	`[]`	`<PEM block>`	内联服务端私钥。
`key_path`	`string`	`(unset)`	`<file path>`	服务端私钥文件路径。
`kernel_tx`	`bool`	`false`	`true \| false`	Linux KTLS —— 把出站流量的 TLS 加密下沉到内核。需要内核 TLS 支持与对应的加密模块。
`kernel_rx`	`bool`	`false`	`true \| false`	入站流量的 Linux KTLS。
`acme`	`*InboundACMEOptions`	`(unset)`	`InboundACMEOptions`	自动 Let's Encrypt 证书签发。与显式 `certificate` / `key` 互斥。
`ech`	`*InboundECHOptions`	`(unset)`	`InboundECHOptions`	Encrypted Client Hello 配置。
`reality`	`*InboundRealityOptions`	`(unset)`	`InboundRealityOptions`	REALITY 服务端配置。与普通 TLS 互斥 —— REALITY 替换 TLS 握手。

源码： option/tls.go:12-34 · 锚定版本 v1.13.11 (553cfa1)

出站 `tls`

字段	类型	默认值	允许值	描述
`enabled`	`bool`	`false`	`true \| false`	总开关。
`disable_sni`	`bool`	`false`	`true \| false`	完全省略 ClientHello 中的 SNI 扩展。
`server_name`	`string`	`(server address)`	`<hostname>`	发送给服务器的 SNI，并据此校验 leaf 证书名称。
`insecure`	`bool`	`false`	`true \| false`	跳过服务端证书校验。
`alpn`	`badoption.Listable[string]`	`[]`	`<ALPN string>`	向服务器宣告的 ALPN 列表。
`min_version`	`string`	`1.2`	`1.0 \| 1.1 \| 1.2 \| 1.3`	可接受的最低 TLS 版本。
`max_version`	`string`	`1.3`	`1.0 \| 1.1 \| 1.2 \| 1.3`	可接受的最高 TLS 版本。
`cipher_suites`	`badoption.Listable[string]`	`(library default)`	`<cipher>`	覆盖加密套件列表。
`curve_preferences`	`badoption.Listable[CurvePreference]`	`(library default)`	`<see inbound>`	密钥交换曲线偏好。
`certificate`	`badoption.Listable[string]`	`[]`	`<PEM block>`	附加到系统根证书的受信 CA。配合 `insecure: false` 接受自签服务器。
`certificate_path`	`string`	`(unset)`	`<file path>`	受信 CA 的路径形式。
`certificate_public_key_sha256`	`badoption.Listable[[]byte]`	`[]`	`<SHA-256 bytes>`	按公钥 SHA-256 锚定服务端证书。
`client_certificate`	`badoption.Listable[string]`	`[]`	`<PEM block>`	客户端证书（mTLS）。
`client_certificate_path`	`string`	`(unset)`	`<file path>`	客户端证书的路径形式。
`client_key`	`badoption.Listable[string]`	`[]`	`<PEM block>`	客户端私钥。
`client_key_path`	`string`	`(unset)`	`<file path>`	客户端私钥的路径形式。
`fragment`	`bool`	`false`	`true \| false`	TCP 层握手分片。把 ClientHello 拆到多个包以规避 SNI DPI。
`fragment_fallback_delay`	`badoption.Duration`	`500ms`	`<duration>`	分片握手未在该期限内完成时，回退到不分片重试。
`record_fragment`	`bool`	`false`	`true \| false`	TLS 记录层分片（比 `fragment` 更激进 —— 在 TLS 记录流内部拆，而不仅是 TCP 包）。
`kernel_tx`	`bool`	`false`	`true \| false`	出站流量的 Linux KTLS。
`kernel_rx`	`bool`	`false`	`true \| false`	入站流量的 Linux KTLS。
`ech`	`*OutboundECHOptions`	`(unset)`	`OutboundECHOptions`	ECH 配置。未设置时不使用（除非通过 HTTPS 记录自动发现）。
`utls`	`*OutboundUTLSOptions`	`(unset)`	`OutboundUTLSOptions`	uTLS ClientHello 模拟。
`reality`	`*OutboundRealityOptions`	`(unset)`	`OutboundRealityOptions`	REALITY 客户端配置。与普通 TLS 互斥。

源码： option/tls.go:97-122 · 锚定版本 v1.13.11 (553cfa1)

`utls`

字段	类型	默认值	允许值	描述
`enabled`	`bool`	`false`	`true \| false`	启用 uTLS。
`fingerprint`	`string`	`chrome`	`chrome \| firefox \| safari \| ios \| android \| edge \| 360 \| qq \| random \| randomized`	要模拟的浏览器指纹。决定整个 ClientHello（加密套件、扩展、签名算法）。

源码： option/tls.go:229-232 · 锚定版本 v1.13.11 (553cfa1)

示例

启用 ACME 签发的入站：

json

{
  "inbounds": [{
    "type": "vless",
    "listen_port": 443,
    "users": [{ "uuid": "..." }],
    "tls": {
      "enabled": true,
      "server_name": "example.com",
      "alpn": ["h2", "http/1.1"],
      "acme": {
        "domain": ["example.com"],
        "email": "admin@example.com"
      }
    }
  }]
}

带 uTLS chrome 指纹与 TCP 分片 SNI 隐藏的出站：

json

{
  "outbounds": [{
    "type": "vless",
    "server": "example.com",
    "server_port": 443,
    "uuid": "...",
    "tls": {
      "enabled": true,
      "server_name": "example.com",
      "utls": { "enabled": true, "fingerprint": "chrome" },
      "fragment": true,
      "fragment_fallback_delay": "500ms"
    }
  }]
}

双向 TLS —— 服务端要求客户端证书：

json

{
  "inbounds": [{
    "type": "http",
    "listen_port": 8443,
    "tls": {
      "enabled": true,
      "certificate_path": "/etc/ssl/cert.pem",
      "key_path": "/etc/ssl/key.pem",
      "client_authentication": "require-and-verify",
      "client_certificate_path": ["/etc/ssl/clients-ca.pem"]
    }
  }]
}

说明

client_authentication 的五个值直接映射到 Go 的 crypto/tls.ClientAuthType：
- no —— 不要求客户端证书（默认）。
- request —— 请求一个，没有也接受。
- require-any —— 必须有但不校验。
- verify-if-given —— 提供则校验。
- require-and-verify —— 严格 mTLS。
fragment 与 record_fragment 是两个不同层：
- fragment 拆 TCP 包（承载 TLS 握手）。
- record_fragment 拆 TLS 记录本身（Handshake 记录被切成多个小片）。先用 fragment；仅当基于 SNI 的 DPI 仍能识别时再启用 record_fragment。
kernel_tx / kernel_rx 为 AES-GCM 与 CHACHA20-POLY1305 启用 Linux KTLS。内核需加载 tls 模块和正确的加密模块。
acme 与显式 certificate / key 互斥。使用 ACME 时 sing-box 会调用内嵌的 autocert 客户端 —— ACME provider 选项见上游文档。
REALITY（reality 子块）完全替换 TLS 握手 —— 见 REALITY — sing-box。
ECH（ech 子块）挂在同一握手内 —— 见 ECH — sing-box。

跨内核说明

Xray-core 使用 streamSettings.tlsSettings 而非内嵌 tls 块。字段名为 camelCase（serverName、cipherSuites）；uTLS 指纹是顶层字段而非子块。参见 TLS — Xray-core。
mihomo 没有集中化 TLS 块 —— 每个 proxy 适配器把 TLS 字段直接内联（tls、sni、alpn、skip-cert-verify 等）。参见 TLS — mihomo。

源码： option/tls.go:12-232 · v1.13.11 (553cfa1)

TLS — sing-box ​

入站 tls ​

出站 tls ​

utls ​

示例 ​

说明 ​

跨内核说明 ​

TLS — sing-box

入站 `tls`

出站 `tls`

`utls`

示例

说明

跨内核说明