Files
ssw-mpc/crates/mpc-cli/src/control_plane.rs
T
admin 3199d16515 feat(tee): TEE 远程调度面与节点自报(集群面 /3020 + 单机面 /3010)
mpc-tee 新增四层:scheduler / dispatch / reconciler / probe;
mpc-hostd 与 mpc-cli 落集群面与单机面。

- 集群面(mpc control-plane,:3020)与单机面(mpc hostd,:3010)
  两个命令、两个端口、两套暴露面,故意不合并。
- 节点自报格式复用 TeeNode::descriptor()/parse() 这一份 fail-closed 口径,
  不自写 JSON schema;JSON 只是外壳。
- 探针只答「文件在不在」这种客观事实,拿不到就 false,不猜;
  默认不自报(没 --node-platform 就不宣称有 TEE 能力)。
- 证明漂移必须立刻把旧记录从 placed 移除:只 destroy 不 remove 会让
  proven_endpoints() 继续公布证明已不通过的旧端点(真 fail-open)。
- DesiredSession.binding 优先于全局绑定,防芯片报告 user_data 跨会话重放。
- probe/reconciler 只在 std 下存在;scheduler/dispatch 是 no_std。

门禁:新增判据并入既有 gate 12(门禁仍 22 条),用假 hostd 补正向对照
(真 socket、create 成功、attestation 四布尔可控):证明 ok ⇒ 端点出现、
证明 bad ⇒ 端点收回、再 ok ⇒ 能恢复。否定式判据在「create 恒失败」链路上
恒为真(空集通过),所以必须有正向对照,否则是假绿。
2026-11-09 13:20:19 +08:00

593 lines
23 KiB
Rust
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
//! `mpc control-plane`:集群控制面(CubeMaster 等价物)的 CLI。
//!
//! # 它是什么
//!
//! 一个**进程**里同时跑两件事:
//!
//! 1. **HTTP 端点**(`mpc-hostd` 的 axum 层):收节点自报(`POST /registry`)、
//! 查注册表(`GET /nodes`)、查已证明的会话端点(`GET /sessions`)、
//! 设期望态(`POST /desired`);
//! 2. **对账长循环**(`mpc-tee::control_plane`):周期把期望态与真实态对齐 ——
//! 选址、下发 create、取证明,证明通过才把端点交给计算面。
//!
//! # 与 `mpc hostd` 的分工
//!
//! - `mpc hostd` = **单机面**(这台机器的 e2b 兼容 API:起 guest、查证明、删实例);
//! - `mpc control-plane` = **集群面**(收自报、选址、对账、公布端点)。
//!
//! 两者是不同角色、不同暴露面、不同生命周期 —— 所以是两个命令、两个端口,
//! 不合并成一个(合并后「集群面必须对所有节点可达」会把「能起 guest」那条路
//! 一起暴露出去)。
//!
//! # fail-closed
//!
//! - 注册表为空 ⇒ 对账必然失败,绝不硬塞一台;
//! - 自报解析失败 ⇒ 拒收,不写注册表;
//! - 证明不齐 ⇒ 会话端点**不**出现在 `GET /sessions`。
//!
//! ★ 诚实边界:本命令把会话**起在远端 hostd 上**(真 qemu、真证明),
//! 但「端点交给计算面后这一轮 MPC 密态会话跑通」是**上层**的事 ——
//! 本命令只保证「端点确实来自一台证明通过的 guest」。
use std::sync::Arc;
use mpc_hostd::client::HostClient;
use mpc_hostd::host_dispatch::HostDispatcher;
use mpc_tee::control_plane::{ControlPlane, ControlPlaneConfig};
use mpc_tee::reconciler::DesiredSession;
use mpc_tee::schedule::{TeeRequirement, TeeNode};
use mpc_tee::session::SessionBinding;
use mpc_tee::PlatformKind;
use crate::report;
/// 控制面命令用法。
const USAGE: &str = "用法:
mpc control-plane serve
起集群控制面(收自报 + 对账长循环)
--listen HOST:PORT (默认 127.0.0.1:3020)
--hostd-port N (节点上 hostd 的端口,用于拼 endpoint,默认 3010)
--node-ttl SECS (节点心跳 TTL,默认 90)
--reconcile-interval SECS (对账周期,默认 10)
--registry-file PATH (注册表落盘路径,不给则不落盘)
--session-id HEX (本轮会话标识,64 位十六进制)
--pubkey HEX (本轮会话公钥哈希,64 位十六进制)
--measurement HEX (本轮镜像度量,64 位十六进制)
--site NAME (本方 site 名,默认 alice)
--platform snp|csv (期望态默认平台;不给则只跑收自报/对账,不预设期望态)
--min-tcb N (期望态最低 TCB,默认 0)
--require-kbc online|offline (期望态要求的密钥代理模式,不给则不限制)
--pin HEX (期望态 pin 的镜像度量,64 位十六进制)
--shared-secret HEX (共享密钥;非回环监听时必填)
--allow-remote (非回环监听时必须显式给)
--allow-unverified-endpoint (降级:允许公布**未做芯片验签**的端点;
默认要求真芯片验签通过才公布)
mpc control-plane nodes
查集群控制面的注册表(--control-plane HOST:PORT)
mpc control-plane sessions
查集群控制面已证明通过的会话端点(--control-plane HOST:PORT)
mpc control-plane set-desired
设期望态(--control-plane HOST:PORT --desired FILE)
mpc control-plane report
查最近一轮对账结论(--control-plane HOST:PORT)";
/// `mpc control-plane` 的分派。
pub fn cmd_control_plane(args: &[String]) -> Result<(), String> {
match args.first().map(String::as_str) {
Some("serve") => cmd_serve(&args[1..]),
Some("nodes") => cmd_query(&args[1..], "/nodes"),
Some("sessions") => cmd_query(&args[1..], "/sessions"),
Some("report") => cmd_query(&args[1..], "/report"),
Some("set-desired") => cmd_set_desired(&args[1..]),
_ => Err(USAGE.to_string()),
}
}
/// 默认控制面监听地址。
const DEFAULT_CP_LISTEN: &str = "127.0.0.1:3020";
/// 解析控制面地址。
fn cp_endpoint(args: &[String]) -> Result<String, String> {
let ep = crate::parse_flag(args, "--control-plane").unwrap_or("127.0.0.1:3020");
Ok(ep.to_string())
}
/// 查控制面的一个只读端点。
fn cmd_query(args: &[String], path: &str) -> Result<(), String> {
let ep = cp_endpoint(args)?;
let client = HostClient::new(ep.clone()).map_err(|e| e.to_string())?;
let client = match crate::parse_flag(args, "--token") {
Some(t) => client.with_token(t),
None => client,
};
let v = client.get(path).map_err(|e| e.to_string())?;
let text = v.to_json_string();
match crate::json::parse(&text) {
Ok(_) => {}
Err(e) => return Err(format!("控制面响应不是合法 JSON: {e}")),
}
report::kv(
&format!("集群控制面 {path}"),
&[
("endpoint", report::Cell::txt(ep)),
("raw", report::Cell::txt(text)),
],
);
Ok(())
}
/// 设期望态(站点端 `site_admit` 的产出)。
fn cmd_set_desired(args: &[String]) -> Result<(), String> {
let ep = cp_endpoint(args)?;
let path = crate::parse_flag(args, "--desired").ok_or("缺少 --desired(期望态 JSON 文件)")?;
let body = std::fs::read_to_string(path)
.map_err(|e| format!("读期望态文件 {path} 失败: {e}"))?;
// 先本地解析一次:格式错就别去打扰控制面了。
if let Err(e) = crate::json::parse(&body) {
return Err(format!("期望态文件不是合法 JSON: {e}"));
}
let client = HostClient::new(ep.clone()).map_err(|e| e.to_string())?;
let client = match crate::parse_flag(args, "--token") {
Some(t) => client.with_token(t),
None => client,
};
client
.post("/desired", &body)
.map_err(|e| e.to_string())?;
report::kv(
"期望态已提交",
&[
("endpoint", report::Cell::txt(ep)),
("file", report::Cell::txt(path.to_string())),
],
);
Ok(())
}
/// 起集群控制面。
fn cmd_serve(args: &[String]) -> Result<(), String> {
let cfg = build_control_plane_config(args)?;
// ★ 下发实现:走各节点 hostd 的 HTTP API(与 `mpc tee up` 同一份客户端)。
// 控制面**不**自己起 guest —— 那是各节点上 hostd 的活。
let dispatch = match &cfg.shared_secret {
Some(s) => HostDispatcher::new().with_token(hex_encode(s)),
None => HostDispatcher::new(),
};
let cp = Arc::new(ControlPlane::new(
cfg.cp_config.clone(),
dispatch,
cfg.binding.clone(),
));
// ★ 期望态:给了 `--platform` 就预设一条;没给就**不设**
// (控制面先只收自报、等站点端下期望态)。
if let Some(req) = &cfg.requirement {
let desired = vec![DesiredSession::with_binding(
"s1".to_string(),
req.clone(),
cfg.binding.clone(),
)];
cp.set_desired(desired);
}
// 鉴权器(配了密钥 = 凭据模式;没配 = 回环信任模式)。
let auth = match &cfg.shared_secret {
Some(s) => mpc_hostd::auth::Authenticator::from_secret(s)
.map_err(|e| format!("共享密钥不合法: {e}"))?,
None => mpc_hostd::auth::Authenticator::unconfigured(),
};
// 对账长循环:独立线程,与 HTTP 服务共用同一个 `Arc<ControlPlane>`
// (同一份注册表 —— 两份注册表等于节点凭空消失)。
let cp_loop = Arc::clone(&cp);
std::thread::Builder::new()
.name("mpc-tee-reconciler".to_string())
.spawn(move || cp_loop.run())
.map_err(|e| format!("起对账线程失败: {e}"))?;
mpc_hostd::control_plane_server::serve_control_plane(&cfg.listen, cp, auth)
}
/// 控制面 CLI 配置(解析后的形态)。
#[derive(Debug)]
struct CpConfig {
listen: String,
cp_config: ControlPlaneConfig,
binding: SessionBinding,
requirement: Option<TeeRequirement>,
shared_secret: Option<Vec<u8>>,
}
/// 字节串 → 小写十六进制(共享密钥要按 hex 文本传给节点 hostd)。
fn hex_encode(b: &[u8]) -> String {
let mut s = String::with_capacity(b.len() * 2);
for x in b {
s.push_str(&format!("{x:02x}"));
}
s
}
/// 解析并校验控制面配置(**不**起服务 —— 便于单测)。
///
/// ★ 硬闸门(任何一道不过都**拒绝启动**,不是警告):
///
/// 1. `--session-id` / `--pubkey` / `--measurement` 三个**要么全给要么全不给**
/// —— 半套绑定等于「一半用真值、一半用猜的」;
/// 2. 绑定材料必须非全零(全零 = 会话没建立);
/// 3. 非回环监听 ⇒ 必须配共享密钥 **且** 显式 `--allow-remote`;
/// 4. 共享密钥太短 ⇒ 拒。
fn build_control_plane_config(args: &[String]) -> Result<CpConfig, String> {
let mut cp_config = ControlPlaneConfig::default();
let listen = crate::parse_flag(args, "--listen")
.unwrap_or(DEFAULT_CP_LISTEN)
.to_string();
if let Some(v) = crate::parse_flag(args, "--hostd-port") {
cp_config.hostd_port = v
.parse()
.map_err(|_| format!("--hostd-port {v:?} 不是整数"))?;
}
if let Some(v) = crate::parse_flag(args, "--node-ttl") {
cp_config.node_ttl_secs = v
.parse()
.map_err(|_| format!("--node-ttl {v:?} 不是整数"))?;
}
if let Some(v) = crate::parse_flag(args, "--reconcile-interval") {
cp_config.reconcile_period_secs = v
.parse()
.map_err(|_| format!("--reconcile-interval {v:?} 不是整数"))?;
}
if let Some(v) = crate::parse_flag(args, "--registry-file") {
cp_config.registry_file = Some(v.to_string());
}
// ★ 公布端点是否要求「真芯片验签通过」。
//
// 默认**要求**(`require_chip_sig = true`)——
// 目标就是「**真 KBS 验签后**的会话端点」。
// 只验结构 + 绑定意味着「报告里那串 user_data 对得上」,
// 而报告签名本身没人验过 —— 那只是一段自述数据。
//
// ★ 显式关掉它要写 `--allow-unverified-endpoint`(**默认关**是安全的那一侧)。
// 运维关它之前必须知道:端点的信任基础会**降一层** ——
// 那时端点只保证「结构与绑定成立」,不保证「芯片签过名」。
if args.iter().any(|a| a == "--allow-unverified-endpoint") {
cp_config.require_chip_sig = false;
}
// ★ 节点 TTL 必须大于对账周期,否则节点会在两次自报之间被剔除
// (表现为「注册表里节点时有时无」,看起来像网络问题)。
if cp_config.node_ttl_secs <= cp_config.reconcile_period_secs {
return Err(format!(
"--node-ttl {} 必须大于 --reconcile-interval {} —— 否则节点会在两次自报之间被剔除",
cp_config.node_ttl_secs, cp_config.reconcile_period_secs
));
}
let site = crate::parse_flag(args, "--site").unwrap_or("alice").to_string();
// ---- 绑定材料:要么全给要么全不给 ----
let sid = crate::parse_flag(args, "--session-id");
let pubkey = crate::parse_flag(args, "--pubkey");
let meas = crate::parse_flag(args, "--measurement");
let binding = match (sid, pubkey, meas) {
(Some(a), Some(b), Some(c)) => {
let a = parse_hex32(a, "--session-id")?;
let b = parse_hex32(b, "--pubkey")?;
let c = parse_hex32(c, "--measurement")?;
SessionBinding::new(a, site.clone(), b, c)
}
(None, None, None) => SessionBinding::new([0u8; 32], site.clone(), [0u8; 32], [0u8; 32]),
_ => {
return Err(String::from(
"--session-id / --pubkey / --measurement 三个必须**同时**给或**同时**不给 —— \
半套绑定等于一半真值一半猜测",
))
}
};
// ---- 期望态 ----
let requirement = match crate::parse_flag(args, "--platform") {
Some(p) => {
let kind = match p {
"snp" | "sev-snp" | "amd" => PlatformKind::SevSnp,
"csv" | "hygon" | "hygon-csv" => PlatformKind::HygonCsv,
other => {
return Err(format!(
"--platform {other:?} 认不出来(可用: snp / csv;其它平台尚无直接启动规格)"
))
}
};
let min_tcb: u32 = match crate::parse_flag(args, "--min-tcb") {
Some(v) => v
.parse()
.map_err(|_| format!("--min-tcb {v:?} 不是整数"))?,
None => 0,
};
let mut req = TeeRequirement::new(kind, min_tcb);
if let Some(v) = crate::parse_flag(args, "--require-kbc") {
req.required_kbc = Some(match v {
"online" | "cc_kbc" => mpc_tee::platform::KbcMode::Online,
"offline" | "offline_fs_kbc" => mpc_tee::platform::KbcMode::Offline,
other => {
return Err(format!(
"--require-kbc {other:?} 认不出来(可用: online / offline)"
))
}
});
}
if let Some(v) = crate::parse_flag(args, "--pin") {
req.pinned_measurement = Some(parse_hex32(v, "--pin")?);
}
Some(req)
}
None => None,
};
// ★ 给了期望态就必须给绑定(没绑定 ⇒ 准入必然拒「会话未建立」,
// 那样起一个永远失败的会话没有意义)。
if requirement.is_some() && !binding.has_session() {
return Err(String::from(
"给了 --platform(要预设期望态)就必须给 --session-id / --pubkey / --measurement —— \
没有会话绑定,准入会直接拒「会话未建立」",
));
}
// ---- 共享密钥与远程监听 ----
let secret = match crate::parse_flag(args, "--shared-secret") {
Some(v) => Some(v.to_string()),
None => std::env::var("MPC_HOSTD_SHARED_SECRET").ok(),
};
let shared_secret = match &secret {
Some(s) => {
if s.as_bytes().len() < mpc_hostd::auth::MIN_SECRET_LEN {
return Err(format!(
"共享密钥至少 {} 字节,当前 {} 字节",
mpc_hostd::auth::MIN_SECRET_LEN,
s.as_bytes().len()
));
}
Some(s.as_bytes().to_vec())
}
None => None,
};
if !is_loopback(&listen) {
if shared_secret.is_none() {
return Err(format!(
"{} 不是回环地址,而集群控制面没有共享密钥 —— 自报端点谁都能写,注册表就是 \
别人说了算。请配 --shared-secret(至少 {} 字节)或环境变量 MPC_HOSTD_SHARED_SECRET。",
listen,
mpc_hostd::auth::MIN_SECRET_LEN
));
}
if !args.iter().any(|a| a == "--allow-remote") {
return Err(format!(
"{} 不是回环地址。集群控制面会**下发 guest 启动**并公布已证明的会话端点,\
暴露到远程会让拿到密钥的任何人都能占机器。请显式加 --allow-remote。",
listen
));
}
}
Ok(CpConfig {
listen,
cp_config,
binding,
requirement,
shared_secret,
})
}
/// 地址是不是回环。
fn is_loopback(listen: &str) -> bool {
let host = listen.rsplit_once(':').map(|(h, _)| h).unwrap_or("");
matches!(host, "127.0.0.1" | "localhost" | "[::1]" | "::1")
}
/// 解析 32 字节十六进制。
fn parse_hex32(raw: &str, flag: &str) -> Result<[u8; 32], String> {
let s = raw.trim();
if s.len() != 64 {
return Err(format!(
"{flag} 必须是 64 位十六进制(32 字节),得到 {} 位",
s.len()
));
}
let mut out = [0u8; 32];
for (i, chunk) in s.as_bytes().chunks(2).enumerate() {
out[i] = (hex_digit(chunk[0], flag)? << 4) | hex_digit(chunk[1], flag)?;
}
Ok(out)
}
fn hex_digit(b: u8, flag: &str) -> Result<u8, String> {
match b {
b'0'..=b'9' => Ok(b - b'0'),
b'a'..=b'f' => Ok(b - b'a' + 10),
b'A'..=b'F' => Ok(b - b'A' + 10),
_ => Err(format!("{flag} 含非十六进制字符 {:?}", b as char)),
}
}
/// 把节点描述文本读出来(给「本地模拟一台节点自报」用)。
#[allow(dead_code)]
fn read_node(path: &str) -> Result<TeeNode, String> {
let src = std::fs::read_to_string(path).map_err(|e| format!("读节点描述 {path} 失败: {e}"))?;
TeeNode::parse(&src).map_err(|e| e.to_string())
}
#[cfg(test)]
mod tests {
use super::*;
fn args(v: &[&str]) -> Vec<String> {
v.iter().map(|s| String::from(*s)).collect()
}
/// ★ 正向:最小配置能过。
#[test]
fn minimal_config_is_accepted() {
let c = build_control_plane_config(&args(&[])).unwrap();
assert_eq!(c.listen, DEFAULT_CP_LISTEN);
assert!(c.requirement.is_none(), "没给 --platform 就不预设期望态");
}
/// ★ 负向:绑定材料只给一半 ⇒ 拒(不拿另一半去猜)。
#[test]
fn half_given_binding_is_rejected() {
let e = build_control_plane_config(&args(&["--session-id", &"01".repeat(32)]))
.unwrap_err();
assert!(e.contains("同时"), "{e}");
}
/// ★ 负向:绑定材料长度不对 ⇒ 拒。
#[test]
fn bad_binding_length_is_rejected() {
let e = build_control_plane_config(&args(&[
"--session-id",
"01",
"--pubkey",
&"02".repeat(32),
"--measurement",
&"03".repeat(32),
]))
.unwrap_err();
assert!(e.contains("--session-id"), "{e}");
}
/// ★ 负向:给了期望态却没给绑定 ⇒ 拒(那必然准入失败)。
#[test]
fn desired_without_binding_is_rejected() {
let e = build_control_plane_config(&args(&["--platform", "snp"])).unwrap_err();
assert!(e.contains("绑定"), "{e}");
}
/// ★ 负向:非回环监听且没密钥 ⇒ 拒。
#[test]
fn remote_listen_without_secret_is_rejected() {
let e = build_control_plane_config(&args(&["--listen", "0.0.0.0:3020"])).unwrap_err();
assert!(e.contains("共享密钥"), "{e}");
}
/// ★ 负向:非回环监听 + 有密钥但没 `--allow-remote` ⇒ 拒。
#[test]
fn remote_listen_without_allow_remote_is_rejected() {
let e = build_control_plane_config(&args(&[
"--listen",
"0.0.0.0:3020",
"--shared-secret",
&"ab".repeat(32),
]))
.unwrap_err();
assert!(e.contains("--allow-remote"), "{e}");
}
/// ★ 正向:非回环 + 密钥 + `--allow-remote` ⇒ 过。
#[test]
fn remote_listen_with_secret_and_flag_is_accepted() {
let c = build_control_plane_config(&args(&[
"--listen",
"0.0.0.0:3020",
"--shared-secret",
&"ab".repeat(32),
"--allow-remote",
]))
.unwrap();
assert_eq!(c.listen, "0.0.0.0:3020");
assert!(c.shared_secret.is_some());
}
/// ★ 负向:共享密钥太短 ⇒ 拒。
#[test]
fn short_secret_is_rejected() {
let e = build_control_plane_config(&args(&["--shared-secret", "abc"])).unwrap_err();
assert!(e.contains("字节"), "{e}");
}
/// ★ 正向:默认**要求**真芯片验签才公布端点。
///
/// 这条钉死「默认是安全的那一侧」——
/// 默认 `require_chip_sig=false` 的话,端点会在**没人验过签名**的情况下
/// 被公布出去,而那正是「真 KBS 验签后的会话端点」这条主线的反面。
#[test]
fn chip_sig_is_required_by_default() {
let c = build_control_plane_config(&args(&[])).unwrap();
assert!(
c.cp_config.require_chip_sig,
"默认必须要求芯片验签(真 KBS 验签后才公布端点)"
);
}
/// ★ 负向(策略面):`--allow-unverified-endpoint` 才允许降级。
///
/// 关掉它意味着端点的信任基础**降一层**(只保证结构与绑定成立),
/// 所以必须**显式**声明,不能靠某个默认值碰巧。
#[test]
fn allow_unverified_endpoint_opts_out_explicitly() {
let c = build_control_plane_config(&args(&["--allow-unverified-endpoint"])).unwrap();
assert!(
!c.cp_config.require_chip_sig,
"显式给了 --allow-unverified-endpoint 才允许降级"
);
}
/// ★ 负向:平台认不出来 ⇒ 拒(不猜一个能跑的)。
#[test]
fn unknown_platform_is_rejected() {
let e = build_control_plane_config(&args(&[
"--platform",
"tdx-weird",
"--session-id",
&"01".repeat(32),
"--pubkey",
&"02".repeat(32),
"--measurement",
&"03".repeat(32),
]))
.unwrap_err();
assert!(e.contains("--platform"), "{e}");
}
/// ★ 负向:TTL ≤ 对账周期 ⇒ 拒(节点会在两次自报之间被剔除)。
#[test]
fn ttl_not_greater_than_interval_is_rejected() {
let e = build_control_plane_config(&args(&[
"--node-ttl",
"10",
"--reconcile-interval",
"10",
]))
.unwrap_err();
assert!(e.contains("--node-ttl"), "{e}");
}
/// ★ 正向:完整绑定 + 期望态 ⇒ 过,且绑定被原样带出。
#[test]
fn full_binding_and_requirement_are_carried_verbatim() {
let c = build_control_plane_config(&args(&[
"--platform",
"snp",
"--min-tcb",
"5",
"--session-id",
&"01".repeat(32),
"--pubkey",
&"02".repeat(32),
"--measurement",
&"09".repeat(32),
"--require-kbc",
"offline",
"--pin",
&"09".repeat(32),
]))
.unwrap();
let r = c.requirement.expect("必须预设期望态");
assert_eq!(r.platform, PlatformKind::SevSnp);
assert_eq!(r.min_tcb, 5);
assert_eq!(r.required_kbc, Some(mpc_tee::platform::KbcMode::Offline));
assert_eq!(r.pinned_measurement, Some([9u8; 32]));
assert_eq!(c.binding.code_measurement, [9u8; 32]);
assert!(c.binding.has_session());
}
}