Skip to content
English下载

TLS ​

TLS 设置属于每个代理,写在 tls 内联表里:

toml
[[proxy]]
name = "office-tls"
type = "http"
server = "proxy.example.org"
port = 8443
tls = { server-name = "proxy.example.org" }

这张表要写在一行里。写成 [proxy.tls] 表头会报错 tls must be an inline table。

什么时候开启 TLS ​

协议TLS
trojan、anytls、hysteria2、tuic始终开启。没有 tls 表时按默认设置使用 TLS;enabled = false 会被忽略并告警
http、socks5、vmess、vless有 tls 表就开启,没有就关闭
ss不允许。任何 TLS 设置都会让整个配置被拒绝,只容许 tls = { enabled = false }

只要写了 tls 表,TLS 就会开启:表一出现,enabled 默认就是 true。tls = {} 是合法的, 意思是「按默认设置使用 TLS」。

字段 ​

字段别名默认取值
enabledenabletruefalse 对 http、socks5、vmess、vless 关闭 TLS。为 false 时不能再写其他 TLS 字段
server-namesni、server_name代理的 server作为 SNI 发送,并用来校验证书
alpn—无字符串或字符串数组。只用于 vmess、vless、trojan、tuic,见 ALPN
skip-cert-verifyinsecure、skip_cert_verifyfalsetrue 接受任何证书,仅用于测试
certificate—无PEM 文本,或按行拆开的数组(会用换行拼接):要信任的 CA 证书
certificate-pathcertificate_path无包含要信任的 CA 证书的 PEM 文件路径
reality—无内联表,见 Reality

字段和别名同时出现时,以上表中排在前面的名字为准(server-name 优先于 sni)。tls 里的其他字段 会被直接忽略,没有提示;被拒绝的字段除外。

服务器名与证书校验 ​

  • 不写 server-name 时,Specola 把代理的 server 作为 SNI 发送,并用它校验证书。
  • 服务器名是 IP 地址时不发送 SNI,证书必须是签发给这个 IP 地址的。
  • 证书签发的名称和 server 不一样时(例如 server 写的是 IP 或 CDN 地址),请设置 server-name。

信任的证书 ​

默认情况下,Specola 信任操作系统的根证书。certificate 和 certificate-path 会为这个代理替换 系统根证书:只信任你给出的证书。

toml
[[proxy]]
name = "lab-ca"
type = "trojan"
server = "proxy.example.org"
port = 443
password = "change-me"
tls = { server-name = "proxy.example.org", certificate = """
-----BEGIN CERTIFICATE-----
...你的 CA 证书...
-----END CERTIFICATE-----
""" }

上面是片段:请把占位内容换成真正的 PEM 证书。

  • 两者都写时使用 certificate-path,忽略 certificate。
  • 加载配置时 certificate-path 指向的文件必须存在,否则整个配置被拒绝,报错 tls.certificate-path file does not exist; tried ...。相对路径按以下顺序查找:配置文件所在目录、 数据目录、Specola 可执行文件旁边的 resources。绝对路径不存在时,Specola 还会在数据目录和 resources 里找同名文件。
  • skip-cert-verify = true 会关闭所有校验,包括名称校验。此时你和服务器之间的任何人都能读到流量。 用它确认故障是证书问题之后,请去修证书。

数据目录在 Windows 上是 %LOCALAPPDATA%\Specola(以服务运行时为 %ProgramData%\Specola), macOS 上是 ~/Library/Application Support/com.specola.Specola,Linux 上是 ~/.config/specola。

ALPN ​

只有 vmess、vless、trojan、tuic 能写 alpn。在 http、socks5、anytls、hysteria2 上写 alpn 会让整个配置被拒绝。

协议不写 alpn 时
trojan提供 h2 和 http/1.1
tuic什么都不提供。大多数服务端要求 alpn = ["h3"]
vmess、vlessraw 下不提供;ws、http、httpupgrade 传输层下为 http/1.1;grpc 下为 h2
hysteria2固定为 h3(不可配置)

VMess 或 VLESS 配了传输层时,自己写的 alpn 必须包含该传输层需要的协议(http/1.1,gRPC 为 h2), 否则配置能加载,但每条连接都会失败。见传输层。

Reality ​

Reality 是 tls 里面的一张内联表,可用于 vless、http、socks5。

toml
[[proxy]]
name = "vless-reality"
type = "vless"
server = "proxy.example.org"
port = 443
uuid = "b1479ae4-f64b-4b27-bdab-4fb0f4ecdba9"
flow = "xtls-rprx-vision"
tls = { server-name = "www.example.com", reality = { enabled = true, public-key = "public-key-from-your-server", short-id = "0123456789abcdef" } }
字段别名默认取值
enabledenablefalse必须写 true 才会使用 Reality
public-keypublic_key无服务端公钥;enabled = true 时必填
short-idshort_id无一个 short ID,字符串或只有一个元素的数组

加载时会检查:

  • 和 tls 不同,reality 表不会自动开启。写了 public-key 或 short-id 却没写 enabled = true,会报错 Reality fields require reality.enabled=true。
  • enabled = true 但没有 public-key,被拒绝。
  • 写了多个 short-id,被拒绝:客户端只发送一个。
  • Reality 需要 TLS 开启:tls.enabled = false 再配 Reality 会被拒绝。
  • 其他协议上配 Reality 会报错 Reality is not supported by this protocol。
  • server-name 填服务端伪装的那个网站,与服务端配置一致。
  • VLESS 使用 Reality 时,传输层只能是 raw 或 grpc。配其他传输层能加载,但连接会失败。
  • private-key、handshake、max-time-difference 是服务端设置,写了会被拒绝。

被拒绝的字段 ​

以下字段能被识别,但不支持。写了其中任何一个,整个配置被拒绝,报错 TLS field '<key>' is not supported:

min-version、max-version、cipher-suites、curve-preferences、fingerprint、 client-authentication、client-certificate、client-certificate-path、 client-certificate-public-key-sha256、key、key-path、kernel-tx、kernel-rx、 handshake-timeout、certificate-provider、acme、ech、reality.private-key、 reality.handshake、reality.max-time-difference。

它们的下划线写法(min_version)同样被拒绝。因此客户端证书(双向 TLS)和 TLS 指纹伪装都不可用。

写在 tls 外面的旧字段 ​

直接写在代理里、tls 外面的 sni、alpn、skip-cert-verify、certificate、certificate-path、 fingerprint 会被忽略并告警。请把它们移进 tls 表。见 代理。

排错 ​

  1. 证书校验失败:证书不是签发给 server-name 的,或者签发它的 CA 系统不信任。设置 server-name, 或在 certificate / certificate-path 里给出 CA。
  2. 只有开了 skip-cert-verify 才能用:原因同上。注意 certificate 会替换系统根证书, 同时配了私有 CA 时,公共证书反而会校验失败。
  3. alpn 被拒绝:这个协议不接受 ALPN,删掉即可。
  4. Reality 被拒绝:补上 enabled = true 和 public-key,只保留一个 short-id。
  5. TUIC 握手失败:加上 alpn = ["h3"]。

另见代理和传输层。