安全模型与敏感数据处理
本文说明本工程的资产、信任边界、权限要求，以及必须让使用者知道的风险。 相关实现见
design-backup-restore.md§6。
1. 资产清单
| 资产 | 存放位置 | 敏感度 |
|---|---|---|
| 卡上私钥 | TPM 内部持久对象；卡内由 TPM 保护 | 最高（不可导出） |
| PIN / PUK / 管理密钥 | 用户记忆；映射数据在 store 的 keymaps/pinmaps/pinpolicy（DPAPI 保护） | 最高 |
| 卡片密钥与 PIN 映射数据 | store 内 5 个 DPAPI blob | 高（解开后即等同密钥材料） |
| DPAPI 主密钥 | …\Microsoft\Protect\<SID>[\User]\（源机） | 高（可解密同账户所有受保护数据） |
备份包 .tsb | 用户自选路径 | 高（含密钥材料明文，见 §4） |
| 日志文件 | %APPDATA%\TPMSmartCard\logs\ | 中（含设备与路径信息，不含 PIN/私钥原文） |
| 云端下发取件码 | 用户持有 | 高（Cryptography.py：PBKDF2-SHA256 派生 + AES-256-CBC） |
2. 信任边界与权限
- 工具以管理员身份运行（清单
requireAdministrator）。管理员的运行期会用到三类高权限操作：- 注册 PnP 设备节点（
SetupDi+ 安装tpmvsc.inf）； - 读写
%ProgramData%、System32\config\systemprofile等系统位置（TPM 密钥索引）； - 借用 SYSTEM 令牌做 DPAPI 加解密（卡片数据由服务账户写入，必须同身份操作）。
- 注册 PnP 设备节点（
- 因此**"能运行本工具的管理员"等价于"能操作本机 TPM 与卡片数据"** —— 这一点必须在使用说明中 让用户知情，不要在不信任的机器上运行。
- 首次运行需要 UAC 提权；未提权时相关功能应明确失败并提示。
3. DPAPI 使用原则
- 优先用户作用域：卡片数据是用户作用域的 DPAPI blob（描述
TPMVSC），实现按 blob 记录的flags还原作用域，不擅自提升为机器作用域（机器作用域可被本机任何账户解开，暴露面更大）。 - 令牌借用取最小面：只借一次、只用于这一次加解密，用完立即
RevertToSelf并关闭句柄； 借用前校验目标账户 SID，借用后做一次 DPAPI 往返探针确认该身份确实可用。 - 不落主密钥：工具不导出、不缓存、不写盘任何 DPAPI 主密钥；重装系统后的恢复采用 「源机解密 → 目标机重新加密」，从设计上避免主密钥离开原机器。
- 回验：重新加密后立刻解密比对，避免把卡片数据写坏（宁可退回原始密文）。
4. 备份包（.tsb）的风险与缓解
风险（必须显式告知）：为了让目标机能解开卡片密钥与 PIN 映射，备份包内含这 5 个文件的 DPAPI 明文。因此 .tsb 的安全等级等同密钥材料：
- 拿到包的人不一定能直接签走卡上私钥（私钥仍在 TPM 内），但可读取卡内数据与 PIN 映射， 并可在有权限的机器上重建同内容的卡片文件结构；
- 包内还含设备注册表与设备属性（含卡片名、store 路径、卡片 GUID 常量），可推断环境信息。
缓解措施（实现已做 + 建议用户做）
| 措施 | 状态 |
|---|---|
清单 notes 与界面文案明确告知"包内含明文密钥材料" | 已实现 |
| 日志中不打印解密后的内容，只打印长度/账户/作用域 | 已实现 |
| 整包加密（用 PIN / 管理口令派生密钥） | 未实现，见 design-backup-restore.md §10 |
| 用户侧：离线保管、限制访问、不进版本库 / 云盘 / 聊天工具 | 使用说明中应写明 |
| 用户侧：备份完成口令提示（同时妥善保存卡片名、PIN、PUK、管理密钥） | 已实现 |
5. 凭据、日志与调试卫生
- 日志不记录 PIN / PUK / 管理密钥 / DPAPI 明文内容；只记录路径、长度、账户、错误码。
- 调试脚本：临时脚本禁止把口令、密钥写进仓库或长期留在磁盘；用完即删。 （本项目历史调试中用过编译
askpass的临时 SSH 助手脚本，均已按此约定清理。） - 测试机卫生：调试留下的计划任务必须禁用或删除；临时文件（探针输出、测试备份包）及时清理。
- 备份包外发：支持场景中收集日志即可，不要收取
.tsb（除非用户明确知情并同意）。
6. 云端下发（简述）
Module/Cryptography.py 负责"云端下发证书/密钥"的本地加解密：取件码先做规范化， 再用 PBKDF2-SHA256 派生密钥，用 AES-256-CBC 加解密。设计要点是密钥不经网络明文传输， 取件码由用户以带外方式获得。协议细节与接口约定待补文档（见 README.md 待补清单）。
7. 安全评审建议关注点
| 关注点 | 说明 |
|---|---|
| 令牌借用的最小化 | 是否存在借用后未 RevertToSelf 的路径；异常路径是否会泄漏令牌句柄 |
| 备份包明文 | 是否接受；若不接受需要设计整包加密与口令找回策略 |
| 设备属性写回 | 覆盖策略（卡片身份不一致即覆盖）是否可能被用于篡改其它设备（当前仅作用于本工具目标设备） |
| 密钥索引写回 | 同名不覆盖；需确认不会影响本机既有 TPM 密钥（如 Windows AIK） |
| 权限提升面 | 管理员 + SYSTEM 令牌借用的组合是否可被本机的非管理员进程利用（工具自身不暴露网络接口，需核对） |