Files
ssw-mvp/scard/code/plan.md
T
admin 3247e9fd15 init: ssw-mvp initial commit
- boot/ (Java/Maven, JNPF 7.0) — 移除旧的 boot/.git,源码直接纳入仓库
- web/ (Vue 3 + Vite + Ant Design Vue, pnpm)
- docs/, scard/, nax/
- refs/INDEX.md + refs/国标/(其余 refs/* 开源子仓库不纳入)
- 已忽略: connector_data/, jweb/, log/, web/{dist,node_modules,.pnpm}, boot/*/target/, .DS_Store, .idea, .vscode
2026-08-05 18:29:12 +08:00

333 lines
8.3 KiB
Markdown

# 安全连接器开发计划
## 项目概述
基于 `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 集成