timamsk/sing-box
1
0
Fork 0
mirror of https://github.com/SagerNet/sing-box.git synced 2026-04-13 20:28:32 +10:00
Code Issues Packages Projects Releases Wiki Activity
Files
ccfdbf2d57ed6d61eedf41bfc14feabc5d2edbac
sing-box/docs/configuration/shared/tls.zh.md
世界 9b75d28ca4 Add Network.framework TLS engine
2026-04-13 01:41:01 +08:00

752 lines
17 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
---
icon: material/new-box
---
!!! quote "sing-box 1.14.0 中的更改"
:material-plus: [certificate_provider](#certificate_provider)
:material-plus: [handshake_timeout](#handshake_timeout)
:material-delete-clock: [acme](#acme-字段)
!!! quote "sing-box 1.13.0 中的更改"
:material-plus: [kernel_tx](#kernel_tx)
:material-plus: [kernel_rx](#kernel_rx)
:material-plus: [curve_preferences](#curve_preferences)
:material-plus: [certificate_public_key_sha256](#certificate_public_key_sha256)
:material-plus: [client_certificate](#client_certificate)
:material-plus: [client_certificate_path](#client_certificate_path)
:material-plus: [client_key](#client_key)
:material-plus: [client_key_path](#client_key_path)
:material-plus: [client_authentication](#client_authentication)
:material-plus: [client_certificate_public_key_sha256](#client_certificate_public_key_sha256)
:material-plus: [ech.query_server_name](#query_server_name)
!!! quote "sing-box 1.12.0 中的更改"
:material-plus: [fragment](#fragment)
:material-plus: [fragment_fallback_delay](#fragment_fallback_delay)
:material-plus: [record_fragment](#record_fragment)
:material-delete-clock: [ech.pq_signature_schemes_enabled](#pq_signature_schemes_enabled)
:material-delete-clock: [ech.dynamic_record_sizing_disabled](#dynamic_record_sizing_disabled)
!!! quote "sing-box 1.10.0 中的更改"
:material-alert-decagram: [utls](#utls)
### 入站
```json
{
"enabled": true,
"server_name": "",
"alpn": [],
"min_version": "",
"max_version": "",
"cipher_suites": [],
"curve_preferences": [],
"certificate": [],
"certificate_path": "",
"client_authentication": "",
"client_certificate": [],
"client_certificate_path": [],
"client_certificate_public_key_sha256": [],
"key": [],
"key_path": "",
"kernel_tx": false,
"kernel_rx": false,
"handshake_timeout": "",
"certificate_provider": "",
// 废弃的
"acme": {
"domain": [],
"data_directory": "",
"default_server_name": "",
"email": "",
"provider": "",
"disable_http_challenge": false,
"disable_tls_alpn_challenge": false,
"alternative_http_port": 0,
"alternative_tls_port": 0,
"external_account": {
"key_id": "",
"mac_key": ""
},
"dns01_challenge": {}
},
"ech": {
"enabled": false,
"key": [],
"key_path": "",
// 废弃的
"pq_signature_schemes_enabled": false,
"dynamic_record_sizing_disabled": false
},
"reality": {
"enabled": false,
"handshake": {
"server": "google.com",
"server_port": 443,
... // 拨号字段
},
"private_key": "UuMBgl7MXTPx9inmQp2UC7Jcnwc6XYbwDNebonM-FCc",
"short_id": [
"0123456789abcdef"
],
"max_time_difference": "1m"
}
}
```
### 出站
```json
{
"enabled": true,
"engine": "",
"disable_sni": false,
"server_name": "",
"insecure": false,
"alpn": [],
"min_version": "",
"max_version": "",
"cipher_suites": [],
"curve_preferences": [],
"certificate": "",
"certificate_path": "",
"certificate_public_key_sha256": [],
"client_certificate": [],
"client_certificate_path": "",
"client_key": [],
"client_key_path": "",
"fragment": false,
"fragment_fallback_delay": "",
"record_fragment": false,
"kernel_tx": false,
"kernel_rx": false,
"handshake_timeout": "",
"ech": {
"enabled": false,
"config": [],
"config_path": "",
"query_server_name": "",
// 废弃的
"pq_signature_schemes_enabled": false,
"dynamic_record_sizing_disabled": false
},
"utls": {
"enabled": false,
"fingerprint": ""
},
"reality": {
"enabled": false,
"public_key": "jNXHt1yRo0vDuchQlIP6Z0ZvjT3KtzVI-T4E7RoLJS0",
"short_id": "0123456789abcdef"
}
}
```
TLS 版本值：
* `1.0`
* `1.1`
* `1.2`
* `1.3`
密码套件值：
* `TLS_RSA_WITH_AES_128_CBC_SHA`
* `TLS_RSA_WITH_AES_256_CBC_SHA`
* `TLS_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_AES_128_GCM_SHA256`
* `TLS_AES_256_GCM_SHA384`
* `TLS_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_ECDSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA`
* `TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA`
* `TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA`
* `TLS_ECDHE_ECDSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256`
* `TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384`
* `TLS_ECDHE_ECDSA_WITH_CHACHA20_POLY1305_SHA256`
* `TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256`
!!! note ""
当内容只有一项时，可以忽略 JSON 数组 [] 标签
### 字段
#### enabled
启用 TLS
#### engine
==仅客户端==
要使用的 TLS 引擎。
可用值：
* `go`
* `apple`
`apple` 使用 Network.framework，仅在 Apple 平台可用，且仅支持 **直接** TCP TLS 客户端连接。
!!! warning ""
仅供实验用途：由于 CGO 和 Network.framework 占用的内存都很多，
不应在 iOS 和 tvOS 的代理路径中使用。
如果您想规避基于 TLS 指纹的代理审查，应使用 [NaiveProxy](/zh/configuration/outbound/naive/)。
支持的字段：
* `server_name`
* `insecure`
* `alpn`
* `min_version`
* `max_version`
* `certificate` / `certificate_path`
* `certificate_public_key_sha256`
* `handshake_timeout`
不支持的字段：
* `disable_sni`
* `cipher_suites`
* `curve_preferences`
* `client_certificate` / `client_certificate_path` / `client_key` / `client_key_path`
* `fragment` / `record_fragment`
* `kernel_tx` / `kernel_rx`
* `ech`
* `utls`
* `reality`
#### disable_sni
==仅客户端==
不要在 ClientHello 中发送服务器名称.
#### server_name
用于验证返回证书上的主机名，除非设置不安全。
它还包含在 ClientHello 中以支持虚拟主机，除非它是 IP 地址。
#### insecure
==仅客户端==
接受任何服务器证书。
#### alpn
支持的应用层协议协商列表，按优先顺序排列。
如果两个对等点都支持 ALPN，则选择的协议将是此列表中的一个，如果没有相互支持的协议则连接将失败。
参阅 [Application-Layer Protocol Negotiation](https://en.wikipedia.org/wiki/Application-Layer_Protocol_Negotiation)。
#### min_version
可接受的最低 TLS 版本。
默认情况下，当前使用 TLS 1.2 作为客户端的最低要求。作为服务器时使用 TLS 1.0。
#### max_version
可接受的最大 TLS 版本。
默认情况下，当前最高版本为 TLS 1.3。
#### cipher_suites
启用的 TLS 1.0–1.2 密码套件列表。列表的顺序被忽略。请注意，TLS 1.3 的密码套件是不可配置的。
如果为空，则使用安全的默认列表。默认密码套件可能会随着时间的推移而改变。
#### curve_preferences
!!! question "自 sing-box 1.13.0 起"
支持的密钥交换机制集合。列表的顺序被忽略，密钥交换机制通过 Golang 的内部偏好顺序从此列表中选择。
可用值，同时也是默认列表：
* `P256`
* `P384`
* `P521`
* `X25519`
* `X25519MLKEM768`
#### certificate
服务器证书链行数组，PEM 格式。
#### certificate_path
!!! note ""
文件更改时将自动重新加载。
服务器证书链路径，PEM 格式。
#### certificate_public_key_sha256
!!! question "自 sing-box 1.13.0 起"
==仅客户端==
服务器证书公钥的 SHA-256 哈希列表，base64 格式。
要生成证书公钥的 SHA-256 哈希，请使用以下命令：
```bash
# 对于证书文件
openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
# 对于远程服务器的证书
echo | openssl s_client -servername example.com -connect example.com:443 2>/dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
```
#### client_certificate
!!! question "自 sing-box 1.13.0 起"
==仅客户端==
客户端证书链行数组，PEM 格式。
#### client_certificate_path
!!! question "自 sing-box 1.13.0 起"
==仅客户端==
客户端证书链路径，PEM 格式。
#### client_key
!!! question "自 sing-box 1.13.0 起"
==仅客户端==
客户端私钥行数组，PEM 格式。
#### client_key_path
!!! question "自 sing-box 1.13.0 起"
==仅客户端==
客户端私钥路径，PEM 格式。
#### key
==仅服务器==
!!! note ""
文件更改时将自动重新加载。
服务器 PEM 私钥行数组。
#### key_path
==仅服务器==
!!! note ""
文件更改时将自动重新加载。
服务器私钥路径，PEM 格式。
#### client_authentication
!!! question "自 sing-box 1.13.0 起"
==仅服务器==
要使用的客户端身份验证类型。
可用值：
* `no`（默认）
* `request`
* `require-any`
* `verify-if-given`
* `require-and-verify`
如果此选项设置为 `verify-if-given` 或 `require-and-verify`，
则需要 `client_certificate`、`client_certificate_path` 或 `client_certificate_public_key_sha256` 中的一个。
#### client_certificate
!!! question "自 sing-box 1.13.0 起"
==仅服务器==
客户端证书链行数组，PEM 格式。
#### client_certificate_path
!!! question "自 sing-box 1.13.0 起"
==仅服务器==
!!! note ""
文件更改时将自动重新加载。
客户端证书链路径列表，PEM 格式。
#### client_certificate_public_key_sha256
!!! question "自 sing-box 1.13.0 起"
==仅服务器==
客户端证书公钥的 SHA-256 哈希列表，base64 格式。
要生成证书公钥的 SHA-256 哈希，请使用以下命令：
```bash
# 对于证书文件
openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
# 对于远程服务器的证书
echo | openssl s_client -servername example.com -connect example.com:443 2>/dev/null | openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
```
#### kernel_tx
!!! question "自 sing-box 1.13.0 起"
!!! quote ""
仅支持 Linux 5.1+，如果可能，使用较新的内核。
!!! quote ""
仅支持 TLS 1.3。
!!! warning ""
kTLS TX 仅当 `splice(2)` 可用时（两端经过握手后必须为没有附加协议的 TCP 或 TLS）才能提高性能；否则肯定会降低性能。
启用内核 TLS 发送支持。
#### kernel_rx
!!! question "自 sing-box 1.13.0 起"
!!! quote ""
仅支持 Linux 5.1+，如果可能，使用较新的内核。
!!! quote ""
仅支持 TLS 1.3。
!!! failure ""
即使使用 `splice(2)`，kTLS RX 也肯定会降低性能，因此不建议启用。
启用内核 TLS 接收支持。
#### handshake_timeout
!!! question "自 sing-box 1.14.0 起"
TLS 握手超时，采用 golang 的 Duration 格式。
默认使用 `15s`。
#### certificate_provider
!!! question "自 sing-box 1.14.0 起"
==仅服务器==
字符串或对象。
为字符串时，共享[证书提供者](/zh/configuration/shared/certificate-provider/)的标签。
为对象时，内联的证书提供者。可用类型和字段参阅[证书提供者](/zh/configuration/shared/certificate-provider/)。
## 自定义 TLS 支持
!!! info "QUIC 支持"
只有 ECH 在 QUIC 中被支持.
#### utls
==仅客户端==
!!! failure "不推荐"
uTLS 已被研究人员多次发现其指纹可被识别的漏洞。
uTLS 是一个试图通过复制 ClientHello 结构来模仿浏览器 TLS 指纹的 Go 库。
然而，浏览器使用完全不同的 TLS 实现（Chrome 使用 BoringSSL，Firefox 使用 NSS），
其实现行为无法通过简单复制握手格式来复现，其行为细节必然存在差异，使得检测成为可能。
此外，此库缺乏积极维护，且代码质量较差，不建议用于反审查场景。
如需 TLS 指纹抵抗，请改用 [NaiveProxy](/zh/configuration/inbound/naive/)。
uTLS 是 "crypto/tls" 的一个分支，它提供了 ClientHello 指纹识别阻力。
可用的指纹值：
!!! warning "已在 sing-box 1.10.0 移除"
一些旧 chrome 指纹已被删除，并将会退到 chrome：
:material-close: chrome_psk
:material-close: chrome_psk_shuffle
:material-close: chrome_padding_psk_shuffle
:material-close: chrome_pq
:material-close: chrome_pq_psk
* chrome
* firefox
* edge
* safari
* 360
* qq
* ios
* android
* random
* randomized
默认使用 chrome 指纹。
### ECH 字段
ECH (Encrypted Client Hello) 是一个 TLS 扩展，它允许客户端加密其 ClientHello 的第一部分信息。
ECH 密钥和配置可以通过 `sing-box generate ech-keypair` 生成。
#### pq_signature_schemes_enabled
!!! failure "已在 sing-box 1.12.0 废弃"
`pq_signature_schemes_enabled` 已在 sing-box 1.12.0 废弃且已在 sing-box 1.13.0 中被移除。
启用对后量子对等证书签名方案的支持。
#### dynamic_record_sizing_disabled
!!! failure "已在 sing-box 1.12.0 废弃"
`dynamic_record_sizing_disabled` 已在 sing-box 1.12.0 废弃且已在 sing-box 1.13.0 中被移除。
禁用 TLS 记录的自适应大小调整。
当为 true 时，总是使用最大可能的 TLS 记录大小。
当为 false 时，可能会调整 TLS 记录的大小以尝试改善延迟。
#### key
==仅服务器==
ECH 密钥行数组，PEM 格式。
#### key_path
==仅服务器==
!!! note ""
文件更改时将自动重新加载。
ECH 密钥路径，PEM 格式。
#### config
==仅客户端==
ECH 配置行数组，PEM 格式。
如果为空，将尝试从 DNS 加载。
#### config_path
==仅客户端==
ECH 配置路径，PEM 格式。
如果为空，将尝试从 DNS 加载。
#### query_server_name
!!! question "自 sing-box 1.13.0 起"
==仅客户端==
覆盖用于 ECH HTTPS 记录查询的域名。
如果为空，使用 `server_name` 查询。
#### fragment
!!! question "自 sing-box 1.12.0 起"
==仅客户端==
通过分段 TLS 握手数据包来绕过防火墙。
此功能旨在规避基于**明文数据包匹配**的简单防火墙，不应该用于规避真正的审查。
由于性能不佳，请首先尝试 `record_fragment`，且仅应用于已知被阻止的服务器名称。
在 Linux、Apple 平台和（需要管理员权限的）Windows 系统上，
可以自动检测等待时间。否则，将回退到
等待 `fragment_fallback_delay` 指定的固定时间。
此外，如果实际等待时间少于 20ms，也会回退到等待固定时间，
因为目标被认为是本地的或在透明代理后面。
#### fragment_fallback_delay
!!! question "自 sing-box 1.12.0 起"
==仅客户端==
当 TLS 分段无法自动确定等待时间时使用的回退值。
默认使用 `500ms`。
#### record_fragment
!!! question "自 sing-box 1.12.0 起"
==仅客户端==
将 TLS 握手分段为多个 TLS 记录以绕过防火墙。
### ACME 字段
!!! failure "已在 sing-box 1.14.0 废弃"
内联 ACME 选项已在 sing-box 1.14.0 废弃且将在 sing-box 1.16.0 中被移除，参阅 [迁移指南](/zh/migration/#迁移内联-acme-到证书提供者)。
#### domain
域名列表。
如果为空则禁用 ACME。
#### data_directory
ACME 数据存储目录。
如果为空则使用 `$XDG_DATA_HOME/certmagic|$HOME/.local/share/certmagic`。
#### default_server_name
如果 ClientHello 的 ServerName 字段为空，则选择证书时要使用的服务器名称。
#### email
创建或选择现有 ACME 服务器帐户时使用的电子邮件地址。
#### provider
要使用的 ACME CA 供应商。
| 值 | 供应商 |
|--------------------|---------------|
| `letsencrypt (默认)` | Let's Encrypt |
| `zerossl` | ZeroSSL |
| `https://...` | 自定义 |
#### disable_http_challenge
禁用所有 HTTP 质询。
#### disable_tls_alpn_challenge
禁用所有 TLS-ALPN 质询。
#### alternative_http_port
用于 ACME HTTP 质询的备用端口；如果非空，将使用此端口而不是 80 来启动 HTTP 质询的侦听器。
#### alternative_tls_port
用于 ACME TLS-ALPN 质询的备用端口； 系统必须将 443 转发到此端口以使质询成功。
#### external_account
EAB（外部帐户绑定）包含将 ACME 帐户绑定或映射到 CA 已知的其他帐户所需的信息。
外部帐户绑定"用于将 ACME 帐户与非 ACME 系统中的现有帐户相关联，例如 CA 客户数据库。
为了启用 ACME 帐户绑定，运行 ACME 服务器的 CA 需要使用 ACME 之外的某种机制向 ACME 客户端提供 MAC 密钥和密钥标识符。§7.3.4
#### external_account.key_id
密钥标识符。
#### external_account.mac_key
MAC 密钥。
#### dns01_challenge
ACME DNS01 验证字段。如果配置，将禁用其他验证方法。
参阅 [DNS01 验证字段](/zh/configuration/shared/dns01_challenge/)。
### Reality 字段
#### handshake
==仅服务器==
==必填==
握手服务器地址和 [拨号参数](/zh/configuration/shared/dial/)。
#### private_key
==仅服务器==
==必填==
私钥，由 `sing-box generate reality-keypair` 生成。
#### public_key
==仅客户端==
==必填==
公钥，由 `sing-box generate reality-keypair` 生成。
#### short_id
==必填==
一个零到八位的十六进制字符串。
#### max_time_difference
==仅服务器==
服务器和客户端之间的最大时间差。
如果为空则禁用检查。
Reference in New Issue View Git Blame Copy Permalink