117 lines
6.7 KiB
Markdown
117 lines
6.7 KiB
Markdown
|
||
# 许可证结构与验证（客户端要点）
|
||
|
||
本系统生成的许可证是一个 **Base64 编码的 JSON 对象**。客户端在启动阶段需要解码该字符串，并据此完成授权校验、硬件绑定判定及密钥验签。下方内容按照「流程 → 数据结构 → 示例 → 验证步骤」的顺序组织，便于查阅。
|
||
|
||
## 1. 启动阶段流程概览
|
||
|
||
先从整体流程入手：以下 Mermaid 流程图展示了客户端拿到许可证字符串后的关键校验路径，帮助定位每一步需要完成的动作与可能的失败分支。
|
||
|
||
```mermaid
|
||
flowchart TD
|
||
%% 节点定义
|
||
Start([客户端启动]) --> GetToken[获取 Base64 许可证字符串]
|
||
GetToken --> Decode[Base64 解码]
|
||
|
||
Decode --> ParseJSON{JSON 结构解析?}
|
||
ParseJSON -- 失败 --> ErrFormat[❌ 停止: 格式错误]
|
||
ParseJSON -- 成功 --> Extract[提取核心字段: <br/>data, signature, algorithm]
|
||
|
||
%% 签名验证阶段
|
||
Extract --> VerifySig[[RSA 签名验证]]
|
||
VerifySig -- 签名不匹配 --> ErrTamper[❌ 停止: 许可证被篡改]
|
||
VerifySig -- 验证通过 --> ParseData[反序列化 data 字符串]
|
||
|
||
%% 业务逻辑检查阶段
|
||
ParseData --> CheckStatus{检查 Status & 有效期}
|
||
|
||
CheckStatus -- "Locked / Expired" --> ErrStatus[❌ 停止: 授权被锁或过期]
|
||
CheckStatus -- "Normal & 有效期内" --> CheckType{判断 Deployment Type}
|
||
|
||
%% 部署类型分支
|
||
CheckType -- "standalone (单机)" --> CheckHW{本地硬件指纹比对}
|
||
CheckType -- "cloud / hybrid" --> CheckNet{联网/心跳验证}
|
||
|
||
%% 最终结果
|
||
CheckHW -- 不匹配 --> ErrHW[❌ 停止: 设备指纹不符]
|
||
CheckNet -- 验证失败 --> ErrNet[❌ 停止: 服务端拒绝]
|
||
|
||
CheckHW -- 匹配 --> Success([✅ 校验通过: 允许运行软件])
|
||
CheckNet -- 验证成功 --> Success
|
||
|
||
%% 样式定义 (可选，用于美化)
|
||
classDef error fill:#f9f2f4,stroke:#c00,stroke-width:2px,color:#c00;
|
||
classDef success fill:#e1fdf4,stroke:#009966,stroke-width:2px,color:#009966;
|
||
classDef process fill:#f9f9f9,stroke:#333,stroke-width:1px;
|
||
|
||
class ErrFormat,ErrTamper,ErrStatus,ErrHW,ErrNet error;
|
||
class Success success;
|
||
class Decode,VerifySig,ParseData,CheckHW,CheckNet process;
|
||
```
|
||
|
||
## 2. 许可证顶层结构
|
||
|
||
当您对许可证字符串完成 Base64 解码后，将得到一个包含三个核心字段的 JSON 对象。该结构设计确保了数据的可视性（明文数据）与安全性（加密签名）。
|
||
|
||
### 顶级字段说明
|
||
|
||
| 字段名 (Field) | 类型 | 说明 |
|
||
| :--- | :--- | :--- |
|
||
| **`algorithm`** | String | 用于生成签名的加密算法（例如：`RSA-PSS-SHA256`）。 |
|
||
| **`data`** | String | **核心授权载体**。这是一个被序列化为字符串的 JSON 对象，包含了具体的授权规则、时间限制和硬件指纹。 |
|
||
| **`signature`** | String | 针对 `data` 字段生成的加密签名（Base64 格式）。客户端需使用公钥验证此签名，以确保授权信息未被篡改。 |
|
||
|
||
-----
|
||
|
||
## 3. `data` Payload 详解
|
||
|
||
`data` 字段是许可证的核心载荷。解析该 JSON 字符串后，客户端可获得决定软件行为的全部控制参数。
|
||
|
||
### 核心参数定义
|
||
|
||
| 参数名 | 枚举值/类型 | 描述与开发建议 |
|
||
| :--- | :--- | :--- |
|
||
| **`status`** | `normal` (正常)<br>`locked` (锁定)<br>`expired` (过期) | 当前授权的状态。<br>**开发建议**：<br>• **normal**: 允许软件正常运行。<br>• **locked**: 授权被管理员强制禁用或检测到违规，应立即阻止运行。<br>• **expired**: 授权已过有效期，应阻止运行或降级为受限模式。 |
|
||
| **`deployment_type`** | `standalone` (单机版)<br>`cloud` (云端版)<br>`hybrid` (混合版) | 部署模式，决定了验证逻辑：<br>• **standalone**: 仅进行本地硬件指纹比对。<br>• **cloud**: 需联网向授权服务器心跳验证。<br>• **hybrid**: 优先联网，断网时允许短时间本地离线验证。 |
|
||
| **`start_date`**<br>**`end_date`** | ISO 8601 时间戳 | 授权的生效与过期时间。<br>**开发建议**：在软件启动时比对当前系统时间。若 `end_date` 小于当前时间，将状态视为过期。 |
|
||
| **`hardware_fingerprint`** | String | 绑定的硬件特征组合（如 MAC, CPU, HostID）取决于客户端的实现。<br>**关键步骤**：客户端需重新计算本地硬件指纹，并与此字段比对。若不一致，说明许可证被非法复制。 |
|
||
| **`usage_limits`** | Object | 使用量限制（如 API 调用次数，用户数量限制等）。 |
|
||
| **`feature_config`** | Object | 功能特性开关（Key-Value）。<br>用于控制软件内特定模块（如 Pro版/基础版）的启用或禁用。 |
|
||
| **`license_key`** | String | 设备的唯一授权标识符。<br>用于日志记录或作为与后端通讯的凭证。 |
|
||
|
||
-----
|
||
|
||
## 4. 解码示例
|
||
|
||
以下示例展示了解码后的标准许可证对象，便于对字段含义与格式建立直观印象：
|
||
|
||
```json
|
||
{
|
||
"algorithm": "RSA-PSS-SHA256",
|
||
"data": "{\"activated_at\":\"2025-11-01T22:30:02...\",\"status\":\"normal\",\"deployment_type\":\"standalone\",\"hardware_fingerprint\":\"MAC:5e:a3...\",\"end_date\":\"3025-03-03T23:59:59+08:00\", ...}",
|
||
"signature": "MQDlxx/crzncJfw2Y00X5spzN1bPWKuU4IDxB48Mwy1WMhOoYUDCcrYjiMgNJHsXzUSD14MURqCBKBMgQAc7EOiUUcwfJ1mhSGvbFYnrSGFxjpbEHUg6dJlgSB4jSxwh4jtHSOb82SvPkHrNE0/p/HKN2Vr3Dj2qU0JB7hM2Jd0vb3Tk7WiFWd9as3vvAChhzoXqHo53vtY7ZyUb56VM/M4UMwJ4w4S7M3DZiPwAAobOn1MfOmOnchXzc+lkhC9c67xprmOi33ms775Dc0tNurv+rCLTQN8wgnt5dfhmdyMbsIk2c188IK/7uca2Pi3qaBKSIkVkSKN78pI2A6gMYIA=="
|
||
}
|
||
```
|
||
|
||
> **注意：** `data` 字段在传输过程中是**字符串格式**。验证签名时必须使用原始的 `data` 字符串，只有在读取配置时才将其反序列化为 JSON 对象。
|
||
|
||
-----
|
||
|
||
## 5. 客户端验证清单
|
||
|
||
为了保证软件的安全性和授权的有效性，建议客户端按照以下步骤执行校验：
|
||
|
||
1. **解码 (Decode):** 将许可证字符串进行 Base64 解码。
|
||
2. **验签 (Verify Signature):** 使用内置的**公钥 (Public Key)**，对 `data` 字符串和 `signature` 进行 RSA 校验。
|
||
* *若验签失败，说明许可证被篡改，应立即终止程序。*
|
||
3. **解析 (Parse):** 将 `data` 字符串反序列化为对象。
|
||
4. **状态检查 (Check Status):**
|
||
* 确认 `status` 等于 `"normal"`。
|
||
* 确认当前时间在 `start_date` 和 `end_date` 之间。
|
||
5. **环境指纹比对 (Fingerprint Match):**
|
||
* 根据 `deployment_type` 执行相应的硬件或网络校验。
|
||
* (单机版) 重新计算本地硬件信息并与 `data` 中的 `hardware_fingerprint` 进行比对。
|
||
|
||
> 可以将上述 5 步实现为模块化的校验管线，以便后续扩展（例如增加联网授权、租户隔离等策略）。
|
||
|