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

Add curve preferences, pinned public key SHA256 and mTLS for TLS options

Browse Source
This commit is contained in:
世界
2025-09-17 08:59:46 +08:00
parent dfd95b2615
commit 79bbce3db3
7 changed files with 576 additions and 137 deletions
Download Patch File Download Diff File Expand all files Collapse all files

111
docs/configuration/shared/tls.md
View File

@@ -5,7 +5,13 @@ icon: material/new-box
!!! quote "Changes in sing-box 1.13.0"
:material-plus: [kernel_tx](#kernel_tx)
:material-plus: [kernel_rx](#kernel_rx)
: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_authentication](#client_authentication)
:material-plus: [client_certificate](#client_certificate)
:material-plus: [client_certificate_path](#client_certificate_path)
:material-plus: [client_certificate_public_key_sha256](#client_certificate_public_key_sha256)
!!! quote "Changes in sing-box 1.12.0"
@@ -29,8 +35,13 @@ icon: material/new-box
"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,
@@ -92,6 +103,7 @@ icon: material/new-box
"cipher_suites": [],
"certificate": "",
"certificate_path": "",
"certificate_public_key_sha256": [],
"fragment": false,
"fragment_fallback_delay": "",
"record_fragment": false,
@@ -195,14 +207,29 @@ By default, the maximum version is currently TLS 1.3.
#### cipher_suites
A list of enabled TLS 1.0–1.2 cipher suites. The order of the list is ignored.
List of enabled TLS 1.0–1.2 cipher suites. The order of the list is ignored.
Note that TLS 1.3 cipher suites are not configurable.
If empty, a safe default list is used. The default cipher suites might change over time.
#### curve_preferences
!!! question "Since sing-box 1.13.0"
Set of supported key exchange mechanisms. The order of the list is ignored, and key exchange mechanisms are chosen
from this list using an internal preference order by Golang.
Available values, also the default list:
* `P256`
* `P384`
* `P521`
* `X25519`
* `X25519MLKEM768`
#### certificate
The server certificate line array, in PEM format.
Server certificates chain line array, in PEM format.
#### certificate_path
@@ -210,7 +237,26 @@ The server certificate line array, in PEM format.
Will be automatically reloaded if file modified.
The path to the server certificate, in PEM format.
The path to server certificate chain, in PEM format.
#### certificate_public_key_sha256
!!! question "Since sing-box 1.13.0"
==Client only==
List of SHA-256 hashes of server certificate public keys, in base64 format.
To generate the SHA-256 hash for a certificate's public key, use the following commands:
```bash
# For a certificate file
openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
# For a certificate from a remote server
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
```
#### key
@@ -228,6 +274,63 @@ The server private key line array, in PEM format.
The path to the server private key, in PEM format.
#### client_authentication
!!! question "Since sing-box 1.13.0"
==Server only==
The type of client authentication to use.
Available values:
* `no` (default)
* `request`
* `require-any`
* `verify-if-given`
* `require-and-verify`
One of `client_certificate`, `client_certificate_path`, or `client_certificate_public_key_sha256` is required
if this option is set to `verify-if-given`, or `require-and-verify`.
#### client_certificate
!!! question "Since sing-box 1.13.0"
==Server only==
Client certificate chain line array, in PEM format.
#### client_certificate_path
!!! question "Since sing-box 1.13.0"
==Server only==
!!! note ""
Will be automatically reloaded if file modified.
List of path to client certificate chain, in PEM format.
#### client_certificate_public_key_sha256
!!! question "Since sing-box 1.13.0"
==Server only==
List of SHA-256 hashes of client certificate public keys, in base64 format.
To generate the SHA-256 hash for a certificate's public key, use the following commands:
```bash
# For a certificate file
openssl x509 -in certificate.pem -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
# For a certificate from a remote server
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 "Since sing-box 1.13.0"

261
docs/configuration/shared/tls.zh.md
View File

@@ -1,18 +1,24 @@
---
icon: material/alert-decagram
icon: material/new-box
---
!!! quote "sing-box 1.13.0 中的更改"
:material-plus: [kernel_tx](#kernel_tx)
: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_authentication](#client_authentication)
:material-plus: [client_certificate](#client_certificate)
:material-plus: [client_certificate_path](#client_certificate_path)
:material-plus: [client_certificate_public_key_sha256](#client_certificate_public_key_sha256)
!!! quote "sing-box 1.12.0 中的更改"
:material-plus: [tls_fragment](#tls_fragment)
:material-plus: [tls_fragment_fallback_delay](#tls_fragment_fallback_delay)
:material-plus: [tls_record_fragment](#tls_record_fragment)
:material-delete-clock: [ech.pq_signature_schemes_enabled](#pq_signature_schemes_enabled)
: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 中的更改"
@@ -29,8 +35,13 @@ icon: material/alert-decagram
"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,
@@ -90,17 +101,20 @@ icon: material/alert-decagram
"min_version": "",
"max_version": "",
"cipher_suites": [],
"certificate": [],
"certificate": "",
"certificate_path": "",
"certificate_public_key_sha256": [],
"fragment": false,
"fragment_fallback_delay": "",
"record_fragment": false,
"ech": {
"enabled": false,
"pq_signature_schemes_enabled": false,
"dynamic_record_sizing_disabled": false,
"config": [],
"config_path": ""
"config_path": "",
// 废弃的
"pq_signature_schemes_enabled": false,
"dynamic_record_sizing_disabled": false
},
"utls": {
"enabled": false,
@@ -191,13 +205,27 @@ TLS 版本值：
#### cipher_suites
启用的 TLS 1.0-1.2密码套件的列表。列表的顺序被忽略。请注意，TLS 1.3 的密码套件是不可配置的。
启用的 TLS 1.0–1.2 密码套件列表。列表的顺序被忽略。请注意，TLS 1.3 的密码套件是不可配置的。
如果为空，则使用安全的默认列表。默认密码套件可能会随着时间的推移而改变。
#### curve_preferences
!!! question "自 sing-box 1.13.0 起"
支持的密钥交换机制集合。列表的顺序被忽略，密钥交换机制通过 Golang 的内部偏好顺序从此列表中选择。
可用值，同时也是默认列表：
* `P256`
* `P384`
* `P521`
* `X25519`
* `X25519MLKEM768`
#### certificate
服务器 PEM 证书行数组。
服务器证书链行数组，PEM 格式。
#### certificate_path
@@ -205,7 +233,25 @@ TLS 版本值：
文件更改时将自动重新加载。
服务器 PEM 证书路径。
服务器证书链路径，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
```
#### key
@@ -221,7 +267,68 @@ TLS 版本值：
==仅服务器==
服务器 PEM 私钥路径。
!!! 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
@@ -307,44 +414,11 @@ uTLS 是 "crypto/tls" 的一个分支，它提供了 ClientHello 指纹识别阻
默认使用 chrome 指纹。
## ECH 字段
### ECH 字段
ECH (Encrypted Client Hello) 是一个 TLS 扩展，它允许客户端加密其 ClientHello 的第一部分
信息。
ECH (Encrypted Client Hello) 是一个 TLS 扩展，它允许客户端加密其 ClientHello 的第一部分信息。
ECH 配置和密钥可以通过 `sing-box generate ech-keypair [--pq-signature-schemes-enabled]` 生成。
#### key
==仅服务器==
ECH PEM 密钥行数组
#### key_path
==仅服务器==
!!! note ""
文件更改时将自动重新加载。
ECH PEM 密钥路径
#### config
==仅客户端==
ECH PEM 配置行数组
如果为空，将尝试从 DNS 加载。
#### config_path
==仅客户端==
ECH PEM 配置路径
如果为空，将尝试从 DNS 加载。
ECH 密钥和配置可以通过 `sing-box generate ech-keypair` 生成。
#### pq_signature_schemes_enabled
@@ -354,8 +428,6 @@ ECH PEM 配置路径
启用对后量子对等证书签名方案的支持。
建议匹配 `sing-box generate ech-keypair` 的参数。
#### dynamic_record_sizing_disabled
!!! failure "已在 sing-box 1.12.0 废弃"
@@ -364,57 +436,91 @@ ECH PEM 配置路径
禁用 TLS 记录的自适应大小调整。
如果为 true，则始终使用最大可能的 TLS 记录大小。
如果为 false，则可能会调整 TLS 记录的大小以尝试改善延迟。
当为 true 时，总是使用最大可能的 TLS 记录大小。
当为 false 时，可能会调整 TLS 记录的大小以尝试改善延迟。
#### tls_fragment
#### key
==仅服务器==
ECH 密钥行数组，PEM 格式。
#### key_path
==仅服务器==
!!! note ""
文件更改时将自动重新加载。
ECH 密钥路径，PEM 格式。
#### config
==仅客户端==
ECH 配置行数组，PEM 格式。
如果为空，将尝试从 DNS 加载。
#### config_path
==仅客户端==
ECH 配置路径，PEM 格式。
如果为空，将尝试从 DNS 加载。
#### fragment
!!! question "自 sing-box 1.12.0 起"
==仅客户端==
通过分段 TLS 握手数据包来绕过防火墙检测。
通过分段 TLS 握手数据包来绕过防火墙。
此功能旨在规避基于**明文数据包匹配**的简单防火墙，不应该用于规避真的审查。
此功能旨在规避基于**明文数据包匹配**的简单防火墙，不应该用于规避真正的审查。
由于性能不佳，请首先尝试 `tls_record_fragment`，且仅应用于已知被阻止的服务器名称。
由于性能不佳，请首先尝试 `record_fragment`，且仅应用于已知被阻止的服务器名称。
在 Linux、Apple 平台和需要管理员权限的 Windows 系统上，可自动检测等待时间。
若无法自动检测，将回退使用 `tls_fragment_fallback_delay` 指定的固定等待时间。
在 Linux、Apple 平台和（需要管理员权限的）Windows 系统上，
可以自动检测等待时间。否则，将回退到
等待 `fragment_fallback_delay` 指定的固定时间。
此外，若实际等待时间小于 20 毫秒，同样会回退至固定等待时间模式，因为此时判定目标处于本地或透明代理之后。
此外，如果实际等待时间少于 20ms，也会回退到等待固定时间，
因为目标被认为是本地的或在透明代理后面。
#### tls_fragment_fallback_delay
#### fragment_fallback_delay
!!! question "自 sing-box 1.12.0 起"
==仅客户端==
当 TLS 分片功能无法自动判定等待时间时使用的回退值。
当 TLS 分段无法自动确定等待时间时使用的回退值。
默认使用 `500ms`。
#### tls_record_fragment
==仅客户端==
#### record_fragment
!!! question "自 sing-box 1.12.0 起"
通过分段 TLS 握手数据包到多个 TLS 记录来绕过防火墙检测。
==仅客户端==
将 TLS 握手分段为多个 TLS 记录以绕过防火墙。
### ACME 字段
#### domain
一组域名。
域名列表。
默认禁用 ACME。
如果为空则禁用 ACME。
#### data_directory
ACME 数据目录。
ACME 数据存储目录。
默认使用 `$XDG_DATA_HOME/certmagic|$HOME/.local/share/certmagic`。
如果为空则使用 `$XDG_DATA_HOME/certmagic|$HOME/.local/share/certmagic`。
#### default_server_name
@@ -452,12 +558,11 @@ ACME 数据目录。
#### external_account
EAB（外部帐户绑定）包含将 ACME 帐户绑定或映射到其他已知帐户所需的信息由 CA。
EAB（外部帐户绑定）包含将 ACME 帐户绑定或映射到 CA 已知的其他帐户所需的信息。
外部帐户绑定“用于将 ACME 帐户与非 ACME 系统中的现有帐户相关联，例如 CA 客户数据库。
外部帐户绑定"用于将 ACME 帐户与非 ACME 系统中的现有帐户相关联，例如 CA 客户数据库。
为了启用 ACME 帐户绑定，运行 ACME 服务器的 CA 需要向 ACME 客户端提供 MAC 密钥和密钥标识符，使用 ACME 之外的一些机制。
§7.3.4
为了启用 ACME 帐户绑定，运行 ACME 服务器的 CA 需要使用 ACME 之外的某种机制向 ACME 客户端提供 MAC 密钥和密钥标识符。§7.3.4
#### external_account.key_id
@@ -507,6 +612,8 @@ ACME DNS01 验证字段。如果配置，将禁用其他验证方法。
#### max_time_difference
服务器与和客户端之间允许的最大时间差。
==仅服务器==
默认禁用检查。
服务器和客户端之间的最大时间差。
如果为空则禁用检查。