ECH — sing-box

sing-box 在 tls: 块的嵌套子块中实现 ECH 两端。结构体共享了 TLS 1.3 草案时期遗留的两个 PQ 签名相关开关 —— 二者在当前版本中都无效。

入站 tls.ech

字段	类型	默认值	允许值	描述
enabled	bool	false	true | false	启用该入站的 ECH。
key	badoption.Listable[string]	[]	<base64 ECH key>	内联 ECH 密钥包。接受单字符串或字符串列表（每条目一个 PEM 风格块）。
key_path	string	(unset)	<file path>	ECH 密钥包文件路径。与 `key` 互斥。
pq_signature_schemes_enabled	bool	false	true | false	已弃用。Go 标准库不支持后量子签名方案。
dynamic_record_sizing_disabled	bool	false	true | false	已弃用。设置后即便在支持时也没有效果。

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

出站 tls.ech

字段	类型	默认值	允许值	描述
enabled	bool	false	true | false	启用该出站的 ECH。
config	badoption.Listable[string]	[]	<base64 ECHConfigList>	锚定的 ECH 配置列表。未设置时 sing-box 通过 HTTPS DNS 记录自动发现。
config_path	string	(unset)	<file path>	锚定配置的路径形式。
query_server_name	string	(server_name)	<hostname>	ECH 自动发现时用于查询 HTTPS 记录的主机名。默认为出站的 `tls.server_name`。
pq_signature_schemes_enabled	bool	false	true | false	已弃用。
dynamic_record_sizing_disabled	bool	false	true | false	已弃用。

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

示例

入站 —— 用密钥文件提供 ECH：

{
  "inbounds": [{
    "type": "vless",
    "listen_port": 443,
    "users": [{ "uuid": "..." }],
    "tls": {
      "enabled": true,
      "server_name": "example.com",
      "certificate_path": "/etc/ssl/cert.pem",
      "key_path": "/etc/ssl/key.pem",
      "ech": {
        "enabled": true,
        "key_path": "/etc/sing-box/ech.key"
      }
    }
  }]
}

出站 —— 机会性 ECH（自动发现）：

{
  "outbounds": [{
    "type": "vless",
    "server": "example.com",
    "server_port": 443,
    "uuid": "...",
    "tls": {
      "enabled": true,
      "server_name": "example.com",
      "ech": { "enabled": true }
    }
  }]
}

出站 —— 锚定的 ECH 配置：

{
  "outbounds": [{
    "type": "vless",
    "server": "example.com",
    "server_port": 443,
    "uuid": "...",
    "tls": {
      "enabled": true,
      "server_name": "example.com",
      "ech": {
        "enabled": true,
        "config": ["<base64 ECHConfigList>"],
        "query_server_name": "cover.example.com"
      }
    }
  }]
}

说明

• ECH 要求 TLS 1.3。如需强制，请设置 tls.min_version: "1.3"； 在 1.2 上 ECH 扩展会被静默丢弃。
• 入站 key 字段接受列表，便于运营者轮换 ECH 密钥 —— 将新旧密钥 并列让带缓存 HKDF 状态的客户端完成最后几个请求后再切换。
• 自动发现（出站 enabled: true 且 config 为空）会查询 query_server_name（或 tls.server_name，若未覆盖）的 HTTPS DNS 记录。解析器链遵循标准的 sing-box DNS 配置。
• 两个已弃用字段（pq_signature_schemes_enabled、 dynamic_record_sizing_disabled）保留是为兼容解析，运行时无效果 —— 现有配置中可以删除。

跨内核说明

• Xray-core 把 ECH 作为 tlsSettings 上的四个直接字段，而非 子块。参见 ECH — Xray-core。
• mihomo 在每个 proxy 上使用 ech-opts 块，含三个用户可见字段 （enable、config、query-server-name）。参见 ECH — mihomo。

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