Files
SimpleRemoter/docs/ClientEmbeddedTLS_Design.md
T
yuanyuanxianganddeepseek-flash c66f410831 Feature: Embed the server TLS certificate in delivered DLLs
Add a "高级 → DLL内嵌TLS证书" toggle (off by default, persisted as
[settings] EmbedTlsInDll). When it is on, ReadKernelDll patches the server's
current TLS anchor into the ServerDll and ShellCode payloads, so clients that
come online through the loaders start their own session over TLS without
waiting for an online push. The plaintext DLL loader in client/main.c is
untouched; only the DLL's fresh connection is protected. The write happens
after SetServer and before CalcMD5FromBytes, and the anchor records the host
part of the master address rather than "ip:port" because the client matches
the anchor against its configured address set. TinyRun has no anchor block and
keeps working as before.

Toggling the switch, and confirming the certificate dialog, rebuild the six
payloads in place, so no server restart is needed after a certificate change.
The payload pointers are replaced as a whole, and the network threads that read
them (SendServerDll and TOKEN_GETVERSION) now take a dedicated critical section
for the full duration of use.

COMMAND_UPDATE no longer clears the tls_disabled marker on the client. Now that
any delivered DLL may carry the anchor, "the payload has an anchor" no longer
means the operator opted this host into TLS, and clearing the marker would
silently flip a host that was explicitly set to plaintext onto TLS against a
plaintext path. Re-enabling TLS stays an explicit action through
COMMAND_TLS_ENABLE and COMMAND_SET_PROTO, which still clear the marker.

Menu and notice strings were added to en_US, zh_TW and de_DE, and the embedded
TLS design document records the new switch and the revised update semantics.

The new menu entry also takes a feature-limits slot so a subordinate master
can hide it like every other 高级 item (see 8807321):
HIDE_MENU_EMBED_TLS_ANCHOR in UIBranding.h, MF_EMBED_TLS_ANCHOR at bit 57
in FeatureFlags.h (the first free one after MF_FILE_SPEED), a row in the
主菜单 tab of CFeatureLimitsDlg, and the matching DeleteMenu on the 高级
menu. The entry still has no bitmap of its own, so it renders without an
icon next to its three siblings.

Co-Authored-By: deepseek-flash
2026-11-02 18:30:37 +01:00

779 lines
61 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.
# 客户端内嵌服务端 TLS 信任锚设计(生成即 TLS)
> 版本:v1.0 · 状态:**已实现(Windows 客户端 + MFC 服务端)** · 日期:2026-11-01
> 关联:`docs/TransportTLS_Design.md`(传输层单向 TLS)、`docs/TransportTLS_MFCServer_Design.md`(MFC 服务端)、
> `server/2015Remote/BuiltinTlsCert.*`(内置证书)
>
> 需求原文:服务端启用 TLS 时,生成客户端就希望把服务端 TLS 内嵌进客户端,让分发出去的客户端一开始就是 TLS。
> 两个待讨论问题:
> 1. 生成客户端时是否增加一个类型来标识客户端协议,比如 `TCP+TLS`?
> 2. 客户端的 `CONNECT_ADDRESS` 剩余空间只有 496 字节,肯定存不下,怎么解决?
>
> v0.3 裁定 §10 全部待定问题(§10 转为决议记录),并补入分享/转移的证书约束与分享实例的 TLS 指令隔离(§3.8)。
> v0.2 相对 v0.1 的改动见 §12(一轮独立审查后的修订),v0.3 的改动见 §13,
> v1.0 的实施偏差与实测记录见 §14。
## 1. 结论摘要
| 问题 | 结论 |
|---|---|
| 是否新增 `protoType`(如 `TCP+TLS`) | **不新增**。生成界面用复选框表达;TLS 状态仍由「有没有信任锚」决定 |
| 496 字节放不下怎么办 | **不动 `CONNECT_ADDRESS`**。在客户端 payload 里放一个独立、自描述的锚块(约 4.2 KB),生成时原地写入 |
| 分享/转移是否要求新主控同证书 | **要求**(对"已下发锚"成立,且今天就是这样)。内嵌锚因绑主控地址而不受此限(§3.8) |
| 分享实例能否被 TLS 启停 | **不能**,与「被分享的主机无权切换协议」同策略,一律忽略(§3.8) |
三条此前没意识到、但会决定方案成败的约束,都在 §3 里展开:
- **锚必须绑主控地址**,否则分享/被转移的客户端会连不上第二台主控(§3.6,阻塞级);
- **锚块必须是"不可被优化掉"的全局变量**,否则 LTCG 会把它整个删掉(§3.3);
- **"取消 TLS"指令送不到离线客户端**,关闭服务端 TLS 是一次单向门(§3.5)。
---
## 2. 现状核实
### 2.1 服务端:TLS 已就绪且默认开启
- `IOCPServer::StartServer()` 第一行无条件执行 `ServerTlsIdentity::Load(THIS_CFG)`(`server/2015Remote/IOCPServer.cpp:491`),在监听套接字创建之前。
- `Load()`(`server/2015Remote/ServerTlsSession.cpp:134`)里 `Enabled` 缺省为 1;`CertPath`/`KeyPath` 都为空时走内置证书分支,`BuiltinTlsCert::Ensure()` 首次生成自签证书并写入配置。
- `ServerTlsIdentity::AnchorPem()` 给出当前信任锚 PEM(内置证书时即该自签证书本身;自定义证书时是**证书文件全文**,`ServerTlsSession.cpp:198`)。
- 设备端口按 ClientHello 逐连接嗅探;`IsReady()==false` 时在 `StartTlsHandshake()`(`IOCPServer.cpp:988`)里 fail-closed 关闭。明文连接无条件放行(`IOCPServer.cpp:1202`)。
**实测数据**:内置证书 PEM **1042 字节**(DER 约 730 字节,RSA-2048 / SHA-256 / CN=yama-server / 10 年有效期)。
### 2.2 客户端:信任锚的三个来源与优先级
`client/TlsChannel.cpp` 的 `ReadTrustAnchor()`(第 62 行)按以下顺序取锚:
1. 注册表 `Software\<exe 路径哈希>\settings\tls_cert`(REG_SZ,直接存 PEM 正文);
2. `settings.ini [settings] tls_cert`(值是**文件路径**),或 exe 同目录 `yama-ca.pem`;
3. 都没有 → 未配置 → 明文。
`TlsEnabled()` == 「当前有没有可用的信任锚」;`TlsEnabledFor(连接目标, 配置里的原始地址)` 是同一问题的**按连接**答案(见 §3.6)。在 `IOCPClient::ConnectServer` 里它是传输层唯一判据:
```cpp
// client/IOCPClient.cpp:540
const std::string tlsConfigured = m_Domain.GetAddress();
if (TlsEnabledFor(m_sCurIP, tlsConfigured) && protoType != PROTO_WS) { /* 握手 */ }
```
> **注意适用范围**:这个判据只存在于 `IOCPClient::ConnectServer`。`IOCPUDPClient` 与 `IOCPKCPClient` 各自 `override ConnectServer`(`IOCPUDPClient.h:11`、`IOCPKCPClient.h:13`),**完全不走 TLS**。详见 §3.7。
### 2.3 现有的下发通道
- `COMMAND_TLS_ENABLE`(`client/KernelManager.cpp:881`):载荷即 PEM 正文,写入注册表后 `ApplyTlsAnchorChange()` 热重载;传输方式变化才断线重连。
- `COMMAND_TLS_DISABLE`(`client/KernelManager.cpp:894`):**只** `RegDeleteValueA(hKey, "tls_cert")`,再热重载。注意服务端入口 `OnExperimentTlsDisable`(`2015RemoteDlg.cpp:5123`)在 `!ServerTlsIdentity::IsReady()` 时**直接拒绝发送**——这条限制在本设计下必须去掉(§3.5)。
- `COMMAND_SET_PROTO`(WSS)随包下发锚(`ProtoSwitchPacket.certLen` + PEM)。
### 2.4 生成客户端的两条路径
**路径 A:生成界面**(`server/2015Remote/BuildDlg.cpp`)
读内嵌/外部资源 → 构造 `CONNECT_ADDRESS` → 按 `szFlag`(`FLAG_FINDEN`)在 payload 里扫描 → `memcpy(ptr+iOffset, &g_ConnectAddress, sizeof(g_ConnectAddress))`(第 581 行)→ 写文件 → 可选压缩/加壳/伪装。默认压缩是 `CLIENT_COMPRESS_SC_AES_OLD`(第 863 行)。
**路径 B:在线下发**(`2015RemoteDlg.cpp:5239` `ReadExeFromResource()`)
同样扫描并改写 `CONNECT_ADDRESS`,用于 `COMMAND_UPDATE`(在线更新)与 `COMMAND_UPLOAD_EXEC`(远程执行),三个调用点:`5334`、`12177`、`12190`。
### 2.5 各生成目标是否含客户端代码
| 生成目标 | 产出文件 | 编译单元 | 可内嵌 |
|---|---|---|---|
| `IndexGhost` / `IndexGhostMsc` / `IndexGhostSystem` | `ghost.exe` | `ghost_vs2015.vcxproj` 直接编 `ClientDll.cpp` + `TlsChannel.cpp` | ✅ |
| `IndexServerDll` | `ServerDll.dll` | `ClientDll_vs2015.vcxproj`(ProjectName=ServerDll),同上 | ✅ |
| `IndexTestRun_*` | `TestRun.exe` | `TestRun_vs2015.vcxproj`,**纯加载器**,不含客户端代码 | ❌(锚要在 `ServerDll.dll` 里) |
| `IndexTinyRun` | `TinyRun.dll` | `TinyRun.vcxproj`,仅 `main.c`,无 TLS 通道 | ❌ |
| `IndexLinuxGhost` / `IndexMacGhost` / `IndexAndroidGhost` | `ghost` / `ghost.apk` | 各平台工程 | 本期不做 |
### 2.6 `CONNECT_ADDRESS` 的空间账
`common/commands.h:884` 起,`#pragma pack(push,4)`:
- `char szFututre[496];`(第 909 行,结构体尾部)——全代码库**零引用**;
- `char szReserved[11];`(第 899 行,位于 `runasAdmin` 与 `clientID` 之间)——全代码库**零引用**。
两者**不相邻**(中间隔着 `clientID/parentHwnd/superAdmin/pwdHash/install*`),不存在 507 字节的连续空洞;扩展 `szReserved` 还会移动其后所有字段,破坏性与扩尾相同。可用的只有尾部 496 字节。
内置证书 PEM 1042 字节,裸 DER 约 730 字节 —— **单张自签证书都放不下**,CA fullchain(约 3.5 KB)差得更远。
---
## 3. 关键决策
### 3.1 D1:不新增 `protoType`
`protoType` 是「传输方式」,TLS 是「是否加密」。在 TCP/HTTP/WS/WSS 这几条路径上两者正交(§2.2),而 `protoType` 恰恰是这份代码里被改写次数最多的字段:
| 位置 | 行为 |
|---|---|
| `BuildDlg.cpp:545` | `GetCurSel()` 直接当协议值;注释明确「序号即取值,中间不能有空洞」 |
| `KernelManager.cpp:41` | `PROTO_RANDOM` 每次连接随机化 |
| `ClientDll.cpp:634` `ApplyProtoSwitch` | 在线升级换 DLL 时被外壳注入的 `protoType` 改写 |
| `2015RemoteDlg.cpp:5259` | 在线下发客户端时再写一遍 |
| `KernelManager.cpp:39` `NewNetClient` | 按值分流,`PROTO_HTTPS` 直接返回 `NULL` |
再加一个枚举值就要在以上五处加分支,并处理「proto=TLS 但没锚」「有锚但 proto=TCP」两类矛盾态。而且它**解决不了 UDP/KCP 的问题**(§3.7)——那需要在复选框上做能力判断,不是加一个协议值能解决的。
**替代**:生成界面加复选框「内嵌服务端 TLS 信任锚(首连即 TLS)」。协议仍为 TCP。
> 若希望下拉框里看得见 `TCP+TLS`,做法是 **UI 别名**:选中它只置 `protoType = PROTO_TCP` 并勾选内嵌复选框,**不产生新的线值**。本文推荐独立复选框。
### 3.2 D2:独立自描述锚块,不动 `CONNECT_ADDRESS`
| 方案 | 结论 | 否决原因 |
|---|---|---|
| **B(采用)** payload 内独立锚块 | ✅ | — |
| A. 把 `szFututre` 扩到 4 KB | ❌ | 生成端 `memcpy(..., sizeof(g_ConnectAddress))` 会按**新**结构体长度写进**老** stub,越界约 3.6 KB,静默损坏且无告警;`szBuildDate` 比的是日期不是尺寸。另外 `ModifyFlag()` 值返回、`new CONNECT_ADDRESS(*conn)` 每实例复制 4 KB |
| C. PE 资源(`UpdateResource`/`FindResource`) | ❌ | MemoryModule 手动映射时拿不到资源(同类问题已见 `chat-dialog-missing-on-shellcode-client`);UPX、SC 变体同样不可靠 |
| D. PE 尾部追加 | ❌ | UPX 后读自己文件是压缩字节;纯 ShellCode 变体没有文件可读 |
| E. 外置 `yama-ca.pem` / `settings.ini` | ⚠️ | **今天已经支持**(§2.2 第 2 级),保留为兜底与调试手段,但不符合「内嵌」要求 |
| F. 只存哈希做钉扎(32 字节) | ❌ | 要新增一条手工校验路径(`SCH_CRED_MANUAL_CRED_VALIDATION` + `SECPKG_ATTR_REMOTE_CERT_CONTEXT`),丢掉链校验,换证书同样全死 |
| G. TOFU:首连明文,登录后自动下发 | ⚠️ | 首连是明文,恰是本需求要消灭的。仅作容错(§6.1) |
**为什么 B 能覆盖所有包装形态**:锚块与 `CONNECT_ADDRESS` 在**同一个镜像、同一条字节搬运路径**上。生成端在写文件(`BuildDlg.cpp:608`)之前就完成写入,其后的 UPX、`MakeShellcode`(`2015RemoteDlg.cpp:2221` 的 `ConvertToShellcode`)、ShellCode BIN、图片/ZIP/PDF 伪装全部在其下游。凡 `CONNECT_ADDRESS` 能活到运行时的变体,锚块也一定能。
**为什么 B 对老 stub 安全**:老 stub 里没有锚块 → 生成端报 `NoBlock` 并**放弃生成**,不会越界写。A 方案做不到这一点。
### 3.3 D3:锚块格式、容量与"不被优化掉"
共享结构放 `common/tls_anchor.h`:
```cpp
#pragma pack(push, 4)
struct EmbeddedTlsAnchor {
char magic[16]; // "YAMA_TLS_ANCHOR"
uint32_t version; // 1
uint32_t capacity; // sizeof(pem),stub 的编译期常量
uint32_t length; // 实际写入的 PEM 字节数;0 = 未内嵌
uint32_t hash; // FNV-1a(pem[0..length)),半截写入可立刻识别
char master[100]; // 生成时配置的主控地址(明文,含分号多地址),见 §3.6
char pem[4096];
};
#pragma pack(pop)
// sizeof == 4228
```
**定义方式(关键,不能省)**:在**独立编译单元** `client/EmbeddedTlsAnchor.cpp` 里定义,且必须
```cpp
volatile EmbeddedTlsAnchor g_embeddedTlsAnchor = {
{ 'Y','A','M','A','_','T','L','S','_','A','N','C','H','O','R','\0' },
1, 4096, 0, 0, { 0 }, { 0 }
};
```
理由:`ghost_vs2015.vcxproj` / `ClientDll_vs2015.vcxproj` 都是 `WholeProgramOptimization=true`(第 46/53 行)+ `Optimization=MinSpace`(139/163 行)+ `EnableCOMDATFolding/OptimizeReferences=true`(150/151 行)。若把它写成 `const`,`length` 恒为 0,`IsAnchorBlockValid()` 会被内联并常量折叠为 `false`,唯一的读取点随之变成死代码,**整个对象可被 LTO 删除**——结果就是所有生成都报 `NoBlock`。`volatile` + 独立 TU + 外部链接,三重保证它必须被发射。
**必须含非零初值**:全零初值会落进 `.bss`,文件里没有这些字节,生成端扫不到 magic。
**查找与校验(关键)**:magic 字符串在二进制里**不止一份**——`"YAMA_TLS_ANCHOR"` 字面量本身也会在 `.rdata` 里出现一次。因此生成端不能"找到第一处就写",必须:
1. `MemoryFind` 扫出**所有** magic 命中;
2. 对每个命中按结构体校验:`version == 1 && capacity == 4096`,且 `length == 0 ? hash == 0 : hash == Fnv1a(pem, length)`;
3. **恰好一个**通过 → 写它;**零个** → `NoBlock`;**多于一个** → `Ambiguous`(宁可报错也不猜)。
容量取 4096:自签证书 1042 B、Let's Encrypt fullchain 约 3.5 KB 都放得下。代价是每个 stub 多约 4.2 KB。超长时**报错,绝不截断**——截断的 PEM 会让客户端进入 fail-closed 且无恢复通道(§6.1)。
### 3.4 D4:读取优先级
`ReadTrustAnchor()` 改为四级(新增的两级加粗):
1. 注册表 `settings\tls_disabled == "1"` → **未配置**(明文),直接返回;
2. 注册表 `settings\tls_cert` 存在 → 用它(值为空仍按 fail-closed 处理,语义不变);
3. `settings.ini [settings] tls_cert` 路径 / exe 同目录 `yama-ca.pem` → 用它;
4. **内嵌锚块**:`length > 0`、hash 校验通过、**且主控地址匹配**(§3.6)→ 用它;
5. 都没有 → 明文。
注册表代表「运维近期下发过」,优先级最高;文件代表「手工投放」,可覆盖构建期默认;内嵌锚是出厂默认。`source` 字符串新增 `"embedded"`。
### 3.5 D5:取消 TLS 的抑制标记,及其边界
**必须补的坑**:现有 `COMMAND_TLS_DISABLE` 只删注册表值;若内嵌锚仍在,客户端会回落到内嵌锚继续 TLS,而服务端此时按明文处理 → ClientHello 被嗅探到但 `IsReady()==false` → fail-closed 关闭 → 客户端再也连不上。
处理:
- `COMMAND_TLS_DISABLE`:写 `settings\tls_disabled = "1"` → 删 `tls_cert` → 热重载;
- `COMMAND_TLS_ENABLE`:删 `tls_disabled` → 写 `tls_cert` → 热重载;
- `COMMAND_SET_PROTO`(WSS,`certLen > 0` 时):**也要删 `tls_disabled`**。否则 `BuildTlsAnchor` 返回 `TLS_ANCHOR_NONE`,`ApplyTlsStateLocked` 走成功分支(`TlsChannel.cpp:203`)把 `g_tlsEnabled` 置 false 并返回 true,切换照常进行、`m_useTls` 保持 false,最终**静默降级成明文 WS**(`IOCPClient.cpp:551`)——正是该分支注释里说要避免的事。
- 服务端 `OnExperimentTlsDisable`(`2015RemoteDlg.cpp:5123`)的 `if (!IsReady()) return;` 守卫**必须去掉**:否则服务端一旦关掉 TLS,就再也无法给在线主机下发"取消 TLS",客户端直接被锁死。
**必须承认的边界(v0.1 说得过头了)**:抑制标记只能通过一条**已经连上的**连接送达。
- 在线主机:指令送达 → 回落明文 → 正常。
- **离线主机 / 刚生成就指向已关闭 TLS 的服务端的主机**:它发 ClientHello → 服务端 `StartTlsHandshake` fail-closed → 永远收不到标记 → **永久失联**,只能重新生成客户端。
因此「关闭服务端 TLS」对已分发内嵌锚客户端是一次**单向门**。运维规程(写进 §6.1 与用户手册):**先对全部在线主机下发"取消 TLS",确认列表里不再有内嵌锚主机,再关闭服务端 TLS**。
为让操作员看得见,新增一个能力位(仿 `CLIENT_CAP_PROTO_SWITCH`,`server/2015Remote/context.h:110`):`CLIENT_CAP_EMBEDDED_ANCHOR`,客户端在**本次连接**的 TLS 锚来源为 `embedded` 时上报(`IOCPClient::IsTlsAnchorEmbedded()`,取自该连接握手时校验用的那套状态,见 §3.6)。在线列表与「取消 TLS」确认框据此提示"选中的主机里有 N 台使用内嵌信任锚"。
### 3.6 D6:锚必须绑定主控地址(阻塞级)
一个客户端会被指向**另一台主控**,而内嵌锚钉的是生成时那台:
```cpp
// client/ClientDll.cpp:743 —— 被转移(assigned)的客户端改连新主控
auto saved_ip = cfg.GetStr("settings", "master");
settings.SetServer(saved_ip.c_str(), saved_port);
// client/ClientDll.cpp:788 —— 分享列表里的实例连到别的分享主控
auto a = NewClientStartArg(shareList[i].c_str(), IsSharedRunning, TRUE, proto, transport);
```
两条路径最终都走 `IOCPClient::ConnectServer` 的 `if (TlsEnabled() && ...) Handshake()`。今天的客户端没有锚,所以连过去是明文、由对方下发自己的锚;**有了内嵌锚就会用 A 的证书去校验 B,握手失败即 fail-closed,分享/转移功能直接失效且无法自愈**。
**做法**:锚块里存生成时的主控地址 `master[100]`(明文原样存 `m_strIP`,含分号多地址,不受 `bEncrypt` 影响)。判定**按连接**做,位置在 `TlsChannel::Handshake()` 入口(`TlsChannel.cpp` 的 `ResolveStateIndex`),依据是这条连接自己的目标地址:
```
本连接目标与锚的主控地址相交 → 本连接用内嵌锚
否则 → 本连接不用内嵌锚(记一行日志),回落到「明文首连 + 由对方下发」
```
「相交」分两层,任一命中即可:
1. 配置里只写了一个地址,且与锚的主控地址字符串相等(域名对域名,不依赖 DNS 答案在两次查询之间保持一致);
2. 连接目标 IP 与锚的主控地址(可能分号多地址、可能是域名)解析出的 IPv4 有交集——并行多主控实例连的是 `DomainPool` 解析后的单个 IP,生成端填的却是域名,只能靠这一层。
被转移的客户端(`assigned`)、分享实例(`IsSharedRunning`)与并行多主控实例都会因为地址不匹配而自动跳过内嵌锚,行为与今天一致。转移窗口过期后仍按同一规则重新判定。
> **不能写成进程级开关**:分享实例与并行实例是**同一进程里的线程**,`TlsChannel` 的状态又是首次访问即缓存。v1.0 实施初稿把判定放在 `ClientDll.cpp::StartClient()` 写一个全局标志,先连上的实例替所有实例做了决定(分享连接/并行连接因此被判成该用 A 的锚 → fail-closed)。现按连接判定,且「允许内嵌锚」「不允许」各缓存一套 store + 链引擎,能力位也随之按连接上报。
> 这条路选"地址匹配"而不是"进程标志",是因为转移/分享的目标地址就写在配置里,判定不依赖任何额外状态,也不会在重连循环里漂移。
### 3.7 D7:UDP / KCP / 随机 协议不支持内嵌
`IOCPUDPClient` 与 `IOCPKCPClient` 各自 override `ConnectServer`,代码里**完全没有 TLS**(两个文件里 `Tls`/`Handshake` 零命中)。因此:
- 协议选 `UDP` / `KCP` / `随机` 时,**内嵌复选框置灰**,提示"该协议不走 TLS";
- 既有的 `LoginServer.cpp:476` `AddReserved(TlsEnabled() ? 1 : 0)` 在这些协议下会**误报加密**(`TlsEnabled()` 为 true 但连接是明文 UDP/KCP)。这是既有缺陷,本设计一并改为按实际传输上报。
**落地时收窄为「只有 `TCP` / `HTTP` 可内嵌」**(v0.3 定稿是「排除 UDP/KCP/随机」,v1.0 实施收窄):
| 协议 | 内嵌锚的结局 | 结论 |
|---|---|---|
| `TCP` / `HTTP` | 直连本服务端,锚就是本服务端的证书 | ✅ 可用 |
| `WS` | `ConnectServer` 的 `protoType != PROTO_WS` 判断直接跳过 TLS 通道,锚永不参与 | 🚫 无意义 |
| `WSS` | 锚被拿去校验**反向代理**(nginx/Let's Encrypt)的证书,不是本服务端的证书 → 换成内嵌锚反而会让原本靠 `yama-ca.pem` 能连的客户端握手失败 | 🚫 有害 |
`WSS` 的锚由「协议切换」随包下发(`ProtoSwitchPacket` 后的 PEM,见 `KernelManager.cpp` 的 `COMMAND_SET_PROTO` 分支),与内嵌锚互不相干。
### 3.8 D8:分享 / 转移与 TLS(本期约束,不改变既有语义)
客户端被指向另一台主控有两条路径(见 §3.6 引用的 `ClientDll.cpp:735` 与 `:766`),它会把**当前生效的锚**一并带过去。锚不绑地址(只有 §3.6 的内嵌锚有地址绑定),于是:
| 客户端持有的锚 | 新主控 B | 结果 |
|---|---|---|
| 已下发(注册表 `tls_cert`) | 与 A **同一张**证书/私钥 | ✅ 正常,仍是 TLS |
| 已下发(注册表 `tls_cert`) | **不同**证书 | ❌ 校验失败 → 客户端 fail-closed |
| 已下发(注册表 `tls_cert`) | 未开 TLS | ❌ 客户端发 ClientHello,B 在 `StartTlsHandshake`(`IOCPServer.cpp:988`)`IsReady()==false` → fail-closed |
| 内嵌锚 | 任何配置 | ✅ §3.6 地址不匹配即跳过 → 明文首连 → B 下发自己的锚 |
| 无锚 | 未开 TLS | ✅ 明文 |
**没有"降级回明文"的退路**:发不发 ClientHello 由 `TlsEnabled()`(只看有没有锚)决定,不看对端是谁。
因此:**只要客户端持有"已下发锚",分享/转移就要求新主控使用同一张证书**——这是今天就已成立的行为,不是本设计引入的。本期**不引入**按主控分键存锚(`tls_cert_<hash(master)>`),而是把它固化为运维约束:
- 多主控部署时把同一对证书/私钥同步到所有主控;内置证书时即把 `[tls] BuiltinCert` / `BuiltinKey` 两项复制过去(它们是 base64 文本,运维上等价于分发同一张自签证书);
- 或**先对目标主机下发"取消 TLS",再转移/分享**。转移完成后原主控已联系不上该主机,这一步不能补。
**分享实例必须隔离 TLS 指令**(新增,约 5 行)。分享实例与主实例是**同一进程里的两个 `ClientApp` 线程**(同一 exe 路径,同一份内存配置),注册表键同为 `Software\<exe 路径哈希>\settings`(`common/iniFile.h:54`),连进程内的 TLS 状态也是共用的。若允许 B 给分享实例下发 `COMMAND_TLS_ENABLE`,写入的正是 A 也在读的 `tls_cert`:
1. 主实例下次重连会用 B 的证书去校验 A → 握手失败;
2. A 从此彻底连不上这台主机(fail-closed),**只能到现场处理**。
`COMMAND_SET_PROTO` 已因同一理由忽略分享实例(`KernelManager.cpp:915-920`,注释:"分享实例的连接入口由分享方控制,主控的协议切换对它无效")。TLS 启停沿用这条策略——与「被分享的主机无权切换协议」一致——`COMMAND_TLS_ENABLE` / `COMMAND_TLS_DISABLE` 在 `IsShared()` 时一律忽略并记一行日志。
代价:分享连接永远不加密(与今天一致)。要支持"多主控各自不同证书都加密",需把锚改为按主控分键存放并处理迁移,留作后续版本。
---
## 4. 详细设计
### 4.1 `common/tls_anchor.h`(新增)
结构如 §3.3;另提供:
```cpp
constexpr uint32_t kAnchorVersion = 1;
constexpr uint32_t kAnchorCapacity = 4096;
uint32_t Fnv1a(const char* data, size_t len); // 与 GetExeHashStr 同一算法
bool IsAnchorBlockValid(const EmbeddedTlsAnchor& a); // version/capacity/hash 全检
```
magic 用**字节初始化列表**写进结构体,不要在运行时引用一个独立的 16 字节常量对象(否则 `.rdata` 里多一份副本,见 §3.3 的查找规则)。
### 4.2 客户端 `client/EmbeddedTlsAnchor.cpp` / `.h`(新增)
`g_embeddedTlsAnchor` 的定义、`GetEmbeddedTlsAnchor()` 访问器。单独成 TU 是为了 §3.3 的发射保证。
### 4.3 客户端 `client/TlsChannel.cpp`
1. `ReadTrustAnchor(pem, source, allowEmbedded, quiet)`:
- 函数开头处理 `tls_disabled`;
- 末尾追加内嵌锚分支:`length > 0` + hash 校验 + `allowEmbedded`(是否允许由调用方按连接决定,见第 3 条);
- hash 校验失败但 `length > 0`:记一行 `Mprintf`,按未配置处理(§6.4)。
2. **两套缓存状态**:`TlsState g_state[2]`——`[1]` 允许内嵌锚、`[0]` 不允许,各自带 store + 链引擎,首次访问时经 `EnsureStateLocked` 建好;`BuildTlsAnchor` / `ApplyTlsStateLocked` 增加 `allowEmbedded` / `quiet` 参数(`quiet` 用于「本连接不用」那套,避免把不适用本连接的 enabled 行印在本连接状态之前)。`TlsReload` 一次重建两套,任一套失败只影响它自己(运行期失败保留原状态,不打死正在工作的客户端)。
3. **按连接判定**:`ResolveStateIndex(host, configured)` 即 §3.6 的两层地址匹配,带 DNS 结果缓存(成功永久缓存、失败负缓存 60 秒),**且必须在取 `g_tlsMtx` 之前调用**——解析域名可能阻塞数秒,不能压在证书校验那把锁里。在 `Handshake()` 开始时定下用哪一套状态(`m_stateIdx`);`VerifyServerCert()` 用 `g_state[m_stateIdx]`,同时把来源写进 `m_anchorEmbedded`(能力位用)。对外接口为 `TlsEnabledFor()` / `TlsLoadErrorFor()` / `TlsChannel::AnchorEmbedded()`。
### 4.4 客户端 `client/KernelManager.cpp`
`COMMAND_TLS_ENABLE` / `COMMAND_TLS_DISABLE` / `COMMAND_SET_PROTO` 三处加 `tls_disabled` 读写(§3.5)。`m_cfg` 恒为 `new iniFile(CLIENT_PATH)`(`KernelManager.cpp:79`),与 `ReadTrustAnchor` 直接读的注册表位置一致,无后端错配。
`COMMAND_TLS_ENABLE` / `COMMAND_TLS_DISABLE` 入口再加一道分享实例判断(§3.8),与 `COMMAND_SET_PROTO`(`KernelManager.cpp:917`)同一策略:
```cpp
if (m_ClientApp && m_ClientApp->IsShared()) {
Mprintf("[TLS] ignored: shared instance follows the sharing host's anchor\n");
break;
}
```
### 4.5 客户端 `client/ClientDll.cpp`
`StartClient()` **不再**比对锚块、也不设任何进程标志(§3.6 的地址判定与 TLS 状态都在 `TlsChannel` 里按连接完成)。登录时上报能力位:`LoginServer::GetLoginInfo(..., ClientObject->IsTlsActive(), ClientObject->IsTlsAnchorEmbedded())`。
### 4.6 服务端 `server/2015Remote/EmbeddedAnchor.h/.cpp`(新增)
```cpp
enum class EmbedResult { Ok, NoBlock, Ambiguous, NoAnchor, TooLong };
EmbedResult EmbedTlsAnchorInto(BYTE* payload, DWORD size, const std::string& master,
DWORD& pemLen, std::string& err);
bool TlsAnchorSummary(std::string& out); // "builtin 2036-11-01 sha1:1a2b3c4d5e6f"
```
实现按 §3.3 的三步校验;写入 `version/length/hash/master/pem`,`pem` 与 `master` 尾部清零。超长报错并带实际字节数。**必须在压缩/加壳之前调用**。
`TlsAnchorSummary` 是 v1.0 实施时新增的:把 PEM 的第一张证书解出来,取 `NotAfter` 与
`CERT_SHA1_HASH_PROP_ID` 前 12 位,拼成一行摘要。用途见 §4.7 最后一条。
(v0.3 还计划过一个 `PayloadSupportsEmbeddedAnchor()`,实施时删掉了:它和
`EmbedTlsAnchorInto()` 的 `NoBlock` 返回值信息重复,留着只是死代码。)
### 4.7 生成界面 `server/2015Remote/BuildDlg.cpp/.h`
- `OnInitDialog()` 里 `CButton::Create()` **动态创建**复选框,DLU 矩形 `(216, 70, 412, 82)`
——「协议」行与「Port」行之间的空白带;文案走 `_TR()`,控件 ID 为
`IDC_CHECK_TLS_ANCHOR`(`resource.h` 2621)。不改进 `.rc` 的理由是位置与文案只在一个
地方维护;`.rc` 本身是 UTF-16,并非不能编辑。
- 可用性三条件,任一不满足即置灰:`ServerTlsIdentity::IsReady()`;生成目标含客户端代码
(§2.5);协议是 `TCP`/`HTTP`(§3.7 的收窄结论)。
- **置灰时把原因写进文案本身**(`内嵌TLS信任锚(服务端未启用TLS)` 等 5 种形态),因为置灰
控件收不到 tooltip——`CBuildDlg` 的 tooltip 只在 `IDC_SLIDER_CLIENT_SIZE` 上生效。
- 勾选状态用三态 `m_nAnchorUserCheck`(-1 未表态 / 0 / 1):没表过态就默认勾选,表过态就
以用户的为准。不能用「由不可用变为可用就打勾」——那样用户取消后切一次协议再切回来,
取消会被悄悄改回勾选(§14.5 第 2 条)。
- 生成流程里在 `CONNECT_ADDRESS` 补丁循环之后、写文件之前调用 `EmbedTlsAnchorInto()`。
**写了一半失败一律放弃生成**(`Ambiguous` / `NoAnchor` / `TooLong`,提示里带 `err` 原文);
`NoBlock` 是例外——模板里压根没有锚块,一个字节都没动,此时提示一句、取消勾选、**照常
生成**。否则「升级主控后忘了重编 ghost/ServerDll 资源」会让每次生成都被那个默认勾选挡住。
- 锚摘要**不在复选框旁**,而是放在生成成功后的提示里(`已内嵌TLS信任锚: builtin 2036-11-01
sha1:…`):那条空白带只有 196 DLU(约 24 个全角字),放不下摘要;而「这批客户端钉的是
哪张证书」在生成那一刻核对即可。
- `TestRun` 系列:置灰,文案为 `内嵌TLS信任锚(锚在ServerDll.dll里)`;生成 `ServerDll.dll`
时若没勾,给一条**非阻塞提示**(`提示: 未内嵌TLS信任锚,本批客户端首次连接为明文…`)。
### 4.8 在线下发路径 `server/2015Remote/2015RemoteDlg.cpp`
`ReadExeFromResource()` 在 `CONNECT_ADDRESS` 循环之后调用 `EmbedTlsAnchorInto()`:`Ok` 则内嵌;
`NoBlock` / `NoAnchor` **静默跳过**(目标可能是 Linux/macOS 客户端或用户自选文件);其余失败
只写一行 `Mprintf`,不中断下发。注意传 `outSize` 而不是 `dwFileSize`——扫描循环已经把后者
递减成「剩余未扫描长度」。
`COMMAND_UPDATE` **不再**顺带清 `tls_disabled`(2026-11-02 修订,见 §6.5)。服务端新增
「高级→DLL内嵌TLS证书」开关后,凡开启期间下发的 ServerDll 都带锚,「镜像里带锚」不再代表
运维特意为这台主机启用 TLS;照旧清除会把运维明确设过的「取消 TLS」在升级时静默翻掉。
重新启用仍走显式命令 `COMMAND_TLS_ENABLE`(在线列表右键「TLS 传输」),那条路径照常清标记。
**DLL 内嵌开关(2026-11-02 新增)**:主对话框「高级→DLL内嵌TLS证书」,默认关,勾选状态存
`[settings] EmbedTlsInDll`。勾选后 `ReadKernelDll()` 在 `SetServer()` 之后、`CalcMD5FromBytes()`
之前调用 `EmbedTlsAnchorInto()`,把服务端当前证书写进 ServerDll / ShellCode 的零值锚块(x86/x64
各一份);TinyRun 没有锚块,返回 `NoBlock` 属正常且不刷日志。锚里写的是 `server->szServerIP`
(纯主机名)而不是 `"ip:port"`——客户端 `EmbeddedAnchorAppliesTo` 按地址集合匹配,带端口两层
都匹配不上。锚必须在 md5 之前写入,否则 md5 不变、客户端会当作「内容没变」不重下。
MDLL 加载器(`client/main.c`)本身仍是明文:它只要 DLL,拿到后 MemoryModule 加载,之后 DLL 自己
新建的会话才是 TLS。切换开关或换证书后 `ReloadKernelPayloads()` 重生成六份载荷(替换指针,持
`m_csPayload`,网络线程读载荷处同样持锁),无需重启服务端;`OnTlsCertificate` 在确认后调用它。
### 4.9 服务端在线列表与「取消 TLS」
- 上报 `CLIENT_CAP_EMBEDDED_ANCHOR`(§3.5),列表可标注。
- `OnExperimentTlsDisable` 去掉 `IsReady()` 守卫(证书损坏时的恢复通道);确认框在
`ResolveCommandTargets()` + `m_cs` 下数出 `UsesEmbeddedAnchor()` 的台数,追加一句警告,
并把默认按钮改到「否」。首发文案沿用原文案,避免已有多语言译文作废。
### 4.10 语言文件
新增 11 条(键为简体中文原文):5 种复选框文案、`NoBlock` 报错、重试提示、摘要前缀、
`ServerDll` 未勾提示、内嵌锚台数警告、模板无锚块时照常生成的非阻塞提示。
台数警告的键带 `%d`(`%d 台主机使用生成时内嵌的信任锚:…`),由 `CString::Format` 填。不要
在代码里拼 `n + _TR("台主机…")`:英文/德文句首没有空格,拼出来就是 `3host(s) use`、
`3Host(s) nutzen`。
落盘:`lang/en_US.ini`、`lang/zh_TW.ini`(同时是内嵌 RCDATA)、`lang/de_DE.ini`。三者均为
**GBK、LF、无 BOM、按字节编辑**,键不能含 `=`,键里的换行写成字面 `\n`(`CIniParser::Unescape`
会还原)。
**源文件编码**:本仓库 `.cpp/.h` 是 **UTF-8 带 BOM**,而 ini 是 GBK——两者能对上,靠的是
编译器用 ACP(936) 作执行字符集把字面量转成 GBK。新增文件若漏了 BOM,MSVC 会按 GBK 解读 UTF-8
源码:CJK 注释里出现「尾字节 0x5C + 换行」就会行拼接,把后面几行吞进注释,报出一串
"`'{'` 语法错误" 且行号整体偏移。本次实施踩过一次,见 §14。
### 4.11 工程文件
`2015Remote_vs2015.vcxproj/.filters` 注册 `EmbeddedAnchor.h/.cpp`;`ghost_vs2015` /
`ClientDll_vs2015` 的 `.vcxproj` 与 `.filters` 注册 `EmbeddedTlsAnchor.h/.cpp`;
`common/tls_anchor.h` 只被 include,无需登记(这两个客户端工程本来也不登记 `common/` 下的文件)。
Linux 客户端编的是 `client/TlsChannelLinux.cpp`,不含 `LoginServer.cpp`,不受影响。
---
## 5. 前置问题与处置
### P1. Windows 客户端只加载 PEM 里的**第一张**证书(既有缺陷)
`client/TlsChannel.cpp:91` `LoadTrustAnchor()` 用 `CryptStringToBinaryA(..., CRYPT_STRING_ANY)` 解出一张证书后 `CertAddCertificateContextToStore` **一次**就返回;而 Linux 端 `client/TlsChannelLinux.cpp:120` `LoadAnchors()` 是**循环读完全部 PEM 块**。
影响:内置自签证书是单张,不受影响;用户自备 **leaf-first fullchain** 时,Windows 客户端只把叶证书放进独占根存储 → 链建不起来 → 握手失败 → fail-closed。即 `ServerTlsSession.cpp:198` 注释里"fullchain 一并下发"在 Windows 端并未真正生效。
与本设计的关系:§3.3 的 4096 容量是为 fullchain 留的;P1 不修则这句话只是容量上的空话。**已决定本期一并修**(约 30 行 + 一个 fullchain 用例),否则内嵌功能只能限定为「仅内置自签证书」。
修法:`LoadTrustAnchor()` 改为与 `TlsChannelLinux.cpp:120` 同构——循环 `CryptStringToBinaryA` 逐块解码(每轮用 `pdwSkip` 前进),每个块 `CertAddCertificateContextToStore` 一次,统计成功数量;至少一个成功才算配好锚。
### P2. stub 二进制与主控资源必须同版本
`ghost.exe` / `ServerDll.dll` 作为资源内嵌在主控里(`IDR_GHOST_X64` 等),也可能从 `res` 目录外部读取。未随本次改动重新编译 → 生成端 `NoBlock` 报错。这是**有意的显式失败**,不会产出坏文件。发布流程需提醒:**刷新 ghost / ServerDll 资源后再发布**(与 `linux/ghost` 由用户收尾提交的既有约定一致)。
### P3. 老客户端不认识 `tls_disabled` / 能力位
老客户端没有内嵌锚,也就没有抑制问题;多一个注册表值、少一个能力位都不影响它。**无兼容问题**。
---
## 6. 安全与运维影响
### 6.1 fail-closed 死锁与恢复通道(最重要的运维风险)
内嵌锚一旦与服务端实际证书不一致,客户端**首连即失败**,且失败后连不上服务端 → 收不到新锚 → 自我封死。触发条件:
1. 运维换了服务端证书(`CertPath`/`KeyPath`,或内置证书被重新生成);
2. 服务端的 Windows 用户变了 / 注册表被清(内置证书存在 HKCU,会重新生成一张);
3. 生成客户端时服务端起的是 A 证书,实际部署用的是 B;
4. 服务端关闭 TLS(§3.5)——在线主机可救,**离线主机不可救**。
**缓解**:
- 生成界面显示锚的**指纹前 12 位 + 有效期**,操作员可核对;
- 在线列表标注内嵌锚主机,「取消 TLS」前给出数量提示;
- 文档与用户手册明确两条单向门:**换证书 = 已分发客户端全部作废**;**关服务端 TLS 前必须先逐台下发取消**;
- **转移/分享前**:要么确认新主控持有同一张证书,要么先对目标主机下发「取消 TLS」(§3.8);
- 不在客户端做「握手失败 N 次后降级明文」——那是降级攻击面,与现有设计一致(`IOCPClient.cpp:526`)。
可选增强(不在本期):锚块写入多张证书(新老并存),给证书轮换留过渡窗口。P1 修好后 PEM 多块拼接天然可用。
### 6.2 取证影响
内嵌证书是**公开信息**,不降低传输安全性;但它把"这台主控用的是哪张自签证书"写死在样本里,取证方据此可关联同源样本。这是"内嵌"相对"下发"的固有代价。
### 6.3 抑制标记与能力位被篡改
`tls_disabled` 在客户端注册表(HKCU,当前用户可写)。能改它的攻击者同样能直接删 `tls_cert`;删掉标记只会让客户端回到内嵌锚状态,**仍是 TLS**。不构成新增攻击面。
### 6.4 锚块损坏时的行为
`length > 0` 但校验不过 → 记日志并按「未配置」处理,回落到下一级来源或明文。**不按 fail-closed 处理**:损坏的可能是构建产物本身,fail-closed 会让整批客户端彻底不可用;明文回落至少还能连上并接受 `COMMAND_TLS_ENABLE`。这与「注册表值为空 → fail-closed」的语义不同是有意的:注册表值代表运维的明确动作,锚块代表构建默认值。
### 6.5 抑制标记会"继承"到重新生成/更新的客户端
注册表以 **exe 全路径哈希**为键(`common/iniFile.h:54` `GetExeHashStr()`)。同一个安装路径重新生成或在线更新后,客户端的注册表状态**保留**,包括 `tls_disabled=1`。后果:运维刚内嵌的锚被上一轮的抑制标记悄悄作废,连接回到明文且无提示。
处理(v0.3 原案):`COMMAND_UPDATE` / `COMMAND_UPLOAD_EXEC` 下发新客户端时顺带清除 `tls_disabled`;且内嵌锚主机被抑制时,客户端日志与在线列表都要能看到(§4.9 的能力位)。
**2026-11-02 修订**:`COMMAND_UPDATE` 的自动清除已撤销(能力位上报不受影响)。服务端新增
「高级→DLL内嵌TLS证书」开关后,开启期间下发的 ServerDll 一律带锚,「镜像带锚」不再是「运维
特意为这台主机启用 TLS」的信号;继续自动清除,等于运维一升级被明确要求走明文的主机就把它翻回
TLS——对明文链路是不可恢复的失联。现在只有显式命令会清标记:`COMMAND_TLS_ENABLE` 与
`COMMAND_SET_PROTO`(WSS,`certLen > 0`)。代价是:被抑制过的主机在重新生成/更新后仍保持明文,
要切到内嵌锚得由运维再下发一次「TLS 传输」——刻意选的保守方向。
---
## 7. 兼容性矩阵
| 客户端 \ 服务端 | 未改动的老服务端 | 本设计的新服务端 |
|---|---|---|
| 老客户端(无锚块、无 tls_cert) | 明文,不变 | 明文,不变 |
| 老客户端 + 已下发 tls_cert | TLS,不变 | TLS,不变 |
| 新客户端(锚块 length=0) | 明文 | 明文 |
| 新客户端(内嵌锚,**同一主控**) | 连不上 | TLS,首连即加密 |
| 新客户端(内嵌锚,**被转移/分享到另一台主控**) | 明文(锚不匹配,跳过) | 明文首连,由对方下发自己的锚 → 之后 TLS |
| 已下发 `tls_cert` 的客户端,**被转移/分享到另一台主控**(新主控**不同**证书或未开 TLS) | 失败(锚不绑地址,§3.8) | 失败,**只能**先取消 TLS 或让新主控持有同一张证书 |
| 同上,新主控持有**同一张**证书 | TLS,不变 | TLS,不变 |
| 分享实例(`IsShared()`)收到 TLS 启停指令 | —— | 忽略,锚与主连接均不变(§3.8) |
| 新客户端 + 服务端已关闭 TLS | —— | 在线时可被下发取消;离线时永久失联(§3.5) |
| 任何客户端 + `UDP`/`KCP`/`随机` 协议 | 明文 | 明文(内嵌复选框已置灰,§3.7) |
「新客户端(内嵌锚)+ 老服务端」这一行:老服务端**没有嗅探逻辑**,会把 ClientHello 的首字节 `0x16` 当成普通命令字节喂给协议解析器,随后因协议不匹配断开(不是"按垃圾关闭",而是"误解析后超时/断开")。这是内嵌的必然后果;生成时若服务端 TLS 未就绪,复选框置灰,从流程上避免产出这种客户端。
---
## 8. 测试计划
**构建产物检查(不依赖运行)**
1. 生成 ghost.exe(不勾选)→ 锚块 `length == 0`;运行后日志 `[TLS] disabled: no trust anchor configured`。
2. 生成 ghost.exe(勾选)→ `length == 1042`、`hash` 匹配、`master` 与配置一致、PEM 与 `AnchorPem()` 逐字节相同;用 `ChainProbe` 复刻客户端校验,`dwErrorStatus == 0`。
3. 用未经刷新的老 ghost.exe 资源生成 → `NoBlock` 报错,**不产生输出文件**。
4. **四种包装各生成一份**(无压缩 / UPX / `PE->ShellCode` / **`ShellCode AES<Old>`(默认档)**),确认锚块内容一致。
5. 同一份 payload 里出现两份 magic 时(人为构造)→ `Ambiguous` 报错。
**端到端**
6. 服务端启用内置 TLS → 生成客户端 → 干净环境运行 → 服务端日志首连即握手,`openssl s_client` 独立验证 `Verification: OK`。
7. 下发"取消 TLS" → 客户端回落明文并重连成功;再下发"启用 TLS" → 回到 TLS。**服务端侧关掉 `[tls] Enabled` 后再下发取消 TLS 也要能发出去**(§3.5 守卫已去掉)。
8. 内嵌锚客户端 + WSS 切换:`tls_disabled` 状态下切换 WSS 必须**不**静默降级(§3.5 第三条)。
9. **分享/转移(内嵌锚)**:内嵌锚客户端被转移到另一台主控 → 明文首连成功、由对方下发锚后转 TLS;分享列表实例同样。
10. **分享/转移(已下发锚)**:先对主机下发 TLS,再转移到新主控。新主控**不同**证书 → 确认连不上(预期失败,§3.8 的约束生效);改走"先取消 TLS 再转移" → 明文连上、由新主控重新启用 TLS 成功。
11. **分享实例隔离**:主控 A 分享一台主机到 B,B 对该分享连接下发"启用 TLS" → 客户端日志出现 `[TLS] ignored: shared instance`,注册表 `tls_cert` 不变,主实例与 A 的连接**不受影响**。反向(`COMMAND_TLS_DISABLE`)同样。
12. `UDP`/`KCP`/`随机` 协议下复选框置灰(§3.7)。
13. mem-DLL 场景:`ServerDll.dll` 内嵌锚,`TestRun.exe` 运行后仍为首连 TLS;**故意用过期的 `ServerDll.dll`** 验证会明确报错而不是静默明文。
14. 在线更新(`COMMAND_UPDATE`)后:`tls_disabled` **保持不变**,被抑制的主机仍是明文(§6.5 修订);
要切到内嵌锚须显式下发「TLS 传输」。
**回归**
15. 老客户端(无锚)连新服务端,明文正常。
16. 已下发 `tls_cert` 的老客户端不受任何影响。
---
## 9. 工作量估算
| 项 | 规模 |
|---|---|
| `common/tls_anchor.h` | ~70 行 |
| `client/EmbeddedTlsAnchor.h/.cpp` | ~50 行 |
| `client/TlsChannel.cpp` | +50 行 |
| `client/KernelManager.cpp`(含 §3.8 分享实例隔离 5 行) | ±35 行 |
| `client/ClientDll.cpp`(主控地址比对) | +25 行 |
| `client/LoginServer.cpp`(如实上报 TLS) | ±10 行 |
| `server/2015Remote/EmbeddedAnchor.h/.cpp` | ~150 行 |
| `BuildDlg.cpp/.h` | +110 行 |
| `2015RemoteDlg.cpp`(下发 + 能力位 + 去守卫) | +50 行 |
| `context.h` 能力位 | +5 行 |
| 语言文件 ×3 | +6 条/个 |
| 工程文件 | 4 处 |
| **合计** | **约 555 行,含验证 3–4 天**(不含 P1) |
P1(Windows fullchain 循环加载):约 30 行 + 测试,半天。
---
## 10. 待定问题裁定(v0.3 已全部确认)
| # | 问题 | 裁定 | 落点 |
|---|---|---|---|
| 1 | UI 形态:独立复选框 vs 下拉框 `TCP+TLS` 别名 | **独立复选框**(不产生新的 `protoType` 线值) | §3.1、§4.7 |
| 2 | 默认是否勾选 | **条件满足时默认勾选** | §4.7 |
| 3 | 锚块容量 | **4096** | §3.3 |
| 4 | 抑制标记命名 | **`settings\tls_disabled`**(值 `"1"`) | §3.5 |
| 5 | P1(Windows 只加载 PEM 首张证书)是否本期修 | **本期修**,fullchain 能力才真正可用 | §5 P1 |
| 6 | Linux / macOS / Android 客户端 | **本期不做**,留到下一版 | §2.5 |
| 7 | 锚绑定主控地址的策略 | **地址不匹配就不使用内嵌锚**(不做"先试一次、失败再退回"的降级) | §3.6 |
| 8 | 能力位 `CLIENT_CAP_EMBEDDED_ANCHOR` | **本期加**,让操作员看得见哪些主机钉的是内嵌锚 | §3.5、§4.9 |
| 9 | 分享/转移是否要求新主控同证书 | **要求**(只对"已下发锚"成立;内嵌锚因绑地址而不受限) | §3.8 |
| 10 | 分享实例能否被 TLS 启停 | **不能**,与「被分享的主机无权切换协议」同策略 | §3.8、§4.4 |
本期范围因此确定为:**Windows 客户端 + MFC 服务端**,附带 P1 修复与分享实例隔离。
---
## 11. 设计自查记录(v0.1 初稿)
| # | 自查发现 | 处理 |
|---|---|---|
| 1 | 若锚块是全零常量,会落进 `.bss`,文件里没有这些字节 | §3.3 要求非零初值 |
| 2 | `memcpy(sizeof)` 方案(A)对老 stub 是"静默损坏 + 看起来成功" | §3.2 把"老 stub 显式失败"提升为选 B 的核心理由 |
| 3 | 只写 `COMMAND_TLS_DISABLE` 会导致永不回落的死锁 | 新增 §3.5 D5 |
| 4 | 初稿默认"4 KB 可放 fullchain",但 Windows 客户端只加载第一张证书 | 新增 §5 P1 |
| 5 | `TestRun.exe` 是加载器,不含 `TlsChannel.cpp` | §2.5 逐目标核实 |
| 6 | `TinyRun.dll` 工程只有 `main.c` | §2.5 表格标为不支持 |
| 7 | 锚块校验失败若按 fail-closed 处理,会锁死整批客户端 | §6.4 明确"损坏 → 视为未配置" |
| 8 | 在线下发若对 `NoBlock` 报错,会阻断运维操作 | §4.8 区分两条路径的失败策略 |
| 9 | 内嵌锚客户端连老服务端是新增失败组合 | §7 单列说明 |
| 10 | 锚块在 UPX / ShellCode 之后是否还在 | §3.2 用同一条搬运路径论证 |
| 11 | `szReserved[11]` 其实也是零引用 | §2.6 一并列出,结论仍是放不下 |
| 12 | 生成端若找到多份 magic,写哪一份不确定 | §3.3 定义 `Ambiguous` |
---
## 12. 独立审查后的修订(v0.1 → v0.2)
第二轮由另一次独立通读完成(对照源码逐条核实)。采纳 11 条、驳回 1 条。
| # | 审查意见 | 处置 | 说明 |
|---|---|---|---|
| 1 | **阻塞**:内嵌锚未绑定主控,分享/被转移的客户端指向另一台主控时必然 fail-closed | **采纳** | 新增 §3.6 D6:锚块存生成时的主控地址,不匹配则本连接不使用内嵌锚(按连接判定,见 §3.6 的"不能写成进程级开关") |
| 2 | **阻塞**:`static const` 锚块在 LTCG + `MinSpace` + COMDAT 折叠下可被整段删除,导致所有生成都报 `NoBlock` | **采纳** | §3.3 改为独立 TU + `volatile` + 外部链接;已核实 `WholeProgramOptimization=true`、`Optimization=MinSpace`、`EnableCOMDATFolding=true` 确实开启 |
| 3 | magic 字面量在 `.rdata` 里另有一份副本,会造成 `Ambiguous` 或读到垃圾 `capacity` | **采纳** | §3.3 改为"扫出全部命中、只认通过结构校验的那一个";magic 用字节列表初始化 |
| 4 | 抑制标记只能送达在线主机,不能解决离线主机 | **采纳** | §3.5 增加"单向门"说明与运维规程;新增能力位让操作员看得见 |
| 5 | `tls_disabled` 会让 WSS 切换静默降级为明文 WS | **采纳** | §3.5 第三条:`COMMAND_SET_PROTO` 在 `certLen>0` 时清除标记 |
| 6 | UDP/KCP 根本不走 TLS,"TLS 与传输正交"只在 `IOCPClient` 成立 | **采纳** | 新增 §3.7:置灰 + `LoginServer` 如实上报 |
| 7 | 抑制标记写入与读取的后端不一致(Debug 用 settings.ini) | **部分驳回** | 核实:`m_cfg = new iniFile(CLIENT_PATH)`(`KernelManager.cpp:79`)恒为注册表,与 `ReadTrustAnchor` 一致;审查方引用的 `KernelManager.h:291` 是 `AuthKernelManager::THIS_CFG`,不是同一个成员。但其中"注册表键是 exe 路径哈希,移动/重命名会复活内嵌锚"成立 → 记入 §6.5 |
| 8 | 抑制标记会"继承"到重装/更新的客户端 | **采纳** | §4.8 下发更新时清除;§6.5 单列 |
| 9 | §3.3 的初始化写法编译不过(数组不能用另一个数组初始化) | **采纳** | 改为字节列表初始化,并给出完整形式 |
| 10 | §2.6 "合计 507 字节"把两个不相邻字段加在一起 | **采纳** | §2.6 改写为"只有尾部 496 连续可用" |
| 11 | mem-DLL 流程下 `ServerDll.dll` 过期会**静默明文**而不报错 | **采纳** | §4.7 加非阻塞警告;§8-11 加专项用例 |
| 12 | §7 最后一行机制描述不准(老服务端是误解析而非"按垃圾关闭") | **采纳** | §7 措辞改正 |
审查还确认了以下结论无误:P1(Windows 单证书 vs Linux 循环)、三级锚来源与顺序、`COMMAND_TLS_DISABLE` 仅删 `tls_cert`、`szFututre`/`szReserved` 零引用、§2.5 的逐项目编译单元表、服务端嗅探与 fail-closed、`memcpy(..., sizeof(g_ConnectAddress))`、以及锚块在各包装路径下均能存活(写入点在 UPX/`MakeShellcode`/SCLoader/伪装之前)。
## 13. 定稿修订(v0.2 → v0.3)
| # | 改动 | 落点 |
|---|---|---|
| 1 | §10 八项待定问题全部裁定,转为决议记录 | §10 |
| 2 | 新增 D8:分享/转移的证书约束(对"已下发锚"成立,今天即如此;内嵌锚因绑地址而不受限) | §3.8、§7、§8-10 |
| 3 | 新增分享实例的 TLS 指令隔离,复用 `COMMAND_SET_PROTO` 的既有策略 | §3.8、§4.4、§8-11 |
| 4 | 运维规程补一条:转移/分享前要么确认新主控同证书,要么先下发「取消 TLS」 | §6.1 |
| 5 | 兼容性矩阵补三行(已下发锚 + 异证书 / 同证书、分享实例收到启停指令) | §7 |
| 6 | 工作量调整:`KernelManager.cpp` ±30 → ±35(分享隔离 5 行) | §9 |
定稿范围:**Windows 客户端 + MFC 服务端**,含 P1(PEM fullchain 循环加载)与分享实例隔离。Linux / macOS / Android 与「按主控分键存锚」明确留到下一版。
## 14. 实施记录(v0.3 → v1.0)
### 14.1 落地清单
| 文件 | 内容 |
|---|---|
| `common/tls_anchor.h`(新) | `EmbeddedTlsAnchor` 结构、`kAnchorVersion/ kAnchorCapacity`、`Fnv1a32`、`IsAnchorMagic`、`IsAnchorBlockValid`、`static_assert(sizeof == 4228)` |
| `client/EmbeddedTlsAnchor.h/.cpp`(新) | `volatile EmbeddedTlsAnchor g_embeddedTlsAnchor`(独立 TU、`.data` 落地) |
| `client/TlsChannel.cpp/.h` | `ReadTrustAnchor` 四级优先级(`tls_disabled` → `tls_cert` → 文件 → 内嵌 → 明文);P1 的 `DecodeAllCerts`(按 BEGIN/END 切块循环解码,见 §14.5);**按连接的两套缓存状态** `g_state[2]` + `ResolveStateIndex()` 地址集合匹配 + `TlsEnabledFor()` / `TlsLoadErrorFor()` / `AnchorEmbedded()`(见 §14.6) |
| `client/KernelManager.cpp` | `SetTlsDisabledMarker()`;启停 TLS 的分享实例隔离;`COMMAND_SET_PROTO` 清标记;`COMMAND_UPDATE` **不清**标记(§6.5 修订) |
| `client/ClientDll.cpp` | 不再有进程级判定(删掉 `SetEmbeddedAnchorEnabled()` 那一套);`GetLoginInfo(..., IsTlsActive(), IsTlsAnchorEmbedded())` |
| `client/IOCPClient.h/.cpp` | `IsTlsActive()`(按实连上报,不看 `protoType`);`IsTlsAnchorEmbedded()`(取本连接握手时的锚来源);`ConnectServer` 改用 `TlsEnabledFor(m_sCurIP, m_Domain.GetAddress())` |
| `client/domain_pool.h` | `GetAddress()`:取配置里的原始地址串(可能分号多地址/域名) |
| `client/LoginServer.cpp/.h` | `LoginInfor.AddReserved(tlsOnWire ? 1 : 0)`;`tlsOnWire && tlsAnchorEmbedded` 时 `DefaultCaps() | CLIENT_CAP_EMBEDDED_ANCHOR` |
| `common/commands.h` | `CLIENT_CAP_EMBEDDED_ANCHOR 0x0040` |
| `server/2015Remote/EmbeddedAnchor.h/.cpp`(新) | `EmbedTlsAnchorInto()`、`TlsAnchorSummary()` |
| `server/2015Remote/BuildDlg.cpp/.h`、`resource.h` | 动态复选框 `IDC_CHECK_TLS_ANCHOR`、`UpdateTlsAnchorState()`、生成时内嵌 |
| `server/2015Remote/2015RemoteDlg.cpp` | `ReadExeFromResource()` 内嵌;`OnExperimentTlsDisable` 去守卫 + 台数警告 |
| `server/2015Remote/context.h` | `UsesEmbeddedAnchor()` |
| `lang/*.ini` | 10 条新文案 × 3 种语言 |
### 14.2 与 v0.3 的偏差
| # | 偏差 | 原因 |
|---|---|---|
| 1 | 可内嵌协议由「排除 UDP/KCP/随机」收窄为 **只有 TCP/HTTP** | `WS` 的 TLS 通道被 `protoType != PROTO_WS` 直接跳过,锚不参与;`WSS` 的锚是**反代**的证书,塞服务端自己的锚会让原本能连的客户端握手失败(§3.7 表格) |
| 2 | 锚摘要从「复选框旁」挪到「生成成功提示里」 | 那条空白带只有 196 DLU(约 24 个全角字),放不下 `builtin 2036-11-01 sha1:…` |
| 3 | `PayloadSupportsEmbeddedAnchor()` 删除 | 与 `EmbedTlsAnchorInto()` 的 `NoBlock` 信息重复 |
| 4 | `COMMAND_UPDATE` 清抑制标记改为**有条件**(payload 里真有可用锚才清) | 无条件清会让一台已被要求走明文的主机重新发 ClientHello,撞上明文服务端即不可恢复的失联 |
| 5 | 复核「取消 TLS」不逐条翻译,首发文案保持原键 | 该键在三个 ini 里已有译文(含字面 `\n`),拆句只会让译文作废 |
### 14.3 实测
- `x64\Debug\ghost.exe`:magic 命中 2 处,`@0xac15d0 ver=1 cap=4096 len=0` 通过结构校验,
另一处是 `.rdata` 的字面量副本(`ver=1699431294`,过不了校验)——正是 §3.3 预期的形态。
- `x64\Debug\ServerDll.dll`(Debug 下仍走 `/LTCG`):同样 1 处有效块,LTCG 未把对象折叠掉。
- 生成链路(Debug 服务端 + 真实构建对话框,无鼠标驱动):选 ghost.exe / TCP / 不压缩,
主控 `127.0.0.1:16543`,产出 `Bin\ghost.exe` 与模板**同尺寸**(11,868,160 字节)—— 锚块容量
在模板里已预留 4096 字节,生成时只是原地填内容,不会撑大镜像;提示框回报
`Embedded TLS trust anchor: custom 2036-10-11 sha1:272f2adfb19c`,与 `TlsAnchorSummary()` 一致。
产物里唯一的有效块 `@0xac1dd0 len=1178`,hash `0xD47F19ED`
自校验通过,`master='127.0.0.1'`,PEM 与 `server/go/certs/server.crt` 逐字节相同、尾部补零。
- 端到端首连(§8 用例):把生成的客户端放进一个从未跑过的目录(因此注册表 `Software\<exe 路径哈希>`
是全新的,没有 `tls_cert` / `tls_disabled`),本机起一个只收不回的监听口 16543。客户端在
0.2 s 内发来 `16 03 03 00 8E 01 00 00 8A 03 03 …`,即 TLS 1.2 ClientHello;
日志为 `[TLS] trust anchor embedded: 1 certificate(s) loaded` →
`[TLS] enabled: trust anchor loaded (embedded), using TLS`。
地址不匹配的场景见 §14.6 的三组首连实测。
- fullchain 多块解码:把 `web.just-do-it.icu.fullchain.pem`(4 块)放到 exe 同目录的
`yama-ca.pem`,日志报 `4 certificate(s) loaded` —— P1 的循环语义成立;删掉文件后回落到
内嵌锚(1 张),两级优先级也按 §3 的顺序生效。
- 待补:真实目标机 + 线上 TLS 服务端的完整握手(本机只有"客户端发出 ClientHello"这一半)。
### 14.4 踩坑:新源文件漏 BOM 导致「行号整体偏移的语法错误」
新建的 5 个文件初版是 UTF-8 **无 BOM**。本机 ACP=936,MSVC 于是按 GBK 解读 UTF-8 源码,
CJK 注释里出现「尾字节 0x5C + 换行」就被当成续行符,把后面 13 行吞进注释;报出来的现象是
`tls_anchor.h(19): 'EmbeddedTlsAnchor::kAnchorVersion' cannot be declared with 'constexpr'`
——行号比真实行号少 13,且标识符被当成类成员。补上 UTF-8 BOM 即恢复。
记住两条:本仓库 `.cpp/.h` 一律 **UTF-8 带 BOM**(执行字符集仍是 GBK,所以 `_TR` 键与 GBK
的 ini 对得上);`lang/*.ini` 一律 **GBK 无 BOM**。
### 14.5 端到端联调揪出的两个缺陷
**(1)`DecodeAllCerts` 误用 `CryptStringToBinaryA` 的 `pdwSkip` —— 所有锚来源全挂。**
P1 为支持 fullchain 改成循环解码,注释写着「每次都传整串,由它回报下一块的起点」。实际该参数
是**纯输出**:回报本次转换前跳过了多少字符,调用方传入的偏移一概不看,整串输入时恒为 0。
于是循环第一轮就撞上 `next <= offset` 的防死循环判断退出,一张证书都没进 store;`added == 0`
被当成「证书损坏」,触发 §6.1 的 fail-closed —— 内嵌锚客户端**首次连接即永久拒绝**,下发锚、
文件锚同样解不出来。现场日志:
```
[TlsChannel.cpp:185] [TLS] failed to decode certificate embedded
[TlsChannel.cpp:246] [TLS] FATAL: ... refusing connections (fail-closed)
```
用 PowerShell 直接对同一个 PEM 复现:`skipIn=0 -> need=969 skipOut=0`、`skipIn=1367 -> need=969
skipOut=0`,输出与原调用完全一致,证实 skip 不承担输入偏移。修法是自己按
`-----BEGIN` / `-----END` 切块,逐块解码;无标记头时退回整串 `CRYPT_STRING_ANY`(覆盖只有
base64 正文的锚),最后兜底裸 DER。修复后 fullchain 报 `4 certificate(s) loaded`,内嵌锚报 1 张。
教训:会失败到 fail-closed 的路径,必须有一次**真机首连**的验证;单看「结构校验通过」不够。
**(2)用户主动取消勾选,切一次协议再切回来会被悄悄勾上。**
`UpdateTlsAnchorState()` 最初按「可用就勾选」实现,于是 WS(不可用,强制未勾)→ TCP 会把用户的
取消覆盖掉,生成时真的内嵌进去。改为三态:`m_nAnchorUserCheck`(-1 未表态 / 0 / 1),不可用时
只显示未勾选但不改表态,可用时按表态恢复;勾选变化由 `ON_BN_CLICKED` 记录。已用 BM_CLICK 实测
「取消 → 切 WS → 切 TCP」后仍为未勾选。
### 14.6 代码评审后的返工:判定从「进程」改到「连接」
v1.0 交付时把 §3.6 的地址比对落成了**进程级**:`StartClient()` 里比较一次
`settings.ServerIP() == anchor.master`,写进 `EmbeddedTlsAnchor.cpp` 的
`g_embeddedAnchorEnabled`,TLS 层首次访问时据此缓存一套 store + 链引擎便不再重算。三处问题:
| # | 问题 | 后果 |
|---|---|---|
| 1 | 判定与 TLS 状态都是**进程级**,而分享实例、并行多主控实例是**同一进程内的线程** | 谁先连上谁替所有实例做了决定:分享连接会被判成该用 A 的锚 → 拿 A 的证书校验 B → fail-closed;能力位也按进程上报,那台主控误判「这台主机靠内嵌锚」 |
| 2 | 只做**整串相等**,而并行模式用 `settings.SetServer(DomainPool 解析出的 IP)`,配置里还可能是分号多地址/域名 | 除「配置里写的正好是生成时那个字符串」以外,一律不匹配:并行、域名、多地址部署全部退化成明文 |
| 3 | `tls_disabled=1` 连手工部署的 PEM 一起屏蔽(§3.5 的既定语义,**不改**) | 只补日志可观测性 |
改法(`client/TlsChannel.cpp` 为主):
- `TlsState g_state[2]`:`[1]` 允许内嵌锚、`[0]` 不允许,各自带 store + 链引擎,首次访问时
`EnsureStateLocked()` 建好(「不允许」那套静默构建,避免把不适用本连接的 enabled 行印在本
连接状态之前)。
- `ResolveStateIndex(host, configured)`:两层地址匹配(§3.6),在取 `g_tlsMtx` **之前**
调用(可能解析域名)。`Handshake()` 开始时定下用哪一套状态,`VerifyServerCert()` 据此取
anchor,并把来源记进 `m_anchorEmbedded`。
- `TlsReload` 一次重建两套;运行期失败只保留该套原状态(不打死正在工作的客户端)。
- 删除 `g_embeddedAnchorEnabled` / `SetEmbeddedAnchorEnabled()` / `EmbeddedAnchorEnabled()`,
`ClientDll.cpp::StartClient()` 里那段全局写随之去掉。
- 域名解析移出 `g_tlsMtx`:地址匹配要解析域名,而 `gethostbyname` 在 DNS 不通时要等满超时。
原先它跑在证书校验那把锁里,一次解析就能把**同一进程里其它连接的握手**一起堵住。现在
匹配用独立的 `g_matchMtx`,只护住缓存读写,解析在锁外;调用方(`TlsEnabledFor` /
`TlsLoadErrorFor` / `Handshake`)先算 `idx` 再取 `g_tlsMtx`。失败按 60 秒负缓存
(`g_dnsFailAt`)——master 域名换过/过期时,不至于每次重连都白等一轮超时。实测:
master 写成不存在的域名时,首次连接仍在 0.8 s 内发出(解析失败约 0.6 s,且之后 60 秒内
不再重试)。
- `Handshake()` 里那句「整条连接生命周期内不变」的注释与实现不符:`m_stateIdx`(用哪一套)
确实是定的,但 store/链引擎会被 `TlsReload` 原地替换,所以握手末尾校验用的是**此刻**的
锚。行为是有意为之(新锚对在途握手立即生效),注释已改成这个说法,免得后来人以为能拿到
握手开始时的快照。
- 顺带修正 `ApplyTlsAnchorChange`:它原先拿**进程级** `TlsEnabled()` 比较热重载前后的传输,
而进程级开关看的是「允许内嵌锚」那套状态。锚不匹配的客户端实际在走明文、开关却恒为
true,于是收到「启用 TLS」时判定为「传输没变」、不断线重连,**明明拿到了锚却继续明文连**。
改为按本连接的目标比:`client->IsTlsActive()` vs `client->TlsEnabledForCurrentTarget()`。
**首连实测**(`x64\Debug\ghost.exe` + 用脚本把锚块原地注入,等价于生成器的填法;本机 6543
只收不回):
| 锚的 `master` | 配置的主控 | 首包 | 日志 |
|---|---|---|---|
| `127.0.0.1` | `127.0.0.1` | `16 03 03 00 8E …`(ClientHello) | `trust anchor embedded: 1 certificate(s) loaded` → `enabled: … (embedded), using TLS` |
| `10.9.9.9` | `127.0.0.1` | 明文(`F9 EB BD 5F …`,随后明文登录成功) | `embedded anchor skipped: connecting 127.0.0.1, built for 10.9.9.9` → `this connection: plaintext mode` |
| `localhost`(域名) | `127.0.0.1` | `16 03 03 00 8E …`(ClientHello) | 同第一行(命中第二层:`localhost` 解析出 127.0.0.1) |
第二、三行正是问题 1、2 的回归用例:同一个二进制里,判定随连接目标变化,且域名/多地址不再
因字符串不等而失配。全限权(Release)客户端在本机无法完成 `RegisterStartup`(无管理员 →
`self_del()`),故实测用 Debug 客户端——`_DEBUG` 下 `RegisterStartup` 直接返回 1,TLS 代码路径
与 Release 完全相同。