- 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
21 KiB
安全平面(scard)设计说明书
配套代码:
scard/code/(Go modulesecurity-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 签发:
- connector
POST /api/v1/device/enroll-nonce{device_id} - server 返回
{nonce(base64), pcr_mask, expire_at}- nonce:32 字节随机,绑定 deviceID、TTL=2min、单次使用、防重放
- connector 用该 nonce 调
TPM.Quote("device_key", nonce, pcr_mask)—— quote 结构为SW_TPM_QUOTE_V1 || nonce || 选中PCR值,hash=SHA256(quoteData),sig=ECDSA-SignASN1(AIK, hash) - connector
POST /api/v1/device/register,携带tpm_quote / quote_signature / nonce(服务端下发) / quote_pcr_mask / firmware_hash - 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_responseregister_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. 已知限制(软实现)
- 软根 CA 私钥是文件,仅适合开发/集成;生产必须通过 FPGA/SE 保护且永不导出。
SoftwareFPGATPM的 PCR extend 是确定性摘要模拟,非真实 measured boot ROM 行为;换硬件 provider 后即为真实度量。- EasyTier 在测试机无
easytier-core/node二进制,自动进入 simulation;真实部署需预置二进制并下发真实网络凭证。 - 当前 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 已知集成限制
- ORB-INT-001 历史 stale 行:设备表
updateById跳过 null,已有行若 sync 时新数据字段为 null 不会覆盖;这是 MP 默认行为,符合预期(避免误清空历史字段)。 - 策略快照只读:管理面只能查看 attestation policy,不能热修改;改策略仍走 scard
--attestation-policy文件 + 重启。 - 多 server 实例的 golden 共享:
attest.Policy当前是文件持久化(attestation-policy.json);多实例需迁移到 DB/Redis 才能避免 golden 不一致(详见 §8 限制 4)。