Files
SimpleRemoter/docs/ClientEmbeddedTLS_Design.md
T
yuanyuanxiang 454d25d37f fix(share): carry the transport in the share and assign payloads
The share payload was host:port:shine and carried no transport at all, so a
shared client fell back to its baked-in protoType. Share instances also skip
ApplyProtoSwitch (ClientDll.cpp:810), so a client upgraded to WSS was shared
to a TLS front end as raw TCP and looped on HTTP/1.1 400.

Extend both payloads with an optional trailing transport field:

    share  : host:port:shine[:transport]
    assign : host:port:days:shine[:transport]

The field is omitted when the source protocol is not TCP/WS/WSS, so HTTP/UDP/
KCP hosts keep their previous behaviour instead of being silently downgraded
to plain TCP.

- server: add SelectedShareTransport(), share it between OnOnlineShare and
  OnOnlineAssignTo, and accept a tcp:// ws:// wss:// prefix in the address.
- client: parse the field on both paths and persist the assigned value to
  settings/master_transport, clearing it when the field is absent.
- share_list: dedup on host:port instead of the whole record, so re-sharing
  a host with a different transport replaces the stale entry.
- assign: guard bToken[_MAX_PATH] against the longer payload.
- lang: translate the reworded prompt and the three new messages in en_US,
  zh_TW and de_DE.

Transport is pinned at share time and does not follow a later protocol switch
on the master link; the m_bShared gate stays as-is on purpose.
2026-11-02 14:01:39 +01:00

59 KiB
Raw Blame History

客户端内嵌服务端 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 里它是传输层唯一判据:

// 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:

#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 里定义,且必须

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:锚必须绑定主控地址(阻塞级)

一个客户端会被指向另一台主控,而内嵌锚钉的是生成时那台:

// 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;另提供:

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)同一策略:

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(新增)

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 落在客户端(KernelManager.cpp):收到新镜像后扫一遍 payload,IsAnchorBlockValid && length > 0 才清。不做无条件清除——否则一台已被要求走明文 的主机会重新发 ClientHello,撞上明文服务端就是不可恢复的失联,正是 §3.5 要避免的那个失败。 被 UPX / AES 包过的镜像扫不到锚,按「没带锚」处理(保持既有行为)。

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。后果:运维刚内嵌的锚被上一轮的抑制标记悄悄作废,连接回到明文且无提示。

处理:COMMAND_UPDATE / COMMAND_UPLOAD_EXEC 下发新客户端时顺带清除 tls_disabled;且内嵌锚主机被抑制时,客户端日志与在线列表都要能看到(§4.9 的能力位)。


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)。

回归 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 按 payload 是否带锚清标记
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()
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 完全相同。