76 lines
1.9 KiB
Markdown
76 lines
1.9 KiB
Markdown
# UX 授权端接口说明
|
||
|
||
本文档描述 UX 服务当前定位：**仅提供底层密码学能力，不维护业务状态**。
|
||
|
||
## 1. 职责边界
|
||
|
||
- UX 只提供加密、解密、签名、ZIP 打包能力
|
||
- UX 不持有设备/任务等业务主数据，不读取业务数据库
|
||
- 调用方（工具箱）负责提供业务上下文与密钥材料
|
||
|
||
## 2. 核心接口
|
||
|
||
### 2.0 `config.get` / `config.setLicence`
|
||
|
||
- `config.get`：读取本地配置（`licence`、`fingerprint`）
|
||
- `config.setLicence`：写入本地 `licence`
|
||
- 说明：`fingerprint` 由 UX 本机计算并持久化，不由调用方传入
|
||
|
||
### 2.1 `crypto.encryptDeviceInfo`
|
||
|
||
- 输入：`platformPublicKey`
|
||
- 输出：`encrypted`（Base64）
|
||
- 说明：读取本地 `licence`/`fingerprint` 组装 JSON 后执行 RSA-OAEP 加密
|
||
|
||
### 2.2 `crypto.decryptTask`
|
||
|
||
- 输入：`encryptedData`
|
||
- 输出：`decrypted`（明文字符串）
|
||
- 说明：使用本地 `licence`/`fingerprint` 推导 `SHA256(licence + fingerprint)` 作为 AES-GCM 密钥
|
||
|
||
### 2.3 `crypto.encryptSummary`
|
||
|
||
- 输入：`salt`、`plaintext`
|
||
- 输出：`encrypted`（Base64）
|
||
- 说明：使用本地 `licence`/`fingerprint` 做 HKDF-SHA256 + AES-256-GCM 加密
|
||
|
||
### 2.4 `crypto.signAndPackReport`
|
||
|
||
- 输入：
|
||
- `rawZip`（multipart 文件）
|
||
- `pgpPrivateKey`
|
||
- `signingContext`
|
||
- `summaryJson`
|
||
- `outputFileName`（可选）
|
||
- 输出：签名后 ZIP 文件（二进制，`application/zip`）
|
||
|
||
`summary.json` 由 UX 生成，结构为：
|
||
|
||
```json
|
||
{
|
||
"deviceSignature": "Base64...",
|
||
"signingContext": "...",
|
||
"payload": { "...": "调用方 summaryJson" },
|
||
"timestamp": 1734571234567
|
||
}
|
||
```
|
||
|
||
签名输出 ZIP 固定包含：
|
||
|
||
- `summary.json`
|
||
- `META-INF/manifest.json`
|
||
- `META-INF/signature.asc`
|
||
|
||
## 3. ZIP 安全约束
|
||
|
||
- 拒绝危险路径（防 Zip Slip）
|
||
- 原始 ZIP ≤ `50 MiB`
|
||
- 单个文件 ≤ `20 MiB`
|
||
- 总解压后大小 ≤ `60 MiB`
|
||
- ZIP 条目数量 ≤ `64`
|
||
|
||
## 4. OpenAPI
|
||
|
||
- 文档：`/api/docs`
|
||
- 规范：`/api/spec.json`
|