//! `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 { 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` // (同一份注册表 —— 两份注册表等于节点凭空消失)。 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, shared_secret: Option>, } /// 字节串 → 小写十六进制(共享密钥要按 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 { 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 { 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 { 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 { 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()); } }