# 安全连接器开发计划 ## 项目概述 基于 `docs/连接器安全增强设计方案.md` 实现安全连接器后端系统,支持: - 设备注册与 TPM 认证 - 密钥分层管理 (KEK/DEK) - 量子安全密钥分发 (预留 PQC 接口) - EasyTier 隧道协调 - k3s API Gateway --- ## 当前状态 | 模块 | 状态 | 说明 | |------|------|------| | 服务端编译 | ✅ | 通过 | | 连接器编译 | ✅ | 通过 | | 服务端运行 | ✅ | 可正常启动 | | 连接器运行 | ✅ | 可正常启动 | | Mock TPM 注册 | ✅ | key size 问题已修复 | | API 端点 | ✅ | 所有端点已实现 | | 健康检查 | ✅ | `/health` 端点已实现 | | TPM Provider | ✅ | 硬件自动检测框架完成 | | 单元测试 | 🔄 | 部分模块已覆盖 | | 集成测试 | ⬜ | 未开始 | --- ## Phase 1: 核心服务 (已完成) ### 1.1 修复 Mock TPM 注册问题 **问题**: `invalid key size` - connector 注册时 StoreKey 加密失败 **根因**: `loadKeys()` 只加载了密钥到内存,但没有初始化 `masterKey`。重启后 `masterKey` 为 nil,长度 0,导致 `EncryptAES256GCM` 失败。 **修复**: - [x] 检查 `keys.Manager.NewManager` masterKey 生成逻辑 - [x] 确保 masterKey 是完整的 32 bytes - [x] 添加 masterKey 为空时的保护逻辑 - [x] 验证 EncryptAES256GCM 调用成功 **修复文件**: `connector/keys/manager.go` **状态**: ✅ 已完成 (2026-05-22) ### 1.2 服务端 API 完善 - [x] 添加 `/api/v1/health` 健康检查端点 - [ ] 添加 OpenAPI/Swagger 文档 - [ ] 添加请求超时和速率限制 - [ ] 添加请求日志中间件 ### 1.3 密钥管理 - [ ] 实现 KEK 派生 (ECDH) - [ ] 实现 DEK 生成 - [ ] 实现密钥轮换 - [ ] 实现增量烧录 (Partial Key Update) - [ ] 添加密钥版本管理 ### 1.4 设备认证 - [ ] 实现 TPM Quote 验证 - [ ] 实现挑战-响应流程 - [ ] 实现 PCR 完整性验证 - [ ] 添加设备状态机 (pending → registered → active → revoked) --- ## Phase 2: TPM 接口 (进行中) ### 2.1 TPM Provider 架构 **新增文件**: - `connector/tpm/provider.go` - TPM 硬件自动检测 - `connector/tpm/linux_tpm.go` - Linux TPM 驱动接口 - `connector/tpm/fpga_forwarder.go` - FPGA TPM 转发器 - `connector/tpm/provider_test.go` - Provider 测试 **检测优先级**: 1. `/dev/tpm0` - Linux 内核 TPM 驱动 2. FPGA 设备路径 - 直接访问 (未来) 3. Mock TPM - 软件模拟 **状态**: ✅ 已完成 ### 2.2 Mock TPM 完善 - [x] 完善 `QuoteToBase64` 返回值 - [x] 添加 PCR 扩展验证 - [x] 添加 key 生成/加载持久化 ### 2.3 真 TPM 接口 - [x] 定义 TPM 接口 interface (已在 `tpm.go`) - [x] 实现 TPM 2.0 命令封装 (LinuxTPM) - [ ] 在 Zynq-7015 上验证 (待硬件) ### 2.4 Connector 集成 - [x] 更新 connector 使用 TPM Provider - [x] EasyTier client 存储到 connector 字段 **状态**: ✅ 已完成 (2026-05-23) ### 2.5 FPGA TPM 实现 **新增文件**: - `connector/tpm/fpga_tpm.go` - FPGA TPM 软件实现 - `connector/tpm/fpga_tpm_test.go` - FPGA TPM 测试 **功能**: - SRK 生成和管理 - 密钥生成 (ECDSA P256) - PCR Extend/Read (仿真模式) - Seal/Unseal (简单 XOR 实现) - Quote 生成 - 密钥持久化 (PEM 格式) **状态**: ✅ 代码已完成,待硬件验证 ### 2.6 FPGA TPM 烧录状态 (2026-05-23) **硬件状态分析**: - FPGA Manager 框架已加载 (Xilinx Zynq FPGA Manager) - `/dev/fpga_tpm` 不存在 - TPM 软核未烧录 - `/dev/tpm0` 不存在 - Linux TPM 驱动未绑定 - 当前 `system.bit` 不含 TPM 逻辑 **TPM 软核实现路径** (需要 HDL 开发): 1. 在 Vivado 中创建/添加 TPM 软核 IP (RSA/ECC 引擎 + SHA-256 + PCR) 2. 连接 AXI 总线与 ARM 通信 3. 生成新的 `.bit` 文件 4. 烧录到 FPGA **当前状态**: 软件框架已完成 (FPGATPM, Provider),硬件 TPM 软核待烧录 **烧录优先级**: ⬜ 低 (Mock TPM 可满足当前开发测试) --- ## Phase 3: EasyTier 集成 ### 3.1 EasyTier 协调器 - [ ] 实现 `authorize_device` 调用 - [ ] 实现设备 ACL 管理 - [ ] 实现凭证管理模式 (`--enable-creds`) ### 3.2 连接器间通信 - [ ] 实现 Cross_SK 会话密钥生成 - [ ] 实现端到端加密通道建立 - [ ] 添加连接超时和重试 --- ## Phase 4: k3s 集成 ### 4.1 API Gateway - [ ] 实现 k8s admission webhook 模式 - [ ] 实现认证头注入 (TPM 签名) - [ ] 实现密钥注入到 Volume ### 4.2 节点注册 - [ ] 实现 `register_k3s_node` 调用 - [ ] 实现 node_token 管理 - [ ] 实现 kubelet 连接验证 --- ## Phase 5: PQC 量子安全 ### 5.1 算法预留 - [ ] 添加 ML-KEM-768 接口 - [ ] 添加 ML-DSA-65 接口 - [ ] 实现混合密钥交换 (ECDH + PQC) ### 5.2 密钥分发 - [ ] 实现 OTP 密钥片段管理 - [ ] 实现光纤模式 QRNG 接口 - [ ] 实现加密隧道模式 --- ## Phase 6: 测试与验证 ### 6.1 单元测试 - [ ] crypto 模块测试 (ECDH, AES-GCM, ECDSA) - [ ] proto 消息解析测试 - [ ] 策略引擎测试 ### 6.2 集成测试 - [ ] 服务端 + 连接器 注册流程 - [ ] 挑战-响应认证流程 - [ ] 密钥更新流程 ### 6.3 端到端测试 - [ ] 两台连接器间加密通信 - [ ] 服务端故障恢复 - [ ] 密钥过期处理 --- ## Phase 7: FPGA 硬件 (待硬件) > 以下模块需等待 Zynq-7015 硬件到位 ### 7.1 FPGA 基础架构 - [ ] Vivado 项目创建 - [ ] PCIe Endpoint IP Core - [ ] AXI 总线互联 - [ ] ARM + FPGA 通信框架 ### 7.2 TPM 软核 - [ ] RSA/ECC 引擎 (~20K LUT) - [ ] SHA-256 引擎 - [ ] TPM 命令接口 (TIS 协议) - [ ] PCR 寄存器 ### 7.3 加密引擎 - [ ] AES-256-GCM 硬件加速 - [ ] TRNG 真随机数 (~3K LUT) - [ ] DMA 引擎 ### 7.4 SED 控制器 - [ ] OPAL 2.0 命令 - [ ] SATA III 接口 - [ ] 硬盘密码管理 --- ## 里程碑 | 里程碑 | 目标日期 | 交付物 | |--------|---------|--------| | M1: 本地运行 | 2026-05-20 | 服务端+连接器可在 Mac 本地运行 | | M2: 注册流程 | 2026-05-25 | 完整设备注册 + 认证流程 | | M3: EasyTier | 2026-06-01 | 隧道协调 + 跨连接器通信 | | M4: k3s 集成 | 2026-06-15 | API Gateway + 节点注册 | | M5: 硬件验证 | TBD | FPGA/TPM 真机测试 | --- ## 技术栈 | 组件 | 技术 | |------|------| | 语言 | Go 1.21+ | | 服务端 | net/http (无外部框架) | | 数据库 | JSON 文件 (开发) / PostgreSQL (生产) | | 加密 | crypto/ecdsa, crypto/aes, golang.org/x/crypto | | TPM | Mock 实现 (Phase 1) / Zynq FPGA (Phase 7) | | 网络 | EasyTier, mTLS | | k8s | k3s, admission webhook | --- ## 文件结构 ``` code/ ├── go.mod ├── README.md ├── plan.md # 本文件 │ ├── common/ │ ├── proto/messages.go # API 消息格式 │ ├── crypto/crypto.go # 共享加密原语 │ └── types/types.go # 共享类型 │ ├── server/ │ ├── main.go # 服务端入口 │ ├── api/handler.go # HTTP 处理器 │ ├── auth/auth.go # 设备认证 │ ├── crypto/keys.go # 服务端密钥管理 │ ├── keyring/keyring.go # KEK/DEK ring │ ├── policy/engine.go # RBAC 策略引擎 │ ├── audit/logger.go # 审计日志 │ └── easytier/coordinator.go # EasyTier 协调 │ ├── connector/ │ ├── main.go # 连接器入口 │ ├── tpm/tpm.go # TPM 接口定义 │ ├── tpm/mock_tpm.go # Mock TPM (Phase 1) │ ├── register/registrar.go # 设备注册 │ ├── keys/manager.go # 本地密钥管理 │ └── k3s/client.go # k3s API 客户端 │ ├── scripts/ │ └── cloudinit/generate.sh # cloud-init 配置生成 │ └── tests/ # 测试 ├── crypto_test.go ├── auth_test.go └── integration_test.go ``` --- ## 已知问题 | Issue | 状态 | 说明 | |-------|------|------| | Mock TPM key size 错误 | ✅ | 已修复 masterKey 初始化逻辑 | | 缺少 health 端点 | ✅ | `/health` 已实现 | | 无单元测试 | ⬜ | 测试覆盖率 0% | | 无配置文件 | ⬜ | 硬编码参数 | | masterKey 未持久化 | ⬜ | 重启后需重新注册 (Phase 1 可接受) | --- ## 下一步行动 1. **立即**: 修复 Mock TPM key size 问题 2. **今天**: 添加 health 端点 3. **本周**: 完成设备注册 + 认证完整流程 4. **下周**: EasyTier 集成