Files
ssw-mvp/docs/security/SECURITY_PLANE.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

21 KiB
Raw Blame History

安全平面(scard)设计说明书

配套代码:scard/code/(Go module security-connector,Go 1.21,唯一第三方依赖 golang.org/x/crypto)。 本文件是 工程视角 的自包含说明,覆盖「根密钥 / 安全启动 / 安全认证 / 建立隧道 / 通讯加密 / 国密算法」六大能力,以及当前软实现(soft-PKI + 软件 TPM)的端到端跑通方式。 状态基线:2026-08-04 完成连接器侧 enroll-nonce 闭环、安全启动 PCR 度量、软 PKI 证书链,并在 OrbStack Ubuntu 虚机内完成跨网络端到端注册。


1. 定位与边界

scard 是 SSWFlow 的安全控制底座,独立于三个业务子系统(TDS / TDC / SSWFLOW)。它提供两条角色:

角色 二进制 / 包 职责
security-server server/ + cmd/(gen-pki) 根信任锚点:签发注册挑战(nonce)、校验远程证明、下发 KEK/会话证书、协调 EasyTier 隧道、审计
connector connector/ 部署在数据提供/使用方边缘节点:软件 TPM 度量启动链、向 server 做远程证明、拉起隧道

当前为软实现:根密钥是文件级软根 CA(非 FPGA/SE),TPM 是 SoftwareFPGATPM 模拟。目标是先打通协议与流程,硬件信任根(FPGA/TPM 2.0)替换时只换底层 provider,协议与策略不变。


2. 六大安全能力对照

能力 软实现落点 代码位置
根密钥 自签软根 CA(gen-pki 生成 ca-key.pem,默认复用不轮换) cmd/gen-pki/main.go
安全启动 启动阶段向 PCR 0/1/2/7 做 PCR_Extend(固件/平台/TPM provider/信任锚) connector/register/registrar.go measureBoot()
安全认证 远程证明:服务端签发 nonce → 设备 quote → 服务端验签 + PCR 覆盖 + golden 度量 server/attest/*、server/auth/auth.go
建立隧道 证明通过后 server 下发 EasyTier 凭证,connector 拉起 easyier-node(无二进制时模拟) server/easytier/、connector/easytier/
通讯加密 全链路 TLS 1.2+;server 用软 PKI 证书,connector 通过 --tls-ca 信任同一根 connector/tlsutil/tlsutil.go
国密算法 SM2/SM3/SM4 合规实现(已通过国标向量) common/crypto/

国密实现已在前期会话重写为合规版本并通过国标测试向量,本文件不再展开;详见 common/crypto/ 与对应测试。


3. 远程证明协议(安全认证核心)

3.1 为什么必须服务端签发 nonce

设备自生成 nonce 的 quote 可以被离线预计算或无限重放。因此证明挑战必须由 verifier 签发:

  1. connector POST /api/v1/device/enroll-nonce {device_id}
  2. server 返回 {nonce(base64), pcr_mask, expire_at}
    • nonce:32 字节随机,绑定 deviceID、TTL=2min、单次使用、防重放
  3. connector 用该 nonce 调 TPM.Quote("device_key", nonce, pcr_mask) —— quote 结构为 SW_TPM_QUOTE_V1 || nonce || 选中PCR值,hash=SHA256(quoteData),sig=ECDSA-SignASN1(AIK, hash)
  4. connector POST /api/v1/device/register,携带 tpm_quote / quote_signature / nonce(服务端下发) / quote_pcr_mask / firmware_hash
  5. server Verify 流程:
    • nonce 消费:查签发记录 → 过期?→ deviceID 绑定?→ 已消费(重放)?→ 否则消费并登记
    • quote 结构:magic 头 SW_TPM_QUOTE_V1、内嵌 nonce 必须与请求 nonce 一致、PCR blob 长度 = onescount(mask)*32
    • 验签:ECDSA-Verify(AIK, hash, sig)
    • 必需 PCR 覆盖:RequiredPCRMask ⊆ QuotePCRMask(默认要求 0/1/2/7)
    • 度量策略:首次记录 golden(TOFU),后续校验漂移;strict 模式拒绝未知设备

3.2 关键常量(server 侧默认策略)

项 值
QuotePCRMask 0x000000FF(quote 0–7)
RequiredPCRMask `(1<<0)
PCRFirmware / Platform / TPMProvider / TrustAnchor 0 / 1 / 2 / 7
nonce TTL 2 min
replay 窗口 30 min
默认模式 strict(fail-closed,漏配也不开放)
TOFU 默认开启;--attestation-no-tofu 关闭(仅认 golden)

3.3 端点与消息(common/proto/messages.go)

  • enroll_nonce_request / enroll_nonce_response
  • register_request / register_response(响应新增 attestation_status: verified|tofu-recorded|unverified|disabled、pcr_digest)
  • 错误码 attestation_failed(与 invalid_signature / auth_failed 区分,便于审计)

3.4 验证强度(已实测)

攻击 / 缺陷 结果
设备自选 nonce 服务端 ErrNonceUnknown 拒绝
重放同一 quote ErrNonceReplay 拒绝
用签发给别的设备的 nonce ErrNonceDeviceMismatch 拒绝
过期 nonce ErrNonceExpired 拒绝
换签名密钥 ErrQuoteSignature 拒绝
篡改 PCR blob ErrQuoteMalformed 拒绝
覆盖 PCR 不足 ErrPCRMaskInsufficient 拒绝
strict 模式 golden 漂移 ErrMeasurementMismatch 拒绝
permissive 模式 golden 漂移 仍 verified 但带 warning

4. 软实现 PKI(根证书)

cmd/gen-pki 生成软信任链,复用已有根 CA(重跑只补 server/device 证书,不废已签发的):

# 生成软根 CA + server 证书(含 SAN),可选 --device-id 同时签发设备证书
go run ./cmd/gen-pki --out ./bin/tls \
  --server-host "127.0.0.1,192.168.139.3" \
  --server-dns "localhost,host.orb.internal" \
  --days 825

产物(bin/tls/):

文件 用途
ca-cert.pem / ca-key.pem 软根 CA(私钥保密)
server-cert.pem / server-key.pem security-server TLS 证书
connector-001-cert.pem / -key.pem (可选)设备证书

验证:openssl verify -CAfile bin/tls/ca-cert.pem bin/tls/server-cert.pem → OK。

connector 信任该根有两种方式(开发/集成仅用其一):

  • --tls-ca bin/tls/ca-cert.pem(推荐,走真实证书校验)
  • --tls-insecure(跳过校验,仅纯实验室)

注册(enroll-nonce/register)与 EasyTier 加入(easytier/join)共用同一 TLS 配置(connector/tlsutil),因此软根一旦被信任,全链路无需 insecure。


5. 端到端跑通(已验证)

5.1 宿主机(server + connector 同机)

# 终端 A:启动 security-server(strict 模式 + 软证书)
go run ./server --listen :8443 \
  --tls-cert bin/tls/server-cert.pem --tls-key bin/tls/server-key.pem \
  --data-dir /tmp/ssw-sc-smoke --attestation-mode strict

# 终端 B:启动 connector(软件 TPM,注册并度量启动链)
go run ./connector --server https://127.0.0.1:8443 \
  --device-id SMOKE-001 --tpm-type software --register \
  --tls-ca bin/tls/ca-cert.pem --data-dir /tmp/ssw-connector-data

预期:connector 日志 [Register] Attestation status: verified|tofu-recorded,server 日志 [REGISTER] admitted device=SMOKE-001 attestation=... pcr_digest=...,随后 EasyTier 拿到 credential=SMOKE-001:... 并进入 RUNNING。

5.2 OrbStack 虚机(连接器端在 Ubuntu VM)

# 1) 交叉编译 connector(静态链接,无需 VM 装运行时)
GOOS=linux GOARCH=amd64 go build -o bin/connector-linux-amd64 ./connector

# 2) 宿主机的 home 已被 OrbStack 挂载进 VM(/Users/xs/... 直接可见),
#    因此把二进制放到 bin/ 即可在 VM 内同路径访问。

# 3) 在 VM 内启动 connector,指向宿主机在 OrbStack 网络的地址
orb -m ubuntu bash -c 'bin/connector-linux-amd64 \
  --server https://192.168.139.3:8443 \
  --device-id ORB-001 --tpm-type software --register \
  --tls-ca bin/tls/ca-cert.pem --data-dir /tmp/conn-data'

实测结果(2026-08-04):VM(192.168.139.67) → 宿主(192.168.139.3:8443) 跨网络成功完成 enroll-nonce → quote → 验签 → TOFU 记录 → EasyTier 凭证下发,设备状态 active。

注意:VM 内用 nohup ... & 在 orb bash -c 中会被会话结束回收,需前台阻塞运行(connector 在 RUNNING 后等待信号)或由 orb 持久会话托管。


6. 代码地图(关键文件)

文件 职责
server/attest/attest.go 远程证明校验器:IssueNonce / Verify、nonce 防重放、quote 解析、PCR 覆盖
server/attest/policy.go PCR 分配、golden 度量、文件持久化策略(FileStore 原子写)
server/attest/attest_test.go 18 个用例,驱动真实 SoftwareFPGATPM 验证协议互操作
server/auth/auth.go RegisterDevice 接入 attestor.Verify(默认 strict fail-closed)
server/api/handler.go /enroll-nonce、/register 路由,区分证明失败类别
server/main.go --attestation-mode/policy/no-tofu 启动参数
connector/register/registrar.go measureBoot() + requestEnrollNonce() + 用服务端 nonce quote
connector/tlsutil/tlsutil.go 共享 TLS 客户端配置(注册与 EasyTier 共用软根信任)
connector/tpm/software_tpm.go SoftwareFPGATPM.Quote(SW_TPM_QUOTE_V1+nonce+PCR,SHA256,ECDSA)
common/proto/messages.go 协议消息、错误码

7. 与 SSWFlow 主项目集成状态

  • 软实现 PKI 根证书 + 安全启动度量(PCR 0/1/2/7)
  • 远程证明服务端校验(nonce 防重放 / 验签 / PCR 覆盖 / golden)
  • 连接器 enroll-nonce 闭环 + 启动度量扩展
  • 国密 SM2/SM3/SM4 合规实现(前期)
  • 宿主机 + OrbStack 虚机端到端跑通(软证书)
  • #4 完成:TDS 子系统桥接 — V1.3.2 DB 迁移 + Java Entity/Service/Controller + 前端 /tds/security
  • 待办:硬件信任根替换(FPGA/TPM 2.0 provider),协议与策略层不动

8. 已知限制(软实现)

  1. 软根 CA 私钥是文件,仅适合开发/集成;生产必须通过 FPGA/SE 保护且永不导出。
  2. SoftwareFPGATPM 的 PCR extend 是确定性摘要模拟,非真实 measured boot ROM 行为;换硬件 provider 后即为真实度量。
  3. EasyTier 在测试机无 easytier-core/node 二进制,自动进入 simulation;真实部署需预置二进制并下发真实网络凭证。
  4. 当前 verifier 策略内存态 + 文件持久化;多 server 实例需共享 golden 存储(如 DB/Redis)。

9. 与 SSWFlow 的集成(任务 #4 完成于 2026-08-04)

scard 安全平面不仅是独立服务,还作为 SSWFlow(TDS)管理平面的一个「子平面」被镜像, 让运营/审计人员能在 SSWFlow 后台看到设备清单、证明状态、绑定关系、审计日志, 而无需直接访问 scard 服务。

9.1 集成架构

┌──────────────────┐       HTTPS / soft PKI        ┌──────────────────────────┐
│   connector      │ ──────────────────────────▶   │   scard security-server  │
│  (OrbStack VM)   │   POST /enroll-nonce          │  (:8443, attestation)    │
│  SoftwareTPM     │   POST /register (Quote)      │  devices + audit JSONL   │
│  EasyTier client │   POST /easytier/join         └──────────┬───────────────┘
└──────────────────┘                                            │ REST (只读)
                                                               ▼
                                            ┌────────────────────────────────┐
                                            │  ssw-admin (Java/Spring Boot)  │
                                            │   ├─ SecurityPlaneClient (JDK) │
                                            │   ├─ SecurityPlaneSyncService │
                                            │   │    @Scheduled 30s cron    │
                                            │   ├─ SecurityDeviceController │
                                            │   ├─ SecurityAuditController  │
                                            │   └─ /api/ssw/tds/...          │
                                            └────────────────┬───────────────┘
                                                             ▼
                                                ┌────────────────────────┐
                                                │  tds_security_device   │
                                                │  tds_attest_record     │
                                                │  tds_connector (+4 列) │
                                                └────────────────────────┘
                                                             ▲
                                                             │
                                                ┌────────────┴────────────┐
                                                │ web/src/views/ssw/tds/  │
                                                │   SecurityPlaneView.vue │
                                                │   /tds/security         │
                                                └─────────────────────────┘

9.2 数据模型(V1.3.2)

迁移文件:boot/db/tds/V1.3.2__tds_security_plane.sql

表 角色 关键列
tds_security_device scard 设备清单镜像 f_id (=device_id), f_status, f_attest_status, f_attest_mode, f_pcr_digest, f_pcr_mask, f_firmware_hash, f_endpoint, f_quote_signed_at, f_last_attest_time, f_last_heartbeat_time
tds_attest_record 审计/证明流水 f_device_id, f_attest_status (=event_type), f_error_code, f_error_message, f_ip_address, f_operator, f_quote_b64, f_signature_b64, f_nonce_b64, f_quote_time, f_verified_time
tds_connector(ALTER) 连接器 ↔ 安全设备绑定 + f_security_device_id, f_attest_status, f_pcr_digest, f_last_attest_time

迁移在 sswflow/tds/tdc 三库中只有 tds 库有 tds_connector 表,因此脚本对 sswflow/tdc 自动 skip; 本集成仅作用于 tds 库。

9.3 接口清单

Go 侧(security-server 新增端点)

路径 方法 说明
/api/v1/health/plane GET 健康/统计快照
/api/v1/attestation/policy GET 当前 attestation 模式 + PCR 掩码 + golden 设备
/api/v1/audit/query?device_id=&event_type=&result=&since=&until=&limit= GET 审计实时查询(最多 2000 条)
/api/v1/audit/stats GET 审计聚合(by_type / by_result / devices / newest/oldest)
/api/v1/device/revoke POST {"device_id","operator","reason"} 撤销设备(写 audit revoke 事件)
/api/v1/device/status[/{id}] GET 修 bug:原精确匹配导致按 ID 查询死代码;改为 prefix 派发,list/detail 都在

Device JSON 现在多了 endpoint / attest_status / attest_mode / pcr_digest / pcr_mask / quote_signed_at / last_attest_time, Java sync 据此落库。

Java 侧(SSWFlow TDS Controller)

路径 方法 说明
/api/ssw/tds/SecurityDevice GET/POST 分页 + 关键字(status / endpoint / pcr_digest / attest_status 模糊)
/api/ssw/tds/SecurityDevice/{id} GET/PUT/DELETE CRUD(继承 TdsCrudController)
/api/ssw/tds/SecurityDevice/Sync POST 手动触发 SecurityPlaneSyncService.syncOnce()
/api/ssw/tds/SecurityDevice/Health GET 透传 scard /health/plane
/api/ssw/tds/SecurityDevice/Policy GET 透传 scard /attestation/policy
/api/ssw/tds/SecurityDevice/Revoke POST 透传 scard /device/revoke(带当前操作者)
/api/ssw/tds/SecurityAudit/Records GET 本地表 tds_attest_record 分页
/api/ssw/tds/SecurityAudit/Query GET 透传 scard 实时查询
/api/ssw/tds/SecurityAudit/Stats GET 透传 scard 审计统计
/api/ssw/tds/SecurityAudit/Sync POST 手动拉取审计

前端

  • 路由:/tds/security(meta.subsystem='tds',侧边栏自动出现在「可信数据空间管理」下)
  • 视图:web/src/views/ssw/tds/SecurityPlaneView.vue
    • 服务健康 + attestation policy(折叠 golden 明细)
    • 安全设备清单(status / attest 彩色 tag / PCR 度量摘要 / 撤销按钮)
    • 审计日志(实时查询 + 统计两个 tab)
  • API:web/src/api/ssw/tds.ts 新增 securityDevice / securityAudit 两个命名空间

9.4 调度与配置

  • 同步节奏:默认 30 秒一次(@Scheduled(cron = "0/30 * * * * ?")),可在 application.yml 覆盖:
    ssw:
      security-plane:
        base-url: https://127.0.0.1:8443
        ca-cert-path: /Users/xs/Desktop/ssw/scard/code/bin/tls/ca-cert.pem
        insecure: false
        timeout-seconds: 5
        sync-cron: "0/30 * * * * ?"
    
  • SSL:使用 JDK HttpClient + 自定义 SSLContext。ca-cert-path 为空时回退到 JVM 默认 truststore;insecure=true 时跳过校验(仅 dev)。
  • 失败策略:单次同步失败 → log warn,不影响下次调度;单行 audit 插入失败(如 NOT NULL 违反)→ 单条 skip。

9.5 端到端跑通记录(2026-08-04)

步骤 命令 期望 实际
1 go run ./cmd/gen-pki --server-host "127.0.0.1,192.168.139.3" ca-cert.pem + server-cert.pem 含 192.168.139.3 SAN ✅ openssl verify 通过
2 /tmp/ssw-server --listen :8443 --tls-cert ... --attestation-mode strict 启动 HTTPS 服务 ✅ health/policy 200
3 /tmp/ssw-connector --server https://127.0.0.1:8443 --device-id ORB-INT-002 --register --tls-ca ca-cert.pem 设备注册成功(attestation=tofu-recorded) ✅
4 curl https://127.0.0.1:8443/api/v1/device/status 设备 status=active,含 attest_status/pcr_digest/pcr_mask/last_attest_time ✅
5 java -jar ssw-admin-7.0.0-RELEASE.jar SSWFlow 启动,30s 后自动 sync ✅ tds_security_device 落库 ORB-INT-002(含完整 attest footprint)
6 curl https://127.0.0.1:8443/api/v1/device/revoke -d '{"device_id":"ORB-INT-002",...}' status=revoked,写 audit revoke 事件 ✅
7 30s 后查 tds_security_device ORB-INT-002 status='revoked';tds_attest_record 新增 revoke 行(operator='smoke-test') ✅

9.6 代码地图

scard/code/                                  # Go 实现
  server/audit/query.go                      # Query/Stats(新)
  server/attest/attest.go                    # PolicySnapshot(新)
  server/api/handler.go                      # 5 个新端点 + status 路由修复
  server/auth/auth.go                        # SetAuditLogger + RevokeDevice(新)

boot/                                        # Java 集成
  db/tds/V1.3.2__tds_security_plane.sql      # 2 张新表 + tds_connector ALTER
  ssw-tds/ssw-tds-entity/src/main/java/ssw/tds/entity/
    SecurityDeviceEntity.java                # 新
    AttestRecordEntity.java                  # 新
    ConnectorEntity.java                     # +4 字段
  ssw-tds/ssw-tds-biz/src/main/java/ssw/tds/
    mapper/SecurityDeviceMapper.java         # 新
    mapper/AttestRecordMapper.java           # 新
    service/SecurityDeviceService.java       # 新(extends SuperService)
    service/AttestRecordService.java         # 新(extends SuperService)
    service/impl/SecurityDeviceServiceImpl.java
    service/impl/AttestRecordServiceImpl.java
    security/SecurityPlaneClient.java        # JDK HttpClient + 自定义 SSL
    security/SecurityPlaneSyncService.java   # @Scheduled 30s cron + SyncResult
    security/SecurityPlaneSchedulingConfig.java  # @EnableScheduling 本模块独立
  ssw-tds/ssw-tds-controller/src/main/java/ssw/tds/controller/
    SecurityDeviceController.java            # 继承 TdsCrudController + 6 个端点
    SecurityAuditController.java             # 4 个端点
  ssw-admin/src/main/resources/application-dev.yml  # 新增 ssw.security-plane 配置块

web/                                          # 前端
  src/router/modules/tds.ts                  # + /tds/security 路由
  src/api/ssw/tds.ts                         # + securityDevice / securityAudit 命名空间
  src/views/ssw/tds/SecurityPlaneView.vue    # 新(健康/策略/设备/审计 4 块)

9.7 已知集成限制

  1. ORB-INT-001 历史 stale 行:设备表 updateById 跳过 null,已有行若 sync 时新数据字段为 null 不会覆盖;这是 MP 默认行为,符合预期(避免误清空历史字段)。
  2. 策略快照只读:管理面只能查看 attestation policy,不能热修改;改策略仍走 scard --attestation-policy 文件 + 重启。
  3. 多 server 实例的 golden 共享:attest.Policy 当前是文件持久化(attestation-policy.json);多实例需迁移到 DB/Redis 才能避免 golden 不一致(详见 §8 限制 4)。