Files
SimpleRemoter/docs/TransportTLS_Design.md
T
6bfa4294cc Feature: Switch a Linux client's transport TLS at runtime
The server's TLS menu already wrote the trust anchor into the Windows
client's registry and expected a restart. The Linux client grew the same
command handling (166/167) but, like Windows, only read the anchor once at
startup, so enabling or disabling TLS still meant restarting it. Both
handlers now take effect immediately.

TlsChannelLinux.cpp no longer initialises through std::call_once. The
process-level state (context, enabled, load error) lives behind a mutex and
TlsReload() rebuilds it from whatever anchor file is on disk, so
TlsEnabled() reflects the new transport as soon as the anchor is written or
removed. In-flight sessions survive the swap because SSL_new increments the
SSL_CTX reference count; the unit test pins that down by keeping an
established TLS connection open across a reload that frees the old context.
A reload that hits a bad anchor keeps the previous state and only logs: one
bad push should not brick a working client, and the next start is still
fail-closed. The pushed PEM is parsed before it is written for the same
reason -- a corrupt anchor on disk would lock the client out of the server
with no way to correct it remotely.

Only a real transport flip (plaintext <-> TLS) asks for a reconnect. An
anchor swap alone, as in a certificate rotation, leaves the current session
alone and applies to the next connection. The receive thread never closes
the socket itself; it sets g_needReconnect and the main heartbeat loop
disconnects so the outer reconnect loop can re-handshake, matching how the
heartbeat timeout path already works.

IOCPClient now latches the transport per connection (m_useTls) at handshake
time instead of consulting TlsEnabled() on every send and receive. Without
the latch, the second or so between the reload and the reconnect would push
plaintext into an established TLS session, or the reverse, producing
protocol errors for no reason.

RES_TLS (szReserved[19]) is refreshed right before each login, including
the resend after a group change, so the TLS column on the server flips with
the transport instead of showing the value from process start.

The confirmation dialogs now say what each platform does, with translations
in en_US, zh_TW and de_DE; the keys carry the literal \n escape the INI
parser understands.

Ending a sub-connection is not an error. OpenSSL 3 classifies a peer that
closes without close_notify as an unexpected-EOF protocol error, so every
terminal or file transfer session logged an SSL_read failure on the real
servers even though Recv promises 0 for a plain close and neither side sends
close_notify. SSL_OP_IGNORE_UNEXPECTED_EOF restores the intended semantics.

Verified with the reload unit test (RELOAD-OK, covering the in-flight
connection across a context swap, garbage payload rejection and a broken
anchor keeping TLS alive), an abrupt-close test (recv now returns 0 instead
of SOCKET_ERROR) and end to end against a protocol-faithful fake server that
signs MasterSettings with libsign: plaintext login, 166, TLS reconnect with
RES_TLS=1, 167, plaintext reconnect with RES_TLS=0. The Linux client, the
Debug Windows client and the Debug MFC server all build.

The cost is inherent to taking effect immediately: a remote session in
progress is dropped when the transport changes, and the MFC server briefly
shows the client as a duplicate login until the old connection is reaped
and the standby entry is promoted.

Co-Authored-By: deepseek-flash
Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-28 14:15:40 +01:00

23 KiB
Raw Blame History

传输层单向 TLS 加密设计(按需加密)

版本:v0.7 · 状态:Go 服务端 + Windows/Linux 客户端已实现并验证;Linux 客户端支持下发即时热切换;MFC 主控端见 TransportTLS_MFCServer_Design.md;macOS/Android 未接入 · 日期:2026-10-28(Linux 客户端接入 + 热切换) 目标:让 YAMA 设备端口(TCP 6543)在继续兼容老客户端(明文/XOR)的同时,允许新客户端在拿到证书后按需开启单向 TLS 加密传输。 本期范围:Go 服务端(server/go)+ Windows 客户端 + Linux 客户端。

需求原文(三点,逐一对应下文):

  1. 新客户端默认不加密,行为与老客户端完全一致;
  2. 某些高要求场景,管理员「颁发一个证书给该客户端 + 重启」,该客户端即改走加密;
  3. 服务端同一端口(6543)同时兼容明文与 TLS 两种客户端,老客户端零改动。

1. 目标与范围

目标

  • 同一 6543 端口上,服务端自动区分「明文客户端」与「TLS 客户端」,按连接路由。
  • 加密是按部署、按客户端开关的:证书(注册表值或文件)在 → TLS;证书不在 → 明文(与老客户端一致)。
  • 老客户端(无证书概念)行为不变、零改动。
  • 满足 Measure 1 的「传输层真加密 + 抗重放」目标(对 TLS 客户端而言)。

非目标(Non-goals,本次不做)

  • 不做 mTLS / 客户端证书:单向 TLS 不验证客户端证书,客户端身份仍由隧道内的现有登录(PwdHmac V1 / ECDSA V2)承担。
  • 不做传输层 PSK(YAMA_TRANSPORT_KEY)方案——本设计改用证书,更贴合「颁发证书」的运维模型。
  • 不改应用层协议(flag 帧格式 / XOR / zstd),不做「TLS 内去掉 XOR」的二次精简(后续可选)。
  • Windows 客户端不做加密开关的运行时热切换(证书只在进程启动时读取一次,改配置需重启——这正是需求)。Linux 客户端例外:服务端下发 166/167 后立即重载信任锚并重连切换(§6.6),语义差异见该节。
  • macOS / Android 客户端的 TLS 接入不在本期(Linux 客户端已按同一模式接入,见 §6.6)。
  • 不做 MFC 服务端(server/2015Remote)的 TLS 接入——本期只做 Go 服务端(server/go),MFC 主控端延后到阶段 3。

2. 现状与复用

2.1 当前传输(已核实)

服务端 TCP 传输链路:server/go/server/server.go acceptLoop()(329–360 行)Accept 后 go handleConnection(conn);handleConnection()(363–425 行)读入 ctx.InBuffer,交给 protocol.Parser。

server/go/protocol/parser.go Parse()(51–85 行):

  1. 可选剥离 HTTP-mask(POST /...\r\n\r\n 外壳,common/mask.h 的 HttpMask);
  2. parseHeader()(88–140 行)调用 CheckHead() 识别协议;
  3. parsePacket()(143–225 行)解头 + XOR 解码 + zstd 解压。

server/go/protocol/header.go CheckHead()(149–165 行)对前 12 字节依次尝试 8 种头混淆 × 4 种魔数,命中即得 FlagType:

FlagType 魔数 首字节
FlagHell(4) HELL H=0x48
FlagShine(1) Shine S=0x53
FlagFuck(2) <<FUCK>> <=0x3C
FlagHello(3) Hello? H=0x48
HTTP-mask POST P=0x50

注意:上表「首字节」是解密后的魔数首字节。实际线上,客户端(common/header.h 的 GetHead)会用 time() % 12 随机选一个混淆方法对前 4 字节魔数加密(仅在 superAdmin 命中的 HellEncoder 路径;默认 ProtocolEncoder 直接发明文 Shine)。因此原始首字节可能是任意值,包括 0x16。这正是 TLS 检测不能只看前两字节、必须再加一字节判据的原因(见 §3.1)。

当前「加密」为 codec.go 的 xorDecoder16(XOR + 两轮伪随机交换,密钥是明文带内 12 字节)+ header.go 的 V0V6 头混淆——等于明文。这正是 Measure 1 要解决的。

2.2 客户端登录(已核实,隧道内照常)

  • V1:client/KernelManager.cpp:1857 从配置读 settings/PwdHmac(预计算摘要),服务端 auth.go:240 VerifyMessage(YAMA_PWD, passcode, hmacSig) 校验。YAMA_PWD 只存在服务端,客户端只有摘要,不持有 YAMA_PWD。
  • V2:auth.go:188 ECDSA P-256 验签(v2:BASE64),客户端持私钥、服务端持公钥。

2.3 关键结论(本设计的基础)

TLS 作为「透明传输包装」,应用层协议一行不改。 即:

明文客户端:   [TCP] = flag 帧 + XOR payload + zstd
TLS 客户端:   [TCP][TLS] = { flag 帧 + XOR payload + zstd }

服务端 parser.go/codec.go/header.go/handler 全部不动;TLS 客户端解密后的字节流就是同一套协议。唯一新增的是连接建立时的 TLS 检测与解包。XOR 套在 TLS 里冗余但无害,保留它换来「应用协议零改动、老新客户端共用同一套代码」。

3. 总体方案

3.1 同端口共存 + 首字节检测

服务端在 handleConnection 开头(Accept 之后)偷看连接开头 6 字节:

  • 命中 0x16 0x03 … 0x01(TLS 握手记录 + TLS 版本号 + 握手类型 ClientHello)→ 交给 tls.Server 解包;
  • 其它 → 走现有明文路径。

为何要看第 6 字节:客户端会随机混淆魔数头(见 §2.1),所以明文连接的前两字节可能恰好是 0x16 0x03。但混淆只作用于前 4 字节魔数,字节 5 对混淆后的 HELL 头恒为 0x00,对明文 Shine/POST 变体是 ASCII 字符——永远不会是 0x01;而任何 TLS 握手记录里,字节 5 就是握手消息类型,ClientHello 恒为 0x01。于是 0x16 0x03 加 b[5]==0x01 三重判据让误判概率趋近于零。

accept
  ├─ 现有 MaxConnections / per-IP 限流(保持,先于 TLS 握手,廉价拒绝 + 抗握手 DoS)
  ├─ peek 3 字节
  │    ├─ 0x16 0x03 → tls.Server(conn, tlsCfg)(惰性握手,首次 Read 触发)
  │    └─ 其它     → 明文
  └─ handleConnection(conn)   // 不区分明文/TLS,tls.Conn 实现 net.Conn

3.2 客户端行为

客户端启动时检查「证书文件是否存在」:

  • 不在 → 明文(与老客户端完全一致,默认即此);
  • 在 → 所有出站 TCP 连接(主连接 + screen/terminal/file 子连接)统一走 TLS。

3.3 架构图

┌──────────── 被控端(客户端,无证书) ────────────┐
│  TCP ── flag+XOR+zstd ─────────────────────────► │  明文
└───────────────────────────────────────────────────┘
┌──────────── 被控端(客户端,有证书) ────────────┐
│  TCP ── TLS ── { flag+XOR+zstd } ──────────────► │  加密
└───────────────────────────────────────────────────┘
                        │
                        ▼
             ┌──────────────────────┐
             │   服务端 6543         │
             │  peek 首字节路由       │
             │  ├─ 0x16 0x03 → TLS   │
             │  └─ 其它    → 明文    │
             │  ── 同一套 parser/handler │
             └──────────────────────┘

4. 证书模型(单向 TLS)

  • 服务端持有一张服务端证书 + 私钥(可自签名,或由自建 CA 签发)。
  • 客户端持有信任锚证书(CA 证书,或自签名服务端证书本身)用于在握手时校验服务端。
  • 「颁发证书给某客户端」= 把信任锚证书投递到该客户端(注册表值,见 §6.1/§9.3)。证书是共享的信任锚(不是每个客户端一张唯一证书),「颁发」的本质是决定给哪个客户端开加密。
  • 单向 TLS 不认证客户端身份;客户端身份仍由隧道内的登录(V1 PwdHmac / V2 ECDSA)承担。
  • 信任锚首选存注册表 Software\<exehash>\settings\tls_cert(REG_SZ 直接存 PEM 正文);兼容旧方式:settings.ini [settings] tls_cert 路径,或 exe 同目录 yama-ca.pem 文件。

5. 服务端改动

5.1 配置(server/go/server/server.go Config)

新增两个字段,均为证书/私钥文件路径;空 = 禁用 TLS(仅明文,向后兼容):

TLSCertFile string // 服务端证书(PEM)
TLSKeyFile  string // 服务端私钥(PEM)

cmd/main.go 读取环境变量(沿用现有 YAMA_* 命名):

cfg.TLSCertFile = os.Getenv("YAMA_TLS_CERT")
cfg.TLSKeyFile  = os.Getenv("YAMA_TLS_KEY")

仅当两者都非空才构建 *tls.Config;否则 s.tlsCfg == nil,acceptLoop 走纯明文。

5.2 tls.Config

tlsCfg := &tls.Config{
    Certificates: []tls.Certificate{cert},
    MinVersion:   tls.VersionTLS12,
    // 单向 TLS:不设 ClientAuth / ClientCAs
}

5.3 handleConnection 检测 + 回放

标准 peek 回放:bufio.Reader 预读 6 字节,封装成 bufferedConn(实现 net.Conn,Read 委托给 Reader),判断后把已读字节一并交给目标。嗅探本身设了 ReadTimeout 截止,超时/EOF 则退回原始 conn 走明文,由读循环处理:

func (s *Server) wrapTLS(conn net.Conn) net.Conn {
    br := bufio.NewReader(conn)
    _ = conn.SetReadDeadline(time.Now().Add(s.config.ReadTimeout)) // 嗅探受超时约束
    hdr, err := br.Peek(6)
    _ = conn.SetReadDeadline(time.Time{})
    if err != nil {
        return conn // 超时/EOF:走明文,交由读循环处理
    }
    bc := &bufferedConn{Conn: conn, r: br}
    if isTLSClientHello(hdr) { // 0x16 0x03 且 b[5]==0x01
        return tls.Server(bc, s.tlsCfg) // 握手惰性,首次 Read 触发
    }
    return bc
}

5.4 握手超时

handleConnection 首次 conn.Read 会触发 TLS 握手,而它已按 ReadTimeout 设了 SetReadDeadline,因此握手天然受 ReadTimeout 约束,无需额外机制。per-IP 限流(现有)继续在握手前生效,压制握手 DoS。

5.5 明确不动的部分

  • parser.go / codec.go / header.go:零改动。
  • handleConnection / processData / handler 栈:零改动(tls.Conn 满足 net.Conn)。

6. 客户端改动

6.1 证书检测

启动时(连接前)按优先级找信任锚:① 注册表 Software\<exehash>\settings\tls_cert(REG_SZ 存 PEM 正文)→ ② settings.ini [settings] tls_cert 路径 → ③ exe 同目录 yama-ca.pem。找到即走 TLS,否则明文。实现:client/TlsChannel.cpp 的 ReadTrustAnchor() + TlsEnabled()(std::call_once 惰性加载、线程安全、幂等)。

Linux 无注册表,信任锚按:① $XDG_CONFIG_HOME/ghost/yama-ca.pem(默认 ~/.config/ghost/yama-ca.pem)→ ② 程序同目录 yama-ca.pem。文件存在即视为已配置:读取/解析失败一律拒绝连接(fail-closed)。实现:client/TlsChannelLinux.cpp。

6.2 TLS 栈选型(已定:Schannel)

  • 已选 Schannel(Windows 原生 SSPI):零第三方依赖/零额外 DLL 部署,secur32.lib/crypt32.lib 均为系统库(secur32.lib 已在 CFFmpegH264Encoder.cpp:38 链接)。
  • 信任锚(PEM/DER 正文,来自注册表或文件)经 CryptStringToBinaryA 解码 → CertCreateCertificateContext → 内存 HCERTSTORE;握手后 CertGetCertificateChain 把服务端证书链到该信任锚,dwErrorStatus == 0 才放行(含时间有效性)。严格钉扎:链引擎用 hExclusiveRoot 只信任该 store,排除系统根库,否则公共 CA 签发的证书也能通过。fail-closed。
  • 握手凭据:SCH_CRED_MANUAL_CRED_VALIDATION | SCH_CRED_NO_DEFAULT_CREDS,grbitEnabledProtocols = SP_PROT_TLS1_2_CLIENT(与 Go 端 MinVersion: TLS 1.2 对齐)。
  • 单向 TLS:不提供客户端证书;客户端身份仍由隧道内登录承担。

6.3 连接层封装

在 socket 建立后、应用协议首包前插入 TLS 握手(IOCPClient::ConnectServer,m_bConnected 置位前);ReceiveData/SendTo 改走 TlsChannel 会话。所有出站连接(主连接 + 子连接)统一遵循 TLS 开关,因此子连接同样被加密——服务端按连接检测,天然支持。实现:client/TlsChannel.{h,cpp},接入点 client/IOCPClient.{h,cpp}。

6.4 关键:无静默降级(fail-closed)

证书文件存在但握手失败(证书不匹配 / 中间人)时,客户端必须报错并放弃连接,禁止回退到明文。 否则攻击者可制造降级。这必须写进实现与测试。

6.5 实现要点:Schannel 流模式 DecryptMessage 的缓冲重组

Schannel 流模式(ISC_REQ_STREAM)下,DecryptMessage 会把输入的那段 SECBUFFER_DATA 重组为 4 段输出,而不是就地解密到原偏移:

索引 类型 内容
bufs[0] SECBUFFER_STREAM_HEADER TLS 记录头(5) + 显式 nonce(8)
bufs[1] SECBUFFER_DATA 明文
bufs[2] SECBUFFER_STREAM_TRAILER 认证标签
bufs[3] SECBUFFER_EXTRA 下一条记录的剩余密文(如有)

因此客户端 Recv 必须从 bufs[1].pvBuffer/bufs[1].cbBuffer 取明文、EXTRA 从 bufs[3] 取。若误用 bufs[0](记录头+nonce)或从原缓冲首字节取数,会把 TLS 记录头 17 03 03 … 当作明文交给协议解析器(表现为 Unknown header)。Send 方向相反:EncryptMessage 用 STREAM_HEADER/DATA/TRAILER 三段布局,本就正确。这一处是联调阶段实际踩到的、唯一的方向性 不对称 bug,已修复。

6.6 Linux 客户端实现(OpenSSL,2026-10-28)

  • 选型:OpenSSL(libssl)。Linux 构建早已因 libsign.a 链接 libcrypto,只多链一个 OpenSSL::SSL,不引入新的运行时依赖包(同一 OpenSSL 3 包提供 libcrypto.so.3 / libssl.so.3)。
  • 代码组织:client/TlsChannel.h 按平台分派(_WIN32 → Schannel,__linux__ && !__ANDROID__ → OpenSSL),Windows 分支内容不变;实现文件为 client/TlsChannelLinux.cpp。YAMA_TLS_CHANNEL 宏标注「本平台有 TLS 通道」,IOCPClient 用它替代原先的 #ifdef _WIN32,因此主连接与子连接共用同一接线点。macOS/Android 不定义该宏,维持明文。
  • 语义对齐:TLS 1.2 钉扎(min=max,与 SP_PROT_TLS1_2_CLIENT 及两套服务端一致);单向 TLS、不提供客户端证书、不校主机名、不做吊销检查;SSL_VERIFY_PEER + 只含信任锚的 X509_STORE(不含系统根库,严格钉扎),握手内完成链校验,失败即断开(fail-closed)。
  • 缓冲差异:OpenSSL 自己管理记录缓冲,不需要 Schannel 的 m_raw/m_pending;一次 SSL_read 交付不完的明文留在 SSL 内部,接收线程在 select 前用 SSL_pending() || SSL_has_pending() 优先消费,否则剩余字节会被 2 秒 select 超时卡住。
  • 下发/撤销:COMMAND_TLS_ENABLE(166) 的 PEM 正文写入 ~/.config/ghost/yama-ca.pem(目录 0700、文件 0600、临时文件 + rename 原子替换);COMMAND_TLS_DISABLE(167) 删除该文件(含程序目录同名回退文件)。写入前先用 OpenSSL 解析一遍,不是合法证书就整包拒绝并保留原状态。
  • 热切换(与 Windows 的唯一语义差异):落盘后立即 TlsReload() 重建 SSL_CTX 并更新开关,然后断开主连接、由外层重连循环用新传输方式重连——主控端菜单点下去几秒内就生效,不需要重启客户端(Windows 客户端仍需重启进程)。
    • 状态不再是 std::call_once,而是 g_stateMtx 保护的 {g_tlsEnabled, g_tlsError, g_tlsCtx};TlsEnabled()/TlsLoadError()/TlsReload()/Handshake() 都在这把锁下读写。
    • 已建立的连接不受影响:SSL_new 会递增 SSL_CTX 引用计数,TlsReload 释放旧 ctx 后旧的 SSL 仍然安全(已用「连接保持打开时撤销锚」验证)。
    • 只在传输方式真的变了(明文↔TLS)时才重连;仅换锚(例如证书轮换,仍是 TLS)不打断现有会话,新锚从下一条新连接生效。
    • 热重载遇到坏锚时保留原状态并记日志,不把正在工作的客户端打死(下次启动仍按 fail-closed 语义)。
    • 重连由 DataProcess(接收线程)只置 g_needReconnect 标志,由主心跳线程 Disconnect() 后走外层重连循环——避免在接收线程里关 socket 与主线程发送竞争。
    • 代价:此刻若正处于远程桌面/文件传输会话,主连接重建会中断该会话(子连接随之失效)。这是「立即生效」的固有代价。
  • 上报:登录 szReserved[19](RES_TLS)填 TlsEnabled() ? 1 : 0,主控端主机信息显示 Y/N。热切换后重连会重新登录,登录前用 RefreshLoginTls() 刷新该字段,主控端在线列表的 TLS 列随之翻转。

7. 兼容矩阵

客户端 服务端行为 结果
老客户端(无证书概念) 明文路径 与现状完全一致
新客户端 · 无证书 明文路径 与老客户端行为一致(默认)
新客户端 · 有证书 TLS 路径 全量加密(主 + 子连接)

服务端 TLS 未配置(YAMA_TLS_CERT/KEY 为空)时,一切与现状一致,TLS 客户端握手自然失败(fail-closed)。

8. 安全考量

  • TLS 提供:机密性、完整性、服务端身份(客户端校验)、抗重放(TLS record 序号 + nonce)。即对 TLS 客户端而言,Measure 1(真加密 + 防重放)达成。
  • TLS 不提供(单向):客户端证书身份——仍由隧道内登录承担;对「未颁证客户端」不强制加密(这是本设计刻意保留的兼容性,也是薄弱点:部署安全性取决于最弱客户端)。
  • 明文前导:TLS ClientHello 前几字节明文(协议固有),仅暴露「这是 TLS 客户端」,不含业务数据;客户端不设 SNI(连接目标是 IP,无域名)。
  • 子连接:客户端统一走 TLS,screen/terminal/file 子连接一并加密;对应 Measure 2 的「源 IP 绑定」降级为纵深防御,不再是唯一防线。
  • 证书轮换:重签服务端证书后,需向已颁证客户端重新投递新信任锚(或在证书到期前提前过渡)。自签名建议 -days 3650,到期前统一更换。
  • 协议强度:MinVersion 固定 TLS 1.2+,套件用 Go 默认安全集(tls.Config 默认已排除弱套件)。

9. 部署与运维

9.1 生成证书

自签名(最简,客户端信任锚即 yama-server.crt):

openssl req -x509 -newkey rsa:2048 -nodes \
  -keyout yama-server.key -out yama-server.crt \
  -days 3650 -subj "/CN=yama-server"

或自建 CA + 签服务端证书(便于轮换,客户端信任锚为 ca.crt):

openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.crt -days 3650 -subj "/CN=yama-ca"
openssl req -newkey rsa:2048 -nodes -keyout server.key -out server.csr -subj "/CN=yama-server"
openssl x509 -req -in server.csr -CA ca.crt -CAkey ca.key -CAcreateserial -out server.crt -days 3650

9.2 服务端

YAMA_TLS_CERT=/etc/yama/server.crt \
YAMA_TLS_KEY=/etc/yama/server.key \
./server_linux_amd64 ...

9.3 客户端「颁发 + 重启」

首选:把信任锚 PEM 正文写入注册表值 Software\<exehash>\settings\tls_cert(REG_SZ),重启客户端:

$pem = Get-Content -Raw 'C:\path\yama-ca.pem'
New-Item -Path 'HKCU:\Software\<exehash>\settings' -Force | Out-Null
Set-ItemProperty -Path 'HKCU:\Software\<exehash>\settings' -Name 'tls_cert' -Value $pem -Type String
  • <exehash> = 客户端 exe 全路径小写后的 FNV 哈希(common/iniFile.h 的 GetRegistryName())。
  • 客户端以服务(SYSTEM)运行时,注册表落在会话用户的 HKEY_USERS\<SID>(GetCurrentUserRegistryKey())。
  • REG_SZ 直接存 PEM 正文(含换行);客户端动态读取,不受 iniFile::GetStr 512 字节固定缓冲限制。

兼容旧方式:把信任锚复制到客户端目录并命名为 yama-ca.pem(或经 settings.ini [settings] tls_cert 指向),重启客户端。

Linux 客户端:把信任锚放到 ~/.config/ghost/yama-ca.pem(或程序同目录 yama-ca.pem),重启客户端生效。MFC 主控端的「启用/停用 TLS 传输」指令对选中主机下发时也会写/删该文件,且 Linux 客户端会立即热切换并重连(无需重启,见 §6.6);Windows 客户端仍需重启。

移除注册表值(或删除文件)并重启即退回明文。远程下发/撤销:Windows 经 COMMAND_TLS_ENABLE/DISABLE 写注册表(重启生效),Linux 写/删上述配置文件(立即生效)。

10. 测试计划

  1. 检测单元:isTLSClientHello 对 0x16 0x03 … 0x01(TLS 1.2/1.3 ClientHello)/ POST / Shine / 混淆 HELL(首两字节恰好 0x16 0x03 但 b[5]==0x00)/ 短于 6 字节 等判定的单测(已实现 server/go/server/tls_test.go)。
  2. TLS 未配置:不设 YAMA_TLS_* → 纯明文,行为与现状一致。
  3. 明文回归:老客户端 + 新客户端(无证书)均走明文,登录/屏幕/终端/文件全链路不回归。
  4. TLS 加密:新客户端(有证书)→ 握手成功,登录/屏幕/终端/文件子连接全部在 TLS 内跑通;抓包确认 payload 不可读。
  5. 混合并发:明文与 TLS 客户端同时在线,互不干扰。
  6. fail-closed:客户端有证书但服务端证书不匹配 / 中间人 → 客户端报错断开,不回退明文。
  7. 握手超时 / 限流:恶意慢握手被 ReadTimeout + per-IP 限流压制。

11. 分期与回滚

  • 阶段 1(Go 服务端,本期优先):Config + tls.Config + acceptLoop 检测回放;明文路径零改动。可独立上线、独立验证——用 openssl s_client 或 Go 测试客户端即可联调 TLS 链路,无需真实客户端配合。
  • 阶段 2(Windows 客户端):证书检测 + TLS 栈 + fail-closed。
  • 阶段 2b(Linux 客户端):OpenSSL 实现,复用同一接线点与协议语义(2026-10-28 完成)。
  • 阶段 3(MFC 服务端 server/2015Remote,延后):与 Go 服务端同款的 TLS 检测 + 解包接入。设计稿见 docs/TransportTLS_MFCServer_Design.md。
  • 回滚:服务端清空 YAMA_TLS_CERT/KEY 即回到纯明文;客户端删除注册表 tls_cert 值(或 yama-ca.pem 文件)即回明文。

12. 待定问题

  1. 客户端 TLS 栈最终选型 → 已定 Schannel(见 §6.2,2026-10-13 落地)。
  2. 信任锚文件固定名(yama-ca.pem)是否需可配置 → 已改为注册表 tls_cert 值优先、文件回退(见 §6.1/§9.3,2026-10-14)。
  3. 是否同步把「TLS 内去掉 XOR」列为后续精简项(当前保留 XOR,换取零协议改动)。
  4. Linux / macOS / Android 客户端的 TLS 接入排期 → Linux 已接入(OpenSSL,2026-10-28);macOS / Android 待定(macOS 需 Security.framework 或自带 OpenSSL,Android 需在 NDK 内构建 OpenSSL)。