docs: access control and enrollment trust chain design [CI SKIP]
This commit is contained in:
justme committed
1 parent
af2962fc58
commit
55b80f0a97
3 files changed
+383
-41
No files matched your search
+24
-40
@@ -71,45 +71,28 @@ Agent、Backend、Probe 之间互相不信任。这份文档只回答三个问
|
||||
不能做的：加入新节点、改地址让 Probe 去探内网、塞恶意更新、冒充节点。
|
||||
```
|
||||
|
||||
## 5. 名册（roster）
|
||||
## 5. 入网信任链
|
||||
|
||||
操作员签名的舰队成员表，节点本地固定操作员的公钥，只采用验签通过的名册。
|
||||
下文和其他章节里的「名册」指节点本地验过链的成员表。**详细设计见 [access.md](access.md)**（账户、角色、能力、API key、提权窗口、签名链、流程和实施顺序）。这里只留结论：
|
||||
|
||||
```text
|
||||
管理端（管理员） Backend Agent / Probe
|
||||
┌──────────────┐ ①提交变更 ┌─────────┐ ┌──────────────┐
|
||||
│批准节点、改地址│───────────────▶│只存、转发│─② 名册 + 签名─▶ │本地固定操作员 │
|
||||
│或吊销 │◀─③ 挑战（哈希）─│ │ │公钥；验签通过 │
|
||||
│触控或确认 │ ④ 签名 │ │ │且 version 更大│
|
||||
│ │───────────────▶│ │ │才采用并持久化 │
|
||||
└──────────────┘ └─────────┘ └──────────────┘
|
||||
```
|
||||
|
||||
内容：`{version, expires_at?, 成员: [{id, 角色, 公钥(SPKI), Agent 的公网地址、端口和 TLS 指纹}]}`。
|
||||
|
||||
- Agent 只接受名册里的 Probe；Probe 只拨名册里的 Agent，并且只用名册里写的地址（缺口 G3、G6 因此消失，不需要另外的拨号白名单）。
|
||||
- **不可回放**：节点持久化见过的最大 `version`，低于它的名册一律拒绝，所以 Backend 无法拿旧名册复活已吊销的节点。
|
||||
- 可选的 `expires_at` 防止 Backend 截留新名册（冻结攻击）。
|
||||
- 每次改动成员或地址都要操作员签名一次：批准新节点（加入令牌的自动批准只让它连上，进名册仍要签）、公网地址变了、吊销。
|
||||
- 任务集、测试请求这类内容不进名册：它们由 Backend 计算，被节点本地硬上限兜住。
|
||||
- 名册不再是「每次变更都要操作员签一整张表」，而是一条可离线验证的链：节点固定创世 owner 公钥 → 操作员集合（带版本，owner 签）→ 委托（passkey 签，限定范围和时间）→ 入网券（委托的密钥签）→ 节点绑定（节点注册时用安装命令里的 `K_code` 签）。加上 passkey 当场签的吊销表。
|
||||
- Agent 只接纳链验得过的 Probe，Probe 只拨链验得过的 Agent，并且只拨公网地址（缺口 G3、G6 因此消失，不需要另外的拨号白名单）。
|
||||
- **不可回放**：节点持久化见过的最大操作员集合版本和吊销表版本，Backend 无法拿旧文档复活已吊销的节点。
|
||||
- 人在场时一次 passkey 触控换一个有时限的提权窗口，窗口内加节点不再确认；自动化用创建时经 passkey 签名的 `enroll` API key。被攻破的 Backend 在窗口和 key 过期后，一个节点都加不进来。
|
||||
|
||||
## 6. 操作员凭证
|
||||
|
||||
节点本地配置里固定一串操作员凭证，每条带类型，验签代码按类型分支；任一条通过即可，所以丢了一个设备不会被锁死，换凭证是改节点本地配置（重新运行部署脚本）。
|
||||
操作员凭证就是 passkey（WebAuthn，ES256，attestation 选 `none`）。节点本地固定创世 owner 公钥，其余凭证靠 owner 签名的操作员集合同步，不用重装节点；每条凭证带角色（`owner`、`admin`）和限制（例如单张入网券的最长有效期），由节点自己执行。
|
||||
|
||||
| 类型 | 适合 | 节点怎么验 | 强度 |
|
||||
| --- | --- | --- | --- |
|
||||
| `webauthn` | 有通行密钥的设备 | 固定凭证公钥，验 `authenticatorData ‖ SHA256(clientDataJSON)` 的 ECDSA 签名，检查 `challenge` 等于名册哈希；注册时 attestation 选 `none`，信任浏览器实现，不验证设备证明 | 最强，每次改动需要本人触控 |
|
||||
| `ecdsa` | 没有通行密钥的设备 | 管理端用 WebCrypto 生成不可导出的 P-256 密钥，存在受信任的 Chromium 里，直接对名册哈希签名 | 中：本机被入侵或页面被 XSS 时可被静默调用 |
|
||||
| `oidc` | 完全不方便装密钥的设备 | 授权请求的 `nonce` 填名册哈希，节点验 ID Token 的签名（固定 IdP 的签名公钥）、`aud`、`sub`、`nonce` 和新鲜度 | 较弱：IdP（例如 Gitea）被攻破就等于操作员被攻破；节点没有 HTTP 客户端，IdP 公钥只能固定在本地，换密钥要改配置 |
|
||||
|
||||
三种在节点上都只用 BCL 的 ECDSA 或 RSA 验签，不增加依赖和资源。
|
||||
- 登录可以用密码、passkey 或 OIDC，但**只有 passkey 能提权**：节点验证不了 IdP 的断言，也不该让密码和 IdP 进入信任域。OIDC 只是账户的另一种登录方式（绑定 `iss + sub`）。
|
||||
- 自动化凭证：`enroll` API key 创建时由 passkey 签一份委托；CI 和测试用软件 ECDSA 凭证，写进测试的操作员集合。
|
||||
- 恢复：passkey 全部丢失时，重装节点并换创世公钥；所以每个账户至少注册两个 passkey。
|
||||
|
||||
## 7. 各类下行消息怎么处置
|
||||
|
||||
| 下行内容 | 授权 | 被攻破的 Backend 最多能做什么 |
|
||||
| --- | --- | --- |
|
||||
| 舰队成员、对端公钥、Agent 地址 | **操作员签名**（名册） | 什么都改不了 |
|
||||
| 舰队成员、对端公钥 | **操作员签名**的入网链和吊销表 | 什么都改不了；Agent 地址由 Backend 下发，但 Probe 只拨公网地址 |
|
||||
| 更新清单 | 发布密钥（已有） | 不能伪造；能转发旧的合法清单，`seq` 防回滚 |
|
||||
| 任务集、测试请求 | Backend 计算；节点本地硬上限兜底（已有） | 只能在名册成员之间、本地速率和端口上限内发测量流量 |
|
||||
| 重启计划（`moshiro.schedule`） | Backend；节点本地启动后 10 分钟内不触发 | 最多让节点每 10 分钟重启一次 |
|
||||
@@ -251,13 +234,14 @@ Agent 和 Probe 的核心永远是纯采集器。**所有敏感能力**（exec
|
||||
```
|
||||
|
||||
- **独立进程，不是插件**：extension 是单独的二进制和镜像，和核心之间**没有进程内接口**，核心不加载任何外部代码、不用反射和动态加载，所以核心的 NativeAOT 和「不能 exec」都不受影响。extension 自己用什么技术实现都行（可以是 NativeAOT，也可以不是）。
|
||||
- **授权只认节点的属主**：每次调用的能力令牌必须由这个节点绑定的属主 passkey 签名，账户角色（owner、admin）不赋予权力；管理员只能删除节点或卸载 extension，读不到、用不了；交互式会话端到端加密。属主的设计见 [access.md](access.md) 第 8 节。
|
||||
- **独立身份**：extension 有自己的密钥、自己向 Backend 注册，在名册里是单独的成员（角色 `extension`，记录它依附的节点 ID）。核心被攻破碰不到 extension 的密钥，反过来也一样。
|
||||
- **独立发布**：沿用签名更新的流程，`component` 不同（例如 `ext-ssh`），独立的镜像、独立的清单；装不装、升不升级都不影响核心的更新。
|
||||
- **独立命名空间**：extension 的方法只能是 `ext.<名字>.*`，同样进方向声明表；核心的声明表里没有 `ext.*`，核心收到一律拒绝。extension 只响应自己命名空间的方法。
|
||||
- **安装像装一个选项**：部署脚本加一个选项（例如 `--extension ssh`）拉起对应容器并写好配置；管理端在节点详情里出现对应入口。卸载就是停掉那个容器。
|
||||
- **本地显式启用**：extension 的本地配置里有 `enabled`、允许的操作员凭证、允许的命令集或目标范围（例如允许登录的用户、允许访问的路径），默认关闭，没有配置就什么都不做。
|
||||
- **每次调用都要授权**：操作员签名的一次性能力令牌，`{节点 ID, extension, 命令哈希, not_before, not_after, nonce}`，有效期以秒计；extension 用本地固定的操作员凭证验签。被攻破的 Backend 不能启用 extension，也伪造不了一次调用。
|
||||
- **交互式会话的内容对 Backend 不透明**（例如 web ssh）：浏览器和 extension 在能力令牌携带的公钥基础上协商一次性会话密钥，Backend 只转发密文，不应该能读到终端里的内容。具体做法还没定，见第 14 节。
|
||||
- **交互式会话的内容对 Backend 不透明**（例如 web ssh）：浏览器和 extension 在能力令牌携带的公钥基础上协商一次性会话密钥，Backend 只转发密文，不应该能读到终端里的内容。做法见 [access.md](access.md) 第 8.2 节：属主 passkey 授权、临时 ECDH 加 AEAD，静态数据用属主的 `enc_pubkey` 封装。
|
||||
- **不做的**：核心里的任何 exec、文件写、加载 extension；用 extension 绕过核心的本地硬上限（extension 有它自己的上限，核心的不放宽）。
|
||||
|
||||
## 12. 实施顺序
|
||||
@@ -266,7 +250,7 @@ Agent 和 Probe 的核心永远是纯采集器。**所有敏感能力**（exec
|
||||
零 协议方向声明表 + 收发校验 + 对账测试 G7，第 8 节；同时把 NodeConnection 按职责拆开（第 13.2 节） 已完成，不破坏
|
||||
一 Probe 自己生成密钥 + 加入令牌注册 + 密钥按用途拆开 G2、G11 已完成，破坏性：旧 probe.json 失效
|
||||
二 预握手敲门（等级一） G4；先基于现有的对端公钥列表，名册出来后换成名册 已完成，破坏性：旧 Probe 被拒绝
|
||||
三 操作员凭证 + 名册 + 节点验签与持久化 G1 的大部分、G3、G6；webauthn 和 ecdsa 先做，oidc 随后 破坏性：节点要固定操作员公钥并重新注册
|
||||
三 访问控制 + 入网信任链 G1 的大部分、G3、G6；拆成 5 步，见 [access.md](access.md) 第 12 节：能力模型与 API key → 账户与 passkey → 操作员集合 → 入网链 → 吊销 破坏性：节点要固定创世公钥并重新注册；旧 admin 令牌不能再生成加入代码
|
||||
四 测量数据的可信 + 入库配额和输入校验 + CSP G5、G8、G9、G10、T5（第 9.1、9.2 节） 破坏性：块格式加签名
|
||||
五 Backend 应用层身份固定 + 下行消息签名 G1 的剩余部分（链路劫持） 破坏性
|
||||
六 extension 框架 独立身份和名册条目、`ext.*` 命名空间、能力令牌、部署脚本的 --extension 选项（先不做具体的 ssh）
|
||||
@@ -316,13 +300,13 @@ Agent 和 Probe 的核心永远是纯采集器。**所有敏感能力**（exec
|
||||
|
||||
## 14. 还没定的事
|
||||
|
||||
1. 操作员凭证第一批做 `webauthn` 和 `ecdsa`，`oidc` 放在名册稳定之后，是否这样；还是 `oidc` 一起做。
|
||||
2. 敲门先做等级一，等级二先记 TODO，是否这样。
|
||||
3. 严格程度：节点没有固定操作员公钥就拒绝一切 Backend 给的对端和地址（推荐），还是保留一个过渡期兼容旧行为。
|
||||
4. 管理员域（T4）的审计日志、令牌过期、危险操作二次确认：还没有核对现状，也没有设计。
|
||||
5. 节点面和外部面是否拆成两个监听端口（8.1 的目标）：拆的话部署文档、Caddy 和隧道的配置都要跟着改。
|
||||
6. extension 的交互式会话要不要做到「Backend 只转发密文」（端到端加密），还是先做成 Backend 可见明文、以后再加。
|
||||
7. extension 的第一个具体实现做不做 web ssh，放在哪个阶段。
|
||||
8. 块摘要固定 SHA-256，不预留算法字段（不协商、不降级，见第 9.4 节）。
|
||||
9. Agent 的 `max_total_mbps` 默认值调到多少（第 9.5 节），比如 100。
|
||||
10. 块的签名放进格式的哪个位置、是否影响现有 `MSRC` 容器版本（第 9.1 节）。
|
||||
访问控制与入网信任链的细节、待确认的默认值见 [access.md](access.md) 第 17 节。这里只列其余的：
|
||||
|
||||
1. 敲门先做等级一，等级二先记 TODO（已按此实现等级一）。
|
||||
2. 严格程度：节点没有固定操作员公钥就拒绝一切 Backend 给的对端（默认），弱信任模式是安装时的显式选择（见 access.md 第 8 节）。
|
||||
3. 节点面和外部面是否拆成两个监听端口（8.1 的目标）：拆的话部署文档、Caddy 和隧道的配置都要跟着改。
|
||||
4. extension 的交互式会话**已定**：端到端加密，Backend 只转发密文（见 access.md 第 8.2 节）；剩下的是静态数据私钥来源和 AEAD 的选择。
|
||||
5. extension 的第一个具体实现做不做 web ssh，放在哪个阶段。
|
||||
6. 块摘要固定 SHA-256，不预留算法字段（不协商、不降级，见第 9.4 节）。
|
||||
7. Agent 的 `max_total_mbps` 默认值调到多少（第 9.5 节），比如 100。
|
||||
8. 块的签名放进格式的哪个位置、是否影响现有 `MSRC` 容器版本（第 9.1 节）。
|
||||
Reference in new issue
Block a user