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

8.3 KiB

安全连接器开发计划

项目概述

基于 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 失败。

修复:

  • 检查 keys.Manager.NewManager masterKey 生成逻辑
  • 确保 masterKey 是完整的 32 bytes
  • 添加 masterKey 为空时的保护逻辑
  • 验证 EncryptAES256GCM 调用成功

修复文件: connector/keys/manager.go

状态: ✅ 已完成 (2026-05-22)

1.2 服务端 API 完善

  • 添加 /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 完善

  • 完善 QuoteToBase64 返回值
  • 添加 PCR 扩展验证
  • 添加 key 生成/加载持久化

2.3 真 TPM 接口

  • 定义 TPM 接口 interface (已在 tpm.go)
  • 实现 TPM 2.0 命令封装 (LinuxTPM)
  • 在 Zynq-7015 上验证 (待硬件)

2.4 Connector 集成

  • 更新 connector 使用 TPM Provider
  • 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 集成