mirror of
https://github.com/hpd840321/craftlabs-authorization-sdk.git
synced 2026-06-09 18:10:30 +08:00
478 lines
20 KiB
Markdown
478 lines
20 KiB
Markdown
# 自研授权 SDK 设计方案
|
||
|
||
> **日期**：2026-05-18
|
||
> **背景**：比特安索授权云费用过高，决定优先推进自研授权方案。
|
||
> **原则**：与比特安索双线共存，Provider 可扩展架构，后续可接入更多第三方授权方式。
|
||
|
||
---
|
||
|
||
## 目录
|
||
|
||
1. [决策摘要](#1-决策摘要)
|
||
2. [总体架构](#2-总体架构)
|
||
3. [许可证协议与数据模型](#3-许可证协议与数据模型)
|
||
4. [Rust 层核心逻辑](#4-rust-层核心逻辑)
|
||
5. [平台后端变更](#5-平台后端变更)
|
||
6. [安全设计](#6-安全设计)
|
||
7. [实施阶段](#7-实施阶段)
|
||
|
||
---
|
||
|
||
## 1. 决策摘要
|
||
|
||
| 决策项 | 选择 | 理由 |
|
||
|--------|------|------|
|
||
| 授权服务形态 | **混合模式** | 有网络时在线验证（心跳/租约续期），断网时本地缓存可用至离线宽限期 |
|
||
| 加密体系 | **非对称签名 RSA-256 + AES-256-GCM 加密载荷** | 离线验签 + 内容加密防窥探，每个 license 独立 AES 密钥防批量破解 |
|
||
| 授权粒度 | **完整属性**：有效期 + 终端限制 + 并发用户数 + 使用次数 + 特性开关 | 对齐现有比特业务属性，功能上不降级 |
|
||
| 后端集成 | **复用 API + Webhook 双服务** | 签发走 API（管理操作需认证鉴权），SDK 交互走 Webhook（高频快速 2xx） |
|
||
| 比特兼容 | **双线共存 + Provider 可扩展架构** | 后续可接入更多第三方 |
|
||
| 终端识别 | **硬件指纹分层采集 + 稳定度评分兜底** | 强指纹精确匹配，弱指纹分配服务器 UUID，管理员可手动释放 |
|
||
| Rust 架构 | **单 cdylib + trait 多 Provider** | 公共模块共享，扩展第三方只需增加 trait 实现 |
|
||
| SDK 交互安全 | **Nonce + Timestamp + HMAC 签名防重放** | 简单有效，无需序列号同步 |
|
||
|
||
---
|
||
|
||
## 2. 总体架构
|
||
|
||
### 2.1 全系统组件图
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 客户现场 │
|
||
│ ┌──────────┐ ┌──────────────────┐ ┌──────────────────┐ │
|
||
│ │ 客户应用 │───▶│ Java SDK │ │ 许可证配置文件 │ │
|
||
│ └──────────┘ │ AuthProvider impl │◀───│ ~/.craftlabs/ │ │
|
||
│ │ ┌──────────────┐ │ │ license_cache │ │
|
||
│ │ │BitAnswerProv │ │ │ device_id │ │
|
||
│ │ ├──────────────┤ │ └──────────────────┘ │
|
||
│ │ │SelfHostedPrv │ │ │
|
||
│ │ └──────┬───────┘ │ │
|
||
│ └────────┼────────┘ │
|
||
│ │ JNI │
|
||
│ ┌────────▼────────┐ │
|
||
│ │ Rust craft-core │ libcraftlabs_auth_core │
|
||
│ │ ◇ trait Provider│ │
|
||
│ │ ┌─────────────┐ │ │
|
||
│ │ │BitAnswer │ │──────▶ 比特安索云 │
|
||
│ │ ├─────────────┤ │ │
|
||
│ │ │SelfHosted │ │──HTTPS▶ license-webhook │
|
||
│ │ └─────────────┘ │ │
|
||
│ │ device.rs │ 硬件指纹分层采集 │
|
||
│ │ crypto.rs │ HKDF+AES-GCM+RSA验签 │
|
||
│ │ security/ │ 反调试/完整性/混淆 │
|
||
│ └────────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
|
||
┌─────────────────────────────────────────────────────────────────┐
|
||
│ 创飞机房 / 云 │
|
||
│ │
|
||
│ ┌──────────────────────────┐ ┌──────────────────────────┐ │
|
||
│ │ license-webhook-ingress │ │ delivery-platform-api │ │
|
||
│ │ :8081 │ │ :8080 │ │
|
||
│ │ SDK 在线端点: │ │ 许可证签发端点: │ │
|
||
│ │ /license/v1/activate │◀──│ /api/v1/licenses │ │
|
||
│ │ /license/v1/heartbeat │ │ /api/v1/licenses/{id} │ │
|
||
│ │ /license/v1/check │ │ /api/v1/licenses/{id}/ │ │
|
||
│ │ /license/v1/release │ │ revoke │ │
|
||
│ │ │ │ │ │
|
||
│ │ 事件回调 ─────────────▶ │ │ 合同/SN/终端/审计 │ │
|
||
│ └──────────────────────────┘ └──────────────────────────┘ │
|
||
│ │ │ │
|
||
│ └──────────┬─────────────────┘ │
|
||
│ ▼ │
|
||
│ ┌──────────────┐ │
|
||
│ │ PostgreSQL 15│ │
|
||
│ └──────────────┘ │
|
||
└─────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### 2.2 Rust 层模块结构（改造后）
|
||
|
||
```
|
||
native/craft-core/src/
|
||
├── lib.rs # cdylib 入口 + C ABI 路由
|
||
├── trait_provider.rs # Provider trait 定义 + select_provider
|
||
│
|
||
├── provider_bitanswer/ # 现有逻辑封装
|
||
│ ├── mod.rs
|
||
│ ├── activate.rs
|
||
│ ├── license.rs
|
||
│ └── heartbeat.rs
|
||
│
|
||
├── provider_selfhosted/ # ★ 本次核心交付
|
||
│ ├── mod.rs # SelfHostedProvider impl Provider
|
||
│ ├── activate.rs # HTTPS POST → webhook:8081
|
||
│ ├── license.rs # 验签 + 解密 + 离线校验
|
||
│ ├── heartbeat.rs # HTTPS 心跳 + 租约续期
|
||
│ ├── protocol.rs # 请求/响应序列化
|
||
│ └── cache.rs # 许可证本地加密存储
|
||
│
|
||
├── device.rs # ★ 硬件指纹分层采集
|
||
├── crypto.rs # ★ HKDF + AES-256-GCM + RSA 验签
|
||
├── session.rs # 泛化 session（去 bit_handle）
|
||
├── error.rs # 自研 + 比特错误码体系
|
||
│
|
||
└── security/ # 不变
|
||
├── mod.rs
|
||
├── anti_debug.rs
|
||
├── integrity.rs
|
||
├── obfuscation.rs
|
||
└── string_encrypt.rs
|
||
```
|
||
|
||
### 2.3 Provider trait 契约
|
||
|
||
```rust
|
||
pub trait Provider: Send + Sync {
|
||
fn initialize(&mut self, ctx: &CraftContext, config: &AuthConfig)
|
||
-> Result<(), LicenseError>;
|
||
fn activate(&self, ctx: &CraftContext, license_key: &str)
|
||
-> Result<ActivateResponse, LicenseError>;
|
||
fn check_license(&self, ctx: &CraftContext)
|
||
-> Result<LicenseStatus, LicenseError>;
|
||
fn heartbeat(&self, ctx: &CraftContext)
|
||
-> Result<HeartbeatResponse, LicenseError>;
|
||
fn has_feature(&self, ctx: &CraftContext, name: &str) -> bool;
|
||
fn release(&mut self, ctx: &CraftContext) -> Result<(), LicenseError>;
|
||
fn get_license_info(&self, ctx: &CraftContext) -> LicenseInfoFFI;
|
||
fn close(&mut self);
|
||
}
|
||
```
|
||
|
||
### 2.4 Java 层变更
|
||
|
||
| 模块 | 变更 |
|
||
|------|------|
|
||
| `craftlabs-auth-core` | 接口不变；`SelfhostedConfigSection` 扩展 `offlineGraceDays`、`heartbeatIntervalHours` 等字段；`FeatureMapping` 扩展 `selfhostedFeatureKey` |
|
||
| `craftlabs-auth-bitanswer` | **不变**（双线共存） |
|
||
| `craftlabs-auth-selfhosted` | 从桩改为真实实现：`System.loadLibrary("craftlabs_auth_core")` |
|
||
| `craftlabs-auth-tests` | 新增 `SelfHostedProviderTest`、`MultiProviderSmokeTest` |
|
||
|
||
### 2.5 关键架构约束
|
||
|
||
- **单一 cdylib**：`craftlabs_auth_core` 包含所有 provider，通过 trait 路由
|
||
- **Java 侧无感知**：各 AuthProvider 均调 NativeBridge，路由在 Rust 层完成
|
||
- **双线 classpath 隔离**：BitAnswer 和 SelfHosted 不同 Maven 模块
|
||
- **契约不变**：AuthProvider 接口 7 方法不变、AuthConfig record 不变
|
||
- **Schema 兼容**：selfhosted 段向后兼容扩展新字段
|
||
|
||
---
|
||
|
||
## 3. 许可证协议与数据模型
|
||
|
||
### 3.1 License JSON 结构
|
||
|
||
```jsonc
|
||
{
|
||
"version": 1,
|
||
"license_id": "01JQXYZ...", // ULID
|
||
"issued_at": "2026-05-18T10:00:00Z",
|
||
|
||
// 载荷：AES-256-GCM 加密后的 Base64 密文
|
||
// 解密后为 LicensePayload：{ tenant_id, product, grant, constraints, features, custom }
|
||
"payload": "A8f3Kd9s...base64url...",
|
||
|
||
"signature": {
|
||
"algorithm": "RS256",
|
||
"key_id": "kp_2026_q2", // 支持密钥轮换
|
||
"value": "MEUCIQDx..." // RS256 签名（对密文 payload 签名）
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.2 LicensePayload（解密后明文）
|
||
|
||
```jsonc
|
||
{
|
||
"tenant_id": "craftlabs-wharf-prod",
|
||
"product": "wharf-inspection-v2",
|
||
|
||
"grant": {
|
||
"type": "perpetual", // perpetual | subscription | trial
|
||
"not_before": "2026-05-01T00:00:00Z",
|
||
"not_after": "2027-05-01T00:00:00Z",
|
||
"offline_grace_days": 7,
|
||
"heartbeat_interval_hours": 24
|
||
},
|
||
|
||
"constraints": {
|
||
"max_devices": 5,
|
||
"max_concurrent_users": 0, // 0=不限制
|
||
"max_activations": 0
|
||
},
|
||
|
||
"features": {
|
||
"advanced_analytics": true,
|
||
"real_time_monitor": false,
|
||
"api_export": true
|
||
},
|
||
|
||
"custom": { // 扩展字段
|
||
"contract_ref": "CT-2026-0042",
|
||
"project_id": "wharf-nansha-phase2"
|
||
}
|
||
}
|
||
```
|
||
|
||
### 3.3 签发与校验流程
|
||
|
||
```
|
||
签发（服务器侧）:
|
||
LicensePayload 明文
|
||
→ AES-256-GCM 加密（key = HKDF(编译期盐, license_id)）
|
||
→ 密文 payload (Base64)
|
||
→ RSA-SHA256 签名（对密文签名）
|
||
→ 完整 license.json
|
||
|
||
校验（Rust SDK 侧）:
|
||
license.json
|
||
→ RSA 公钥验签（快速排除伪造）
|
||
→ HKDF 派生 AES 密钥
|
||
→ AES-256-GCM 解密
|
||
→ 时间窗口校验（not_before ≤ now ≤ not_after + 离线宽限期）
|
||
→ 特性/约束校验
|
||
```
|
||
|
||
### 3.4 在线交互协议
|
||
|
||
端点：`license-webhook-ingress:8081/license/v1/*`
|
||
|
||
| 端点 | 方法 | 请求体 | 成功响应 | 错误响应 |
|
||
|------|------|--------|----------|----------|
|
||
| `/activate` | POST | `{license_key, device_fingerprint}` | 200 `{status:"activated", device_id, license_payload}` | 409 终端满 / 403 已吊销 / 422 无效 |
|
||
| `/heartbeat` | POST | `{license_key, device_hash, local_time}` | 200 `{status:"ok", lease_renewed_until}` | 410 已过期/吊销 |
|
||
| `/check` | POST | `{license_key, device_hash}` | 200 `{status:"valid", features, not_after}` | 410 已过期/吊销 |
|
||
| `/release` | POST | `{license_key, device_hash}` | 200 `{status:"released"}` | — |
|
||
|
||
**防重放**：每个请求携带 `X-Craft-Nonce`、`X-Craft-Timestamp`、`X-Craft-Signature`（HMAC-SHA256），服务器时间窗口 5 分钟 + Nonce 去重。
|
||
|
||
### 3.5 签发端点（API 侧）
|
||
|
||
```
|
||
POST /api/v1/licenses # 创建/签发许可证
|
||
GET /api/v1/licenses # 分页查询
|
||
GET /api/v1/licenses/{licenseId} # 详情
|
||
POST /api/v1/licenses/{id}/revoke # 吊销
|
||
GET /api/v1/licenses/{id}/activations # 激活记录
|
||
POST /api/v1/licenses/{id}/activations/{aid}/release # 释放设备
|
||
```
|
||
|
||
### 3.6 数据库表（新增）
|
||
|
||
| 表 | 用途 |
|
||
|----|------|
|
||
| `platform_licenses` | 许可证主表（license_id、有效期、约束、状态、签名快照） |
|
||
| `platform_license_features` | 特性开关（license_id, feature_key, enabled） |
|
||
| `platform_license_activations` | 终端激活记录（license_id, device_hash, stability_score, status） |
|
||
| `platform_license_heartbeats` | 心跳审计（可选，视量级） |
|
||
| `platform_license_keys` | RSA 密钥对管理（key_id, public_key, private_key） |
|
||
| `platform_license_policies` | 策略模板（默认有效期、终端数、特性等） |
|
||
|
||
---
|
||
|
||
## 4. Rust 层核心逻辑
|
||
|
||
### 4.1 新增依赖
|
||
|
||
```toml
|
||
reqwest = { version = "0.12", features = ["json", "rustls-tls"], default-features = false }
|
||
rsa = { version = "0.9", features = ["sha2"] }
|
||
aes-gcm = "0.10"
|
||
hkdf = "0.12"
|
||
base64 = "0.22"
|
||
serde = { version = "1", features = ["derive"] }
|
||
serde_json = "1"
|
||
chrono = { version = "0.4", features = ["serde"] }
|
||
```
|
||
|
||
### 4.2 关键数据结构
|
||
|
||
```rust
|
||
pub struct DeviceFingerprint {
|
||
pub composite_hash: String, // SHA-256(layer1|layer2|layer3|layer4)
|
||
pub stability_score: u8, // 0~100，影响匹配策略
|
||
pub layers: Vec<FingerprintLayer>,
|
||
}
|
||
|
||
pub struct LicenseStatus {
|
||
pub licensed: bool,
|
||
pub not_after: Option<i64>,
|
||
pub features: HashMap<String, bool>,
|
||
pub device_count: u32,
|
||
pub max_devices: u32,
|
||
pub heartbeat_due: Option<i64>,
|
||
}
|
||
```
|
||
|
||
### 4.3 硬件指纹分层采集
|
||
|
||
| 层级 | 权重 | 来源 |
|
||
|------|------|------|
|
||
| Layer 1 硬件 | 40 | Linux: DMI product_uuid / Windows: SMBIOS UUID / macOS: IOPlatformUUID |
|
||
| Layer 2 OS | 30 | Linux: /etc/machine-id / Windows: MachineGuid / macOS: 同 L1 |
|
||
| Layer 3 存储 | 20 | 根文件系统 UUID (blkid/VolumeSerialNumber) |
|
||
| Layer 4 网络 | 10 | 物理网卡 MAC（跳过 docker/tap/lo/veth） |
|
||
|
||
**稳定度评分**：Layer1=有+Layer2=有 → 70（强指纹）；仅 Layer2 有 → 40；仅 Layer4 → 10。
|
||
|
||
**兜底**：稳定度 < 20 时，服务器分配 UUID 并加密存储到 `~/.craftlabs/device_id`，管理员可手动吊销释放配额。
|
||
|
||
### 4.4 离线宽限期
|
||
|
||
```rust
|
||
fn check_license离线(&self) -> Result<LicenseStatus, LicenseError> {
|
||
// 1. 加载缓存许可证
|
||
// 2. 检查距离上次在线心跳的天数
|
||
// 3. 超过 offline_grace_days → OfflineGraceExceeded
|
||
// 4. 未超过 → 时间窗口校验（not_before/not_after）
|
||
// 5. 返回 LicenseStatus（device_count=0 标记离线）
|
||
}
|
||
```
|
||
|
||
### 4.5 错误码体系
|
||
|
||
```rust
|
||
pub enum LicenseError {
|
||
// 通用
|
||
Success, ConfigMissing, Network, NotInitialized,
|
||
// 签名/加密
|
||
InvalidFormat, InvalidSignature, SignatureMismatch, CryptoError,
|
||
DecryptionFailed, CorruptedPayload, LicenseIdMismatch,
|
||
// 许可状态
|
||
NotYetValid, Expired, NoCachedLicense,
|
||
OfflineGraceExceeded { days_offline, max_days },
|
||
InvalidLicense, LicenseRevoked,
|
||
DeviceLimitReached, ConcurrentUserLimitReached, ActivationLimitReached,
|
||
// 兼容比特
|
||
BitAnswerStatus(u32),
|
||
UnknownStatus(u16),
|
||
}
|
||
```
|
||
|
||
### 4.6 本地缓存
|
||
|
||
```
|
||
~/.craftlabs/
|
||
├── device_id # 硬件指纹或服务器 UUID
|
||
├── license_cache.json # AES-256-GCM 加密的许可证副本
|
||
│ # 加密密钥 = SHA256(device_id + EMBEDDED_SALT)
|
||
└── heartbeat_state.json # { last_heartbeat, lease_until }
|
||
```
|
||
|
||
### 4.7 编译期公钥嵌入
|
||
|
||
`build.rs` 读取 `native/craft-core/embedded/pubkey.pem`，生成 `const EMBEDDED_PUBLIC_KEY: &str = "..."`，`crypto.rs` 在 `initialize` 时解析为 `RsaPublicKey`。
|
||
|
||
---
|
||
|
||
## 5. 平台后端变更
|
||
|
||
### 5.1 delivery-platform-api 新增模块
|
||
|
||
```
|
||
license/
|
||
├── LicenseController.java # REST /api/v1/licenses
|
||
├── LicenseService.java # 签发/吊销/查询
|
||
├── LicenseSigner.java # RSA+AES 签发
|
||
└── LicenseKeyManager.java # 密钥对管理
|
||
|
||
persistence/license/
|
||
├── PlatformLicense.java & Mapper
|
||
├── PlatformLicenseFeature.java & Mapper
|
||
├── PlatformLicenseActivation.java & Mapper
|
||
├── PlatformLicenseKey.java & Mapper
|
||
└── PlatformLicensePolicy.java & Mapper
|
||
```
|
||
|
||
新增角色：`LICENSE_OPS`，管理 `/api/v1/licenses/**` 的写权限。
|
||
|
||
### 5.2 license-webhook-ingress 新增模块
|
||
|
||
```
|
||
license/
|
||
├── LicenseController.java # /license/v1/*
|
||
├── LicenseActivateService.java # 激活 + 终端匹配
|
||
├── LicenseHeartbeatService.java # 心跳 + 吊销检测
|
||
├── LicenseCheckService.java # 在线校验
|
||
├── LicenseReleaseService.java # 设备释放
|
||
├── DeviceMatcher.java # 分层指纹匹配
|
||
└── NonceValidator.java # 防重放
|
||
```
|
||
|
||
### 5.3 事件回调
|
||
|
||
激活/心跳失败/到期/吊销等事件，沿现有 Webhook→API 异步投递链路通知 API 更新台账和审计。
|
||
|
||
---
|
||
|
||
## 6. 安全设计
|
||
|
||
### 6.1 许可证防篡改
|
||
|
||
| 措施 | 作用 |
|
||
|------|------|
|
||
| **载荷 AES-256-GCM 加密** | 阻止直接查看许可证内容（特性/期限/终端数），每个 license_id 独立密钥防批量破解 |
|
||
| **密文 RSA-SHA256 签名** | 验签不通过 = 篡改，先行快速拒绝 |
|
||
| **HKDF 密钥派生** | 盐编译期嵌入 + license_id，增加逆向提取难度 |
|
||
| **公钥编译期嵌入** | 不在运行时从文件或网络加载，防替换攻击 |
|
||
|
||
### 6.2 SDK 在线交互安全
|
||
|
||
| 措施 | 说明 |
|
||
|------|------|
|
||
| **TLS** | 全链路 HTTPS，证书校验 |
|
||
| **HMAC 签名** | 每个请求 X-Craft-Signature = HMAC-SHA256(nonce|ts|method|path|body, tenantKey) |
|
||
| **Nonce 去重** | Redis SETNX + 时间窗口 5 分钟，防重放 |
|
||
| **Authorization 头** | Bearer tenantKey 双向验证 |
|
||
|
||
### 6.3 运行时保护
|
||
|
||
Rust 侧复用现有 `security/` 模块：反调试检测、完整性校验、字符串混淆，适配自研路径。
|
||
|
||
---
|
||
|
||
## 7. 实施阶段
|
||
|
||
### Phase 1：离线核心
|
||
**目标**：管理员签发 → 文件交付 → SDK 本地验签解密
|
||
|
||
- Rust: crypto.rs、license.rs、cache.rs、device.rs、error.rs
|
||
- Java: SelfhostedConfigSection 扩展字段
|
||
- 平台: 数据库迁移、LicenseSigner、LicenseController（签发/查询/吊销）
|
||
- 验证: AES 往返测试、RSA 验签测试、过期拒绝测试
|
||
|
||
### Phase 2：在线激活
|
||
**目标**：SDK 网络激活获取许可证，终端配额限制
|
||
|
||
- Rust: activate.rs、protocol.rs、trait_provider.rs、reqwest 集成
|
||
- Webhook: LicenseController、ActivateService、DeviceMatcher、NonceValidator
|
||
- 平台: 终端释放端点
|
||
- 验证: Mock HTTP 测试、终端满 409 测试
|
||
|
||
### Phase 3：心跳 + 离线兜底
|
||
**目标**：心跳维持租约、离线宽限期降级、吊销远程生效
|
||
|
||
- Rust: heartbeat.rs、check_license 离线逻辑
|
||
- Webhook: HeartbeatService、CheckService、ReleaseService
|
||
- 验证: 心跳成功更新租约、断网 8 天 OfflineGraceExceeded、吊销后 410
|
||
|
||
### Phase 4：完善与生产加固
|
||
**目标**：双 Provider 切换、CI/CD、文档
|
||
|
||
- Rust: build.rs 公钥嵌入、security 模块适配
|
||
- Java: MultiProviderSmokeTest、SelfHostedProviderTest
|
||
- CI: ci-native.yml 适配、ci-platform.yml 新增
|
||
- 文档: 集成指南、操作手册、CHANGELOG
|
||
|
||
### 工作量估算
|
||
|
||
| Phase | Rust | Java SDK | Platform API | Webhook | 合计 |
|
||
|-------|------|----------|-------------|---------|------|
|
||
| P1 | M | S | M | — | M~L |
|
||
| P2 | M | — | S | M | M |
|
||
| P3 | S | — | — | M | M |
|
||
| P4 | S | S | — | — | S |
|
||
|
||
（S=小，M=中，L=大）
|