72 lines
2.0 KiB
Markdown
72 lines
2.0 KiB
Markdown
# UX 授权端接口说明
|
||
|
||
本文档描述当前 UX 服务端实现的授权对接接口与职责边界。
|
||
|
||
## 1. 职责边界
|
||
|
||
- UX **只与工具箱交互**（HTTP RPC），不直接与手机 App 交互。
|
||
- 手机 App 仅承担扫码和与管理平台联网通信。
|
||
- 报告签名流程由工具箱上传原始 ZIP 到 UX，UX 返回已签名 ZIP。
|
||
|
||
## 2. 设备注册
|
||
|
||
`device.register`
|
||
|
||
- 输入：`licence`、`platformPublicKey`
|
||
- UX 在本机采集设备特征并计算 `fingerprint`
|
||
- UX 将 `licence + fingerprint + 公钥 + PGP 密钥对` 持久化到数据库
|
||
|
||
## 3. 核心加密接口
|
||
|
||
### 3.1 设备授权二维码密文
|
||
|
||
`crypto.encryptDeviceInfo`
|
||
|
||
- 使用平台公钥 RSA-OAEP 加密：`{ licence, fingerprint }`
|
||
- 返回 Base64 密文（工具箱用于生成二维码）
|
||
|
||
### 3.2 任务二维码解密
|
||
|
||
`crypto.decryptTask`
|
||
|
||
- 密钥：`SHA256(licence + fingerprint)`
|
||
- 算法：AES-256-GCM
|
||
- 输入：任务二维码中的 Base64 密文
|
||
- 输出：任务 JSON
|
||
|
||
### 3.3 摘要二维码加密
|
||
|
||
`crypto.encryptSummary`
|
||
|
||
- 密钥派生：HKDF-SHA256
|
||
- `ikm = licence + fingerprint`
|
||
- `salt = taskId`
|
||
- `info = "inspection_report_encryption"`
|
||
- 算法：AES-256-GCM
|
||
- 输出：`{ taskId, encrypted }` JSON（工具箱用于生成二维码）
|
||
|
||
### 3.4 原始 ZIP 签名打包（最终报告）
|
||
|
||
`crypto.signAndPackReport`
|
||
|
||
- 输入：`rawZipBase64` + `taskId` + `inspectionId` + `enterpriseId` + `summary`
|
||
- UX 在服务端完成：
|
||
1. 校验并解包原始 ZIP
|
||
2. 计算文件 SHA-256
|
||
3. HKDF + HMAC 生成 `deviceSignature`
|
||
4. 生成 `summary.json`
|
||
5. 生成 `META-INF/manifest.json`
|
||
6. OpenPGP 分离签名生成 `META-INF/signature.asc`
|
||
7. 重新打包为 signed ZIP
|
||
- 输出：`signedZipBase64` 与 `deviceSignature`
|
||
|
||
## 4. 安全约束（签名打包）
|
||
|
||
- 拒绝危险 ZIP 路径（防 Zip Slip）
|
||
- 限制原始 ZIP 和单文件大小
|
||
- 强制存在以下文件：
|
||
- `assets.json`
|
||
- `vulnerabilities.json`
|
||
- `weakPasswords.json`
|
||
- `漏洞评估报告*.html`
|