Files

330 lines
20 KiB
Markdown
Raw Permalink Normal View History

# 插件签名 / 许可策略 / 权限模型 / 工件哈希 / 密钥轮换(P3-1 + P3-5)
> 微内核插件架构安全基础:P3-1 提供清单级签名/策略/权限(分层正确版),P3-5 增加
> DLL/数据文件工件哈希(artifacts[{path,sha256}])与密钥轮换/吊销(key_id + 多受信 key)。
> 内核插件库只定义协议/策略/权限语义,不依赖业务模块 vde_license、也不内置非对称加密;
> Ed25519 验签由宿主注入 SignatureVerifier 回调完成;工件完整性用 SHA-256。
> 实现:include/vde/plugin/plugin_security.h + src/plugin/plugin_security.cpp
> (编译进内核库 vde_plugin,只依赖 foundation)。
## 1. 设计原则
1. **分层**:内核插件库只定义协议/策略/权限语义,**不做任何加密运算**;
Ed25519 验签由宿主通过 SignatureVerifier 注入(vde_license::crypto::ed25519_verify、
平台 KMS/HSM、企业签名服务均可)。
2. **默认兼容**:默认不强制签名(allow_unsigned = true),P0/P1/P2 已有无签名插件
(sample_vbox、官方 STL/OBJ/PLY 等)加载行为不变;严格模式由宿主显式开启。
3. **默认拒绝**:权限默认拒绝(permissions_default_deny = true);清单未声明
permissions 视为空请求(向后兼容)。
4. **结构化失败**:所有失败返回 PluginSecurityErrorCode + 可读原因,宿主可审计,
工具可映射退出码(见 §6)。
## 2. 威胁模型
| 编号 | 威胁 | 本任务覆盖 | 说明 |
|---|---|---|---|
| T1 | 未签名/来源不明插件被加载 | 是(策略 require_signature) | 默认兼容不强制,严格模式开启 |
| T2 | 清单被篡改(id/entry/capabilities) | 是(canonical payload 签名) | 顶层 signature 字段不参与载荷 |
| T3 | 发布者冒充 | 是(publisher + 白名单) | 白名单必须与验签公钥绑定使用 |
| T4 | 插件滥用文件/网络/进程权限 | 声明式(P3-1);强制在 P3-3/P2-4 沙箱 | 权限声明 + 默认拒绝 |
| T5 | 供应链替换(合法插件换恶意 DLL) | 是(P3-5 artifacts 哈希) | 清单声明每个 DLL/数据文件 SHA-256,加载前校验 |
| T6 | 密钥泄露/吊销 | 是(P3-5 key_id/轮换/吊销) | 多受信 key + revoked_key_ids;密钥轮换过渡期兼容 |
| T7 | 已加载恶意代码在进程内作恶 | 否 | 进程内无法强制隔离,见进程外沙箱 |
**安全边界**:P3-1 是**进程内尽力而为**的"来源校验 + 策略 + 权限声明"层;能阻止
未授权来源插件被宿主按策略加载,但**不能**约束已加载原生代码在进程内的行为。
真正的权限强制与崩溃隔离在 P3-3 进程外沙箱 / P2-4 vde-service 沙箱中实现。
## 3. 分层架构
```
宿主应用 / vde_plugin_tool
PluginSecurityPolicy(require_signature/allow_unsigned/publisher白名单/权限授予)
SignatureVerifier 实现:vde_license / KMS / HSM(注入回调)
│ 注入
▼
内核 vde_plugin(只依赖 foundation):plugin_security.h/.cpp
- canonical payload / 签名解析 / 策略判定 / 权限默认拒绝 / 结构化错误码
- SignatureVerifier 纯虚接口 + CallbackSignatureVerifier 适配器
```
vde_plugin **不链接** vde_license;find_package(vde-kernel) 的 kernel SDK 可直接使用
安全协议层,宿主按需注入验证器。vde_plugin_tool verify 是宿主:license 模块可用时
链接 vde_license 并定义 VDE_TOOL_HAS_ED25519=1;license OFF 时 verify 仍做结构/策略
检查,加密校验不可用(退出码 4)。
## 4. 签名规范
### 4.1 清单字段
```
{
"id": "com.acme.step",
"name": "ACME STEP",
"version": "1.2.3",
"kind": "format",
"abi": { "major": 1, "minor": 2 },
"entry": { "windows": "acme_step.dll", "linux": "libacme_step.so" },
"capabilities": ["format:step.read"],
"publisher": "com.acme",
"permissions": ["fs.read"],
"key_id": "acme-2026",
"artifacts": [
{ "path": "acme_step.dll", "sha256": "<64 hex>" },
{ "path": "data/step_profiles.json", "sha256": "<64 hex>" }
],
"signature": "ed25519:<base64(64B Ed25519 signature)>"
}
```
signature 可选(P0 起解析),格式 ed25519:<base64(标准 RFC 4648,带填充)>;算法名
大小写不敏感;签名 64 字节。publisher、permissions 为 P3-1 新增可选语义字段:
**不修改** PluginManifest 结构与插件 ABI,由安全模块从原始 JSON 解析。
### 4.2 Canonical payload(规范化签名载荷)
签名对象是清单的**确定性序列化字节**(canonical_manifest_payload()):
1. 解析清单 JSON 对象;**删除顶层 signature 字段**(嵌套同名键保留);
2. 对象键按 UTF-8 字节序(字典序)递归排序;数组顺序**保留**;
3. 无任何空白字符;字符串标准 JSON 转义,非 ASCII UTF-8 原样输出;
4. 数字最短往返十进制表示;
5. 输出 UTF-8 字节序列(无结尾换行/BOM)。
示例:{"b":2,"a":{"y":1,"x":[3,4]},"signature":"..."}
→ canonical = {"a":{"x":[3,4],"y":1},"b":2}
与键序、缩进、换行、BOM 无关;C++ 参考实现基于 nlohmann::json(对象 std::map
字典序 + dump() 紧凑输出),跨语言可按规则复现。
### 4.3 签发与验证
签发(发布者工具,不在本任务实现):
1. 删除清单顶层 signature;2. 按 §4.2 生成 canonical payload;
3. sig = Ed25519(私钥, canonical_payload);4. 写回 "signature": "ed25519:<base64>"。
验证(evaluate_plugin_security() 顺序):清单合法性 → 签名(缺失/格式/算法/公钥/
验签)→ 发布者白名单 → 权限;返回 PluginSecurityReport(Ok 时也含签名/发布者/权限
明细供审计)。
### 4.4 公钥分发
- 32B Ed25519;文本支持 ed25519:<base64>、裸 base64、64 hex 字符
(parse_public_key_text();工具 --pubkey <path|inline> 同规则)。
- 产品公钥建议随宿主发布(配置/注册表/内嵌,参考
vde_license::crypto::default_verification_public_key())。
- **发布者白名单必须与验签公钥绑定**:publisher 是清单自称值,只有验签通过后
才可信;单独白名单不验签不提供安全保证(见 §8)。
### 4.5 工件哈希(artifacts,P3-5)
清单可声明 `artifacts`(数组):每个工件 `{path, sha256}`,path 为**插件目录内相对路径**,
sha256 为文件字节的 SHA-256(FIPS 180-4,64 位小写/大写 hex)。签名覆盖整个清单
(artifacts 也在 canonical payload 内),因此"清单声明的哈希"本身受签名保护。
校验(`verify_plugin_artifacts()`,管理器/工具在 dlopen 前调用):
1. 语法:artifacts 必须是对象数组;path 非空字符串;sha256 为 64 hex 字符;
2. 路径安全:拒绝绝对路径/盘符/UNC 与任何 `..` 组件(目录逃逸 → ArtifactPathInvalid);
3. 存在性:解析为 `plugin_dir/path` 后必须存在且可读(→ ArtifactMissing);
4. 哈希:实际 SHA-256 与声明不一致 → ArtifactHashMismatch。
策略:
- `require_artifact_hashes=false`(普通默认):清单未声明 artifacts 时跳过;**已声明则总是校验**;
- `require_artifact_hashes=true`(**strict_plugin_security_policy() 默认**):清单必须声明
artifacts,否则 ArtifactMissing;
- 旧重载 evaluate_plugin_security()(无 plugin_dir)不做文件哈希;策略强制或已声明
artifacts 时返回明确错误(管理器必须使用带 plugin_dir 的重载)。
### 4.6 密钥轮换与吊销(key_id,P3-5)
- 清单可选 `key_id`:标识签名所用密钥;签名语义不变(仍是对 canonical payload 的 Ed25519);
- 策略 `trusted_keys`:`key_id → 32B 公钥` 映射(多受信 key,支持轮换);
- 策略 `revoked_key_ids`:吊销列表,**优先于受信表**(RevokedKey);
- 选择规则:
1. 清单有 key_id:先查吊销(RevokedKey)→ 再查 trusted_keys(缺失 → UnknownKeyId);
trusted_keys 为空时回退到调用方传入的 public_key(P3-1 兼容路径);
2. 清单无 key_id:trusted_keys 恰好 1 条 → 自动选用(轮换过渡期兼容);
多条 → PublicKeyMissing(要求清单显式 key_id);受信表为空 → 用调用方 public_key;
- 轮换流程:新密钥签新清单(key_id 变化)→ 宿主 trusted_keys 同时保留新旧 → 旧 key
加入 revoked_key_ids 后,旧清单立即被拒绝(RevokedKey);吊销列表更新无需重新签清单。
### 4.7 索引级 key_id 吊销强制(P3-13b)
- 索引顶层 `key_id` 与清单 `key_id` 同样可吊销:`vde_plugin_tool --verify-index / --install /
--upgrade ... --revoked-keys <file>`;
- 吊销文件两种格式(调用方/宿主策略提供,**不从索引内读取**,避免签名者自证吊销):
1. 每行一个 key_id(`#` 起注释;一行也允许逗号分隔多个);
2. JSON `{"revoked_key_ids": ["key-id", ...]}`;空文件/格式错误 → 退出码 3,诊断含
`invalid --revoked-keys`;
- 强制顺序:索引验签通过后检查签名 key_id;命中吊销列表 → 退出码 3,诊断含
`index signing key_id '<id>' is revoked (see --revoked-keys)`;不同 key(未吊销)不受影响;
- unsigned 索引不受 `--revoked-keys` 影响(仍受 `--allow-unsigned` 门禁);
- 清单级语义不变:`PluginSecurityPolicy.trusted_keys/revoked_key_ids` 仍优先于受信表,并独立于
索引级吊销(`verify` 命令行为不变);
- 回归:CTest `VDE_PluginToolIndexRevocation`(行/JSON 拒绝、不同 key 放行、格式错误诊断、
install/upgrade 拒绝)。
### 4.8 签名 CRL(可分发吊销列表,P4-08)
§4.6/§4.7 的 `revoked_key_ids` 由调用方(宿主配置/发布说明)提供,多宿主/跨团队分发需
各自同步。P4-08 定义**可签名分发的 CRL(JSON)**,工具在 `--verify-index` /
`--install` / `--upgrade` 时合并 CRL 吊销列表,宿主只需固定一个 CRL 公钥即可
自动获得吊销更新。
格式(schema v1):
```json
{
"version": 1,
"issued_at": "2026-01-01T00:00:00Z",
"expires_at": "2026-04-01T00:00:00Z",
"revoked_key_ids": ["acme-2025-release", "acme-2026-beta"],
"signature": "ed25519:<base64(64B)>"
}
```
- 签名载荷 = 去掉顶层 `signature` 后的 canonical JSON(与 §4.2 清单/索引同一规范:
对象键字典序、无空白、UTF-8);签名串 `ed25519:<base64(64B)>`;
- 时间字段 UTC ISO8601 `YYYY-MM-DDTHH:MM:SSZ`;`expires_at` 必须晚于
`issued_at`;加载时检查未生效/已过期(→ 退出码 3);
- 发布方生成:`vde_plugin_tool --sign-crl <payload.json> -o <crl.json> --sign <seed>`;
该命令复用 canonical 签名规范并输出带 `signature` 的 CRL。
工具集成(P4-08):
- `--verify-index / --install / --upgrade` 新增 `--crl <file|url>` 与
`--crl-pubkey <path|inline>`;
- CRL 验签公钥:`--crl-pubkey` 优先,缺省回退 `--pubkey`(索引验签公钥);
都未提供 → 退出码 4(加密校验不可用);
- 顺序:读取 CRL(本地文件;Windows 另支持 `http(s)` URL,经 WinHTTP)→ schema/时间/
签名校验 → 与 `--revoked-keys` 并集去重后合并 → 索引验签后按 §4.7 检查 index key_id;
- 退出码:**3** = CRL 格式/过期/未生效/验签失败;**4** = CRL 不可获取(文件缺失/HTTP 失败)或
工具未编译 vde_license Ed25519 支持;
- 信任模型:CRL 公钥由宿主/安装器固定(建议独立于索引 key,便于轮换);不传 `--crl`
即不做 CRL 检查;CRL 状态不由索引自证(不从索引读取),防止签名者撤销自己的吊销记录;
防回滚依赖宿主固定公钥 + 短有效期(建议 30 天)与发布流程重签;
- 限制(P4-08 范围):无 OCSP/实时撤销、无 delta CRL、无自动后台刷新与 `--crl-cache`
(宿主可周期拉取覆盖本地文件实现缓存);非 Windows 平台 `--crl <http(s) URL>` 不可用
(本地文件/`file://` 可用);CRL 仅约束索引/清单签名 key_id,不负责卸载已安装插件;
- 回归:CTest `PluginToolCrlTest.*`(命中吊销失败/不同 key 放行/过期/未生效/篡改/
错误公钥/格式/install/upgrade/本地 HTTP)。
## 5. 策略与权限语义
### 5.1 PluginSecurityPolicy
| 字段 | 默认 | 语义 |
|---|---|---|
| require_signature | false | 强制签名;无签名 → SignatureMissing |
| allow_unsigned | true | 允许未签名(仅 require_signature=false);P0/P1 兼容默认 |
| allowed_publishers | 空 | 发布者白名单(精确匹配;空=不限制) |
| permissions_default_deny | true | 权限默认拒绝:请求必须在 granted_permissions 中 |
| require_permission_declaration | false | 要求显式声明 permissions,否则 PermissionNotDeclared |
| granted_permissions | 空 | 宿主授予;"*" 表示授予全部请求 |
| require_artifact_hashes | false(strict=true) | 要求清单声明 artifacts 且全部哈希通过 |
| trusted_keys | 空 | key_id → 32B 公钥;支持多 key/轮换;空则回退 public_key 参数 |
| revoked_key_ids | 空 | 已吊销 key_id(优先于 trusted_keys 拒绝) |
strict_plugin_security_policy() = require_signature=true、allow_unsigned=false、
permissions_default_deny=true、**require_artifact_hashes=true**(发布者/受信 key/权限由宿主继续填充)。
### 5.2 权限声明
- 清单 permissions:字符串数组,可选;缺失=空(**向后兼容**)。
- 命名建议:fs.read、fs.write、net.client、net.listen、shell.exec、process.spawn、
gpu.compute、license.check、ui.notify;第三方可扩展。
- 判定:granted = requested ∩ granted_permissions;未授予进 denied_permissions;
default_deny 且 denied 非空 → PermissionDenied。
- 权限仅声明式契约:P3-1 不拦截系统调用,强制在进程外沙箱实现。
### 5.3 错误码
| 码 | 触发 |
|---|---|
| Ok | 通过 |
| ManifestInvalid | JSON 非法/字段类型错 |
| SignatureMissing | 要求签名但无 signature(或不允许未签名) |
| SignatureMalformed | 缺 alg: / Base64 错 / ed25519 非 64B |
| SignatureAlgorithmUnsupported | 算法非 ed25519 / verifier 不支持 |
| SignatureInvalid | 验签失败(篡改/错误公钥) |
| PublicKeyMissing | 有签名但未提供公钥 |
| VerifierUnavailable | 有签名但宿主未注入 verifier |
| PublisherNotAllowed | publisher 不在白名单(签名通过后判定) |
| PermissionNotDeclared | 要求显式声明权限但清单无 permissions |
| PermissionDenied | 请求权限未被授予(默认拒绝) |
| ArtifactMissing | 策略要求 artifacts 或清单已声明但文件不存在/不可读 |
| ArtifactHashMismatch | artifacts SHA-256 与清单声明不一致(篡改/损坏) |
| ArtifactPathInvalid | artifact 路径绝对/逃逸插件目录(`..`)/非法 |
| UnknownKeyId | 清单 key_id 不在 policy.trusted_keys |
| RevokedKey | 清单 key_id 在 policy.revoked_key_ids |
## 6. 工具:vde_plugin_tool verify
```
vde_plugin_tool verify <plugin_dir_or_manifest> [--pubkey <path|inline>]
[--key-id <id>] [--hash]
vde_plugin_tool verify build/plugins/sample_vbox --pubkey test_pub.b64
vde_plugin_tool verify path/to/vde-plugin.json --pubkey ed25519:AAAA...
vde_plugin_tool verify build/plugins/acme --pubkey acme_pub.b64 --key-id acme-2026 --hash
```
- 目录 → 读取其中 vde-plugin.json(并以其父目录解析 artifacts 相对路径);也可给清单文件;
- --pubkey:文件内容(base64/hex/ed25519:)或内联文本;
- --key-id:断言清单 key_id 必须等于该值(不匹配 → 退出码 3);用于部署侧固定预期密钥;
- --hash:显式要求 artifacts 全部通过哈希校验,并逐个打印 expected/actual/OK|MISMATCH|MISSING;
不带 --hash 时:已声明 artifacts 仍会校验(安全默认),但不强制"必须声明";
- 输出 id/version/publisher/signature 状态/key_id(trusted/revoked)/权限/artifacts/判定;
注:权限仅**展示**(宿主 grant 列表不在 CLI 上下文,默认拒绝判定由宿主在 load() 执行);
- 退出码:0 通过;2 参数/公钥格式错误;3 未签名/坏签名/工件/密钥/策略拒绝;
4 加密校验不可用(无公钥或工具构建时 license 不可用)。
- --abi / --list / --inspect 行为不变。
## 7. 与 vde_license 的关系
- vde_license 是**业务模块**(许可/授权),内核插件库不得依赖;
- P3-1 复用其 Ed25519(RFC 8032)实现,但仅通过**宿主注入**:
宿主/工具链接 vde_license 并实现 SignatureVerifier;
- kernel-only SDK 也可使用 P3-1 协议层,验签实现可由宿主自行提供(KMS/HSM);
- LicenseTier/feature gating 可在策略层组合:安全判定通过后再由宿主做许可检查,二者解耦。
## 8. 已知限制(P3 范围)
1. **进程内尽力而为**:无法阻止已加载原生代码的恶意行为;强制隔离/权限拦截在
P3-3 进程外(P2-4 已提供 env 白名单/超时/退出码映射基础)。
2. **DLL 本体完整性**:P3-5 起由清单 artifacts SHA-256 覆盖(签名保护哈希清单);
未做 OS 代码签名/Authenticode;哈希校验与 dlopen 之间仍有 TOCTOU 窗口(见 5)。
3. **密钥管理**:支持多受信 key + key_id + 吊销列表;P4-08 起支持签名 CRL 分发
(`--crl`,本地文件/Windows HTTP;无 OCSP/在线实时刷新/`--crl-cache`);
密钥有效期、多签名(发布者+企业)未实现。
4. **发布者白名单依赖签名**:未签名插件下 publisher 是自称值,白名单不提供安全
保证(宿主应同时要求签名)。
5. **TOCTOU**:artifacts 哈希校验与 dlopen 之间文件可被替换;强保证需"校验后独占句柄/
文件锁加载"(P3 后续)。哈希校验可检出部署后静态篡改,但无法防御同时具备写权限的
本地攻击者在窗口期替换。
6. **原生崩溃隔离**:不含;进程内崩溃仍拖垮宿主(P3-3 进程外)。
## 9. 集成到 PluginManager(P3 后续接线)
管理器集成钩子见 build-fb-dllsec/manager_hook.patch(task-51 合并后由 Lead 接线):
PluginManager 增加 set_security_policy() / set_security_verifier() / security_report(id);
load() 在 dlopen 前调用 evaluate_plugin_security(manifest_json, plugin_dir, ...)(P3-5 扩展
重载,plugin_dir 用于 artifacts 相对路径解析与 SHA-256 校验),失败即拒绝并记录 last_error。
P3-1/P3-5 期间管理器行为不变(默认不设置策略 = 不校验)。
## 10. 测试与验收
- tests/plugin/test_plugin_security.cpp(**42 用例**):P3-1 的 canonical payload/签名/公钥/
strict/allow_unsigned/mock 验签/发布者白名单/权限/错误码,加 P3-5 的 SHA-256 已知向量、
artifacts schema/路径逃逸/哈希通过-篡改-缺失、strict 强制 artifacts、工件+签名联合评估、
key_id 选择/未知 key/吊销/轮换(旧 key 吊销+新 key 接受)/单 key 回退/多 key 无 key_id、
错误码别名分类、旧 evaluate 重载兼容。
- vde_plugin_tool verify 手工用例:签名通过/篡改失败/未签名/坏公钥/无公钥退出码;
P3-5 工件哈希(--hash 通过/篡改)、--key-id 匹配/不匹配、key 吊销/轮换;
证据在 build-fb-dllsec/。
- tests/plugin/test_plugin_crl.cpp(**10 用例**,P4-08):签名 CRL 生成(`--sign-crl`)→
verify-index/install/upgrade 命中吊销失败、不同 key 放行、过期/未生效、篡改/错误公钥验签失败、
格式错误(3)/不可获取(4)、本地 HTTP 获取(Windows 内建 server;POSIX skip 并保留文件路径覆盖)。
- 单元测试不依赖加密库(mock 验签)保证协议层确定性;真实验签由工具手工用例覆盖
(build-fb-security/ 下生成测试密钥对与签名清单证据)。