justme/MoShiro
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity
Files
fc2bbdcc6d9196964dba0674a9b87d143234b225
MoShiro/docs/security.md
T

32 KiB
Raw Blame History

零信任设计

实现状态：阶段零（协议方向声明表和卡口，第 8 节）已实现，其余是设计稿，尚未实现。 第 3 节的缺口是对当前代码的核对结果（G7 已解决）；第 4 节起是目标设计和实施顺序。第 14 节列出还没定的事。

Agent、Backend、Probe 之间互相不信任。这份文档只回答三个问题：现在谁听谁的、被攻破之后最坏会怎样、怎么用密码学把信任从 Backend 身上拿走。纯采集的边界、本地硬上限和签名更新见 architecture.md 第 5 节，这里不重复。

1. 范围

要防的

  • Backend（或 Backend 前面的 Cloudflare Tunnel、frp、Caddy 等中间环节）被攻破或被劫持之后，给节点下发恶意内容。
  • Agent 或 Probe 自己被入侵之后，去影响 Backend 或对端。

有意不做的

  • 进程沙箱（seccomp、pids 和内存上限、出站白名单）。Agent 和 Probe 的定位是 1 核 1 GB 的小机器，不能吃资源。
  • 供应链的多签、冷却期和可复现构建。代码风险靠 PR 评审降一个等级；发布仍然是单把发布密钥签名（见 deployment.md）。以后需要时再加，不属于这份设计。
  • 顺带记一条：Agent 的单元现在挂了 /:/host/root:ro、/proc、/sys，被攻破的 Agent 能遍历宿主机。它们多半是不必要的（宿主网络模式下容器自己的 /proc 就是宿主的，磁盘用量可以对已挂载的 /etc/os-release 做 statvfs），属于沙箱范畴，先不动，实现时再核实。

2. 威胁模型

编号 假设被攻破的是 现实来源
T1 Backend，或它前面的中间环节 链路经过 Cloudflare Tunnel、frp、Caddy，它们都能看到 wss 的明文
T2 某个 Agent（在 VPS 上，旁边还有别的服务） VPS 被入侵
T3 某个 Probe（在客户内网里） 客户机器被入侵
T4 管理员的会话或令牌 令牌泄露
T5 管理员的浏览器 XSS，或者节点上报的字符串被渲染

3. 现状：节点听谁的，缺口在哪

                      CI 发布私钥（单把）
                            │ 签名清单
 管理员 ──令牌/会话──▶ ┌──────────┐ ◀── 原始块、事件、主机数字（没有按节点的配额）
                       │ Backend  │
                       └──┬───┬───┘
        任务集、对端公钥、   │   │  Agent 名单（host:port，Probe 全部照拨）
        重启计划、更新清单   ▼   ▼
                   ┌──────┐   ┌──────┐
                   │Agent │◀─▶│Probe │   Probe 私钥由 Backend 生成
                   └──────┘   └──────┘
# 缺口 依据 后果
G1 节点不验证 Backend 的身份，只靠 TLS 加公共 CA Fleet.Link 里没有证书固定，也没有应用层验证 链路上任一环节被攻破，就能给节点下发任务集、Agent 名单、对端公钥、重启计划（更新清单有签名，不受影响）
G2 Probe 的私钥由 Backend 生成 ProbeService 里的 NodeIdentity.Generate（创建和轮换） Backend 接触过 Probe 的私钥，可以冒充它；Agent 的密钥是自己生成的，没有这个问题
G3 Probe 会拨 Backend 给的任意 host:port AgentDirectory、AgentConnection 不做任何地址检查；本地 limits 只有速率和 pps 被攻破的 Backend 能让客户内网里的 Probe 去探测内网。固定 SPKI 只能防止建立会话，防不了探测本身
G4（已修，阶段二） Agent 的 TCP 端口对任何人完成 TLS 握手并出示证书 TcpAcceptor、PeerListener 在 AcceptTcpClient 之后直接 AuthenticateAsServer 自签证书、TLS 参数、JARM 都能被扫描器指纹识别，一眼看出这是个服务
G5 Backend 入库只限制了单块的大小 MaxDecodedChunkBytes 等；没有找到按节点的速率或配额 恶意节点可以灌满磁盘
G6 对端公钥、Agent 地址全由 Backend 决定 TaskSet.Peers、ProbeAgentList 被攻破的 Backend 能把恶意 Probe 加进 Agent 的白名单，或把 Probe 指向恶意 Agent
G7（已解决） 方法的方向和角色没有统一声明：原来靠「谁注册了处理器」隐式决定 NodeConnection.HandleMessageAsync 只按方法名分发到路由器；文档里的 B→A、A→B 只存在于 protocol.md，没有对账 新增一个方法时，方向写反、角色写错（例如 Probe 调了只给 Agent 的方法）不会被任何东西发现
G8 测量数据没有产生者签名 Raw/ 的编解码里没有任何签名或 MAC，块只有 CRC32C；Probe 的列块（通道 17）经 Agent 合并进原始块再上传 隧道等中间环节可以改写测量数据；被攻破的 Agent 可以伪造 Probe 侧的时间戳（t1、t4）
G9 入库只核对了 agent_id IngestService 在 header.AgentId != agent 之后直接采用块头里的 series（形如 line:<probe_id>），全文没有出现 Probe 被攻破的 Agent 可以为从没连过它的 Probe 灌入假线路数据
G10 没有合理性检查 EchoOps 里没有对回显时间戳做任何一致性检查 恶意 Agent 可以谎报 t2、t3，把自己的处理时延说成任意值，让线路 RTT 好看或难看
G11 Probe 的一把密钥多处使用 architecture.md 第 5 节写明同一把用来连 Backend 和连 Agent；已有用途前缀（auth、peer）做域隔离 一处泄露，两处都沦陷

没有问题的部分：UDP 端口对未认证的包静默丢弃，不回应（DropInvalid，有测试）；Probe 本身没有 TCP 监听；任务有本地硬上限；更新清单有签名和 seq 防回滚。

4. 核心思路：信任锚点从 Backend 移走

要防 Backend 被攻破，下行内容必须由 Backend 之外的密钥授权。Backend 只搬运、计算和存储，不创造信任：

  ① 发布密钥（CI）          ──▶ 「跑什么代码」               已有：清单签名、seq 防重放
  ② 操作员密钥（管理员本人）  ──▶ 「谁是舰队成员、去哪拨」      新增：Backend 持有不了
  ③ 节点自己的密钥           ──▶ 「我是我」                   已有；Probe 要改成自己生成

  被攻破的 Backend 能做的：拒绝服务、看数据。
  不能做的：加入新节点、改地址让 Probe 去探内网、塞恶意更新、冒充节点。

5. 入网信任链

下文和其他章节里的「名册」指节点本地验过链的成员表。详细设计见 access.md（账户、角色、能力、API key、提权窗口、签名链、流程和实施顺序）。这里只留结论：

  • 名册不再是「每次变更都要操作员签一整张表」，而是一条可离线验证的链：节点固定创世 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）和限制（例如单张入网券的最长有效期），由节点自己执行。

  • 登录可以用密码、passkey 或 OIDC，但只有 passkey 能提权：节点验证不了 IdP 的断言，也不该让密码和 IdP 进入信任域。OIDC 只是账户的另一种登录方式（绑定 iss + sub）。
  • 自动化凭证：enroll API key 创建时由 passkey 签一份委托；CI 和测试用软件 ECDSA 凭证，写进测试的操作员集合。
  • 恢复：passkey 全部丢失时，重装节点并换创世公钥；所以每个账户至少注册两个 passkey。

7. 各类下行消息怎么处置

下行内容 授权 被攻破的 Backend 最多能做什么
舰队成员、对端公钥 操作员签名的入网链和吊销表 什么都改不了；Agent 地址由 Backend 下发，但 Probe 只拨公网地址
更新清单 发布密钥（已有） 不能伪造；能转发旧的合法清单，seq 防回滚
任务集、测试请求 Backend 计算；节点本地硬上限兜底（已有） 只能在名册成员之间、本地速率和端口上限内发测量流量
重启计划（moshiro.schedule） Backend；节点本地启动后 10 分钟内不触发 最多让节点每 10 分钟重启一次
未来的 extension（exec 等） 操作员签名的一次性能力令牌，见第 11 节 什么都做不了

另外 Backend 自己对节点也有一条应用层身份：Backend 有长期签名密钥，节点在注册时固定它，下行消息带签名、节点 ID、序号和有效期。它防的是你的 Cloudflare、frp 链路被劫持（G1）；对 Backend 自己被攻破没有帮助，那一类靠名册。

8. 协议的方向与平面

8.1 三个平面，各认各的凭证

 外部面（人、浏览器、脚本）   /api/public（匿名只读，SSE）   /api/admin（Cookie + CSRF，或 API 令牌）
                              /install.sh  /openapi  /healthz  /metrics
 节点面（节点主动拨入）        /api/agent/v1/enroll（加入令牌，一次性）   /api/agent/v1/rpc（wss，节点签名认证）
 对等面（Probe 拨 Agent）      TLS 控制 7443/tcp、数据 7443/udp、7444/tcp（名册里的成员才能通过）
  • 每个平面只认自己的凭证：节点面不接受令牌和 Cookie；外部面不接受节点签名；对等面只认名册成员。任何一个平面的凭证都换不到另一个平面的权限。
  • 连接方向固定：节点面永远是节点拨入 Backend，Backend 从不主动连节点，所谓「下发」只是在节点拨入的连接上发下行消息；对等面永远是 Probe 拨 Agent，Agent 不拨 Probe。
  • 外部面不能直通节点面：管理端的操作（例如发起测试）只会触发 Backend 里一个强类型的下行方法，管理端不能指定方法名，也不能把请求体原样转给节点。现状已满足（IAgentGateway 里全是强类型方法），要写成约束并用测试守住。
  • 现状：三个平面共用同一个监听端口和同一条 ASP.NET 管线，靠路径和凭证类型区分。目标是把节点面和外部面做成可以分别配置监听地址（默认仍同一个），这样管理面可以只对内网或 VPN 开放，节点面单独放出去。

8.2 每个方法声明方向、类型和角色

同一个方法名只允许一个发起方，不存在「双向方法」。需要两个方向交互时，定义两个方法。一个方法声明四件事：

声明 取值 含义
发起方 B→A、B→P、A→B、P→B、P→A、A→P 只有它能发出这个方法，对方收到就是违规
类型 请求（有响应）、通知（无响应） 通知不允许回复；响应只对应一个未决的请求 ID，且那个方法必须是请求
角色 A、P、A+P 节点角色不对就拒绝（Probe 不能调 Agent 的方法）
授权 无、operator（需要操作员签名的能力令牌） 为 extension 预留，核心方法都是「无」

方向总表（来自 protocol.md，实现时以代码里的声明为准）：

方法 方向 类型 角色
fleet.challenge、fleet.state.sync、fleet.outbox.ack、fleet.revoked B→节点 见 Fleet 说明 A+P
fleet.auth、fleet.hello、fleet.heartbeat 节点→B 见 Fleet 说明 A+P
moshiro.test.run、moshiro.test.cancel、moshiro.probe.disconnect B→A 请求 A
moshiro.update.offer、moshiro.update.apply、moshiro.schedule B→节点 通知 A+P
moshiro.test.status、moshiro.event、moshiro.host A→B 通知 A
二进制通道 16（RawChunk） A→B 发件箱 A
对等面的方法和通道 17（列块） P→A、A→P，按 protocol.md 按声明 P、A

8.3 强制方式

  1. 一份声明表，单一真源，放在 MoShiro.Protocol（Fleet 自己的 fleet.* 放在 Fleet）；文档里的方向表由它生成或对账。
  2. 发送前检查：发错方向是编程错误，直接失败。
  3. 接收时检查：收到不该由对方发起的方法、未声明的方法、角色不对的方法，丢弃并计数，连续违规断开连接。
  4. 响应匹配：只接受对应未决请求 ID 的响应，不接受主动「响应」。
  5. 对账测试（ArchitectureTests）：声明表和实际注册的处理器逐项比对，新增方法绕不过声明。
  6. 下行消息只是建议，不是命令：节点按本地硬上限执行或拒绝；任何带副作用的敏感能力都不走核心的下行消息，见第 11 节。

已实现（阶段零）：

  • 声明表：Fleet.Rpc/MethodTable.cs（MethodSpec、ChannelSpec、MethodTable）；框架的 fleet.* 在 FleetMethodTable，moshiro.* 和两条二进制通道在 MoShiro.Protocol 的 MoShiroMethodTable；角色是 NodeRoles（服务端按节点 ID 前缀判断）。声明表按（平面，名字）查找，同名方法在两个平面里可以有不同的发起方（fleet.state.sync 在节点面是 Backend→节点，在对等面是 Agent→Probe）。
  • 卡口：RpcRouter 创建时必须给出本侧（RpcSide）和声明表。注册处理函数时核对方向、类型、角色，不符就在启动时失败；分发时拒绝没有声明、方向不对、请求和通知用反了、角色不允许的消息，回 fleet_protocol_violation 并报告违规；发送前核对本侧有没有资格发起（CheckSend，违反是程序缺陷，抛异常）。
  • 违规处理：RpcSession 和服务端的 NodeConnection 对违规计数，超过上限（MaxViolations，默认 20）就断开连接；二进制通道也在服务端按声明核对（节点只能往声明过、并且允许它的角色使用的通道发）。
  • 对账测试：Fleet.Tests/MethodDirectionTests 覆盖卡口本身；MoShiro.Backend.Tests/ProtocolDeclarationTests 核对「每个方法常量都声明了」「文档里写了每个方法」「Backend、Agent、Probe 两个平面各自该处理的方法都注册了处理函数」「每条声明的通道都有收件箱」。
  • 这次落地时对账发现了两处不一致并修掉：文档漏了 fleet.peer.challenge、fleet.peer.auth；Agent 的 moshiro.schedule 处理函数原来只在传入重启控制器时才注册。

9. 节点自己被攻破时：数据可信与归属

9.1 测量数据的可信（G8、G9、G10）

测量数据是这个项目的产出，不能只靠传输层可信：你的链路有 Cloudflare 这样的中间环节，Agent 又要转发 Probe 的数据。

  • 产生者签名：每个列块由 Probe 签名，每个原始块由上传它的节点签名；Agent 转发 Probe 的块时原样保留 Probe 的签名。签名覆盖块的摘要（见第 13 节），签名串带用途前缀 chunk 和节点 ID。Backend 入库时逐个验签，不通过的丢弃并计数。每 10 秒一块，一次 ECDSA 验签的开销可以忽略。
  • 归属校验：入库时核对块里的 Probe 是名册里和这个 Agent 有线路的成员，不是就丢弃并计数；线路只由名册里的（Probe，Agent）对产生。
  • 合理性检查：t3−t2 必须小于 t4−t1，各时间戳单调；违反的样本不计入指标，记为异常并产生事件。
  • 边界：这样中间环节改不了数据，被攻破的 Agent 改不了 Probe 一侧的数据；但它仍然可以谎报自己一侧的 t2、t3，合理性检查只能限制它的幅度，消除不了，因为这一侧的真值只有它自己知道。

9.2 对 Backend 的资源和输入

  • 按节点的配额：每个节点的字节、块数和速率上限，只是计数，不占资源；全局再限制同时解码的块数（单块解码上限是 64 MiB，多个节点同时发大块可以耗尽内存）。
  • 节点上报的字符串：hello 里的 platform、事件的 detail 等一律当不可信数据，入库前统一校验长度、字符集和换行，不依赖前端转义；管理端加 CSP，不渲染成 HTML。
  • 匿名公开接口：登录已经有限流，但热力图、分布这类重查询只有范围和指标数的上限，要加每源限速和结果缓存（TODO 里的人机验证会部分覆盖）。
  • webhook（TODO 里有）：实现之前先定约束：只允许 HTTPS、禁止私网和回环地址、不跟随重定向、限制超时和响应大小、解析之后再检查地址。
  • 解码器保持大小上限；模糊测试已在 TODO。

9.3 对对端和身份

  • 被攻破的 Probe 只能拿到名册授权的会话，Agent 的速率上限由本地兜底；被攻破的 Agent 发来的数据只会影响它自己的线路。
  • 身份被偷：操作员签一份新名册吊销它，所有节点立即拒绝，且因为 version 递增不可回放。
  • Probe 私钥要自己生成：现在 Backend 知道它（G2），名册也防不了这一点。改成和 Agent 一样用加入令牌注册，私钥只在节点上。
  • 密钥按用途拆开（G11）：面向 Backend 的和面向对等面的是两把独立的 P-256 密钥；敲门、会话等对称用途用 KDF 加用途标签派生，不复用签名密钥直接做别的事。

9.4 对设计的补充要求（实现时核实现状）

  • 所有下行状态文档都防回放：节点持久化每种状态文档见过的最大 version，低版本一律拒绝，不只是名册。
  • UDP 会话迁移要做路径验证：协议允许会话在 NAT 映射变化后跟随新的源地址，路径上的攻击者可以借此把会话牵到自己的地址。迁移前先做一次挑战应答，验证前限制发送量（不超过收到字节数的 3 倍），类似 QUIC 的 path validation。
  • 名册里的主机名解析之后再检查地址：签名保护的是字符串，不是解析结果；默认只放行公网地址，内网需要节点本地显式允许；名册里优先写地址字面量。
  • 不协商、不降级：现在固定 ECDSA P-256 和固定的签名串格式，没有算法协商，保持这一点；升级是硬失败，任何「兼容旧版」的开关都要有明确的下线期限。

9.5 默认值

Agent 的 max_total_mbps 默认是 1200，对 1 核 1 GB 的小机器没有意义，却是被攻破的 Backend 能让 Agent 向某个 Probe 打出去的上限。默认值应该保守，需要的人再调高；allowed_target_cidrs 默认为空是对的。

10. 监听隐身：预握手敲门

目标：Agent 的 TCP 端口对没有完成挑战的人不写出任何字节，包括 TLS 的 ServerHello，扫描器拿不到证书和 TLS 指纹（G4）。UDP 端口本来就是静默的。

 Probe                                              Agent TCP 7443 / 7444
   │── TCP 连接 ───────────────────────────────────▶ accept（内核已完成三次握手）
   │── 敲门包 32 字节：nonce(16) │ tag(16) ─────────▶ 读 32 字节（限时 3 秒）
   │      tag = HMAC(K_pair, 时间窗 ‖ nonce)          用名册里每个 Probe 的 K_pair 逐个核对
   │                                                   ├ 合法：继续 TLS 握手 → 现有的签名认证
   │◀──────────── TLS ServerHello ─────────────────── └ 不合法或超时：什么都不发，直接断开
  • K_pair = HKDF(ECDH(Probe 身份私钥, Agent 身份公钥), "moshiro-knock-v1")：只有名册里的成员算得出；ECDH 和签名共用同一把 P-256 密钥时，用不同的 HKDF 标签做域隔离。
  • 时间窗 30 秒，接受前后各一个窗（容忍时钟偏差）；nonce 在窗内去重，防重放；每个来源地址限速，避免陌生人用随机数据消耗 HMAC 计算。
  • 这是破坏性变更：旧 Probe 不发敲门包，会被拒绝。
  • 已实现：Fleet.Identity.Knock（构造与核对）和 KnockGate（读 32 字节、名册、nonce 去重、按来源限速，默认每来源每 10 秒 300 次）；控制端口（PeerListener）和数据端口（TcpAcceptor）共用同一个关卡，Probe 一侧 PeerConnector 和 TcpLink 在 TCP 连接建立后、TLS 之前发敲门包。名册是期望状态里的 peers（Probe 的对等面公钥）。Probe 需要 Agent 的证书公钥来派生配对密钥，所以 probe_agents 下发的是 public_key（Agent 在 hello 里上报，面板自己算指纹）。陌生连接得到的是被关闭的连接（Windows 上可能表现为重置），没有任何字节。

局限，必须说清楚：TCP 的 SYN-ACK 由内核发出，用户态进程拦不住，所以端口在扫描器眼里仍是「开着，但不说话」，不是「没监听」。要做到真正的没监听，有两条路：

  • 等级二：UDP 单包授权。TCP 平时不监听；Probe 先发一个签名的 UDP 敲门包（UDP 对陌生包本来就静默），Agent 才临时开 TCP 监听几秒，并只放行敲门者的源地址。代价是每次连接多一个往返、要处理 UDP 丢包重试、多出口的 Probe 源地址可能对不上。
  • 宿主防火墙规则：需要 root，不适合小鸡节点，不做。

先做等级一，等级二作为可选。

11. extension：敏感能力的归宿

Agent 和 Probe 的核心永远是纯采集器。所有敏感能力（exec、web ssh 和终端、文件读写、抓包等）都不进核心，做成 extension，用户可选安装，默认没有。这样核心保持 NativeAOT、体积小、没有可被滥用的能力，需要这些功能的人装上，不需要的人什么都不用管，便利性不丢。

 节点主机
 ┌ 核心容器（NativeAOT，纯采集）┐      ┌ extension 容器（可选，例如 ssh）┐
 │ 身份 A：节点自己的密钥         │      │ 身份 E：自己的密钥，独立注册      │
 │ 方法：moshiro.*               │      │ 方法：ext.ssh.*                 │
 └───────────────┬──────────────┘      └───────────────┬────────────────┘
                 │ wss（节点面）                          │ wss（节点面，另一条独立的会话）
                 ▼                                       ▼
                       Backend（核心不知道 extension，extension 不能调用核心）
  • 独立进程，不是插件：extension 是单独的二进制和镜像，和核心之间没有进程内接口，核心不加载任何外部代码、不用反射和动态加载，所以核心的 NativeAOT 和「不能 exec」都不受影响。extension 自己用什么技术实现都行（可以是 NativeAOT，也可以不是）。
  • 授权只认节点的属主：每次调用的能力令牌必须由这个节点绑定的属主 passkey 签名，账户角色（owner、admin）不赋予权力；管理员只能删除节点或卸载 extension，读不到、用不了；交互式会话端到端加密。属主的设计见 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 只转发密文，不应该能读到终端里的内容。做法见 access.md 第 8.2 节：属主 passkey 授权、临时 ECDH 加 AEAD，静态数据用属主的 enc_pubkey 封装。
  • 不做的：核心里的任何 exec、文件写、加载 extension；用 extension 绕过核心的本地硬上限（extension 有它自己的上限，核心的不放宽）。

12. 实施顺序

 零  协议方向声明表 + 收发校验 + 对账测试      G7，第 8 节；同时把 NodeConnection 按职责拆开（第 13.2 节）   已完成，不破坏
 一  Probe 自己生成密钥 + 加入令牌注册 + 密钥按用途拆开    G2、G11                                        已完成，破坏性：旧 probe.json 失效
 二  预握手敲门（等级一）                        G4；先基于现有的对端公钥列表，名册出来后换成名册             已完成，破坏性：旧 Probe 被拒绝
 三  访问控制 + 入网信任链                      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）
 可选 等级二：UDP 单包授权；UDP 会话迁移的路径验证

阶段一和二是敲门的前提（双方身份密钥都由节点自己生成）。项目允许破坏性变更，当前只有三台节点，重新注册的成本很小。

13. 密码学原语与代码落点

13.1 原语现状，以及为什么不用 BLAKE3

用途 现状
身份签名 ECDSA P-256 加 SHA-256（BCL）
数据面逐包认证 HMAC-SHA256 截断到 16 字节（UdpPacket、TcpWire）
会话密钥派生 HKDF-SHA256（SessionKeys）
令牌哈希、SPKI 指纹 SHA-256
原始块完整性 CRC32C，不是密码学校验

BLAKE3 的评估（已定：不采用）：

  • 适合的位置：数据面的逐包 MAC（原生的 keyed 模式，一个原语、32 字节密钥）、KDF（derive_key 自带用途标签，比手拼 HKDF 的 info 更不容易出错）、给块做摘要再签名（第 9.1 节需要一个块摘要）。
  • 不能替换的位置：ECDSA P-256 本身用 SHA-256，令牌哈希和 SPKI 指纹也继续用 SHA-256。所以 BLAKE3 是多一个哈希族，不是换掉一个，两套原语的表面都要维护。
  • 代价：BCL 里没有；Probe 和 Agent 不引用 NuGet 包，只能在仓库里自己实现，几百行的便携实现加官方测试向量，这是要长期维护的密码学代码。托管实现没有 SHA-NI 加速，而 .NET 的 SHA-256 走系统 OpenSSL、有硬件加速，所以在 x86 上未必更快；收益主要在没有 SHA 指令的 ARM、MIPS 路由器上。
  • 结论：不采用，原语保持现状（签名 ECDSA P-256 加 SHA-256，逐包 MAC 用 HMAC-SHA256，KDF 用 HKDF-SHA256）：不增加一套要长期维护的自实现密码学代码，也不多一个哈希族。块摘要（第 9.1 节）用 SHA-256。若以后在目标硬件上实测发现逐包 MAC 是瓶颈，再单独评估，届时只替换 Fleet.Identity 里 Mac 和 Kdf 两个静态函数，调用方不动。

13.2 代码落点与分层原则

目标是每个机制只有一个落点，层数尽量少，方便维护：

  1. 一个机制，一个落点，纯函数优先：输入字节、输出判定，不引入新的接口、适配层、端口或注册。节点侧继续不用 DI。
  2. 声明和校验放在同一个项目：fleet.* 的声明表在 Fleet.Rpc，moshiro.* 的在 MoShiro.Protocol；校验统一在 RpcRouter，节点和服务端共用，这是唯一的卡口。
  3. 新代码进现有项目，不新增项目：Fleet 侧进 Identity、Rpc、Link；Backend 侧的入库检查就放在 IngestService，不为安全另建一层。
  4. 先收缩再加：NodeConnection（703 行）里混着认证、收包分发、状态推送、在线状态和帧编解码，先按职责拆成同一项目里的几个文件，再往里加方向校验；否则每加一个安全机制它就更难读。已拆：NodeConnection.cs（生命周期）、.Auth、.Receive、.Send、.State、.Wire 六个 partial 文件，原来的 729 行主文件现在 143 行。
机制 落点 调用点
方向和角色声明、收发校验 声明：Fleet.Rpc、MoShiro.Protocol；校验：RpcRouter 节点和服务端各一处创建路由器的地方
对账测试 ArchitectureTests（已有） 比对声明表和实际注册的处理器
敲门的构造与验证 Fleet.Identity 里一个静态类 服务端两处：Fleet.Link.PeerListener（7443）、Measurement.TcpAcceptor（7444）；客户端两处：PeerConnector、TcpLink
操作员凭证验签、名册 Fleet.Identity（三种凭证各一个验签函数） Fleet.Link 的 StateHandler 采用名册，用 ConfigStore 持久化版本
块和列块的签名与验签 MoShiro.Protocol/Raw（格式和签名都在这里） 签名：Probe 的列块、节点上传的原始块；验签：IngestService
归属校验 IngestService 入库的唯一入口
合理性检查 Backend.Analysis 的 EchoOps 计算指标的入口
密钥按用途拆开、Mac、Kdf Fleet.Identity 原有的使用方

14. 还没定的事

访问控制与入网信任链的细节、待确认的默认值见 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 View Git Blame Copy Permalink