Feature: Add on-demand TLS transport with hot-switch to the Android client

Reuse the Linux OpenSSL TlsChannel implementation (platform guard widened
to __linux__); the trust anchor lives in the app-private filesDir, injected
via TlsSetAnchorDir in nativeInit before the connection thread starts.
COMMAND_TLS_ENABLE/DISABLE save/remove the anchor, hot-reload and reconnect
only when the transport actually changes, so the master menu takes effect
within seconds without restarting the app. Login reports RES_TLS, refreshed
before each re-login. The reconnect flag is consumed before the drop check
and cleared before reconnecting so a switch racing a disconnect cannot
cause an extra reconnect/login cycle.

Cross-compile OpenSSL 3.5.0 per ABI with build_openssl_android.sh (NDK
clang + MSYS2 perl/make), integrated into build_android_libs.ps1
(-OpenSslOnly). Static libs and per-ABI headers are tracked like the
existing libzstd/libsign prebuilts; --exclude-libs keeps OpenSSL symbols
private to libyama.so, isolated from the Java-layer Conscrypt.

Co-Authored-By: Qoder <noreply@qoder.com>
This commit is contained in:
yuanyuanxiangandQoder committed 2026-11-11 11:56:32 +01:00
1 parent 36618b0ad0
commit 51747dc0ea
586 files changed
+183905 -35

No files matched your search

+20 -6
View File
@@ -1,8 +1,8 @@
# 传输层单向 TLS 加密设计(按需加密)
> 版本:v0.7 · 状态:**Go 服务端 + Windows/Linux 客户端已实现并验证;Linux 客户端支持下发即时热切换;MFC 主控端见 `TransportTLS_MFCServer_Design.md`;macOS/Android 未接入** · 日期:2026-10-28(Linux 客户端接入 + 热切换)
> 版本:v0.8 · 状态:**Go 服务端 + Windows/Linux/Android 客户端已实现并验证;Linux/Android 客户端支持下发即时热切换;MFC 主控端见 `TransportTLS_MFCServer_Design.md`;macOS 未接入** · 日期:2026-11-11(Android 客户端接入 + 热切换)
> 目标:让 YAMA 设备端口(TCP 6543)在继续兼容老客户端(明文/XOR)的同时,允许新客户端在拿到证书后按需开启**单向 TLS** 加密传输。
> 本期范围:**Go 服务端(`server/go`)+ Windows 客户端 + Linux 客户端**。
> 本期范围:**Go 服务端(`server/go`)+ Windows 客户端 + Linux 客户端 + Android 客户端**。
>
> 需求原文(三点,逐一对应下文):
> 1. 新客户端**默认不加密**,行为与老客户端完全一致;
@@ -23,8 +23,8 @@
- 不做 **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)。
- Windows 客户端**不做**加密开关的运行时热切换(证书只在进程启动时读取一次,改配置需重启——这正是需求)。Linux / Android 客户端例外:服务端下发 166/167 后立即重载信任锚并重连切换(§6.6 / §6.7),语义差异见该两节。
- macOS 客户端的 TLS 接入不在本期(Linux / Android 客户端已按同一模式接入,见 §6.6 / §6.7)。
- 不做 **MFC 服务端(`server/2015Remote`)的 TLS 接入**——本期只做 Go 服务端(`server/go`),MFC 主控端延后到阶段 3。
## 2. 现状与复用
@@ -192,6 +192,8 @@ func (s *Server) wrapTLS(conn net.Conn) net.Conn {
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` 实现。
### 6.2 TLS 栈选型(已定:Schannel)
- **已选 Schannel(Windows 原生 SSPI)**:零第三方依赖/零额外 DLL 部署,`secur32.lib`/`crypt32.lib` 均为系统库(`secur32.lib` 已在 `CFFmpegH264Encoder.cpp:38` 链接)。
@@ -228,7 +230,7 @@ Schannel 流模式(`ISC_REQ_STREAM`)下,`DecryptMessage` 会把输入的
### 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 不定义该宏,维持明文。
- **代码组织**:`client/TlsChannel.h` 按平台分派(`_WIN32` → Schannel,`__linux__` → OpenSSL,含 Android,见 §6.7),Windows 分支内容不变;实现文件为 `client/TlsChannelLinux.cpp`。`YAMA_TLS_CHANNEL` 宏标注「本平台有 TLS 通道」,`IOCPClient` 用它替代原先的 `#ifdef _WIN32`,因此主连接与子连接共用同一接线点。macOS 不定义该宏,维持明文。
- **语义对齐**:`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 解析一遍,不是合法证书就整包拒绝并保留原状态。
@@ -241,6 +243,15 @@ Schannel 流模式(`ISC_REQ_STREAM`)下,`DecryptMessage` 会把输入的
- **代价**:此刻若正处于远程桌面/文件传输会话,主连接重建会中断该会话(子连接随之失效)。这是「立即生效」的固有代价。
- **上报**:登录 `szReserved[19]`(`RES_TLS`)填 `TlsEnabled() ? 1 : 0`,主控端主机信息显示 Y/N。热切换后重连会重新登录,登录前用 `RefreshLoginTls()` 刷新该字段,主控端在线列表的 TLS 列随之翻转。
### 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`)。
## 7. 兼容矩阵
| 客户端 | 服务端行为 | 结果 |
@@ -306,6 +317,8 @@ Set-ItemProperty -Path 'HKCU:\Software\<exehash>\settings' -Name 'tls_cert' -Val
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. 测试计划
@@ -323,6 +336,7 @@ Linux 客户端:把信任锚放到 `~/.config/ghost/yama-ca.pem`(或程序
- **阶段 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 完成)。
- **阶段 3(MFC 服务端 `server/2015Remote`,延后)**:与 Go 服务端同款的 TLS 检测 + 解包接入。设计稿见 `docs/TransportTLS_MFCServer_Design.md`。
- **回滚**:服务端清空 `YAMA_TLS_CERT/KEY` 即回到纯明文;客户端删除注册表 `tls_cert` 值(或 `yama-ca.pem` 文件)即回明文。
@@ -331,4 +345,4 @@ Linux 客户端:把信任锚放到 `~/.config/ghost/yama-ca.pem`(或程序
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)。
4. ~~Linux / macOS / Android 客户端的 TLS 接入排期~~ → **Linux(2026-10-28)、Android(2026-11-11)已接入**(均 OpenSSL、支持热切换);macOS 待定(需 Security.framework 或自带 OpenSSL)。
+2 -2
View File
@@ -112,7 +112,7 @@ Host 头同理:用**配置里的地址(域名)**,而不是解析后的 I
| 有锚但加载失败(损坏/为空) | 拒绝连接(fail-closed)——管理员已「颁发」证书,不能静默回退明文 |
| 无锚 + `PROTO_WS` | 明文(本来如此) |
| 有锚 + `PROTO_WS` | **仍是明文**(显式选择的形态,见下) |
| 平台无 TLS(macOS / Android 未定义 `YAMA_TLS_CHANNEL`)+ `PROTO_WSS` | 直接断开并打日志:没有热切换路径,回退只会让人误以为在加密 |
| 平台无 TLS(macOS 未定义 `YAMA_TLS_CHANNEL`)+ `PROTO_WSS` | 直接断开并打日志:没有热切换路径,回退只会让人误以为在加密 |
| WS 握手失败 | 断开,`Mprintf` 里带上服务端返回的状态行 |
回退的判据是「本机**根本没有**信任锚」这一可观测状态,而不是握手中途失败——TLS 握手
@@ -415,7 +415,7 @@ server {
升级线程里才有。若这是硬性合规要求,需单独评估(本特性未改变这一点,只是让它的漏检更
容易发生)。
- 裸 `PROTO_WS` 是明文,只适合内网或回环(nginx 已在同一台机器上终止 TLS 的情形用 WSS 即可)。
- macOS / Android 客户端没有 TLS 实现,只能选 `PROTO_WS`(明文),走不了 443。
- macOS 客户端没有 TLS 实现,只能选 `PROTO_WS`(明文),走不了 443(Linux / Android 已有 TLS,见 `TransportTLS_Design.md` §6.6 / §6.7)。
- 经反代接入时地址只应填**一个域名**(多地址取第一个做 Host/SNI)。
- 不改应用协议、不改 MCP、不改 Web 控制台。