---
url: /configuration/shared/tls-client.md
description: 出站、DNS 和下载共用的 TLS 客户端引擎、信任、证书和伪装字段
---

# TLS 客户端

所有主动讲 TLS 的共享写法。统一的是配置语法；每个使用者和平台支持的子集不同。

```yaml check
dns:
  servers:
    secure:
      type: tls
      address: 127.0.0.1:853
      tls:
        server_name: dns.example
  final: secure
```

## 字段

### engine

* 类型：字符串枚举。
* 默认：`boringssl`。
* 取值：`boringssl`、`cronet`。
* 限制：需要对应平台或构建；DNS 的 QUIC/H3 固定 rustls。

### fingerprint

* 类型：字符串枚举。
* 默认：`chrome`。
* 取值：当前只实现 `chrome`。

### server_name

* 类型：字符串。
* 默认：服务器地址中的主机名或 IP。
* 行为：作为 SNI 发出，并默认作为证书校验名。

### verify_name

* 类型：字符串。
* 必填：可选。
* 行为：换一个证书校验名，`server_name` 仍照常发出。

### ca

* 类型：路径。
* 必填：可选。
* 默认：系统/公共根证书。
* 行为：用这一份根证书替换默认信任库。

### insecure

* 类型：布尔值。
* 默认：`false`。
* 限制：与 `ca` 不能同时设置。

### certificate_sha256

* 类型：摘要字符串或数组。
* 默认：不钉证书。
* 行为：钉整张证书的 SHA-256；与 `ca` 或 `insecure` 一起会被拒绝。

### certificate_public_key_sha256

* 类型：摘要字符串或数组。
* 默认：不钉公钥。
* 行为：钉叶证书公钥的 SHA-256；与 `ca` 或 `insecure` 一起会被拒绝。

### alpn

* 类型：字符串或数组。
* 必填：可选。
* 默认：使用者协议自己的 ALPN。
* 限制：cronet 引擎、QUIC 和 H3 不接受自定义 `alpn`。

### client_certificate

* 类型：路径。
* 必填：可选。
* 限制：必须与 `client_key` 一起出现。

### client_key

* 类型：路径。
* 必填：可选。
* 限制：必须与 `client_certificate` 一起出现。

### ech

* 类型：字符串。
* 必填：可选。
* 行为：ECHConfigList，写成 PEM 文本或文件路径。

### reality

* 类型：映射。
* 必填：可选。
* 限制：需要 BoringSSL 引擎；REALITY 与普通信任、钉子、ECH 和客户端证书不能并用。

### reality.public_key

* 类型：字符串。
* 必填：是。
* 行为：服务器 X25519 公钥的 Base64。

### reality.short_id

* 类型：字符串。
* 默认：全零 short id。
* 行为：最多八字节的十六进制。

### kotodama

* 类型：字符串。
* 必填：可选。
* 行为：`ktb1.` 开头的客户端 bundle。

## 说明

::: info 平台边界
Linux 的 BoringSSL 路径支持完整字段。QUIC、H3 以及非 Linux 的 DoT/DoH 使用 rustls，只接受 `server_name`、`ca`、`insecure` 这类信任设置。naive 的 cronet 承载只读取 `server_name` 和 `ca`。
:::

## 相关

* [共享块总览](/configuration/shared/)
* [http_clients](/configuration/http-client)
* [TLS 服务端](/configuration/shared/tls-server)