20 KiB
插件签名 / 许可策略 / 权限模型 / 工件哈希 / 密钥轮换(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. 设计原则
- 分层:内核插件库只定义协议/策略/权限语义,不做任何加密运算; Ed25519 验签由宿主通过 SignatureVerifier 注入(vde_license::crypto::ed25519_verify、 平台 KMS/HSM、企业签名服务均可)。
- 默认兼容:默认不强制签名(allow_unsigned = true),P0/P1/P2 已有无签名插件 (sample_vbox、官方 STL/OBJ/PLY 等)加载行为不变;严格模式由宿主显式开启。
- 默认拒绝:权限默认拒绝(permissions_default_deny = true);清单未声明 permissions 视为空请求(向后兼容)。
- 结构化失败:所有失败返回 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()):
- 解析清单 JSON 对象;删除顶层 signature 字段(嵌套同名键保留);
- 对象键按 UTF-8 字节序(字典序)递归排序;数组顺序保留;
- 无任何空白字符;字符串标准 JSON 转义,非 ASCII UTF-8 原样输出;
- 数字最短往返十进制表示;
- 输出 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 签发与验证
签发(发布者工具,不在本任务实现):
- 删除清单顶层 signature;2. 按 §4.2 生成 canonical payload;
- sig = Ed25519(私钥, canonical_payload);4. 写回 "signature": "ed25519:"。
验证(evaluate_plugin_security() 顺序):清单合法性 → 签名(缺失/格式/算法/公钥/ 验签)→ 发布者白名单 → 权限;返回 PluginSecurityReport(Ok 时也含签名/发布者/权限 明细供审计)。
4.4 公钥分发
- 32B Ed25519;文本支持 ed25519:、裸 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 前调用):
- 语法:artifacts 必须是对象数组;path 非空字符串;sha256 为 64 hex 字符;
- 路径安全:拒绝绝对路径/盘符/UNC 与任何
..组件(目录逃逸 → ArtifactPathInvalid); - 存在性:解析为
plugin_dir/path后必须存在且可读(→ ArtifactMissing); - 哈希:实际 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); - 选择规则:
- 清单有 key_id:先查吊销(RevokedKey)→ 再查 trusted_keys(缺失 → UnknownKeyId); trusted_keys 为空时回退到调用方传入的 public_key(P3-1 兼容路径);
- 清单无 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>; - 吊销文件两种格式(调用方/宿主策略提供,不从索引内读取,避免签名者自证吊销):
- 每行一个 key_id(
#起注释;一行也允许逗号分隔多个); - JSON
{"revoked_key_ids": ["key-id", ...]};空文件/格式错误 → 退出码 3,诊断含invalid --revoked-keys;
- 每行一个 key_id(
- 强制顺序:索引验签通过后检查签名 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):
{
"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 范围)
- 进程内尽力而为:无法阻止已加载原生代码的恶意行为;强制隔离/权限拦截在 P3-3 进程外(P2-4 已提供 env 白名单/超时/退出码映射基础)。
- DLL 本体完整性:P3-5 起由清单 artifacts SHA-256 覆盖(签名保护哈希清单); 未做 OS 代码签名/Authenticode;哈希校验与 dlopen 之间仍有 TOCTOU 窗口(见 5)。
- 密钥管理:支持多受信 key + key_id + 吊销列表;P4-08 起支持签名 CRL 分发
(
--crl,本地文件/Windows HTTP;无 OCSP/在线实时刷新/--crl-cache); 密钥有效期、多签名(发布者+企业)未实现。 - 发布者白名单依赖签名:未签名插件下 publisher 是自称值,白名单不提供安全 保证(宿主应同时要求签名)。
- TOCTOU:artifacts 哈希校验与 dlopen 之间文件可被替换;强保证需"校验后独占句柄/ 文件锁加载"(P3 后续)。哈希校验可检出部署后静态篡改,但无法防御同时具备写权限的 本地攻击者在窗口期替换。
- 原生崩溃隔离:不含;进程内崩溃仍拖垮宿主(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/ 下生成测试密钥对与签名清单证据)。