documentation: Update TLS ECH struct

SagerNet · Aug 30, 2023 · 82993a6 · 82993a6
1 parent c3b4723
commit 82993a6
Show file tree

Hide file tree

Showing 2 changed files with 133 additions and 38 deletions.
diff --git a/docs/configuration/shared/tls.md b/docs/configuration/shared/tls.md
@@ -8,9 +8,9 @@
   "min_version": "",
   "max_version": "",
   "cipher_suites": [],
-  "certificate": "",
+  "certificate": [],
   "certificate_path": "",
-  "key": "",
+  "key": [],
   "key_path": "",
   "acme": {
     "domain": [],
@@ -27,6 +27,13 @@
       "mac_key": ""
     }
   },
+  "ech": {
+    "enabled": false,
+    "pq_signature_schemes_enabled": false,
+    "dynamic_record_sizing_disabled": false,
+    "key": [],
+    "key_path": ""
+  },
   "reality": {
     "enabled": false,
     "handshake": {
@@ -62,7 +69,8 @@
     "enabled": false,
     "pq_signature_schemes_enabled": false,
     "dynamic_record_sizing_disabled": false,
-    "config": ""
+    "config": [],
+    "config_path": ""
   },
   "utls": {
     "enabled": false,
@@ -162,7 +170,7 @@ This may change in the future.
 
 #### certificate
 
-The server certificate, in PEM format.
+The server certificate line array, in PEM format.
 
 #### certificate_path
 
@@ -172,27 +180,14 @@ The path to the server certificate, in PEM format.
 
 ==Server only==
 
-The server private key, in PEM format.
+The server private key line array, in PEM format.
 
 #### key_path
 
 ==Server only==
 
 The path to the server private key, in PEM format.
 
-#### ech
-
-==Client only==
-
-!!! warning ""
-
-    ECH is not included by default, see [Installation](/#installation).
-
-ECH (Encrypted Client Hello) is a TLS extension that allows a client to encrypt the first part of its ClientHello
-message.
-
-If you don't know how to fill in the other configuration, just set `enabled`.
-
 #### utls
 
 ==Client only==
@@ -222,6 +217,58 @@ Available fingerprint values:
 
 Chrome fingerprint will be used if empty.
 
+## ECH Fields
+
+!!! warning ""
+
+    ECH is not included by default, see [Installation](/#installation).
+
+ECH (Encrypted Client Hello) is a TLS extension that allows a client to encrypt the first part of its ClientHello
+message.
+
+The ECH key and configuration can be generated by `sing-box generate ech-keypair [-pq-signature-schemes-enabled]`.
+
+#### pq_signature_schemes_enabled
+
+Enable support for post-quantum peer certificate signature schemes.
+
+It is recommended to match the parameters of `sing-box generate ech-keypair`.
+
+#### dynamic_record_sizing_disabled
+
+Disables adaptive sizing of TLS records.
+
+When true, the largest possible TLS record size is always used.  
+When false, the size of TLS records may be adjusted in an attempt to improve latency.
+
+#### key
+
+==Server only==
+
+ECH key line array, in PEM format.
+
+#### key_path
+
+==Server only==
+
+The path to ECH key, in PEM format.
+
+#### config
+
+==Client only==
+
+ECH configuration line array, in PEM format.
+
+If empty, load from DNS will be attempted.
+
+#### config_path
+
+==Client only==
+
+The path to ECH configuration, in PEM format.
+
+If empty, load from DNS will be attempted.
+
 ### ACME Fields
 
 !!! warning ""
@@ -345,4 +392,4 @@ Check disabled if empty.
 
 ### Reload
 
-For server configuration, certificate and key will be automatically reloaded if modified.
+For server configuration, certificate, key and ECH key will be automatically reloaded if modified.
diff --git a/docs/configuration/shared/tls.zh.md b/docs/configuration/shared/tls.zh.md
@@ -8,9 +8,9 @@
   "min_version": "",
   "max_version": "",
   "cipher_suites": [],
-  "certificate": "",
+  "certificate": [],
   "certificate_path": "",
-  "key": "",
+  "key": [],
   "key_path": "",
   "acme": {
     "domain": [],
@@ -27,6 +27,13 @@
       "mac_key": ""
     }
   },
+  "ech": {
+    "enabled": false,
+    "pq_signature_schemes_enabled": false,
+    "dynamic_record_sizing_disabled": false,
+    "key": [],
+    "key_path": ""
+  },
   "reality": {
     "enabled": false,
     "handshake": {
@@ -56,13 +63,14 @@
   "min_version": "",
   "max_version": "",
   "cipher_suites": [],
-  "certificate": "",
+  "certificate": [],
   "certificate_path": "",
   "ech": {
     "enabled": false,
     "pq_signature_schemes_enabled": false,
     "dynamic_record_sizing_disabled": false,
-    "config": ""
+    "config": [],
+    "config_path": ""
   },
   "utls": {
     "enabled": false,
@@ -162,7 +170,7 @@ TLS 版本值：
 
 #### certificate
 
-服务器 PEM 证书。
+服务器 PEM 证书行数组。
 
 #### certificate_path
 
@@ -172,27 +180,14 @@ TLS 版本值：
 
 ==仅服务器==
 
-服务器 PEM 私钥。
+服务器 PEM 私钥行数组。
 
 #### key_path
 
 ==仅服务器==
 
 服务器 PEM 私钥路径。
 
-#### ech
-
-==仅客户端==
-
-!!! warning ""
-
-    默认安装不包含 ECH, 参阅 [安装](/zh/#_2)。
-
-ECH (Encrypted Client Hello) 是一个 TLS 扩展，它允许客户端加密其 ClientHello 的第一部分
-信息。
-
-如果您不知道如何填写其他配置，只需设置 `enabled` 即可。
-
 #### utls
 
 ==仅客户端==
@@ -222,6 +217,59 @@ uTLS 是 "crypto/tls" 的一个分支，它提供了 ClientHello 指纹识别阻
 
 默认使用 chrome 指纹。
 
+## ECH 字段
+
+!!! warning ""
+
+    默认安装不包含 ECH, 参阅 [安装](/zh/#_2)。
+
+ECH (Encrypted Client Hello) 是一个 TLS 扩展，它允许客户端加密其 ClientHello 的第一部分
+信息。
+
+
+ECH 配置和密钥可以通过 `sing-box generated ech-keypair [-pq-signature-schemes-enabled]` 生成。
+
+#### pq_signature_schemes_enabled
+
+启用对后量子对等证书签名方案的支持。
+
+建议匹配 `sing-box generated ech-keypair` 的参数。
+
+#### dynamic_record_sizing_disabled
+
+禁用 TLS 记录的自适应大小调整。
+
+如果为 true，则始终使用最大可能的 TLS 记录大小。
+如果为 false，则可能会调整 TLS 记录的大小以尝试改善延迟。
+
+#### key
+
+==仅服务器==
+
+ECH PEM 密钥行数组
+
+#### key_path
+
+==仅服务器==
+
+ECH PEM 密钥路径
+
+#### config
+
+==仅客户端==
+
+ECH PEM 配置行数组
+
+如果为空，将尝试从 DNS 加载。
+
+#### config_path
+
+==仅客户端==
+
+ECH PEM 配置路径
+
+如果为空，将尝试从 DNS 加载。
+
 ### ACME 字段
 
 !!! warning ""