macOS shares the Linux transport: TlsChannel.h now dispatches __APPLE__ to the OpenSSL implementation, so handshake, pinned trust anchor, reload and removal all come from client/TlsChannelLinux.cpp. Only the platform glue is new: ConfigDir() follows initConfigPaths (HOME, then getpwuid(), then /tmp; no XDG) so the anchor sits next to config.conf, and ExeDir() uses _NSGetExecutablePath. First connect stays plaintext. The operator turns TLS on from the online list: COMMAND_TLS_ENABLE carries the anchor PEM, COMMAND_TLS_DISABLE removes it. macos/main.mm saves the anchor, calls TlsReload() and only reconnects when the transport actually changed, so re-saving the same anchor does not drop a live session. RES_TLS is filled from TlsEnabled() and refreshed on every reconnect; fillLoginInfo clears szReserved first now, because AddReserved appends and it runs twice on a group change. CMake builds arm64 only (deployment target 11.0) and links Homebrew openssl@3 statically when libcrypto.a is present, so the binary carries no Homebrew path dependency. Not built or run on a Mac yet: the Apple branch was syntax-checked under WSL and the login refresh probe-tested; macos/README.txt has the build and verify steps. Co-Authored-By: deepseek-flash
367 lines
31 KiB
Markdown
367 lines
31 KiB
Markdown
# 传输层单向 TLS 加密设计(按需加密)
|
||
|
||
> 版本:v0.9 · 状态:**Go 服务端 + Windows/Linux/Android 客户端已实现并验证;Linux/Android 客户端支持下发即时热切换;macOS 客户端已按同一模式实现(2026-11-14,待 Mac 实机构建验证);MFC 主控端见 `TransportTLS_MFCServer_Design.md`** · 日期:2026-11-14(macOS 客户端接入)
|
||
> 目标:让 YAMA 设备端口(TCP 6543)在继续兼容老客户端(明文/XOR)的同时,允许新客户端在拿到证书后按需开启**单向 TLS** 加密传输。
|
||
> 本期范围:**Go 服务端(`server/go`)+ Windows 客户端 + Linux 客户端 + Android 客户端**。
|
||
>
|
||
> 需求原文(三点,逐一对应下文):
|
||
> 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 / Android / macOS 客户端例外:服务端下发 166/167 后立即重载信任锚并重连切换(§6.6 / §6.7 / §6.8),语义差异见该三节。
|
||
- 不做 **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 + 两轮伪随机交换,密钥是明文带内 1~2 字节)+ `header.go` 的 V0~V6 头混淆——**等于明文**。这正是 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(仅明文,向后兼容):
|
||
|
||
```go
|
||
TLSCertFile string // 服务端证书(PEM)
|
||
TLSKeyFile string // 服务端私钥(PEM)
|
||
```
|
||
|
||
`cmd/main.go` 读取环境变量(沿用现有 `YAMA_*` 命名):
|
||
|
||
```go
|
||
cfg.TLSCertFile = os.Getenv("YAMA_TLS_CERT")
|
||
cfg.TLSKeyFile = os.Getenv("YAMA_TLS_KEY")
|
||
```
|
||
|
||
仅当两者都非空才构建 `*tls.Config`;否则 `s.tlsCfg == nil`,`acceptLoop` 走纯明文。
|
||
|
||
### 5.2 `tls.Config`
|
||
|
||
```go
|
||
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 走明文,由读循环处理:
|
||
|
||
```go
|
||
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`。
|
||
|
||
Android 同样无注册表,信任锚为 App 私有 `context.filesDir/yama-ca.pem`(目录由 `TlsSetAnchorDir()` 在 `nativeInit` 注入,见 §6.7),无程序目录回退;存在即视为已配置、fail-closed。与 Linux 共用 `client/TlsChannelLinux.cpp` 实现。
|
||
|
||
macOS 无注册表,信任锚为 `~/.config/ghost/yama-ca.pem`(与 `macos/main.mm` 的 `config.conf` 同目录;**不看 `XDG_CONFIG_HOME`**,保持与 macOS 客户端既有配置路径一致)→ ② 程序目录(`_NSGetExecutablePath`)`yama-ca.pem`。存在即视为已配置、fail-closed。与 Linux/Android 共用 `client/TlsChannelLinux.cpp` 实现(见 §6.8)。
|
||
|
||
### 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,见 §6.7)与 `__APPLE__`(macOS,见 §6.8)→ OpenSSL),Windows 分支内容不变;实现文件为 `client/TlsChannelLinux.cpp`。`YAMA_TLS_CHANNEL` 宏标注「本平台有 TLS 通道」,`IOCPClient` 用它替代原先的 `#ifdef _WIN32`,因此主连接与子连接共用同一接线点。
|
||
- **语义对齐**:`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 列随之翻转。Android 同。
|
||
|
||
### 6.7 Android 客户端实现(OpenSSL,2026-11-11)
|
||
|
||
- **选型 / 代码组织**:完全复用 Linux 的 OpenSSL 实现(`client/TlsChannelLinux.cpp`)。`TlsChannel.h` 的平台分支由 `__linux__ && !__ANDROID__` 放宽为 `__linux__`(Android 同时定义两宏),`YAMA_TLS_CHANNEL` 随之在 Android 生效,主连接与子连接共用和 Linux 相同的接线点(`IOCPClient`)。**服务端零改动**:在线主机菜单本就向所有选中主机下发 166/167,不区分平台。
|
||
- **信任锚目录**:Android 无注册表、无「程序目录」概念,锚文件放 App 私有 `context.filesDir/yama-ca.pem`(无需存储权限、跨重启持久、按 App 隔离)。目录在 `nativeInit` 里经 `TlsSetAnchorDir()` 注入一次(先于连接线程首次 `TlsEnabled()`);`ConfigDir()` 在 Android 返回该目录,`ExeDir()` 返回空。
|
||
- **语义 / 热切换**:与 Linux 完全一致——TLS1.2 钉扎信任锚、单向、fail-closed、`TlsReload()` 热重载、仅在传输方式真变(明文↔TLS)时重连(`g_needReconnect` 由接收线程置位、心跳线程断开后走外层重连循环)。主控端点「启用/停用 TLS」后几秒内生效,**无需重启 App**。WSS 在无锚时按明文 WS 打通隧道、下发锚后下一次连接自动升级(与 Linux 同,见 `IOCPClient::ConnectServer`)。
|
||
- **上报**:登录 `szReserved[19]`(`RES_TLS`)填 `TlsEnabled()`,热切换重连登录前用 `RefreshLoginTls()` 刷新,在线列表 TLS 列随之翻转。
|
||
- **OpenSSL 构建**:Android 的 `libsign.a` 用便携纯 C SHA256、不含 OpenSSL,故需新交叉编译 `libssl.a`/`libcrypto.a`。`android/build_openssl_android.sh`(已并入 `build_android_libs.ps1`,可 `-OpenSslOnly` 单跑)用 NDK clang + MSYS2 perl/make 按 ABI(arm64-v8a / armeabi-v7a / x86 / x86_64,API 21)构建 OpenSSL 3.5.0 静态库(`no-shared no-apps no-legacy` 等裁剪);产物落 `app/src/main/cpp/lib/<ABI>/`,`opensslconf.h` 各架构不同故头文件也按 ABI 存放。CMake 链接 `libssl.a`+`libcrypto.a`,并用 `-Wl,--exclude-libs,ALL` 不让静态库符号泄出 `libyama.so`(与 Java 层 Conscrypt 隔离;JNI 入口来自目标文件,不受影响)。
|
||
- **Windows 构建坑(已解决)**:Git for Windows 的精简 perl 缺 Configure 所需模块,且其 bash/env 会抢占 PATH——跨 MSYS 运行时传子进程丢环境变量(Configure 拿不到 `ANDROID_NDK_ROOT`),脚本改用 `#!/bin/bash` 并把 MSYS2 `/usr/bin` 置顶;NDK 自带原生 make 不认 Makefile 里的 `/c/...` 路径,须用 MSYS2 make(`pacman -S make`)。
|
||
|
||
### 6.8 macOS 客户端实现(OpenSSL,2026-11-14)
|
||
|
||
- **选型 / 代码组织**:复用 Linux/Android 的 OpenSSL 实现。`client/TlsChannel.h` 的平台分支由 `__linux__` 放宽为 `__linux__ || __APPLE__`,`TlsChannelLinux.cpp` 的编译守卫同步放宽(该文件本就是 OpenSSL + POSIX,无 Linux 专有调用);`YAMA_TLS_CHANNEL` 随之在 macOS 生效,主连接/子连接共用与 Linux 相同的接线点(`IOCPClient`)。**服务端零改动**。
|
||
- **平台差异点(都在 `TlsChannelLinux.cpp` 内条件编译)**:
|
||
- **配置目录**:`ConfigDir()` 在 Apple 上**不读 `XDG_CONFIG_HOME`**,HOME 兜底顺序与 `macos/main.mm` 的 `initConfigPaths` 逐字对齐(`HOME` → `getpwuid()->pw_dir` → `/tmp`),最终都是 `<home>/.config/ghost`——否则信任锚和 `config.conf` 会落在两个目录(launchd daemon 不导出 `HOME` 时尤其明显:锚落到程序目录,重装 app bundle 时跟着被删,客户端静默退回明文而服务端仍以为它是 TLS)。
|
||
- **程序目录回退**:`ExeDir()` 用 `_NSGetExecutablePath`(`<mach-o/dyld.h>`)截取目录;Linux 继续用 `/proc/self/exe`,Android 仍返回空。
|
||
- **`SIGPIPE`**:`macos/main.mm` 启动时已 `signal(SIGPIPE, SIG_IGN)`(WSS 引入时加的),TLS 写入对端已关时不会直接杀掉进程。
|
||
- **热切换接线(`macos/main.mm`)**:与 Linux 同一套语义。`DataProcess` 收到 `COMMAND_TLS_ENABLE`(166) → `TlsTrustAnchorSave()`;`COMMAND_TLS_DISABLE`(167) → `TlsTrustAnchorRemove()`;两者随后都走 `ApplyTlsAnchorChange()`:`TlsReload()` 重建 `SSL_CTX`,只在传输方式真的变化(明文↔TLS)时置 `g_needReconnect`(接收线程只置标志),主心跳循环每秒检查、`Disconnect()` 后由外层重连循环用新传输方式重连。仅换锚不打断现有会话。
|
||
- **上报**:登录 `szReserved[19]`(`RES_TLS`)填 `TlsEnabled() ? 1 : 0`;重连登录前用 `RefreshLoginTls()` 刷新(`logInfo` 启动时填一次、之后复用)。顺带修掉一个既有缺陷:分组变更重发登录时 `fillLoginInfo()` 会被再次调用,而 `AddReserved()` 是追加语义,原先会把整套保留字段再拼一遍,导致服务端按 `LOGIN_RES` 下标读到错位/重复字段——现在 `fillLoginInfo()` 入口先清空 `szReserved`。
|
||
- **构建(`macos/CMakeLists.txt` / `build.sh`)**:
|
||
- 源码列表加入 `client/TlsChannelLinux.cpp`;链接 `OpenSSL::SSL`、`OpenSSL::Crypto`。
|
||
- Homebrew 的 `openssl@3` 不在 CMake 默认搜索路径,`CMakeLists.txt` 自动探测 `/opt/homebrew/opt/openssl@3`(及其它常见前缀),找不到直接 `FATAL_ERROR` 并提示 `brew install openssl@3`,也可 `-DOPENSSL_ROOT_DIR=...` 指定。
|
||
- 有静态库(`libssl.a`/`libcrypto.a`)时优先静态链接(`OPENSSL_USE_STATIC_LIBS`),避免发布包还得让目标 Mac 装 Homebrew OpenSSL;只有动态库时给 `WARNING`,需自行把 dylib 放进 `Contents/Frameworks`。
|
||
- 目标为 **arm64 单架构**(Homebrew OpenSSL 只有本机架构,保留 x86_64 slice 会链接失败)、部署目标 macOS 11.0。`build.sh` 通过命令行显式传 `-DCMAKE_OSX_ARCHITECTURES=arm64 -DCMAKE_OSX_DEPLOYMENT_TARGET=11.0`——这两个是 CMake **cache 变量**,在已存在的 `build/` 目录里改了 `CMakeLists.txt` 也不会生效,必须命令行覆盖或删目录重建。
|
||
- **注意**:macOS 客户端在线升级仍不支持(服务端 `OnOnlineUpdate` 无 MAC 分支),升级 TLS 相关代码需重新 `macos/build.sh` 并按 `macos/install.sh` 部署(会重置 TCC 授权)。
|
||
|
||
## 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`):
|
||
|
||
```bash
|
||
openssl req -x509 -newkey rsa:2048 -nodes \
|
||
-keyout yama-server.key -out yama-server.crt \
|
||
-days 3650 -subj "/CN=yama-server"
|
||
```
|
||
|
||
或自建 CA + 签服务端证书(便于轮换,客户端信任锚为 `ca.crt`):
|
||
|
||
```bash
|
||
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 服务端
|
||
|
||
```bash
|
||
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),重启客户端:
|
||
|
||
```powershell
|
||
$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 客户端仍需重启。
|
||
|
||
Android 客户端:信任锚写入 App 私有 `filesDir/yama-ca.pem`(经 166/167 下发/撤销),**同样立即热切换并重连**(无需重启 App,见 §6.7);无需手工放置文件。
|
||
|
||
移除注册表值(或删除文件)并重启即退回明文。远程下发/撤销: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 完成)。
|
||
- **阶段 2c(Android 客户端)**:复用 Linux OpenSSL 实现,NDK 按 ABI 交叉编译 OpenSSL,热切换(2026-11-11 完成)。
|
||
- **阶段 2d(macOS 客户端)**:复用 Linux OpenSSL 实现(`__APPLE__` 分支 + `_NSGetExecutablePath`),Homebrew OpenSSL 静态链接,热切换(2026-11-14 完成代码,待 Mac 实机验证)。
|
||
- **阶段 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(2026-10-28)、Android(2026-11-11)、macOS(2026-11-14)已接入**(均 OpenSSL、支持热切换)。
|