102 lines
5.1 KiB
Markdown
102 lines
5.1 KiB
Markdown
---
|
||
title: WinUnLock 项目关键决策汇总
|
||
type: curated
|
||
permalink: main/projects/ea207d36-693c-4349-b3c8-7c40c8c889f5/curated/win-un-lock-项目关键决策汇总
|
||
stable_id: 937e5888-0a9b-45ee-9312-6e110ef1619b
|
||
scope: project
|
||
project_id: ea207d36-693c-4349-b3c8-7c40c8c889f5
|
||
workspace_type: development
|
||
usage_profile_id: null
|
||
preference_context: development
|
||
document_type: decisions
|
||
revision: 1
|
||
source_memory_ids:
|
||
- 67499b3a-97a6-4982-9c16-4afaa59d45f3
|
||
- d821d390-15d1-484a-98e1-6d9656f69bfe
|
||
- ffcc24b6-2d1a-46e8-bceb-49e187dd0c20
|
||
source_checkpoint_ids: []
|
||
source_file_ids: []
|
||
source_git_commit: null
|
||
source_git_commits: []
|
||
source_agent_sync_ids: []
|
||
model_connection: Sub2API
|
||
model_name: git-restore
|
||
source_count: 15
|
||
source_revisions:
|
||
memory:d821d390-15d1-484a-98e1-6d9656f69bfe: '1'
|
||
memory:67499b3a-97a6-4982-9c16-4afaa59d45f3: '1'
|
||
memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20: '1'
|
||
source_dispositions:
|
||
processed: 15
|
||
unchanged: 0
|
||
unsupported: 0
|
||
skipped: 0
|
||
cited_source_ids:
|
||
- memory:d821d390-15d1-484a-98e1-6d9656f69bfe
|
||
- memory:67499b3a-97a6-4982-9c16-4afaa59d45f3
|
||
- memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20
|
||
job_cited_source_ids:
|
||
- memory:d821d390-15d1-484a-98e1-6d9656f69bfe
|
||
- memory:67499b3a-97a6-4982-9c16-4afaa59d45f3
|
||
- memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20
|
||
conflicts: []
|
||
supersedes: []
|
||
preferences: []
|
||
source_cursor: 92
|
||
source_hash: 4ba0814abe7570a9e62a54340ca352579628d92bc49f330cda285b38a0442283
|
||
prompt_version: 2026-08-12.3
|
||
schema_version: '3'
|
||
curation_job_id: null
|
||
created_at: '2026-08-19T10:01:20.395598+00:00'
|
||
updated_at: '2026-09-23T15:12:13.999439+00:00'
|
||
tags:
|
||
- decision
|
||
- architecture
|
||
- security
|
||
- implementation
|
||
restored_from_commit: 6a6a895eafcca6052e81a14fca103a42635dd1c2
|
||
---
|
||
|
||
# WinUnLock 项目关键决策
|
||
|
||
以下决策直接来源于项目记忆（memory）文档，按重要性分组。
|
||
|
||
## 1. 项目整体技术方向
|
||
- **决定** 实现一个工程化的 **Credential Provider DLL + 命名管道 + 定时解锁客户端**（保留会话、不重启）。放弃 AutoAdminLogon 重启方案，因为需保留当前会话。*来源: [memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20]*
|
||
|
||
## 2. Rust 工作区结构与关键参数
|
||
- Rust 工作区划分为四个 crate：
|
||
- `common`（管道协议、配置、DPAPI 包装）
|
||
- `provider`（cdylib，生成 Credential Provider COM DLL）
|
||
- `client`（binary，负责每日定时读取凭据并通过管道发送）
|
||
- `setup`（binary，交互式设置账户名/密码并使用 DPAPI 加密）
|
||
- 附加 PowerShell 安装/卸载脚本与中文 README。*来源: [memory:d821d390-15d1-484a-98e1-6d9656f69bfe]*
|
||
- **唯一 CLSID**：`{E9C67B30-B120-4838-A5A3-FBC2DE03C532}`（新生成，避免冲突）。
|
||
- **命名管道**：`\\.\pipe\WinUnLock`
|
||
- **数据目录**：`%PROGRAMDATA%\WinUnLock\`（包含 `config.toml`, `cred.bin`（DPAPI 加密凭据），日志子目录 `logs\provider.log`、`logs\client.log`）。
|
||
- 已验证的依赖组合：Rust edition 2024，`windows = 0.62.2`，`windows-core = 0.62.2`。
|
||
|
||
## 3. 管道协议与安全措施
|
||
- **管道协议 v1**（小端）：
|
||
- `magic u32 = 0x554E4C4B ('UNLK')`
|
||
- `version u32 = 1`
|
||
- `user_len u32` + UTF‑16LE 字符串
|
||
- `pass_len u32` + UTF‑16LE 字符串
|
||
- `domain_len u32` + UTF‑16LE 字符串
|
||
- 长度上限检查，读取完毕后 **zeroize** 内存。
|
||
- 数据流：系统计划任务（SYSTEM, Highest） → `client.exe` 读取 `cred.bin`（DPAPI LocalMachine 解密） → 通过命名管道发送凭据（带重试） → Provider 线程接收 → `CredentialsChanged` 通知 LogonUI → `GetSerialization` 调用 `CredPackAuthenticationBufferW` 序列化 → LSA 验证 → 解锁恢复原桌面。
|
||
- **安全恢复注意**：如果 Credential Provider 注册错误导致登录卡死，需要进入 WinRE/安全模式手动删除注册表中的 CLSID 项恢复。*来源: [memory:d821d390-15d1-484a-98e1-6d9656f69bfe]*
|
||
|
||
## 4. 原型验证经验教训（来自 Gitee winlogon 项目）
|
||
- 可成功编译生成 `winlogon.dll`（约 256 KB），导出 `DllGetClassObject`、`DllCanUnloadNow`、`DllMain`，说明 Rust cdylib 自动导出。*来源: [memory:67499b3a-97a6-4982-9c16-4afaa59d45f3]*
|
||
- **缺陷 & 教训**：
|
||
1. `DllMain` 里硬编码日志路径 `D:\log\winlogon.log` 并使用 `.expect()`，导致加载时在不存在路径下 panic → 系统卡住。**决策**：在实现中绝不在 `DllMain` 中 panic，避免硬编码日志路径。
|
||
2. README 内容占位、命名不规范、死代码。**决策**：提供完整、中文、使用说明的 README，移除死代码。
|
||
3. 必须使用 **长度前缀协议**、**ACL 拒绝远程访问**、**仅在解锁场景激活**、**密码使用后 zeroize**。*来源: [memory:67499b3a-97a6-4982-9c16-4afaa59d45f3]*
|
||
|
||
## 5. 开发与测试约束
|
||
- **协作约定**：AI 负责完整实现（多 crate、安装/卸载脚本、中文文档），用户在虚拟机中验证后再部署到生产机器。
|
||
- **禁止** 在开发机器上实际执行 `regsvr32`、修改注册表或创建真实计划任务，只做构建、导出检查等只读验证。*来源: [memory:ffcc24b6-2d1a-46e8-bceb-49e187dd0c20]*
|
||
|
||
---
|
||
*本决策文档仅引用了项目记忆来源，未添加任何未在来源中出现的事实。* |