Files
ssw-mvp/refs/tee/TEE_DEV_HANDOFF.md
T
admin 680f780e8d docs(tee): 更新交接文档使同事 clone 后可在自环境落地
- TEE_DEV_HANDOFF.md 增补:
  §0.5 clone 后文件清单(标注全部已进 git)+ 6 步落地顺序
  §5.5 产品 application.yml 必改配置键(澄清配置在 ssw-admin 模块,
        tdc 为其内嵌子模块, 共享该 application.yml)
  §5.6 证据暴露方案A(runLog [TEE_EVIDENCE_JSON]+parseTeeEvidence+
        GET /{id}/TeeEvidence)+ 前端 TeeExecutionFlow 可视化
  §9.1/§9.2 文件清单(含 jweb force-add 说明)+ 落地检查清单
- 发现 kata-install.md / trustee.md 未进 git(handoff §9 引用了它们)
  → force-add 进 git, 同事 clone 即得
- 参数化两文档去掉明文凭据与内部地址(符合生产禁明文主机密码原则):
  trustee.md: r.mayishangshu.cn:82→<REGISTRY_HOST>(21处)/192.168.1.18→<KBS_URL>/
    Ttee1234→<REG_PASS>/Abc123→<COSIGN_PASSWORD>/tee→<REG_USER>, 顶部加
    警告(部分命令与已验证 CDH 正路冲突, 以 handoff 为准)
  kata-install.md: r.mayishangshu.cn:82→<REGISTRY_HOST>/192.168.1.7→<TEE_HOST>,
    顶部加安装阶段安全提示
2026-08-08 14:57:16 +08:00

26 KiB
Raw Blame History

TEE 机密计算 —— 开发交接手册(给独立一条线的同事)

适用对象:自有 AMD SEV-SNP 硬件 + 自建 KBS/Trustee 的同事,从零把 SSW 的 TEE 链路在自己的环境跑起来。 文档定位:可移植、自包含。所有环境相关值都写成 <占位符>,不绑定我们的 IP / 密码 / Token。 详细命令若需逐字照搬,文末「相关文件」指向带完整命令的参考文档(注意那些文档含我们内部值,只用其结构、替换你的环境值)。


0. 一句话架构(必须理解)

数据属主(你的后端)                  K8s 节点(TEE 主机)                AMD SEV-SNP Guest VM
─────────────────                  ──────────────────                ──────────────────────
kbs-client set-resource
   ↓ 明文只留在属主侧
你的 KBS/Trustee  ← ── ── ── ── ── ── ── ── ──  attestation-agent
   │  POST /kbs/v0/auth     (RCAR 握手)                     ↑
   │  POST /kbs/v0/attest   (提交 SEV-SNP report)           │ 硬件签名报告 /dev/sev-guest
   │      └→ AS: "Snp Verifier/endorsement check passed."   │
   │  GET  /kbs/v0/resource/<path> → JWE 密文               ↓
   └─────────────────────────────────────────────→  confidential-data-hub (CDH)
                                                      ↓ guest 内解密
                                                  compute.py 机密计算
                                                      ↓ AES-256-GCM
                                                  密文结果信封 → stdout
   ↓ 属主用 KBS 上的「结果密钥」解封
明文结果

信任根:KBS/AS 的 Snp Verifier/endorsement check passed.(AMD 背书链验签)。 安全性质:宿主机 root、K8s 管理员、日志采集器全程只看得到密文;输入/结果密钥都在远程证明通过后才释放。


0.5 拿到仓库后:文件清单与落地顺序

clone 下来后,TEE 相关文件分布如下(全部已在 git 中,clone 即得):

路径 作用 落地时是否要改
refs/tee/image/ssw-tee-compute/{Dockerfile,compute.py} 计算镜像 + Pod 内 4 步逻辑(CDH 证明门控取数 + AES-GCM 封装) 构建你自己的镜像 tag
refs/tee/k8s/ssw-tee-e2e-job.yaml 端到端烟测 Job(含全部必需注解) 替换 <KBS_HOST> / 镜像
refs/tee/tools/unseal_result.py 属主侧解封脚本(验证结果信封) 直接用
refs/tee/TEE_DEV_HANDOFF.md(本文件) 开发交接手册 —
refs/tee/TEE_E2E_RUNBOOK.md 我们真机跑通完整记录(含内部 IP,只参考结构) —
refs/tee/tee-test/kata-install.md 节点/kata 安装逐字命令(含内部 IP,替换你的) —
refs/tee/trustee.md KBS/Trustee 部署逐字命令(含内部镜像源,换你的源) —
refs/tee/TEE_SECURITY_BASELINE.md / TEE_DEBUG_MANAGEMENT_DEVELOPMENT.md 安全基线 / 管理面设计 —
boot/ssw-tdc/.../resources/k8s/tee-job.yaml 产品侧 Job 模板(CDH 正路) 一般无需改
boot/ssw-tdc/.../client/K8sSandboxClient.java 产品侧 stage→起Job→抓日志→解封 参考实现
boot/ssw-admin/src/main/resources/application.yml 产品配置入口(k8s.tee.* 都在这里) 必须改(见 §5.5)
jweb/.../views/ssw/{api/tdc.ts, registerSswComp.ts, views/tdc/PrivacyView.vue, TeeSecurityView.vue, components/sswflow/TeeExecutionFlow.vue} 前端 TEE 证据可视化 直接用(前端 jweb 整体被 gitignore,这些文件已 git add -f 强制纳入,clone 即得)

注:jweb/ 在仓库根 .gitignore 中整体忽略,TEE-UI 相关文件是 force-add 进 git 的。若你的 checkout 里没有 jweb/.../TeeExecutionFlow.vue,说明该提交未被 pull,先 git pull。 所有 refs/tee/*.md 中若含我们的内部 IP / 密码,仅作结构参考,落地时一律换成你的环境值。

落地顺序(建议严格按此):

  1. 准备环境:§1 前置清单全部满足(SNP 硬件 / kata / KBS 可达 / kubeconfig / 镜像仓库)。
  2. 部署 KBS/Trustee:§4 起好 4 容器,注入 cosign 公钥与 reference-values;生成属主侧 ed25519 密钥对。
  3. 构建并分发镜像:§3.3 docker build + docker save + 节点 ctr import,tag 成你的 <REGISTRY>/ssw/tee-compute:<tag>。
  4. 配置产品:§5.5 在 application.yml 填 k8s.tee.kbs-url / k8s.runtime-class / k8s.tee-image / k8s.kubeconfig / kbs.url / kbs.client-key-path,fail-closed 保持 true。
  5. 起后端 + 跑一次交付任务:触发一次 TEE 交付,或 §7 的烟测 Job。看 §7 正向预期;再去掉注解跑一次反向验证 fail-closed。
  6. 看 UI:登录前端,打开该交付任务的日志弹窗 → 「TEE 执行链路」页签,应见数据流图 / 交互时序 / 安全特征(§5.6)。

1. 环境前置清单(把 <占位符> 换成你的值)

项 要求 验证命令
<TEE_HOST> AMD EPYC 7002/9004(Milan/Genoa)+ BIOS 开 SEV-SNP cat /proc/cpuinfo | grep sev_snp(非空)
OS Linux 6.x + kata-containers ≥ 3.1(CC operator v0.15.0) kata-runtime --version
<KBS_HOST>:<KBS_PORT> Trustee 部署完成,http://<KBS_HOST>:<KBS_PORT> 可达(默认 8080) curl http://<KBS_HOST>:<KBS_PORT>/kbs/v0/auth
<REGISTRY> 你自己的镜像仓库(放 tee-compute 镜像) docker login <REGISTRY> 成功
cosign v2.4+(镜像签名/验签) cosign version
<KUBE_API> 集群 API https://<TEE_HOST>:6443,带 SA token 的 kubeconfig kubectl --kubeconfig <KUBECONFIG> get nodes

缺真实 SNP 硬件时可先走「基础沙箱」回退,但 security.fail-closed=true 时必须阻断、不得冒充真 TEE。


2. 四条必须遵守的铁律(真机踩坑所得,违反必失败)

# 规则 违反后果
1 guest-components 的 api-server-rest 监听 127.0.0.1:8006,且该构建只有 /cdh/* 路由(/aa/token、/aa/evidence 一律 404) 用 8080 或 /aa/* 会误判「AA 不存在」
2 绝不能用 hostNetwork: true kata 下 guest VM 只剩 lo,CDH 连不到 KBS,静默失败
3 节点 kata 默认 kernel_params 没有 aa_kbc_params,必须按 Pod 注解注入 CDH 不知道 KBS 地址 → Get Resource failed 500
4 探活不要用不存在的资源路径去 GET CDH 会真发起 RCAR 握手并重试,拖慢 40s+ 且污染 AA 状态

Pod 注解写法(enable_annotations 已含 kernel_params,无需改节点配置):

annotations:
  io.katacontainers.config.hypervisor.kernel_params: "agent.aa_kbc_params=cc_kbc::http://<KBS_HOST>:<KBS_PORT>"

3. TEE 主机(节点)安装

安全原则:主机 OS 帐户密码(<TEE_HOST_USER> / <TEE_HOST_PASS>)只允许在「设备安装阶段」使用(装系统、导入镜像、排障登录)。 产品运行期(后端 / K8s / KBS)不依赖主机密码——只通过 K8s API(SA token)与 KBS(HTTPS)触达节点。请不要把主机密码写进任何常驻服务配置。

3.1 开启 SEV-SNP(BIOS)

CBS → CPU Common →
        SEV-ES ASID Space Limit → 100
        SNP Memory Coverage → Enabled
        SMEE → Enabled
    → NBIO Common → SEV-SNP → Enabled

GRUB 开启内存加密:mem_encrypt=on kvm_amd.sev=1,重启后 dmesg \| grep -i sev 应见 SNP 相关行。

3.2 装 k8s + kata(CC operator)

# kubeadm 起集群(自行替换为你的 init 流程),label 节点
kubectl label node <TEE_HOST> node.kubernetes.io/worker=

# 装 Confidential Containers operator + 默认 RuntimeClass
kubectl apply -k "github.com/confidential-containers/operator/config/release?ref=v0.15.0"
kubectl get pods -n confidential-containers-system   # 等 Running
kubectl apply -k "github.com/confidential-containers/operator/config/samples/ccruntime/default?ref=v0.15.0"
kubectl get runtimeclass                            # 应出现 kata-qemu-snp

3.3 镜像分发到节点(仅安装/更新时用主机密码)

docker build --platform linux/amd64 -t <REGISTRY>/ssw/tee-compute:<tag> refs/tee/image/ssw-tee-compute
docker save <REGISTRY>/ssw/tee-compute:<tag> -o /tmp/tee.tar
# —— 以下仅在「设备安装阶段」用主机帐户密码;生产运行期不需要 ——
scp /tmp/tee.tar <TEE_HOST_USER>@<TEE_HOST>:/tmp/tee.tar
ssh <TEE_HOST_USER>@<TEE_HOST> \
  'sudo ctr -n k8s.io images import /tmp/tee.tar; \
   sudo ctr -n k8s.io images tag docker.io/ssw/tee-compute:<tag> <REGISTRY>/ssw/tee-compute:<tag>'

Pod 用 imagePullPolicy: IfNotPresent 直接命中节点本地镜像。

坑:某些本地 registry 按 digest 寻址 manifest 会 404(skopeo 推入状态损坏)。上面的 docker save+ctr import 是最稳的绕过。

3.4 给后端用的 kubeconfig(SA token,短时效)

# <KUBECONFIG> 结构(生产请把 insecure-skip-tls-verify 去掉、信任集群 CA;token 用短时效)
apiVersion: v1
kind: Config
clusters:
- name: ssw
  cluster:
    server: <KUBE_API>            # https://<TEE_HOST>:6443
    # insecure-skip-tls-verify: true   # ← 生产去掉,改用 certificate-authority
contexts:
- name: ssw
  context: { cluster: ssw, namespace: <NAMESPACE>, user: ssw }
current-context: ssw
users:
- name: ssw
  user:
    token: <KUBE_TOKEN>           # 见下方生成方式,勿用永久 token

K8s 1.30+ 的 SA token 必须带 exp/iat/jti/aud claim,老式永久 token 会被拒:

kubectl -n <NAMESPACE> create token <sa-name> --duration=24h   # 生成 <KUBE_TOKEN>

(SA 重建后旧 clusterrolebinding 失效,需重新 kubectl create clusterrolebinding 绑定新 uid。)


4. KBS / Trustee 部署(自建)

Trustee 由 4 个容器组成:trustee-kbs + trustee-as(验签/背书)+ trustee-rvps(reference-values)+ coco-keyprovider,对外暴露 <KBS_PORT>(默认 8080)。

# 1) 生成 KBS 签名的 ed25519 密钥对
openssl genpkey -algorithm ed25519 -out kbs/config/private.key
openssl pkey -in kbs/config/private.key -pubout -out kbs/config/public.pub

# 2) 加载 4 个 trustee 镜像并 docker compose 启动(用官方 trustee 仓库的 docker-compose.yml,
#    或你们内部镜像源的 trustee 打包;替换成你环境可达的镜像源)
#    docker compose up -d

# 3) 注入信任材料:
#    - cosign 公钥(见 §5.1)给 KBS 信任
#    - reference-values:受信镜像 digest、允许的 runtimeClass(kata-qemu-snp)、允许的 KBS path 前缀
# 4) 起属主侧 kbs-client(用于 set-resource 把输入/结果密钥放上 KBS)

完整逐字命令见 refs/tee/trustee.md(注意它绑的是我们内部镜像源 r.mayishangshu.cn:82/...,你需换成自己的源或上游 confidential-containers/trustee release)。

4.1 属主侧把数据/结果密钥放上 KBS

# 输入数据(KBS 资源路径严格三段 <repo>/<type>/<tag>)
kbs-client --url http://<KBS_HOST>:<KBS_PORT> \
  config --auth-private-key <kbs-private.key> \
  set-resource --path default/ssw-tds-input/<taskId> --resource-file input.json

# 结果加密密钥(base64 的 32 字节 AES-256 key,不要带换行)
python3 -c "import os,base64;print(base64.b64encode(os.urandom(32)).decode())" | tr -d '\n' > reskey.raw
kbs-client ... set-resource --path default/ssw-tds-reskey/<taskId> --resource-file reskey.raw

坑:kbs-client 镜像若 ENTRYPOINT 已是 kbs-client,命令里不要再写一遍;全局 --url 必须在子命令之前。


5. Workload 契约(后端 ↔ Pod 的接口)

镜像源码在 refs/tee/image/ssw-tee-compute/{Dockerfile,compute.py};产品侧 Job 模板在 boot/.../resources/k8s/tee-job.yaml。

5.1 镜像签名(你的后端配置验签要用的公钥)

COSIGN_PASSWORD="" cosign generate-key-pair --output-key-prefix /etc/ssw/tee/keys/ssw-tee-cosign
# 公钥 fingerprint: shasum -a 256 /etc/ssw/tee/keys/ssw-tee-cosign.pub
docker build -t <REGISTRY>/ssw/tee-compute:<tag> refs/tee/image/ssw-tee-compute
docker push <REGISTRY>/ssw/tee-compute:<tag>
DIGEST=$(docker inspect --format='{{index .RepoDigests 0}}' <REGISTRY>/ssw/tee-compute:<tag> | awk -F@ '{print $2}')
COSIGN_PASSWORD="" cosign sign --key /etc/ssw/tee/keys/ssw-tee-cosign.key <REGISTRY>/ssw/tee-compute@${DIGEST}

5.2 Pod 内 compute.py 的环境变量契约

变量 含义
CDH_URL 默认 http://127.0.0.1:8006(guest 内 CDH)
KBS_INPUT_PATH KBS 资源路径 <repo>/<type>/<tag>,如 default/ssw-tds-input/<taskId>
KBS_RESKEY_PATH 结果密钥路径 default/ssw-tds-reskey/<taskId>;空则不加密(仅调试)
INPUT_FILE 本地文件回退(K8s Secret 挂载)
TASK_ID / DELIVERY_TYPE 任务标识
ALLOW_INSECURE_FALLBACK 0=fail-closed(拿不到 KBS 数据直接失败);1=降级用内置 demo(仅开发)

compute.py 4 步:① 采集 TEE 证据(/dev/sev-guest 按 sysfs 设备号自建、/proc/cmdline 的 aa_kbc_params、CDH 仅 TCP 探活)→ ② 经 CDH GET /cdh/resource/<path> 取 KBS 资源(自动触发 RCAR 远程证明,拿到即证明通过)→ ③ 机密计算(明文只在加密内存,不打印)→ ④ 用 KBS 取到的结果密钥做 AES-256-GCM 封装。

5.3 输出信封(后端解析契约)

stdout 会被包在 SSW_TEE_RESULT_BEGIN / SSW_TEE_RESULT_END 之间,内含:

{
  "ok": true, "taskId": "<taskId>",
  "teeEvidence": { "tee":"amd-sev-snp", "sevGuestDevice": true, "aaKbcParams":"cc_kbc::http://<KBS>:8080",
                   "kernel":"6.12.x", "cdhAlive": true,
                   "rawReport": { "measurementSha256":"...", "signatureNonZeroBytes":96, "reportDataEcho":"..." } },
  "inputSource": { "attestationGated": true, "source":"cdh-kbs" },
  "resultSealed": true,
  "sealedResult": { "alg":"AES-256-GCM", "nonceB64":"...", "ciphertextB64":"...",
                    "plaintextSha256":"...", "keyAttestationGated": true }
}
  • measurementSha256(跨次稳定)是证明该 guest 软件栈未被篡改的关键;reportDataEcho 每次带 nonce 回显,正常会变。
  • 属主侧解封:用 KBS 上的结果密钥(base64)→ AESGCM(key).decrypt(nonce, ct) → 校验 plaintextSha256 一致。参考 refs/tee/tools/unseal_result.py。

5.4 后端集成要点(Java 侧已固化,供你对齐自己的实现)

  1. stageResource 把任务 input 上 KBS(default/ssw-tds-input/<taskId>);
  2. 现场生成一次性 AES-256 结果密钥也 stage 到 KBS(default/ssw-tds-reskey/<taskId>),只属主进程留副本;
  3. 渲染 Job 模板(CDH 正路 + 注入 aa_kbc_params + ALLOW_INSECURE_FALLBACK 由 fail-closed 驱动);
  4. Job 完成后 kubectl logs 抓 SSW_TEE_RESULT_BEGIN/END 载荷,AES-GCM 解封 + 校验 plaintextSha256;
  5. 证据摘要写入交付记录;fail-closed 失败时把 FATAL: 原因带回;
  6. 清理时删除 input 和 reskey(一次性密钥绝不留在 KBS)。

5.5 产品 application.yml 必改配置(落地第 4 步)

可运行 jar 来自 ssw-admin 模块,所以配置写在 boot/ssw-admin/src/main/resources/application.yml(tdc 是其内嵌子模块,共享这份配置)。所有键默认空或为我们环境值,接真 TEE 时改这几项:

键 含义 你的取值
k8s.enabled 是否启用 k8s 沙箱 true
k8s.runtime-class 机密容器 RuntimeClass kata-qemu-snp(留空=普通容器,无机密性)
k8s.tee-image TEE 计算镜像 <REGISTRY>/ssw/tee-compute:<tag>
k8s.kubeconfig 后端用的 kubeconfig 路径 你的 <KUBECONFIG>(SA token,见 §3.4)
k8s.tee.kbs-url KBS 地址 http://<KBS_HOST>:<KBS_PORT>
k8s.tee.cdh-url guest 内 CDH 地址 默认 http://127.0.0.1:8006,一般不改
k8s.tee.kernel-params CoCo kernel_params 留空 → 自动派生 agent.aa_kbc_params=cc_kbc::<kbs-url>(铁律 3);不要加 guest_components_rest_api=all
k8s.tee.fail-closed 证明失败是否阻断 true(真 TEE 必须);KBS 未介入时不生效
kbs.url KBS 客户端 URL(与 k8s.tee.kbs-url 二选一) http://<KBS_HOST>:<KBS_PORT>
kbs.client-key-path 属主侧 ed25519 私钥 PEM 你的 kbs/config/private.key(与 KBS 服务端同一对)
kbs.client-bin 客户端执行方式 Linux 节点填 kbs-client 绝对路径;macOS 留空走 docker 镜像 ssw-kbs-client:latest

未填 kbs-url / kbs.client-key-path 时 KbsOperations.enabled() 返 false,runTeeJob 自动回退「基础沙箱」(无证明门控、用内置 demo 数据跑通流程),不会报错——这是零回归设计,但要真 TEE 必须填全。 仓库里的 application.yml 目前带的是我们环境的默认值(192.168.1.18:8080、/Users/xs/... 路径等),clone 后务必改成你的。

5.6 证据暴露方案 + 前端可视化(同事的 UI 也能看)

后端(方案A,零 DB 依赖,已落地):K8sSandboxClient.runTeeJob 在拼 runLog 时,于末尾追加一段机器可解析的结构化证据块,标记 [TEE_EVIDENCE_JSON]:

[TEE_EVIDENCE_JSON]{"teeType":"amd-sev-snp","attestationGated":true,"resultSealed":true,
 "kbc":"cc_kbc","guestKernel":"6.12.x","measurementSha256":"...","signatureNonZeroBytes":96,
 "runtimeClass":"kata-qemu-snp","kbsEngaged":true,"failClosed":true,
 "inputSource":"cdh-kbs","resultJson":"<属主解封后的明文JSON>","status":"SUCCESS"}

PrivacyController / SandboxController 各暴露 GET /{id}/TeeEvidence,内部调静态 K8sSandboxClient.parseTeeEvidence(runLog) 把这段解析回 Map 返回前端。

备选方案B:给 DeliveryTaskEntity 加 f_tee_attestation / f_tee_sealed 两列做结构化存储,查询更干净,但需要 DBA 手动跑迁移;本仓库当前用方案A。

前端(jweb/.../views/ssw/ 下):

  • api/tdc.ts 的 privacy / sandbox 各加 teeEvidence(id) → GET /{id}/TeeEvidence;
  • components/sswflow/TeeExecutionFlow.vue(新组件,纯已注册 antd 组件,无裸 div 风险)三块可视化:
    • A. 数据流通过程:属主 → KBS加密 → TEE机密VM → 机密计算 → AES-GCM封装 → 属主解封(6 节点带状态/箭头);
    • B. 交互过程(时序):KBS上载 → 起Pod → CDH↔KBS远程证明 → 密文载入 → 计算 → 封装 → 属主解封(7 步);
    • C. 安全特征:远程证明门控 / TEE类型 / fail-closed / 结果加密 / RuntimeClass / KBC / guest kernel / 输入来源 / measurement(SHA256) / SNP签名字节数 / reportData / 属主解封后明文。
  • views/tdc/PrivacyView.vue:交付任务日志弹窗新增「TEE 执行链路」页签渲染上述组件;
  • views/tdc/TeeSecurityView.vue:顶部加端到端数据流参考卡;registerSswComp.ts 补注册 Tabs。

前端双栈:真源在 jweb/apps/jnpf-web-apps-main/src/views/ssw/**(web/ 是指向它的软链)。改前端请改 jweb 真源,再 pnpm dev。


6. 调试排错表(最有用的部分)

症状 根因 修法
GET /cdh/resource 报 500 / Get Resource failed 节点 kata 缺 aa_kbc_params → guest 不知 KBS 地址 Pod 注解注入 kernel_params=agent.aa_kbc_params=cc_kbc::http://<KBS>:8080
Job Pending / CDH 连 KBS 超时 用了 hostNetwork:true → guest VM 只剩 lo 删掉 hostNetwork(铁律 2)
/aa/token、/aa/evidence 返回 404 该 CDH 构建只暴露 /cdh/* 改用 GET /cdh/resource/<path>
探活拖 40s+ / AA 状态被污染 用不存在的资源路径 GET 探活,触发真 RCAR 重试 改用 TCP 探活(socket.create_connection)
结果密钥取不到 / 结果输出明文 KBS_RESKEY_PATH 未配或取失败 配 reskey 路径(同样证明门控);未配则 seal 失败仅调试
原始 SNP report ioctl 报 ENOTTY 结构体字段多一个 → sizeof 不匹配(易被误判"内核不支持") 用指针 ABI:{u8 msg_version; u64 req_data; u64 resp_data; u64 exitinfo2},sizeof=32;ioc=(3<<30)|(32<<16)|(0x53<<8)|0
老式永久 k8s token 被拒 K8s 1.30+ 要求 exp/iat/jti/aud claim kubectl create token <sa> --duration=24h 生成短时效 token
本地 registry 按 digest 取 404 skopeo 推入 manifest 状态损坏 docker save + ctr -n k8s.io images import 进节点 + IfNotPresent
fail-closed 时 Job Failed 无降级 预期(ALLOW_INSECURE_FALLBACK=0) 确认 aa_kbc_params 已注入;非调试不要置 1
measurementSha256 每次不同 report_data 含 nonce 回显,正常 看 measurement 是否跨次稳定;只有稳定才有意义
kata-qemu-snp RuntimeClass 不存在 CC operator 未装/未起 kubectl apply -k operator release + ccruntime/default
镜像拉取失败 / 验签失败 未签名或 digest 不在 reference-values cosign 签名 + KBS reference-values 配受信 digest
节点 /dev/sev-guest 在容器内不存在 kata 不透传该设备 读 /sys/class/misc/sev-guest/dev(如 10:126)后自行 mknod

7. 正负向烟测

# 正向:注入 aa_kbc_params + KBS 已 stage 数据 → 应 Succeeded
kubectl --kubeconfig <KUBECONFIG> apply -f refs/tee/k8s/ssw-tee-e2e-job.yaml
kubectl --kubeconfig <KUBECONFIG> logs -l job-name=<job-name>
# 期望: inputSource.attestationGated=true, resultSealed=true, measurementSha256 稳定

# 反向(fail-closed 验证):去掉 aa_kbc_params 注解 → 应 Failed,无降级
# 期望日志: FATAL: fail-closed: 无法从 KBS 取得受保护输入,且未允许降级

# 属主侧解封结果
kubectl ... logs -l job-name=<job> | sed -n '/SSW_TEE_RESULT_BEGIN/,/SSW_TEE_RESULT_END/p' | sed '1d;$d' > sealed.json
python3 refs/tee/tools/unseal_result.py sealed.json "<base64 结果密钥>"

正向预期(真机实测):全程 2~3s,KBS/AS 日志 Snp Verifier/endorsement check passed.,属主解封 sha256 match=True、明文 inputTag 与注册一致(非 demo)。


8. 安全要求(交接时务必保留)

  • 运行期零主机密码依赖:后端/K8s/KBS 只走 SA token + HTTPS;主机帐户密码仅设备安装阶段用,绝不写进常驻配置。
  • fail-closed:KBS 已介入时 ALLOW_INSECURE_FALLBACK=0;证明失败直接 Job Failed,绝不静默降级到 demo。
  • measurement 追踪:把 measurementSha256、KBS path、证明结果写入交付/审计链(只存摘要,不存 token 原文)。
  • 镜像身份:用 @sha256: digest + cosign 验签;签名公钥/证书来自受信任根。
  • 禁止项:Pod 不得用 privileged、hostNetwork、hostPID、hostPath;runtimeClass 必须在白名单(如 kata-qemu-snp)。
  • 一次性密钥:结果密钥只属主留副本,任务结束从 KBS 删除。

9. 相关文件(全部已在 git 中,clone 即得;含我们内部值的文档只参考结构、替换你的环境值)

9.1 仓库内 TEE 文件清单(clone 后即可用)

文件 内容 注意
refs/tee/image/ssw-tee-compute/{Dockerfile,compute.py} 计算镜像 + Pod 内 4 步逻辑 可直接复用,构建你自己的 tag
refs/tee/k8s/ssw-tee-e2e-job.yaml 端到端烟测 Job(含全部必需注解) 可直接复用,替换 <KBS_HOST>/镜像
refs/tee/tools/unseal_result.py 属主侧解封脚本 可直接复用
refs/tee/TEE_DEV_HANDOFF.md(本文件) 开发交接手册 自包含、全参数化
refs/tee/TEE_E2E_RUNBOOK.md 我们真机跑通完整记录 含我们 IP,只参考结构
refs/tee/tee-test/kata-install.md 节点/kata 安装逐字命令 含我们 IP,替换你的
refs/tee/trustee.md KBS/Trustee 部署逐字命令 含内部镜像源,换成你的源
refs/tee/runbooks/real-tee-e2e.md cosign 签名/OPA/配置开关 配置参考
refs/tee/TEE_SECURITY_BASELINE.md 安全基线检查项 可直接复用
refs/tee/TEE_DEBUG_MANAGEMENT_DEVELOPMENT.md 管理面/审计链设计 设计参考
boot/ssw-tdc/ssw-tdc-biz/src/main/resources/k8s/tee-job.yaml 产品侧 Job 模板(CDH 正路) 后端集成参考
boot/ssw-tdc/ssw-tdc-biz/src/main/java/ssw/tdc/client/K8sSandboxClient.java 产品侧 stage→起Job→抓日志→解封 + parseTeeEvidence 后端集成参考
boot/ssw-tdc/ssw-tdc-controller/src/main/java/ssw/tdc/controller/{PrivacyController,SandboxController}.java GET /{id}/TeeEvidence 接口 后端集成参考
boot/ssw-admin/src/main/resources/application.yml 产品配置入口(k8s.tee.* 在此) clone 后改你的环境值
jweb/apps/jnpf-web-apps-main/src/views/ssw/api/tdc.ts privacy/sandbox 的 teeEvidence(id) 前端集成
jweb/.../views/ssw/components/sswflow/TeeExecutionFlow.vue TEE 数据流/交互/安全特征可视化组件 前端集成(force-add 进 git)
jweb/.../views/ssw/views/tdc/{PrivacyView,TeeSecurityView}.vue 日志弹窗「TEE 执行链路」页签 + 数据流参考卡 前端集成
jweb/.../views/ssw/registerSswComp.ts 补注册 Tabs(前端 jweb 平台层唯一改动) 前端集成

关于 gitignore:仓库根 .gitignore 整体忽略 jweb/,TEE-UI 前端文件已用 git add -f 强制纳入;refs/ 大部分被忽略,TEE 参考文档也已 force-add。所以 clone 后即含上表全部文件。若某个文件缺失,先 git pull 拉到最新提交(含 fe8f075/f8fff39 之后的 TEE 提交)。

9.2 落地检查清单(clone 后逐条核对)

  • refs/tee/image/ssw-tee-compute/ 在,docker build 能出镜像
  • refs/tee/k8s/ssw-tee-e2e-job.yaml 在,替换 <KBS_HOST> 后能 apply
  • boot/ssw-admin/.../application.yml 里 k8s.tee.kbs-url / k8s.runtime-class / kbs.url / kbs.client-key-path 已改成你的
  • jweb/.../TeeExecutionFlow.vue 在(前端可视化)
  • 你的 KBS 已起、属主侧 ed25519 私钥与 KBS 服务端是同一对
  • 你的 <KUBECONFIG> 用短时效 SA token、能 kubectl get nodes