diff --git a/Cargo.lock b/Cargo.lock index 458b6000aa..47659b9289 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -4379,6 +4379,7 @@ dependencies = [ "prost-types", "rcgen", "reqwest 0.12.28", + "russh", "rustls", "serde", "serde_json", diff --git a/crates/openshell-cli/Cargo.toml b/crates/openshell-cli/Cargo.toml index 18c0b84099..c0ab40524a 100644 --- a/crates/openshell-cli/Cargo.toml +++ b/crates/openshell-cli/Cargo.toml @@ -95,6 +95,7 @@ futures = { workspace = true } openshell-server = { path = "../openshell-server", features = ["test-support"] } rcgen = { workspace = true } reqwest = { workspace = true } +russh = "0.65.0" serde_json = { workspace = true } temp-env = "0.3" tokio-stream = { workspace = true } diff --git a/crates/openshell-cli/src/main.rs b/crates/openshell-cli/src/main.rs index 8bcf8f00f3..8d8b4df287 100644 --- a/crates/openshell-cli/src/main.rs +++ b/crates/openshell-cli/src/main.rs @@ -21,6 +21,7 @@ use openshell_cli::completers; use openshell_cli::run; use openshell_cli::tls::TlsOptions; use openshell_core::proto::{GpuResourceRequirements, ServiceAuthorizationMode}; +use openshell_core::ssh_host_key::{HostKeyCheck, HostKeyExpectation, KnownHostsPin}; /// Resolved gateway context: name + gateway endpoint. struct GatewayContext { @@ -664,10 +665,12 @@ enum Commands { /// Two mutually exclusive modes: /// /// **Token mode** (used internally by `sandbox connect`): - /// `openshell ssh-proxy --gateway --sandbox --token ` + /// `openshell ssh-proxy --gateway --sandbox --token + /// --host-key --known-hosts ` /// /// **Name mode** (for use in `~/.ssh/config`): - /// `openshell ssh-proxy --gateway --name ` + /// `openshell ssh-proxy --gateway --name + /// --known-hosts ` #[command(hide = true, help_template = LEAF_HELP_TEMPLATE, next_help_heading = "FLAGS")] SshProxy { /// Gateway URL (e.g., ). @@ -694,6 +697,17 @@ enum Commands { /// Sandbox name. Used in name mode. #[arg(long)] name: Option, + + /// SSH host key the sandbox must present: the fingerprint the gateway + /// published, or `unverified`. Token mode only; name mode asks the + /// gateway instead. + #[arg(long, requires = "known_hosts", conflicts_with = "name")] + host_key: Option, + + /// Known-hosts file in which the verified host key is pinned for `ssh`. + /// Without it the host key is not verified. + #[arg(long)] + known_hosts: Option, }, } @@ -3723,7 +3737,7 @@ async fn run_async() -> Result<()> { } SandboxCommands::SshConfig { name } => { let name = resolve_sandbox_name(name, &ctx.name, &cli.workspace)?; - run::print_ssh_config(&ctx.name, &name, &cli.workspace); + run::print_ssh_config(&ctx.name, &name, &cli.workspace)?; } SandboxCommands::Provider(command) => match command { SandboxProviderCommands::List { @@ -4179,10 +4193,33 @@ async fn run_async() -> Result<()> { server, gateway_name, name, + host_key, + known_hosts, }) => { match (gateway, sandbox, token, server, gateway_name, name) { // Token mode (existing behavior): pre-created session credentials. (Some(gw), Some(sandbox), Some(tok), _, gateway_name_opt, _) => { + let host_key = match (host_key, known_hosts) { + (Some(expectation), Some(known_hosts)) => Some( + KnownHostsPin::at(known_hosts, &sandbox, &cli.workspace) + .and_then(|pin| HostKeyCheck::for_relay(expectation, pin)) + .map_err(|err| miette::miette!("{err}"))?, + ), + // The `ssh` of such a client accepts any host key. + (None, None) => { + eprintln!( + "openshell: warning: this SSH connection was started by an OpenShell client that predates host-key verification, so the SSH host key is NOT verified.\n\ + Restart that client (the openshell command or openshell term)." + ); + None + } + // Nothing would pin a key for the `ssh` that reads the file. + _ => { + return Err(miette::miette!( + "--known-hosts requires --host-key when --token is given" + )); + } + }; let mut effective_tls = match gateway_name_opt { Some(ref g) => tls.with_gateway_name(g), None => tls, @@ -4190,8 +4227,15 @@ async fn run_async() -> Result<()> { if let Some(ref g) = gateway_name_opt { apply_auth(&mut effective_tls, g)?; } - run::sandbox_ssh_proxy(&gw, &sandbox, &cli.workspace, &tok, &effective_tls) - .await?; + run::sandbox_ssh_proxy( + &gw, + &sandbox, + &cli.workspace, + &tok, + &effective_tls, + host_key, + ) + .await?; } // Name mode with --gateway-name: resolve endpoint from metadata. (_, _, _, server_override, Some(g), Some(n)) => { @@ -4209,11 +4253,27 @@ async fn run_async() -> Result<()> { }; let mut tls = tls.with_gateway_name(&g); apply_auth(&mut tls, &g)?; - run::sandbox_ssh_proxy_by_name(&endpoint, &n, &tls, &cli.workspace).await?; + run::sandbox_ssh_proxy_by_name( + &endpoint, + Some(&g), + &n, + &tls, + &cli.workspace, + known_hosts, + ) + .await?; } // Legacy name mode with --server only (no --gateway-name). (_, _, _, Some(srv), None, Some(n)) => { - run::sandbox_ssh_proxy_by_name(&srv, &n, &tls, &cli.workspace).await?; + run::sandbox_ssh_proxy_by_name( + &srv, + None, + &n, + &tls, + &cli.workspace, + known_hosts, + ) + .await?; } _ => { return Err(miette::miette!( @@ -5131,6 +5191,10 @@ mod tests { "tok-abc", "--gateway-name", "my-gateway", + "--host-key", + "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA", + "--known-hosts", + "/home/u/.config/openshell/known_hosts/my-gateway/openshell-my-box.team-a", ]) .expect("TUI proxy command flags must be accepted by the CLI"); assert_eq!(cli.workspace, "team-a"); diff --git a/crates/openshell-cli/src/ssh.rs b/crates/openshell-cli/src/ssh.rs index 5eb6738ddd..d0f368ae85 100644 --- a/crates/openshell-cli/src/ssh.rs +++ b/crates/openshell-cli/src/ssh.rs @@ -14,12 +14,17 @@ use miette::{IntoDiagnostic, Report, Result, WrapErr}; use nix::sys::signal::Signal; use openshell_core::driver_mounts; use openshell_core::forward::{ - ForwardSpec, build_proxy_command, format_gateway_url, resolve_ssh_gateway, sandbox_ssh_args, - shell_escape, validate_ssh_session_response, write_forward_pid, + ForwardSpec, SandboxProxyCommand, format_gateway_url, resolve_ssh_gateway, + sandbox_proxy_command, sandbox_ssh_args, shell_escape, validate_ssh_session_response, + write_forward_pid, }; use openshell_core::proto::{ - CreateSshSessionRequest, GetSandboxRequest, SandboxPhase, SshRelayTarget, TcpForwardFrame, - TcpForwardInit, tcp_forward_init, + CreateSshSessionRequest, CreateSshSessionResponse, GetSandboxRequest, SandboxPhase, + SshRelayTarget, TcpForwardFrame, TcpForwardInit, tcp_forward_init, +}; +use openshell_core::ssh_host_key::{ + HostKeyCheck, HostKeyExpectation, HostKeyGate, KnownHostsPin, SandboxSshTarget, + host_key_alias as host_alias, }; use openshell_core::upload::{ DestinationKind as UploadDestinationKind, ExpectedDestination, UploadPlan, @@ -104,22 +109,25 @@ impl Editor { } struct SshSessionConfig { - proxy_command: String, + proxy_command: SandboxProxyCommand, sandbox_id: String, - sandbox_name: String, - gateway_url: String, - token: String, main_terminal: bool, +} + +struct CreatedSshSession { + response: CreateSshSessionResponse, + gateway_url: String, replica: Option, + main_terminal: bool, } -async fn ssh_session_config( +async fn create_ssh_session( server: &str, name: &str, tls: &TlsOptions, workspace: &str, terminal_relay_registration_timeout: Option, -) -> Result { +) -> Result { let mut client = grpc_client(server, tls).await?; // Resolve the sandbox and retain its ID for local lifecycle tracking. @@ -165,11 +173,6 @@ async fn ssh_session_config( validate_ssh_session_response(&session) .map_err(|err| miette::miette!("gateway returned invalid SSH session response: {err}"))?; - let exe = std::env::current_exe() - .into_diagnostic() - .wrap_err("failed to resolve OpenShell executable")?; - let exe_command = exe.to_string_lossy().into_owned(); - // When using Cloudflare bearer auth, the SSH CONNECT must go through the // external tunnel endpoint (the cluster URL), not the server's internal // scheme/host/port which may be plaintext HTTP on 127.0.0.1. @@ -189,30 +192,62 @@ async fn ssh_session_config( ); format_gateway_url(&gateway_scheme, &gateway_host, gateway_port) }; + + Ok(CreatedSshSession { + response: session, + gateway_url, + replica, + main_terminal: sandbox.spec.as_ref().is_none_or(|spec| spec.tty), + }) +} + +async fn ssh_session_config( + server: &str, + name: &str, + tls: &TlsOptions, + workspace: &str, + terminal_relay_registration_timeout: Option, +) -> Result { + let session = create_ssh_session( + server, + name, + tls, + workspace, + terminal_relay_registration_timeout, + ) + .await?; + + let exe = std::env::current_exe() + .into_diagnostic() + .wrap_err("failed to resolve OpenShell executable")?; let gateway_name = tls .gateway_name() .ok_or_else(|| miette::miette!("gateway name is required to build SSH proxy command"))?; - let proxy_command = build_proxy_command( - &exe_command, - &gateway_url, - name, + let target = SandboxSshTarget { + gateway: gateway_name, workspace, - &session.token, - gateway_name, + sandbox: name, + }; + let host_key = HostKeyCheck::for_session(&session.response, &target).into_diagnostic()?; + if let Some(warning) = host_key.unverified_warning(name) { + eprintln!("{warning}"); + } + let proxy_command = sandbox_proxy_command( + &exe.to_string_lossy(), + &session.gateway_url, + &target, + &session.response.token, + host_key, ); Ok(SshSessionConfig { proxy_command, - sandbox_id: session.sandbox_id.clone(), - sandbox_name: name.to_string(), - gateway_url, - token: session.token, - main_terminal: sandbox.spec.as_ref().is_none_or(|spec| spec.tty), - replica, + sandbox_id: session.response.sandbox_id, + main_terminal: session.main_terminal, }) } -fn ssh_base_command(proxy_command: &str) -> Command { +fn ssh_base_command(proxy_command: &SandboxProxyCommand) -> Command { // An explicit environment override wins over the CLI verbosity default. let ssh_log_level = std::env::var("OPENSHELL_SSH_LOG_LEVEL").unwrap_or_else(|_| { DEFAULT_SSH_LOG_LEVEL @@ -820,7 +855,11 @@ pub async fn sandbox_forward( /// A forward must stay owned by the process we spawn so it can be reaped or /// tracked by PID. User SSH config may otherwise fork it into the background. -fn ssh_forward_command(proxy_command: &str, sandbox_id: &str, spec: &ForwardSpec) -> Command { +fn ssh_forward_command( + proxy_command: &SandboxProxyCommand, + sandbox_id: &str, + spec: &ForwardSpec, +) -> Command { let mut command = ssh_base_command(proxy_command); command .arg("-o") @@ -1314,7 +1353,7 @@ async fn ssh_tar_upload( /// Upload EOF marks a complete archive and the SSH exit status reports /// extraction, so the session must stay in the process we spawn. User SSH /// config may otherwise fork it into the background. -fn ssh_upload_command(proxy_command: &str) -> Command { +fn ssh_upload_command(proxy_command: &SandboxProxyCommand) -> Command { let mut command = ssh_base_command(proxy_command); command .arg("-o") @@ -1955,13 +1994,15 @@ async fn sandbox_sync_down_directory( stream_sandbox_tar(session, tar_cmd, dest_path).await } -/// Run the SSH proxy, connecting stdin/stdout to the gateway. +/// Run the SSH proxy, connecting stdin/stdout to the gateway. Without +/// `host_key`, the sandbox's host key is not checked. pub async fn sandbox_ssh_proxy( gateway_url: &str, sandbox_name: &str, workspace: &str, token: &str, tls: &TlsOptions, + host_key: Option, ) -> Result<()> { let server = grpc_server_from_ssh_gateway_url(gateway_url)?; let mut client = grpc_client(&server, tls).await?; @@ -1976,7 +2017,15 @@ pub async fn sandbox_ssh_proxy( .await .ok() .and_then(|response| owner_replica(&response)); - relay_ssh_proxy(client, sandbox_name, workspace, token, replica.as_ref()).await + relay_ssh_proxy( + client, + sandbox_name, + workspace, + token, + replica.as_ref(), + host_key.map(HostKeyCheck::into_gate), + ) + .await } async fn relay_ssh_proxy( @@ -1985,6 +2034,7 @@ async fn relay_ssh_proxy( workspace: &str, token: &str, replica: Option<&AsciiMetadataValue>, + mut gate: Option, ) -> Result<()> { let init = TcpForwardFrame { payload: Some(openshell_core::proto::tcp_forward_frame::Payload::Init( @@ -2052,6 +2102,17 @@ async fn relay_ssh_proxy( else { continue; }; + let data = match gate.as_mut().map(|gate| gate.push(&data)) { + None => data, + Some(Ok(released)) => released, + Some(Err(refusal)) => { + // Printed rather than returned: ssh passes this text to the + // user as is, and a returned error would be reformatted as + // a report. + eprintln!("openshell: {refusal}"); + std::process::exit(1) + } + }; if data.is_empty() { continue; } @@ -2112,43 +2173,90 @@ fn grpc_server_from_ssh_gateway_url(gateway_url: &str) -> Result { /// and sandbox name instead of pre-created gateway/token credentials. It is /// suitable for use as an SSH `ProxyCommand` in `~/.ssh/config` because it /// creates a fresh session on every invocation. +/// +/// `known_hosts` is the pin file the config entry also names as its +/// `UserKnownHostsFile`. An entry without it predates host-key verification +/// and tells `ssh` to accept any host key: it keeps working, with a warning. +/// `gateway_name` is the gateway the entry names, when it names one. pub async fn sandbox_ssh_proxy_by_name( server: &str, + gateway_name: Option<&str>, name: &str, tls: &TlsOptions, workspace: &str, + known_hosts: Option, ) -> Result<()> { - let session = ssh_session_config(server, name, tls, workspace, None).await?; + let session = create_ssh_session(server, name, tls, workspace, None).await?; + let gate = if let Some(known_hosts) = known_hosts { + let expectation = + HostKeyExpectation::from_published(&session.response.host_key_fingerprint) + .into_diagnostic()?; + let pin = KnownHostsPin::at(known_hosts, name, workspace).into_diagnostic()?; + let host_key = HostKeyCheck::for_relay(expectation, pin).into_diagnostic()?; + if let Some(warning) = host_key.unverified_warning(name) { + eprintln!("{warning}"); + } + Some(host_key.into_gate()) + } else { + eprintln!( + "{}", + stale_ssh_config_warning(gateway_name, workspace, name) + ); + None + }; let server = grpc_server_from_ssh_gateway_url(&session.gateway_url)?; let client = grpc_client(&server, tls).await?; relay_ssh_proxy( client, - &session.sandbox_name, + name, workspace, - &session.token, + &session.response.token, session.replica.as_ref(), + gate, ) .await } -fn host_alias(name: &str, workspace: &str) -> String { - format!("openshell-{name}.{workspace}") +fn stale_ssh_config_warning(gateway: Option<&str>, workspace: &str, sandbox: &str) -> String { + let gateway = gateway.map_or_else(String::new, |gateway| { + format!(" -g {}", shell_escape(gateway)) + }); + let openshell = format!("openshell{gateway} --workspace {}", shell_escape(workspace)); + let name = shell_escape(sandbox); + format!( + "openshell: warning: this SSH config entry for sandbox '{sandbox}' (workspace '{workspace}') predates host-key verification, so the SSH host key is NOT verified.\n\ + Regenerate it: {openshell} sandbox connect {name} --editor vscode\n\ + Or replace the entry with the output of: {openshell} sandbox ssh-config {name}" + ) } -fn render_ssh_config(gateway: &str, name: &str, workspace: &str) -> String { +fn render_ssh_config(gateway: &str, name: &str, workspace: &str) -> Result { let exe = std::env::current_exe().expect("failed to resolve OpenShell executable"); let exe = shell_escape(&exe.to_string_lossy()); + let pin = KnownHostsPin::for_target(&SandboxSshTarget { + gateway, + workspace, + sandbox: name, + }) + .into_diagnostic()?; let proxy_cmd = format!( - "{exe} ssh-proxy --gateway-name {} --name {} --workspace {}", + "{exe} ssh-proxy --gateway-name {} --name {} --workspace {} --known-hosts {}", shell_escape(gateway), shell_escape(name), shell_escape(workspace), + shell_escape(&pin.ssh_path()), ); let host_alias = host_alias(name, workspace); - format!( - "Host {host_alias}\n User sandbox\n StrictHostKeyChecking no\n UserKnownHostsFile /dev/null\n GlobalKnownHostsFile /dev/null\n LogLevel ERROR\n ServerAliveInterval 15\n ServerAliveCountMax 3\n ProxyCommand {proxy_cmd}\n" - ) + let options = pin + .ssh_options() + .into_iter() + .map(|(key, value)| format!(" {key} {value}")) + .collect::>() + .join("\n"); + Ok(format!( + "Host {host_alias}\n User sandbox\n{options}\n ControlMaster no\n ControlPath none\n ControlPersist no\n LogLevel ERROR\n ServerAliveInterval 15\n ServerAliveCountMax 3\n ProxyCommand {proxy_cmd}\n" + )) } fn openshell_ssh_config_path() -> Result { @@ -2272,6 +2380,7 @@ fn upsert_host_block(contents: &str, alias: &str, block: &str) -> String { } pub fn install_ssh_config(gateway: &str, name: &str, workspace: &str) -> Result { + let block = render_ssh_config(gateway, name, workspace)?; let managed_config = openshell_ssh_config_path()?; let main_config = user_ssh_config_path()?; ensure_openshell_include(&main_config, &managed_config)?; @@ -2281,7 +2390,6 @@ pub fn install_ssh_config(gateway: &str, name: &str, workspace: &str) -> Result< } let alias = host_alias(name, workspace); - let block = render_ssh_config(gateway, name, workspace); let contents = fs::read_to_string(&managed_config).unwrap_or_default(); let updated = upsert_host_block(&contents, &alias, &block); fs::write(&managed_config, updated) @@ -2334,8 +2442,9 @@ fn launch_editor_command( /// The `ProxyCommand` uses `--gateway-name` so that `ssh-proxy` resolves the /// gateway endpoint and TLS certificates from the gateway metadata directory /// (`~/.config/openshell/gateways//mtls/`). -pub fn print_ssh_config(gateway: &str, name: &str, workspace: &str) { - print!("{}", render_ssh_config(gateway, name, workspace)); +pub fn print_ssh_config(gateway: &str, name: &str, workspace: &str) -> Result<()> { + print!("{}", render_ssh_config(gateway, name, workspace)?); + Ok(()) } #[cfg(test)] @@ -2351,7 +2460,7 @@ mod tests { environment.run(|| { set_default_ssh_log_level("DEBUG"); let expected = override_level.unwrap_or("DEBUG"); - let command = ssh_base_command("openshell ssh-tunnel"); + let command = ssh_base_command(&pinned_proxy("known_hosts").0); assert!( command .get_args() @@ -2467,6 +2576,25 @@ mod tests { use crate::TEST_ENV_LOCK; use crate::test_utils::Environment; + const PUBLISHED_FINGERPRINT: &str = "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA"; + + /// A proxy command for sandbox `demo`, and the file under `directory` in + /// which its host key is pinned. + fn pinned_proxy(directory: &str) -> (SandboxProxyCommand, PathBuf) { + let dir = tempfile::tempdir().unwrap(); + let known_hosts = dir.path().join(directory).join("openshell-demo.default"); + let target = SandboxSshTarget { + gateway: "prod", + workspace: "default", + sandbox: "demo", + }; + let pin = KnownHostsPin::at(known_hosts.clone(), "demo", "default").unwrap(); + let host_key = + HostKeyCheck::for_relay(PUBLISHED_FINGERPRINT.parse().unwrap(), pin).unwrap(); + let proxy = sandbox_proxy_command("openshell", "https://gw:443", &target, "tok", host_key); + (proxy, known_hosts) + } + #[test] fn upsert_host_block_appends_when_missing() { let input = "Host existing\n HostName example.com\n"; @@ -2557,13 +2685,9 @@ mod tests { async move { if setup { let session = SshSessionConfig { - proxy_command: String::new(), + proxy_command: pinned_proxy("known_hosts").0, sandbox_id: String::new(), - sandbox_name: String::new(), - gateway_url: String::new(), - token: String::new(), main_terminal: false, - replica: None, }; return ssh_run_capture_stdout(&session, "unused").await.map(|_| ()); } @@ -2795,18 +2919,66 @@ mod tests { } #[test] - fn render_ssh_config_includes_workspace_in_proxy_command() { - let config = render_ssh_config("my-gw", "demo", "beta"); - assert!( - config.contains("Host openshell-demo.beta"), - "host alias should be workspace-qualified: {config}" - ); - assert!( - config.contains("--workspace beta"), - "ProxyCommand should include --workspace: {config}" + fn stale_ssh_config_warning_names_the_gateway_and_workspace_of_the_entry() { + assert_eq!( + stale_ssh_config_warning(Some("my gw"), "beta", "demo"), + "openshell: warning: this SSH config entry for sandbox 'demo' (workspace 'beta') predates host-key verification, so the SSH host key is NOT verified.\n\ + Regenerate it: openshell -g 'my gw' --workspace beta sandbox connect demo --editor vscode\n\ + Or replace the entry with the output of: openshell -g 'my gw' --workspace beta sandbox ssh-config demo" ); } + /// `ssh` resolves the rendered block to the intended options, also when + /// the pin path needs quoting and a later block enables connection sharing. + #[cfg(unix)] + #[test] + fn rendered_ssh_config_makes_ssh_trust_only_the_pin() { + let home = tempfile::tempdir().unwrap(); + crate::test_utils::with_tmp_xdg(&home.path().join("o'brien config home"), |config_home| { + let known_hosts = config_home + .join("openshell/known_hosts/my-gw/openshell-demo.beta") + .display() + .to_string(); + let config = config_home.join("rendered_ssh_config"); + fs::create_dir_all(config_home).unwrap(); + let user_sharing = format!( + "Host *\n ControlMaster auto\n ControlPath \"{}/mux-%C\"\n ControlPersist yes\n", + config_home.display() + ); + fs::write( + &config, + render_ssh_config("my-gw", "demo", "beta").unwrap() + &user_sharing, + ) + .unwrap(); + + let output = Command::new("ssh") + .arg("-F") + .arg(&config) + .args(["-G", "openshell-demo.beta"]) + .output() + .unwrap(); + let effective = String::from_utf8(output.stdout).unwrap(); + + assert_only_the_pin_is_trusted( + &effective, + Path::new(&known_hosts), + "openshell-demo.beta", + ); + assert_connection_sharing_disabled(&effective); + let proxy_command = effective + .lines() + .find_map(|line| line.strip_prefix("proxycommand ")) + .unwrap(); + assert!( + proxy_command.ends_with(&format!( + " ssh-proxy --gateway-name my-gw --name demo --workspace beta --known-hosts {}", + shell_escape(&known_hosts) + )), + "{proxy_command}" + ); + }); + } + #[test] fn host_alias_includes_workspace() { assert_eq!(host_alias("demo", "default"), "openshell-demo.default"); @@ -2871,8 +3043,10 @@ mod tests { fs::write( &config, format!( - "Host sandbox\n ControlMaster auto\n ControlPath {}/mux-%C\n ControlPersist yes\n ForkAfterAuthentication yes\n", - dir.path().display() + "Host sandbox\n ControlMaster auto\n ControlPath {dir}/mux-%C\n ControlPersist yes\n ForkAfterAuthentication yes\n \ + StrictHostKeyChecking no\n UserKnownHostsFile /dev/null\n GlobalKnownHostsFile {dir}/global_known_hosts\n \ + HostKeyAlias another-host\n HostKeyAlgorithms rsa-sha2-512\n VerifyHostKeyDNS yes\n UpdateHostKeys yes\n", + dir = dir.path().display() ), ) .unwrap(); @@ -2904,22 +3078,42 @@ mod tests { ); } + #[cfg(unix)] + fn assert_only_the_pin_is_trusted(effective: &str, known_hosts: &Path, alias: &str) { + for option in [ + "stricthostkeychecking true", + &format!("userknownhostsfile {}", known_hosts.display()), + "globalknownhostsfile /dev/null", + &format!("hostkeyalias {alias}"), + "hostkeyalgorithms ssh-ed25519", + "verifyhostkeydns false", + "updatehostkeys false", + ] { + assert!(effective.lines().any(|line| line == option), "{option}"); + } + } + #[cfg(unix)] #[test] - fn ssh_base_command_overrides_user_connection_sharing() { - let effective = - effective_ssh_config(&ssh_base_command("openshell ssh-proxy"), &["-N", "sandbox"]); - assert_connection_sharing_disabled(&effective); + fn ssh_base_command_overrides_user_connection_sharing_and_host_key_trust() { + for directory in [ + "known_hosts", + "known hosts", + "o'brien known=hosts", + "100% #1", + ] { + let (proxy, known_hosts) = pinned_proxy(directory); + let effective = effective_ssh_config(&ssh_base_command(&proxy), &["-N", "sandbox"]); + assert_connection_sharing_disabled(&effective); + assert_only_the_pin_is_trusted(&effective, &known_hosts, "openshell-demo.default"); + } } #[cfg(unix)] #[test] fn forward_ssh_command_overrides_user_multiplexing_and_forking() { - let forward = ssh_forward_command( - "openshell ssh-proxy --sandbox demo", - "sandbox-id", - &ForwardSpec::new(18080), - ); + let (proxy, _) = pinned_proxy("known_hosts"); + let forward = ssh_forward_command(&proxy, "sandbox-id", &ForwardSpec::new(18080)); let effective = effective_ssh_config(&forward, &[]); assert_connection_sharing_disabled(&effective); assert!( @@ -2932,7 +3126,7 @@ mod tests { #[cfg(unix)] #[test] fn upload_ssh_command_overrides_user_multiplexing_and_forking() { - let upload = ssh_upload_command("openshell ssh-proxy --sandbox demo"); + let upload = ssh_upload_command(&pinned_proxy("known_hosts").0); let effective = effective_ssh_config(&upload, &[]); assert_connection_sharing_disabled(&effective); for expected in [ diff --git a/crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs b/crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs index 8e7c0b190f..df3cb8b923 100644 --- a/crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs +++ b/crates/openshell-cli/tests/sandbox_create_lifecycle_integration.rs @@ -58,6 +58,8 @@ fn selected_workspace( } } +const PUBLISHED_HOST_KEY: &str = "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA"; + #[derive(Clone, Default)] struct SandboxState { /// Make `ListProviderProfiles` fail while every other RPC keeps working, @@ -508,6 +510,7 @@ impl OpenShell for TestOpenShell { gateway_scheme: "https".to_string(), gateway_host: "localhost".to_string(), gateway_port: 443, + host_key_fingerprint: PUBLISHED_HOST_KEY.to_string(), ..CreateSshSessionResponse::default() })) } @@ -1319,6 +1322,22 @@ fn install_fake_ssh(dir: &TempDir) -> std::path::PathBuf { install_executable_script(dir, "ssh", "#!/bin/sh\nexit 0\n") } +/// A fake `ssh` that answers the workspace probe and records its arguments, +/// one per line, in the returned file. Also installs a fake `code`. +fn install_recording_ssh(dir: &TempDir) -> std::path::PathBuf { + let arguments = dir.path().join("ssh-arguments"); + install_executable_script( + dir, + "ssh", + format!( + "#!/bin/sh\nprintf '%s\\n' \"$@\" > '{}'\nprintf '/sandbox\\n'\n", + arguments.display() + ), + ); + install_executable_script(dir, "code", "#!/bin/sh\nexit 0\n"); + arguments +} + fn install_fake_pgrep_no_match(dir: &TempDir) -> std::path::PathBuf { install_executable_script(dir, "pgrep", "#!/bin/sh\nexit 1\n") } @@ -3303,6 +3322,43 @@ async fn sandbox_forward_background_tracks_owned_child_when_pid_discovery_fails( .await; } +#[tokio::test] +async fn editor_connect_hands_ssh_the_published_host_key_and_its_pin() { + let server = run_server().await; + let fake_ssh_dir = helpers::tempdir().unwrap(); + let xdg_dir = helpers::tempdir().unwrap(); + + test_env(&fake_ssh_dir, &xdg_dir) + .run_async(async { + let tls = test_tls(&server); + let ssh_arguments = install_recording_ssh(&fake_ssh_dir); + let pin = xdg_dir + .path() + .join("openshell/known_hosts/openshell/openshell-pinned.default"); + + run::sandbox_connect_editor( + &server.endpoint, + "openshell", + "pinned", + run::Editor::Vscode, + &tls, + "default", + ) + .await + .unwrap(); + + let ssh_arguments = fs::read_to_string(ssh_arguments).unwrap(); + let pin = pin.display(); + for expected in [ + format!(" --host-key '{PUBLISHED_HOST_KEY}' --known-hosts {pin}\n"), + format!("\nUserKnownHostsFile=\"{pin}\"\n"), + ] { + assert!(ssh_arguments.contains(&expected), "{ssh_arguments}"); + } + }) + .await; +} + #[tokio::test] #[ignore = "flaky under concurrent test execution"] async fn sandbox_forward_foreground_fails_when_ssh_exits_before_listener_opens() { diff --git a/crates/openshell-cli/tests/ssh_proxy_host_key_integration.rs b/crates/openshell-cli/tests/ssh_proxy_host_key_integration.rs new file mode 100644 index 0000000000..68c88a38db --- /dev/null +++ b/crates/openshell-cli/tests/ssh_proxy_host_key_integration.rs @@ -0,0 +1,595 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +use bytes::Bytes; +use http_body_util::{BodyExt, StreamBody}; +use hyper::body::{Frame, Incoming}; +use hyper::service::service_fn; +use hyper_util::rt::{TokioExecutor, TokioIo}; +use openshell_core::proto::{ + CreateSshSessionResponse, Sandbox, SandboxResponse, TcpForwardFrame, tcp_forward_frame, +}; +use prost::Message; +use russh::keys::ssh_key::private::Ed25519Keypair; +use russh::keys::{HashAlg, PrivateKey}; +use std::convert::Infallible; +use std::net::SocketAddr; +use std::path::Path; +use std::process::{Output, Stdio}; +use std::sync::Arc; +use std::time::Duration; +use tokio::io::{AsyncReadExt, AsyncWriteExt, DuplexStream}; +use tokio_stream::wrappers::ReceiverStream; + +const SANDBOX: &str = "my-sb"; +const WORKSPACE: &str = "team-a"; +const PIN_HEADER: &str = + "# Managed by OpenShell. Rewritten from the gateway-published fingerprint; do not edit.\n"; + +type GrpcFrames = tokio::sync::mpsc::Sender, Infallible>>; +type GrpcBody = StreamBody, Infallible>>>; + +fn host_key(seed: u8) -> PrivateKey { + PrivateKey::from(Ed25519Keypair::from_seed(&[seed; 32])) +} + +fn fingerprint(key: &PrivateKey) -> String { + key.public_key().fingerprint(HashAlg::Sha256).to_string() +} + +/// The pin file `ssh-proxy` leaves behind: holding `key`, or no key at all. +fn pin_content(key: Option<&PrivateKey>) -> String { + key.map_or_else( + || PIN_HEADER.to_string(), + |key| { + format!( + "{PIN_HEADER}openshell-{SANDBOX}.{WORKSPACE} {}\n", + key.public_key().to_openssh().unwrap() + ) + }, + ) +} + +/// A gateway that publishes one host-key fingerprint for the sandbox and +/// relays every SSH connection to `sandbox`. +struct Gateway { + published: String, + sandbox: Box, +} + +impl Gateway { + async fn serve(self) -> SocketAddr { + let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap(); + let address = listener.local_addr().unwrap(); + let gateway = Arc::new(self); + tokio::spawn(async move { + while let Ok((socket, _)) = listener.accept().await { + openshell_core::net::set_tcp_nodelay_best_effort(&socket); + let gateway = gateway.clone(); + let service = service_fn(move |request| { + let gateway = gateway.clone(); + async move { Ok::<_, Infallible>(gateway.respond(request, address).await) } + }); + tokio::spawn(async move { + let _ = hyper::server::conn::http2::Builder::new(TokioExecutor::new()) + .serve_connection(TokioIo::new(socket), service) + .await; + }); + } + }); + address + } + + async fn respond( + &self, + request: hyper::Request, + address: SocketAddr, + ) -> hyper::Response { + let (frames, body) = tokio::sync::mpsc::channel(16); + match request.uri().path() { + "/openshell.v1.OpenShell/GetSandbox" => { + let found = SandboxResponse { + sandbox: Some(Sandbox::default()), + ..Default::default() + }; + respond_once(&frames, &found).await; + } + "/openshell.v1.OpenShell/CreateSshSession" => { + let session = CreateSshSessionResponse { + sandbox_id: "sandbox-1".to_string(), + token: "test-token".to_string(), + gateway_host: address.ip().to_string(), + gateway_port: u32::from(address.port()), + gateway_scheme: "http".to_string(), + host_key_fingerprint: self.published.clone(), + ..Default::default() + }; + respond_once(&frames, &session).await; + } + "/openshell.v1.OpenShell/ForwardTcp" => { + let (relay_end, sandbox_end) = tokio::io::duplex(64 * 1024); + (self.sandbox)(sandbox_end); + tokio::spawn(relay(request.into_body(), relay_end, frames)); + } + _ => {} + } + let mut response = hyper::Response::new(StreamBody::new(ReceiverStream::new(body))); + response + .headers_mut() + .insert("content-type", "application/grpc".parse().unwrap()); + response + } +} + +fn grpc_message(message: &impl Message) -> Frame { + let encoded = message.encode_to_vec(); + let mut framed = vec![0]; + framed.extend_from_slice(&u32::try_from(encoded.len()).unwrap().to_be_bytes()); + framed.extend_from_slice(&encoded); + Frame::data(framed.into()) +} + +fn grpc_status(status: tonic::Status) -> Frame { + Frame::trailers(status.into_http::<()>().into_parts().0.headers) +} + +async fn respond_once(frames: &GrpcFrames, message: &impl Message) { + let _ = frames.send(Ok(grpc_message(message))).await; + let _ = frames.send(Ok(grpc_status(tonic::Status::ok("")))).await; +} + +/// Copies `ForwardTcp` data frames to the sandbox and the sandbox's bytes back. +async fn relay(mut inbound: Incoming, sandbox: DuplexStream, frames: GrpcFrames) { + let (mut from_sandbox, mut to_sandbox) = tokio::io::split(sandbox); + let to_sandbox = tokio::spawn(async move { + let mut pending = Vec::new(); + while let Some(Ok(frame)) = inbound.frame().await { + let Ok(data) = frame.into_data() else { + continue; + }; + pending.extend_from_slice(&data); + while let Some(length) = pending + .get(1..5) + .map(|length| u32::from_be_bytes(length.try_into().unwrap()) as usize) + .filter(|length| pending.len() >= 5 + length) + { + let frame = TcpForwardFrame::decode(&pending[5..5 + length]).unwrap(); + pending.drain(..5 + length); + if let Some(tcp_forward_frame::Payload::Data(data)) = frame.payload + && to_sandbox.write_all(&data).await.is_err() + { + return; + } + } + } + let _ = to_sandbox.shutdown().await; + }); + // Smaller than any key exchange packet, so the proxy has to reassemble + // each one. + let mut chunk = [0_u8; 97]; + while let Ok(read @ 1..) = from_sandbox.read(&mut chunk).await { + let frame = TcpForwardFrame { + payload: Some(tcp_forward_frame::Payload::Data(chunk[..read].to_vec())), + }; + if frames.send(Ok(grpc_message(&frame))).await.is_err() { + break; + } + } + let _ = frames.send(Ok(grpc_status(tonic::Status::ok("")))).await; + to_sandbox.abort(); +} + +/// The `ssh-proxy` arguments of a generated config entry. +fn name_mode(gateway: SocketAddr, known_hosts: &Path) -> String { + let known_hosts = known_hosts.display(); + format!("{} --known-hosts {known_hosts}", old_name_mode(gateway)) +} + +/// The same, as releases before host-key verification generated them. +fn old_name_mode(gateway: SocketAddr) -> String { + format!("ssh-proxy --server http://{gateway} --name {SANDBOX} --workspace {WORKSPACE}") +} + +/// Runs `command` to completion. +async fn finished(mut command: tokio::process::Command, config: &Path) -> Output { + let run = command + .env("XDG_CONFIG_HOME", config) + .env("OPENSHELL_TELEMETRY_ENABLED", "false") + .env_remove("OPENSHELL_GATEWAY") + .env_remove("OPENSHELL_GATEWAY_ENDPOINT") + .env_remove("OPENSHELL_WORKSPACE") + .stdin(Stdio::null()) + .kill_on_drop(true) + .output(); + tokio::time::timeout(Duration::from_secs(30), run) + .await + .expect("the command must exit") + .unwrap() +} + +/// Runs `openshell` with `args`, which are separated by single spaces. +async fn openshell(args: &str, config: &Path) -> Output { + let mut command = tokio::process::Command::new(env!("CARGO_BIN_EXE_openshell")); + command.args(args.split(' ')); + finished(command, config).await +} + +fn mismatch_message(published: &PrivateKey, presented: &PrivateKey) -> String { + format!( + "openshell: SSH host key mismatch for sandbox '{SANDBOX}' (workspace '{WORKSPACE}')\n \ + gateway published: {}\n \ + server presented: {}\n\ + The SSH server reached through the gateway is not this sandbox's. The handshake was not forwarded.\n\ + Do not connect. Compare the published value with `openshell --workspace {WORKSPACE} sandbox get {SANDBOX} --output json`, then stop and start the sandbox.\n\ + If the mismatch persists, contact the gateway operator.\n", + fingerprint(published), + fingerprint(presented) + ) +} + +/// What an SSH server presenting `key` sends: up to its key exchange reply, +/// then from the reply to its first encrypted bytes. The proxy does not check +/// block alignment, so every packet has four bytes of padding. +fn handshake(key: &PrivateKey) -> [Vec; 2] { + let packet = |payload: &[u8]| { + let length = u32::try_from(payload.len() + 5).unwrap().to_be_bytes(); + [&length[..], &[4], payload, &[0; 4]].concat() + }; + let key = key.public_key().to_bytes().unwrap(); + let key_length = u32::try_from(key.len()).unwrap().to_be_bytes(); + let reply = [&[31][..], &key_length, &key, &[0; 127]].concat(); + [ + [ + &b"SSH-2.0-OpenShell_test\r\n"[..], + &packet(&[&[20][..], &[0; 61]].concat()), + ] + .concat(), + [packet(&reply), packet(&[21]), vec![0xff; 48]].concat(), + ] +} + +/// A sandbox whose SSH server sends `bytes` and hangs up. +fn sending(bytes: Vec) -> Box { + Box::new(move |mut stream| { + let bytes = bytes.clone(); + tokio::spawn(async move { + let _ = stream.write_all(&bytes).await; + }); + }) +} + +#[tokio::test] +async fn name_mode_proxy_withholds_a_key_the_gateway_did_not_publish() { + let published = host_key(1); + let presented = host_key(2); + let [before_reply, reply_onward] = handshake(&presented); + let gateway = Gateway { + published: fingerprint(&published), + sandbox: sending([before_reply.clone(), reply_onward].concat()), + } + .serve() + .await; + let scratch = tempfile::tempdir().unwrap(); + let pin = scratch.path().join("known_hosts/pin"); + + let proxy = openshell(&name_mode(gateway, &pin), scratch.path()).await; + + let stderr = String::from_utf8_lossy(&proxy.stderr); + assert_eq!(proxy.status.code(), Some(1), "{stderr}"); + assert!( + before_reply.starts_with(&proxy.stdout), + "no byte of the key exchange reply may reach ssh" + ); + assert!( + stderr.contains(&mismatch_message(&published, &presented)), + "{stderr}" + ); + assert_eq!(std::fs::read_to_string(&pin).unwrap(), pin_content(None)); +} + +/// A gateway that predates sandbox SSH identities publishes nothing. +#[tokio::test] +async fn name_mode_proxy_warns_and_relays_when_the_gateway_published_no_key() { + let key = host_key(1); + let transcript = handshake(&key).concat(); + let gateway = Gateway { + published: String::new(), + sandbox: sending(transcript.clone()), + } + .serve() + .await; + let scratch = tempfile::tempdir().unwrap(); + let pin = scratch.path().join("known_hosts/pin"); + + let proxy = openshell(&name_mode(gateway, &pin), scratch.path()).await; + + let stderr = String::from_utf8_lossy(&proxy.stderr); + assert!(proxy.status.success(), "{stderr}"); + assert_eq!(proxy.stdout, transcript); + assert!( + stderr.contains("warning: SSH host key of sandbox 'my-sb' is NOT verified"), + "{stderr}" + ); + assert_eq!( + std::fs::read_to_string(&pin).unwrap(), + pin_content(Some(&key)) + ); +} + +/// An `ssh` started by a client or a config entry from before host-key +/// verification accepts any key. It keeps working, and is told so. +#[tokio::test] +async fn proxy_warns_and_relays_for_a_caller_that_predates_host_key_verification() { + let transcript = handshake(&host_key(2)).concat(); + let gateway = Gateway { + published: fingerprint(&host_key(1)), + sandbox: sending(transcript.clone()), + } + .serve() + .await; + let scratch = tempfile::tempdir().unwrap(); + let old_client = format!( + "ssh-proxy --gateway http://{gateway}/proxy/connect --sandbox {SANDBOX} --workspace {WORKSPACE} --token test-token" + ); + + for (args, caller) in [ + (old_client, "started by an OpenShell client that predates"), + ( + old_name_mode(gateway), + "SSH config entry for sandbox 'my-sb'", + ), + ] { + let proxy = openshell(&args, scratch.path()).await; + + let stderr = String::from_utf8_lossy(&proxy.stderr); + assert!(proxy.status.success(), "{stderr}"); + assert_eq!(proxy.stdout, transcript); + assert!(stderr.contains(caller), "{stderr}"); + assert!( + stderr.contains("the SSH host key is NOT verified"), + "{stderr}" + ); + } +} + +/// The real `ssh` client against a real SSH server, with `ssh-proxy` as its +/// `ProxyCommand`. +#[cfg(unix)] +mod openssh { + use super::*; + use openshell_core::forward::{sandbox_proxy_command, sandbox_ssh_args}; + use openshell_core::ssh_host_key::{HostKeyCheck, KnownHostsPin, SandboxSshTarget}; + use russh::server::{Auth, ChannelOpenHandle, Msg, Session}; + use russh::{Channel, ChannelId}; + + const COMMAND: &str = "report-ready"; + const COMMAND_OUTPUT: &str = "ready\n"; + const GATEWAY: &str = "test-gateway"; + + fn write_pin(pin: &Path, content: &str) { + std::fs::create_dir_all(pin.parent().unwrap()).unwrap(); + std::fs::write(pin, content).unwrap(); + } + + /// Accepts every login and answers every command with [`COMMAND_OUTPUT`]. + struct Shell; + + impl russh::server::Handler for Shell { + type Error = russh::Error; + + async fn auth_none(&mut self, _user: &str) -> Result { + Ok(Auth::Accept) + } + + async fn channel_open_session( + &mut self, + _channel: Channel, + reply: ChannelOpenHandle, + _session: &mut Session, + ) -> Result<(), Self::Error> { + reply.accept().await; + Ok(()) + } + + async fn exec_request( + &mut self, + channel: ChannelId, + _data: &[u8], + session: &mut Session, + ) -> Result<(), Self::Error> { + session.channel_success(channel)?; + session.data(channel, COMMAND_OUTPUT)?; + session.exit_status_request(channel, 0)?; + session.eof(channel)?; + session.close(channel)?; + Ok(()) + } + } + + /// The gateway in front of a sandbox whose SSH server presents `key`. + async fn sandbox_presenting(key: &PrivateKey) -> SocketAddr { + // The supervisor's server also keeps the default algorithms. + let config = Arc::new(russh::server::Config { + keys: vec![key.clone()], + ..Default::default() + }); + Gateway { + published: fingerprint(key), + sandbox: Box::new(move |stream| { + let config = config.clone(); + tokio::spawn(async move { + if let Ok(session) = russh::server::run_stream(config, stream, Shell).await { + let _ = session.await; + } + }); + }), + } + .serve() + .await + } + + /// Runs [`COMMAND`] with the `ssh` arguments the CLI and TUI build for + /// a session whose published fingerprint is `published`. `ssh` takes + /// the first value of an option, so `overrides` win. + async fn ssh_as_client( + gateway: SocketAddr, + published: &str, + pin: &Path, + config: &Path, + overrides: &[String], + ) -> Output { + let target = SandboxSshTarget { + gateway: GATEWAY, + workspace: WORKSPACE, + sandbox: SANDBOX, + }; + let pin = KnownHostsPin::at(pin.to_path_buf(), SANDBOX, WORKSPACE).unwrap(); + let host_key = HostKeyCheck::for_relay(published.parse().unwrap(), pin).unwrap(); + let proxy_command = sandbox_proxy_command( + env!("CARGO_BIN_EXE_openshell"), + &format!("http://{gateway}"), + &target, + "test-token", + host_key, + ); + let mut ssh = tokio::process::Command::new("ssh"); + ssh.args(["-F", "/dev/null", "-o", "BatchMode=yes"]) + .args(overrides.iter().flat_map(|option| ["-o", option])) + .args(sandbox_ssh_args(&proxy_command, "ERROR")) + .args(["sandbox", COMMAND]); + finished(ssh, config).await + } + + /// Runs [`COMMAND`] through the config entry `sandbox ssh-config` + /// prints, with no other configuration and no options of its own. + async fn ssh_through_config_entry(gateway: SocketAddr, config: &Path) -> Output { + let gateway_dir = config.join("openshell/gateways").join(GATEWAY); + std::fs::create_dir_all(&gateway_dir).unwrap(); + let metadata = serde_json::json!({ + "name": GATEWAY, + "gateway_endpoint": format!("http://{gateway}"), + "gateway_port": gateway.port(), + "is_remote": false, + "auth_mode": "plaintext", + }); + std::fs::write(gateway_dir.join("metadata.json"), metadata.to_string()).unwrap(); + + let print_entry = + format!("--gateway {GATEWAY} --workspace {WORKSPACE} sandbox ssh-config {SANDBOX}"); + let printed = openshell(&print_entry, config).await; + assert!( + printed.status.success(), + "{}", + String::from_utf8_lossy(&printed.stderr) + ); + let entry = config.join("ssh_config_entry"); + std::fs::write(&entry, printed.stdout).unwrap(); + + let mut ssh = tokio::process::Command::new("ssh"); + ssh.arg("-F") + .arg(entry) + .args(["-o", "BatchMode=yes"]) + .args([format!("openshell-{SANDBOX}.{WORKSPACE}").as_str(), COMMAND]); + finished(ssh, config).await + } + + /// The proxy accepts and forwards any key here, so the refusal is `ssh`'s + /// own strict check against a file the proxy does not write. + #[tokio::test] + async fn ssh_refuses_a_key_missing_from_its_own_known_hosts_file() { + let key = host_key(1); + let gateway = sandbox_presenting(&key).await; + let scratch = tempfile::tempdir().unwrap(); + let proxy_pin = scratch.path().join("known_hosts/proxy"); + let ssh_pin = scratch.path().join("known_hosts/ssh"); + let another_key = pin_content(Some(&host_key(2))); + write_pin(&ssh_pin, &another_key); + + let ssh = ssh_as_client( + gateway, + "unverified", + &proxy_pin, + scratch.path(), + &[format!("UserKnownHostsFile=\"{}\"", ssh_pin.display())], + ) + .await; + + let stderr = String::from_utf8_lossy(&ssh.stderr); + assert_eq!(ssh.status.code(), Some(255), "{stderr}"); + assert!(stderr.contains("Host key verification failed"), "{stderr}"); + assert_eq!(ssh.stdout, b""); + assert_eq!( + std::fs::read_to_string(&proxy_pin).unwrap(), + pin_content(Some(&key)), + "the proxy forwarded the key exchange reply" + ); + assert_eq!(std::fs::read_to_string(&ssh_pin).unwrap(), another_key); + } + + /// `ssh` is already running when the proxy pins the key, so this holds + /// only because `ssh` reads its known-hosts file when it processes the key + /// exchange reply, not when it starts. Host-key verification rests on it. + /// The `%` is one `ssh` would expand in the path it is given. + #[tokio::test] + async fn ssh_with_the_client_arguments_reaches_the_published_sandbox() { + let key = host_key(1); + let gateway = sandbox_presenting(&key).await; + let scratch = tempfile::tempdir().unwrap(); + let pin = scratch.path().join("100% known_hosts/pin"); + + let ssh = ssh_as_client(gateway, &fingerprint(&key), &pin, scratch.path(), &[]).await; + + let stderr = String::from_utf8_lossy(&ssh.stderr); + assert!(ssh.status.success(), "{stderr}"); + assert_eq!(String::from_utf8_lossy(&ssh.stdout), COMMAND_OUTPUT); + assert_eq!( + std::fs::read_to_string(&pin).unwrap(), + pin_content(Some(&key)) + ); + } + + #[tokio::test] + async fn ssh_with_the_client_arguments_never_reaches_another_server() { + let presented = host_key(1); + let published = host_key(2); + let gateway = sandbox_presenting(&presented).await; + let scratch = tempfile::tempdir().unwrap(); + let pin = scratch.path().join("known_hosts/pin"); + + let ssh = ssh_as_client(gateway, &fingerprint(&published), &pin, scratch.path(), &[]).await; + + let stderr = String::from_utf8_lossy(&ssh.stderr); + assert_eq!(ssh.status.code(), Some(255), "{stderr}"); + assert!( + stderr.contains(&mismatch_message(&published, &presented)), + "{stderr}" + ); + assert_eq!(ssh.stdout, b""); + assert_eq!(std::fs::read_to_string(&pin).unwrap(), pin_content(None)); + } + + /// The pin still holds the stale key when `ssh` starts, so this holds only + /// because the proxy replaces it before `ssh` reads the file. + #[tokio::test] + async fn ssh_connects_through_the_generated_config_entry_despite_a_stale_pin() { + let key = host_key(1); + let gateway = sandbox_presenting(&key).await; + let scratch = tempfile::tempdir().unwrap(); + let config = scratch.path().join("100% config"); + let pin = config + .join("openshell/known_hosts") + .join(GATEWAY) + .join(format!("openshell-{SANDBOX}.{WORKSPACE}")); + write_pin(&pin, &pin_content(Some(&host_key(2)))); + + let ssh = ssh_through_config_entry(gateway, &config).await; + + let stderr = String::from_utf8_lossy(&ssh.stderr); + assert!(ssh.status.success(), "{stderr}"); + assert_eq!(String::from_utf8_lossy(&ssh.stdout), COMMAND_OUTPUT); + assert_eq!( + std::fs::read_to_string(&pin).unwrap(), + pin_content(Some(&key)) + ); + } +} diff --git a/crates/openshell-core/src/forward.rs b/crates/openshell-core/src/forward.rs index c8e6c10131..f99efed0a5 100644 --- a/crates/openshell-core/src/forward.rs +++ b/crates/openshell-core/src/forward.rs @@ -7,6 +7,7 @@ //! start, stop, list, and track background SSH port forwards. use crate::paths::{create_dir_restricted, xdg_config_dir}; +use crate::ssh_host_key::{HostKeyCheck, SandboxSshTarget}; use miette::{IntoDiagnostic, Result, WrapErr}; use std::borrow::Cow; use std::net::TcpListener; @@ -364,7 +365,7 @@ fn proxy_command_option_present(args: &[&str], proxy_index: usize) -> bool { fn proxy_option_takes_value(arg: &str) -> bool { matches!( arg, - "--gateway" | "--workspace" | "--token" | "--gateway-name" + "--gateway" | "--workspace" | "--token" | "--gateway-name" | "--host-key" | "--known-hosts" ) } @@ -928,7 +929,7 @@ pub fn shell_escape(value: &str) -> String { /// Every interpolated argument is shell-escaped so that server-supplied values /// (gateway URL, sandbox name, workspace, token, gateway name) cannot inject shell /// metacharacters into the command that OpenSSH executes via `/bin/sh -c`. -pub fn build_proxy_command( +fn build_proxy_command( exe: &str, gateway_url: &str, sandbox_name: &str, @@ -947,23 +948,57 @@ pub fn build_proxy_command( ) } +/// The `ProxyCommand` of a sandbox SSH connection, with the host-key decision +/// it was built with. +pub struct SandboxProxyCommand { + command: String, + host_key: HostKeyCheck, +} + +/// Build the `ProxyCommand` that tunnels `ssh` to a sandbox and checks the +/// host key the sandbox presents. +pub fn sandbox_proxy_command( + exe: &str, + gateway_url: &str, + target: &SandboxSshTarget<'_>, + token: &str, + host_key: HostKeyCheck, +) -> SandboxProxyCommand { + let mut command = build_proxy_command( + exe, + gateway_url, + target.sandbox, + target.workspace, + token, + target.gateway, + ); + for flag in host_key.proxy_flags() { + command.push(' '); + command.push_str(&shell_escape(&flag)); + } + SandboxProxyCommand { command, host_key } +} + /// Build the `ssh` options shared by every sandbox session. /// /// Every sandbox is addressed as the host `sandbox`, so a user's `ControlMaster` /// or `ControlPath` would reuse one sandbox's connection for another. Command /// line options beat `ssh_config`, so connection sharing is turned off here. -pub fn sandbox_ssh_args(proxy_command: &str, log_level: &str) -> Vec { +pub fn sandbox_ssh_args(proxy: &SandboxProxyCommand, log_level: &str) -> Vec { + let host_key_options = proxy + .host_key + .ssh_options() + .into_iter() + .map(|(key, value)| format!("{key}={value}")); [ - format!("ProxyCommand={proxy_command}"), - "StrictHostKeyChecking=no".to_string(), - "UserKnownHostsFile=/dev/null".to_string(), - "GlobalKnownHostsFile=/dev/null".to_string(), + format!("ProxyCommand={}", proxy.command), format!("LogLevel={log_level}"), "ControlMaster=no".to_string(), "ControlPath=none".to_string(), "ControlPersist=no".to_string(), ] .into_iter() + .chain(host_key_options) .flat_map(|option| ["-o".to_string(), option]) .collect() } @@ -1015,7 +1050,7 @@ fn is_fingerprint_byte(b: u8) -> bool { /// Validate a `CreateSshSessionResponse` before any of its fields are used to /// build a shell command or config file. /// -/// This is a belt-and-suspenders pair to [`build_proxy_command`]: escaping +/// This is a belt-and-suspenders pair to [`sandbox_proxy_command`]: escaping /// alone is sufficient to prevent injection, but rejecting malformed fields /// at the trust boundary fails loudly before the string is assembled and /// catches gateway bugs or tampering early. @@ -1107,6 +1142,7 @@ pub fn build_sandbox_notes( #[cfg(test)] mod tests { use super::*; + use crate::ssh_host_key::KnownHostsPin; use crate::test_environment::Environment; #[test] @@ -1394,9 +1430,25 @@ mod tests { ); } + const HOST_KEY_FINGERPRINT: &str = "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA"; + + fn sandbox_proxy(exe: &str, known_hosts: &std::path::Path) -> SandboxProxyCommand { + let target = SandboxSshTarget { + gateway: "local", + workspace: "team-a", + sandbox: "sbx-1", + }; + let pin = + KnownHostsPin::at(known_hosts.to_path_buf(), target.sandbox, target.workspace).unwrap(); + let host_key = HostKeyCheck::for_relay(HOST_KEY_FINGERPRINT.parse().unwrap(), pin).unwrap(); + sandbox_proxy_command(exe, "https://127.0.0.1:9443", &target, "tok_123", host_key) + } + #[test] fn sandbox_ssh_args_disable_connection_sharing() { - let args = sandbox_ssh_args("openshell ssh-proxy", "DEBUG"); + let dir = tempfile::tempdir().unwrap(); + let proxy = sandbox_proxy("openshell", &dir.path().join("pin")); + let args = sandbox_ssh_args(&proxy, "DEBUG"); let options: Vec<&str> = args .chunks(2) .map(|pair| { @@ -1404,7 +1456,7 @@ mod tests { pair[1].as_str() }) .collect(); - assert!(options.contains(&"ProxyCommand=openshell ssh-proxy")); + assert!(options[0].starts_with("ProxyCommand=openshell ssh-proxy ")); assert!(options.contains(&"LogLevel=DEBUG")); for option in ["ControlMaster=no", "ControlPath=none", "ControlPersist=no"] { assert!(options.contains(&option), "missing {option}"); @@ -1790,6 +1842,29 @@ mod tests { )); } + #[test] + fn ssh_forward_command_matches_generated_host_key_flags() { + let dir = tempfile::tempdir().unwrap(); + let proxy = sandbox_proxy("/path/openshell", &dir.path().join("pin")); + let mut argv = vec!["/usr/bin/ssh".to_string()]; + argv.extend(sandbox_ssh_args(&proxy, "ERROR")); + argv.extend(["-N", "-L", "80:127.0.0.1:80", "sandbox"].map(str::to_string)); + let line = argv.join(" "); + + assert!(command_matches_ssh_forward( + &line, + 80, + Some("team-a"), + Some("sbx-1") + )); + assert!(!command_matches_ssh_forward( + &line, + 80, + Some("team-b"), + Some("sbx-1") + )); + } + #[test] fn split_proxy_command_words_round_trips_shell_escape() { assert_eq!(split_proxy_command_words("a b c"), vec!["a", "b", "c"]); diff --git a/crates/openshell-core/src/lib.rs b/crates/openshell-core/src/lib.rs index 12473a702c..5c48ea056b 100644 --- a/crates/openshell-core/src/lib.rs +++ b/crates/openshell-core/src/lib.rs @@ -66,6 +66,7 @@ pub mod secrets; pub mod settings; pub mod shell; pub mod spiffe; +pub mod ssh_host_key; pub mod telemetry; pub mod time; pub mod token_grant_failure; diff --git a/crates/openshell-core/src/ssh_host_key.rs b/crates/openshell-core/src/ssh_host_key.rs new file mode 100644 index 0000000000..be9efc9624 --- /dev/null +++ b/crates/openshell-core/src/ssh_host_key.rs @@ -0,0 +1,1234 @@ +// SPDX-FileCopyrightText: Copyright (c) 2025-2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +//! SSH host-key verification for sandbox connections. +//! +//! The fingerprint the gateway publishes is the authority. A per-sandbox +//! `known_hosts` file is a cache that must hash to that fingerprint, and `ssh` +//! enforces it with `StrictHostKeyChecking=yes`. This module owns the +//! fingerprint format, the pin location and file format, the `ssh` options, +//! the `ssh-proxy` flags, and the scan of the server's key exchange reply. + +use std::fmt; +use std::fs; +use std::io::{self, Write as _}; +use std::path::{MAIN_SEPARATOR, Path, PathBuf}; +use std::str::FromStr; +use std::sync::atomic::{AtomicU64, Ordering}; + +use base64::Engine as _; +use base64::engine::general_purpose::{STANDARD, STANDARD_NO_PAD}; + +use crate::forward::shell_escape; +use crate::proto::CreateSshSessionResponse; + +const FINGERPRINT_PREFIX: &str = "SHA256:"; +const UNVERIFIED: &str = "unverified"; +const HOST_KEY_ALGORITHM: &str = "ssh-ed25519"; +const PIN_HEADER: &str = + "# Managed by OpenShell. Rewritten from the gateway-published fingerprint; do not edit.\n"; +/// `string "ssh-ed25519"`, then the length prefix of the 32-byte key. +const ED25519_BLOB_PREFIX: &[u8] = b"\0\0\0\x0bssh-ed25519\0\0\0\x20"; +const ED25519_KEY_LEN: usize = 32; +/// The longest identification line of RFC 4253, with its line ending. Every +/// `ssh` release reads a line this short whole; older ones split a longer one. +const MAX_BANNER_LINE_LEN: usize = 255; +/// The padding length byte plus one payload byte, up to the largest packet +/// `ssh` accepts. +const PACKET_LENGTHS: std::ops::RangeInclusive = 2..=262_144; +const MSG_KEXINIT: u8 = 20; +const KEXINIT_COOKIE_LEN: usize = 16; +const KEXINIT_NAME_LISTS: usize = 10; +const MSG_NEWKEYS: u8 = 21; +/// The key exchange reply of every method but group exchange, where it is the +/// group instead. +const MSG_KEX_REPLY: u8 = 31; +const MSG_KEX_GEX_REPLY: u8 = 33; + +static TEMP_FILE_SEQUENCE: AtomicU64 = AtomicU64::new(0); + +/// SHA-256 of an SSH public key blob. Text form: `SHA256:` followed by 43 +/// characters of unpadded standard base64. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub struct HostKeyFingerprint([u8; 32]); + +impl FromStr for HostKeyFingerprint { + type Err = HostKeyError; + + fn from_str(s: &str) -> Result { + s.strip_prefix(FINGERPRINT_PREFIX) + .and_then(|encoded| STANDARD_NO_PAD.decode(encoded).ok()) + .and_then(|digest| <[u8; 32]>::try_from(digest).ok()) + .map(Self) + .ok_or(HostKeyError::BadFingerprint) + } +} + +impl fmt::Display for HostKeyFingerprint { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + write!(f, "{FINGERPRINT_PREFIX}{}", STANDARD_NO_PAD.encode(self.0)) + } +} + +impl HostKeyFingerprint { + /// Hashes the blob exactly as it appears in the server's key exchange + /// reply and in a `known_hosts` line. + pub fn of_blob(blob: &[u8]) -> Result { + openshell_crypto::sha256(blob) + .map(Self) + .map_err(|err| HostKeyError::Crypto(err.to_string())) + } +} + +/// What `ssh-proxy` must see before it forwards the server's key exchange +/// reply. Text form: a fingerprint, or `unverified`. +#[derive(Clone, Copy, PartialEq, Eq, Debug)] +pub enum HostKeyExpectation { + Fingerprint(HostKeyFingerprint), + /// Only when the gateway published nothing. + AcceptAny, +} + +impl FromStr for HostKeyExpectation { + type Err = HostKeyError; + + fn from_str(s: &str) -> Result { + if s == UNVERIFIED { + Ok(Self::AcceptAny) + } else { + s.parse().map(Self::Fingerprint) + } + } +} + +impl fmt::Display for HostKeyExpectation { + fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result { + match self { + Self::Fingerprint(fingerprint) => fingerprint.fmt(f), + Self::AcceptAny => f.write_str(UNVERIFIED), + } + } +} + +impl HostKeyExpectation { + /// Interprets the fingerprint field of a gateway response. A gateway + /// that predates sandbox SSH identities leaves it empty. + pub fn from_published(published: &str) -> Result { + if published.is_empty() { + Ok(Self::AcceptAny) + } else { + published.parse().map(Self::Fingerprint) + } + } +} + +#[derive(Debug, thiserror::Error)] +pub enum HostKeyError { + #[error("SSH host key fingerprint is not 'SHA256:' followed by 43 unpadded base64 characters")] + BadFingerprint, + #[error( + "SSH host key mismatch for sandbox '{sandbox}' (workspace '{workspace}')\n \ + gateway published: {expected}\n \ + server presented: {presented}\n\ + The SSH server reached through the gateway is not this sandbox's. The handshake was not forwarded.\n\ + Do not connect. Compare the published value with `openshell --workspace {} sandbox get {} --output json`, then stop and start the sandbox.\n\ + If the mismatch persists, contact the gateway operator.", + shell_escape(.workspace), + shell_escape(.sandbox) + )] + Mismatch { + sandbox: String, + workspace: String, + expected: HostKeyFingerprint, + presented: HostKeyFingerprint, + }, + #[error("malformed SSH stream from the sandbox: {0}")] + Malformed(&'static str), + #[error( + "SSH known-hosts path '{}' cannot be used: it must be absolute, be built from plain gateway, \ + sandbox and workspace names, and contain no '\"', '\\', \"${{\" or newline", + .0.display() + )] + UnusablePath(PathBuf), + #[error("SSH known-hosts file: {0}")] + Io(#[from] io::Error), + #[error("SSH host key fingerprint could not be computed: {0}")] + Crypto(String), +} + +/// The sandbox an SSH connection is for. Keys the pin file. +#[derive(Clone, Copy, Debug)] +pub struct SandboxSshTarget<'a> { + pub gateway: &'a str, + pub workspace: &'a str, + pub sandbox: &'a str, +} + +/// `openshell-.`: the `Host` alias of a generated SSH +/// config block, the `HostKeyAlias` of every connection, and the host field of +/// the pin line. +pub fn host_key_alias(sandbox: &str, workspace: &str) -> String { + format!("openshell-{sandbox}.{workspace}") +} + +/// One `known_hosts` file holding at most one key line for one alias. +#[derive(Debug)] +pub struct KnownHostsPin { + path: PathBuf, + sandbox: String, + workspace: String, +} + +impl KnownHostsPin { + /// `/known_hosts//`, with the gateway + /// name flattened to one directory name. + pub fn for_target(target: &SandboxSshTarget<'_>) -> Result { + let config_dir = crate::paths::openshell_config_dir() + .map_err(|err| io::Error::other(err.to_string()))?; + Self::under(&std::path::absolute(config_dir)?, target) + } + + /// The `ssh-proxy` side: the path the `ssh` invocation or config block + /// handed over. + pub fn at(path: PathBuf, sandbox: &str, workspace: &str) -> Result { + // `ssh` expands `${VAR}` in UserKnownHostsFile and has no escape for + // it, a quote or newline would end the value early, and a backslash + // escapes the character after it. Where the backslash separates path + // components, rejecting it would reject every path. + let expands_or_breaks = |text: &str| { + text.contains(['"', '\n']) + || text.contains("${") + || (MAIN_SEPARATOR != '\\' && text.contains('\\')) + }; + // A relative path would let `ssh` and `ssh-proxy` resolve different + // files, and would make the working directory the pin directory. + let usable = path.is_absolute() + && path.file_name().is_some() + && path.to_str().is_some_and(|text| !expands_or_breaks(text)); + if usable { + Ok(Self { + path, + sandbox: sandbox.to_string(), + workspace: workspace.to_string(), + }) + } else { + Err(HostKeyError::UnusablePath(path)) + } + } + + fn under(config_dir: &Path, target: &SandboxSshTarget<'_>) -> Result { + let alias = host_key_alias(target.sandbox, target.workspace); + // A gateway reached by its endpoint alone is named by its URL. + let gateway = target.gateway.replace( + |ch: char| !ch.is_ascii_alphanumeric() && !matches!(ch, '.' | '-' | '_'), + "_", + ); + let path = config_dir.join("known_hosts").join(&gateway).join(&alias); + let is_one_component = |name: &str| Path::new(name).file_name() == Some(name.as_ref()); + if !is_one_component(&gateway) || !is_one_component(&alias) { + return Err(HostKeyError::UnusablePath(path)); + } + Self::at(path, target.sandbox, target.workspace) + } + + fn alias(&self) -> String { + host_key_alias(&self.sandbox, &self.workspace) + } + + pub fn path(&self) -> &Path { + &self.path + } + + /// The path as `ssh` must be given it in `UserKnownHostsFile` and inside + /// a `ProxyCommand`: it expands `%` tokens in both, and `%%` is a `%`. + pub fn ssh_path(&self) -> String { + self.path.display().to_string().replace('%', "%%") + } + + /// The options of every sandbox SSH connection that decide which host key + /// it trusts, in the order they are passed. Rendered as `-o key=value` on + /// a command line and as `key value` lines in a config block. + pub fn ssh_options(&self) -> Vec<(&'static str, String)> { + vec![ + ("StrictHostKeyChecking", "yes".to_string()), + // Quoted, so that no `ssh` release splits the path at whitespace, + // `=` or an apostrophe. + ("UserKnownHostsFile", format!("\"{}\"", self.ssh_path())), + ("GlobalKnownHostsFile", "/dev/null".to_string()), + ("HostKeyAlias", self.alias()), + ("HostKeyAlgorithms", HOST_KEY_ALGORITHM.to_string()), + ("VerifyHostKeyDNS", "no".to_string()), + ("UpdateHostKeys", "no".to_string()), + ] + } + + /// Rewrites the file header-only when it holds anything other than one key + /// hashing to `fingerprint`. With no fingerprint, no key is kept. + fn forget_unless(&self, fingerprint: Option<&HostKeyFingerprint>) -> io::Result<()> { + // Decided from one read: a second read could see the key another + // connection stored in between, and the rewrite would erase it. + let trusts_nothing_else = self.read()?.is_some_and(|content| { + content == PIN_HEADER.as_bytes() + || self + .key_blob(&content) + .zip(fingerprint) + .is_some_and(|(blob, fingerprint)| { + HostKeyFingerprint::of_blob(&blob).is_ok_and(|kept| kept == *fingerprint) + }) + }); + if trusts_nothing_else { + Ok(()) + } else { + self.replace(PIN_HEADER) + } + } + + /// No-op when the content is already identical; otherwise a temp file + /// (0600) in the same directory, then a rename. + fn store(&self, blob: &[u8]) -> io::Result<()> { + let content = format!("{}{}\n", self.key_line_prefix(), STANDARD.encode(blob)); + if self.read()?.is_some_and(|kept| kept == content.as_bytes()) { + return Ok(()); + } + self.replace(&content) + } + + fn key_line_prefix(&self) -> String { + format!("{PIN_HEADER}{} {HOST_KEY_ALGORITHM} ", self.alias()) + } + + /// The key blob, when `content` is exactly what [`Self::store`] writes. + fn key_blob(&self, content: &[u8]) -> Option> { + content + .strip_prefix(self.key_line_prefix().as_bytes()) + .and_then(|rest| rest.strip_suffix(b"\n")) + .and_then(|encoded| STANDARD.decode(encoded).ok()) + } + + fn read(&self) -> io::Result>> { + match fs::read(&self.path) { + Ok(content) => Ok(Some(content)), + Err(err) if err.kind() == io::ErrorKind::NotFound => Ok(None), + Err(err) => Err(self.with_path(&err)), + } + } + + fn replace(&self, content: &str) -> io::Result<()> { + self.write_then_rename(content) + .map_err(|err| self.with_path(&err)) + } + + fn write_then_rename(&self, content: &str) -> io::Result<()> { + let dir = self.path.parent().ok_or(io::ErrorKind::InvalidInput)?; + create_owner_only_dir(dir)?; + // Unique among the writers of this process. `create_new` refuses a + // file or link someone else left there. + let sequence = TEMP_FILE_SEQUENCE.fetch_add(1, Ordering::Relaxed); + let temp_path = dir.join(format!(".{}.{sequence}.tmp", std::process::id())); + let mut options = fs::OpenOptions::new(); + options.write(true).create_new(true); + #[cfg(unix)] + std::os::unix::fs::OpenOptionsExt::mode(&mut options, 0o600); + let replaced = options + .open(&temp_path) + .and_then(|mut file| file.write_all(content.as_bytes())) + .and_then(|()| fs::rename(&temp_path, &self.path)); + if replaced.is_err() { + let _ = fs::remove_file(&temp_path); + } + replaced + } + + fn with_path(&self, err: &io::Error) -> io::Error { + io::Error::new(err.kind(), format!("{}: {err}", self.path.display())) + } +} + +fn create_owner_only_dir(dir: &Path) -> io::Result<()> { + let mut builder = fs::DirBuilder::new(); + builder.recursive(true); + #[cfg(unix)] + { + use std::os::unix::fs::DirBuilderExt as _; + builder.mode(0o700); + } + builder.create(dir) +} + +/// The host-key decision for one SSH connection. +#[derive(Debug)] +pub struct HostKeyCheck { + expectation: HostKeyExpectation, + pin: KnownHostsPin, +} + +impl HostKeyCheck { + /// For the CLI and TUI, before `ssh` is spawned. Leaves the pin holding + /// nothing `ssh` could trust except the key the gateway published. + pub fn for_session( + session: &CreateSshSessionResponse, + target: &SandboxSshTarget<'_>, + ) -> Result { + let expectation = HostKeyExpectation::from_published(&session.host_key_fingerprint)?; + Self::for_relay(expectation, KnownHostsPin::for_target(target)?) + } + + /// For `ssh-proxy`, before the first byte is relayed. + pub fn for_relay( + expectation: HostKeyExpectation, + pin: KnownHostsPin, + ) -> Result { + pin.forget_unless(match &expectation { + HostKeyExpectation::Fingerprint(fingerprint) => Some(fingerprint), + HostKeyExpectation::AcceptAny => None, + })?; + Ok(Self { expectation, pin }) + } + + #[must_use] + pub fn unverified_warning(&self, sandbox: &str) -> Option { + matches!(self.expectation, HostKeyExpectation::AcceptAny).then(|| { + format!( + "warning: SSH host key of sandbox '{sandbox}' is NOT verified: the gateway published no fingerprint. \ + Upgrade a gateway that predates sandbox SSH identities; otherwise stop and start the sandbox." + ) + }) + } + + pub(crate) fn ssh_options(&self) -> Vec<(&'static str, String)> { + self.pin.ssh_options() + } + + /// `["--host-key", , "--known-hosts", ]`, for a + /// `ProxyCommand`. + pub(crate) fn proxy_flags(&self) -> [String; 4] { + [ + "--host-key".to_string(), + self.expectation.to_string(), + "--known-hosts".to_string(), + self.pin.ssh_path(), + ] + } + + pub fn into_gate(self) -> HostKeyGate { + HostKeyGate { + check: self, + phase: GatePhase::Banner, + buffer: Vec::new(), + } + } + + /// Pins `blob`, unless a fingerprint is expected and `blob` does not hash + /// to it. + fn admit(&self, blob: &[u8]) -> Result<(), HostKeyError> { + if let HostKeyExpectation::Fingerprint(expected) = self.expectation { + let presented = HostKeyFingerprint::of_blob(blob)?; + if presented != expected { + return Err(HostKeyError::Mismatch { + sandbox: self.pin.sandbox.clone(), + workspace: self.pin.workspace.clone(), + expected, + presented, + }); + } + } + self.pin.store(blob)?; + Ok(()) + } + + /// The phase after one cleartext packet from the server. Every packet + /// outside the one accepted order is refused. + fn phase_after( + &self, + awaited: GatePhase, + message: u8, + fields: &[u8], + ) -> Result { + let host_key = matches!(message, MSG_KEX_REPLY | MSG_KEX_GEX_REPLY) + .then(|| ed25519_host_key(fields)) + .flatten(); + match (awaited, message, host_key) { + (GatePhase::KexInit, MSG_KEXINIT, _) if first_kex_packet_follows(fields) == Some(0) => { + Ok(GatePhase::GroupOrReply) + } + (GatePhase::GroupOrReply, MSG_KEX_REPLY, Some(blob)) + | (GatePhase::Reply, MSG_KEX_GEX_REPLY, Some(blob)) => { + self.admit(blob)?; + Ok(GatePhase::NewKeys) + } + (GatePhase::GroupOrReply, MSG_KEX_REPLY, None) => Ok(GatePhase::Reply), + (GatePhase::NewKeys, MSG_NEWKEYS, _) => Ok(GatePhase::Done), + (GatePhase::GroupOrReply | GatePhase::Reply, MSG_NEWKEYS, _) => Err( + HostKeyError::Malformed("key exchange finished without an Ed25519 host key"), + ), + _ => Err(HostKeyError::Malformed( + "packet outside the key exchange order", + )), + } + } +} + +/// The server-to-client side of the `ssh-proxy` relay. Holds back the server's +/// key exchange reply until the host key in it is checked and pinned. +#[derive(Debug)] +pub struct HostKeyGate { + check: HostKeyCheck, + phase: GatePhase, + /// Bytes not yet released. Its head is the line or packet being decided. + buffer: Vec, +} + +/// What the gate waits for: the identification line, then the cleartext +/// packets of a key exchange in the only order the server may send them. `ssh` +/// can discard a packet outside this order, so a gate that let one through +/// could be shown one host key while `ssh` acts on another. +#[derive(Clone, Copy, Debug)] +enum GatePhase { + Banner, + KexInit, + /// The reply, or before it the group of a group exchange. + GroupOrReply, + Reply, + NewKeys, + Done, +} + +impl HostKeyGate { + /// Feed bytes read from the gateway; returns the bytes that may be written + /// to `ssh` now. Lines are released whole up to the `SSH-` identification + /// line. Then exactly these packets are released whole, in this order: + /// KEXINIT, the group of a group exchange if there is one, the key + /// exchange reply once its Ed25519 host key is pinned, and NEWKEYS. + /// Everything after NEWKEYS passes through. + /// + /// On an error nothing from this call is released, and every later call + /// fails on the same line or packet. + pub fn push(&mut self, chunk: &[u8]) -> Result, HostKeyError> { + self.buffer.extend_from_slice(chunk); + let mut released = Vec::new(); + while let Some(len) = self.releasable()? { + released.extend(self.buffer.drain(..len)); + } + Ok(released) + } + + /// The length of the buffer's head that may be released, or `None` when + /// deciding needs more bytes. An error leaves the head in place. + fn releasable(&mut self) -> Result, HostKeyError> { + match self.phase { + GatePhase::Banner => { + let head = &self.buffer[..self.buffer.len().min(MAX_BANNER_LINE_LEN)]; + let Some(newline) = head.iter().position(|&byte| byte == b'\n') else { + return if head.len() == MAX_BANNER_LINE_LEN { + Err(HostKeyError::Malformed("identification line is too long")) + } else { + Ok(None) + }; + }; + if head.starts_with(b"SSH-") { + self.phase = GatePhase::KexInit; + } + Ok(Some(newline + 1)) + } + GatePhase::Done => Ok((!self.buffer.is_empty()).then_some(self.buffer.len())), + awaited => { + let Some((length, rest)) = self.buffer.split_first_chunk::<4>() else { + return Ok(None); + }; + let length = usize::try_from(u32::from_be_bytes(*length)) + .ok() + .filter(|length| PACKET_LENGTHS.contains(length)) + .ok_or(HostKeyError::Malformed("packet length is out of range"))?; + let Some(packet) = rest.get(..length) else { + return Ok(None); + }; + let padding = usize::from(packet[0]); + let (message, fields) = packet + .get(1..length.saturating_sub(padding)) + .and_then(<[u8]>::split_first) + .ok_or(HostKeyError::Malformed("packet padding leaves no payload"))?; + self.phase = self.check.phase_after(awaited, *message, fields)?; + Ok(Some(4 + length)) + } + } + } +} + +/// The boolean that follows the cookie and the ten name-lists of a KEXINIT. +fn first_kex_packet_follows(fields: &[u8]) -> Option { + let mut rest = fields.get(KEXINIT_COOKIE_LEN..)?; + for _ in 0..KEXINIT_NAME_LISTS { + let (length, after_length) = rest.split_first_chunk::<4>()?; + rest = after_length.get(usize::try_from(u32::from_be_bytes(*length)).ok()?..)?; + } + rest.first().copied() +} + +/// The first string of a key exchange reply, when it is exactly an Ed25519 +/// public key blob. +fn ed25519_host_key(fields: &[u8]) -> Option<&[u8]> { + let (length, rest) = fields.split_first_chunk::<4>()?; + let blob = rest.get(..usize::try_from(u32::from_be_bytes(*length)).ok()?)?; + let key = blob.strip_prefix(ED25519_BLOB_PREFIX)?; + (key.len() == ED25519_KEY_LEN).then_some(blob) +} + +#[cfg(test)] +mod tests { + use super::*; + use crate::test_environment::{Environment, fixture_dir}; + + const KEY_A: [u8; 32] = [ + 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, + 25, 26, 27, 28, 29, 30, 31, + ]; + const FINGERPRINT_A: &str = "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA"; + const KNOWN_HOSTS_KEY_A: &str = + "AAAAC3NzaC1lZDI1NTE5AAAAIAABAgMEBQYHCAkKCwwNDg8QERITFBUWFxgZGhscHR4f"; + const KEY_B: [u8; 32] = [ + 255, 254, 253, 252, 251, 250, 249, 248, 247, 246, 245, 244, 243, 242, 241, 240, 239, 238, + 237, 236, 235, 234, 233, 232, 231, 230, 229, 228, 227, 226, 225, 224, + ]; + const FINGERPRINT_B: &str = "SHA256:LIHRKjP8oeafKrX0BHkvTYI/ZcB3tRHZHr9uyEhysws"; + const KNOWN_HOSTS_KEY_B: &str = + "AAAAC3NzaC1lZDI1NTE5AAAAIP/+/fz7+vn49/b19PPy8fDv7u3s6+rp6Ofm5eTj4uHg"; + + const TARGET: SandboxSshTarget<'static> = SandboxSshTarget { + gateway: "prod", + workspace: "default", + sandbox: "my-sb", + }; + + fn ed25519_blob(key: [u8; 32]) -> Vec { + let mut blob = Vec::new(); + for field in [HOST_KEY_ALGORITHM.as_bytes(), &key] { + blob.extend_from_slice(&u32::try_from(field.len()).unwrap().to_be_bytes()); + blob.extend_from_slice(field); + } + blob + } + + fn fingerprint(text: &str) -> HostKeyFingerprint { + text.parse().unwrap() + } + + fn pin_in(config_dir: &Path) -> KnownHostsPin { + KnownHostsPin::under(config_dir, &TARGET).unwrap() + } + + fn pin_file(key: &str) -> String { + format!("{PIN_HEADER}openshell-my-sb.default ssh-ed25519 {key}\n") + } + + fn published(fingerprint: &str) -> CreateSshSessionResponse { + CreateSshSessionResponse { + host_key_fingerprint: fingerprint.to_string(), + ..Default::default() + } + } + + fn with_config_dir(assertions: impl FnOnce(&Path)) { + let config_home = fixture_dir().unwrap(); + Environment::new() + .set("XDG_CONFIG_HOME", config_home.path()) + .run(|| assertions(&config_home.path().join("openshell"))); + } + + const BANNER: &[u8] = b"SSH-2.0-OpenShell_0.0.0\r\n"; + /// Stands in for the encrypted stream: read as a packet, its length is out + /// of range. + const ENCRYPTED: [u8; 48] = [0xff; 48]; + + fn string(bytes: &[u8]) -> Vec { + [&u32::try_from(bytes.len()).unwrap().to_be_bytes(), bytes].concat() + } + + /// Four bytes of padding: the gate does not check block alignment. + fn packet(payload: &[u8]) -> Vec { + let length = u32::try_from(payload.len() + 5).unwrap().to_be_bytes(); + [&length[..], &[4], payload, &[0; 4]].concat() + } + + fn kexinit() -> Vec { + kexinit_ending(&[0; 5]) + } + + /// A KEXINIT whose ten name-lists are followed by `ending`: normally + /// `first_kex_packet_follows` and the reserved word. + fn kexinit_ending(ending: &[u8]) -> Vec { + let mut payload = vec![20]; + payload.extend_from_slice(&[0x11; 16]); + for length in [17, 11, 29, 29, 13, 13, 4, 4, 0, 0] { + payload.extend(string(&vec![b'a'; length])); + } + payload.extend_from_slice(ending); + packet(&payload) + } + + fn group() -> Vec { + let prime = [&[0][..], &[0xff; 256]].concat(); + packet(&[vec![31], string(&prime), string(&[2])].concat()) + } + + fn kex_reply(message: u8, host_key: &[u8]) -> Vec { + let signature = [string(b"ssh-ed25519"), string(&[0x5a; 64])].concat(); + packet( + &[ + vec![message], + string(host_key), + string(&[0x42; 32]), + string(&signature), + ] + .concat(), + ) + } + + fn newkeys() -> Vec { + packet(&[21]) + } + + /// What the server sends before its reply, the reply, and what follows it. + fn curve25519_exchange(host_key: [u8; 32]) -> [Vec; 3] { + [ + [BANNER, &kexinit()].concat(), + kex_reply(31, &ed25519_blob(host_key)), + [newkeys(), ENCRYPTED.to_vec()].concat(), + ] + } + + fn group_exchange(host_key: [u8; 32]) -> [Vec; 3] { + [ + [BANNER, &kexinit(), &group()].concat(), + kex_reply(33, &ed25519_blob(host_key)), + [newkeys(), ENCRYPTED.to_vec()].concat(), + ] + } + + fn gate_in(config_dir: &Path, expectation: &str) -> HostKeyGate { + HostKeyCheck::for_relay(expectation.parse().unwrap(), pin_in(config_dir)) + .unwrap() + .into_gate() + } + + /// What the gate released, how it ended, and the pin file it left. + fn relay<'a>( + expectation: &str, + chunks: impl IntoIterator, + ) -> (Vec, Result<(), HostKeyError>, Option) { + let config_dir = tempfile::tempdir().unwrap(); + let mut gate = gate_in(config_dir.path(), expectation); + let mut released = Vec::new(); + let result = chunks.into_iter().try_for_each(|chunk| { + released.extend(gate.push(chunk)?); + Ok(()) + }); + let pin = fs::read_to_string(pin_in(config_dir.path()).path()).ok(); + (released, result, pin) + } + + /// Every way to deliver `stream` in two chunks, then one byte at a time. + fn every_split(stream: &[u8]) -> impl Iterator> { + (0..=stream.len()) + .map(|at| vec![&stream[..at], &stream[at..]]) + .chain([stream.chunks(1).collect()]) + } + + #[test] + fn fingerprint_of_blob_matches_fixed_vector() { + let computed = HostKeyFingerprint::of_blob(&ed25519_blob(KEY_A)).unwrap(); + assert_eq!(computed.to_string(), FINGERPRINT_A); + assert_eq!(fingerprint(FINGERPRINT_A), computed); + assert_ne!(fingerprint(FINGERPRINT_B), computed); + } + + #[test] + fn fingerprint_rejects_every_other_text_form() { + for text in [ + "", + "SHA256:", + "ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA", + "sha256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA", + "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA=", + "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncC", + "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCAA", + "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCB", + "SHA256:ZkAslGjFiUHdGf_WUL8rQvkib4PTvQatUV0OUQSncCA", + "SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA\n", + " SHA256:ZkAslGjFiUHdGf/WUL8rQvkib4PTvQatUV0OUQSncCA", + "MD5:b4:f6:6e:5f:3c:0a:9d:11:27:35:5d:42:8e:0c:71:aa", + ] { + assert!( + matches!( + text.parse::(), + Err(HostKeyError::BadFingerprint) + ), + "{text:?}" + ); + } + } + + /// Only an empty field means that nothing was published. A malformed one + /// is refused, also when it spells `unverified`. + #[test] + fn expectation_verifies_a_published_fingerprint_and_refuses_a_malformed_one() { + assert_eq!( + HostKeyExpectation::from_published(FINGERPRINT_A).unwrap(), + HostKeyExpectation::Fingerprint(fingerprint(FINGERPRINT_A)), + ); + assert_eq!( + HostKeyExpectation::from_published("").unwrap(), + HostKeyExpectation::AcceptAny, + ); + for malformed in ["unverified", "SHA256:inconsistent", "MD5:00:11"] { + assert!( + matches!( + HostKeyExpectation::from_published(malformed), + Err(HostKeyError::BadFingerprint) + ), + "{malformed:?}" + ); + } + } + + #[test] + fn pin_for_target_resolves_a_relative_config_dir_against_the_working_directory() { + Environment::new() + .set("XDG_CONFIG_HOME", "relative/.config") + .run(|| { + let pin = KnownHostsPin::for_target(&TARGET).unwrap(); + assert_eq!( + pin.path(), + std::env::current_dir().unwrap().join( + "relative/.config/openshell/known_hosts/prod/openshell-my-sb.default" + ) + ); + }); + } + + #[test] + fn pin_for_a_gateway_named_by_its_endpoint_lives_in_one_directory() { + let config_dir = Path::new("/home/u/.config/openshell"); + for (gateway, directory) in [ + ("http://127.0.0.1:18080", "http___127.0.0.1_18080"), + ("https://gw.example.com/a b%", "https___gw.example.com_a_b_"), + ("../../etc", ".._.._etc"), + ] { + let target = SandboxSshTarget { gateway, ..TARGET }; + assert_eq!( + KnownHostsPin::under(config_dir, &target).unwrap().path(), + config_dir + .join("known_hosts") + .join(directory) + .join("openshell-my-sb.default"), + "gateway {gateway:?}" + ); + } + } + + #[test] + fn pin_rejects_names_that_are_not_one_path_component() { + let config_dir = Path::new("/home/u/.config/openshell"); + for (gateway, workspace, sandbox) in [ + ("", "default", "my-sb"), + (".", "default", "my-sb"), + ("..", "default", "my-sb"), + ("prod", "default", "a/b"), + ("prod", "../x", "my-sb"), + ("prod", "x/", "my-sb"), + ] { + let target = SandboxSshTarget { + gateway, + workspace, + sandbox, + }; + assert!( + matches!( + KnownHostsPin::under(config_dir, &target), + Err(HostKeyError::UnusablePath(_)) + ), + "{target:?}" + ); + } + } + + #[test] + fn pin_rejects_paths_ssh_would_expand_or_split() { + for path in [ + "/home/a\"b/pin", + "/home/${HOME}/pin", + "/home/a\nb/pin", + #[cfg(unix)] + "/home/a\\b/pin", + "relative/pin", + "", + "/", + "/tmp/..", + ] { + assert!( + matches!( + KnownHostsPin::at(PathBuf::from(path), "my-sb", "default"), + Err(HostKeyError::UnusablePath(_)) + ), + "{path:?}" + ); + } + } + + /// The pin directory is created owner-only; a directory that already + /// exists keeps its mode. + #[cfg(unix)] + #[test] + fn pin_store_creates_owner_only_files_and_leaves_existing_directories_alone() { + use std::os::unix::fs::PermissionsExt as _; + let shared = tempfile::tempdir().unwrap(); + fs::set_permissions(shared.path(), fs::Permissions::from_mode(0o755)).unwrap(); + let mode = |path: &Path| fs::metadata(path).unwrap().permissions().mode() & 0o777; + + for pin in [shared.path().join("pin"), shared.path().join("new/pin")] { + let pin = KnownHostsPin::at(pin, "my-sb", "default").unwrap(); + pin.store(&ed25519_blob(KEY_A)).unwrap(); + assert_eq!(mode(pin.path()), 0o600); + } + assert_eq!(mode(&shared.path().join("new")), 0o700); + assert_eq!(mode(shared.path()), 0o755); + } + + #[test] + fn pin_drops_anything_that_is_not_exactly_one_matching_key() { + let matching = pin_file(KNOWN_HOSTS_KEY_A); + let other_line = format!("openshell-my-sb.default ssh-ed25519 {KNOWN_HOSTS_KEY_B}\n"); + for content in [ + String::new(), + "not a known_hosts file".to_string(), + format!("{matching}{other_line}"), + format!("{PIN_HEADER}{other_line}{}", &matching[PIN_HEADER.len()..]), + format!("{PIN_HEADER}* ssh-ed25519 {KNOWN_HOSTS_KEY_A}\n"), + format!("{PIN_HEADER}openshell-other.default ssh-ed25519 {KNOWN_HOSTS_KEY_A}\n"), + format!( + "{PIN_HEADER}@cert-authority openshell-my-sb.default ssh-ed25519 {KNOWN_HOSTS_KEY_A}\n" + ), + format!("{PIN_HEADER}openshell-my-sb.default ssh-ed25519 not-base64\n"), + matching[PIN_HEADER.len()..].to_string(), + matching.trim_end().to_string(), + ] { + let config_dir = tempfile::tempdir().unwrap(); + let pin = pin_in(config_dir.path()); + fs::create_dir_all(pin.path().parent().unwrap()).unwrap(); + fs::write(pin.path(), &content).unwrap(); + + pin.forget_unless(Some(&fingerprint(FINGERPRINT_A))) + .unwrap(); + + assert_eq!( + fs::read_to_string(pin.path()).unwrap(), + PIN_HEADER, + "{content:?}" + ); + } + } + + /// Before `ssh` can read the pin, it holds the published key or no key. + #[test] + fn check_for_session_keeps_only_the_published_key() { + with_config_dir(|config_dir| { + let pin = pin_in(config_dir); + let path = pin.path().display().to_string(); + for (stored, kept) in [ + (KEY_B, PIN_HEADER.to_string()), + (KEY_A, pin_file(KNOWN_HOSTS_KEY_A)), + ] { + pin.store(&ed25519_blob(stored)).unwrap(); + + let check = HostKeyCheck::for_session(&published(FINGERPRINT_A), &TARGET).unwrap(); + + assert_eq!(fs::read_to_string(pin.path()).unwrap(), kept); + assert_eq!(check.unverified_warning("my-sb"), None); + assert_eq!( + check.proxy_flags(), + ["--host-key", FINGERPRINT_A, "--known-hosts", path.as_str()] + ); + } + }); + } + + #[test] + fn check_for_session_never_trusts_a_cached_pin_when_unverified() { + with_config_dir(|config_dir| { + let pin = pin_in(config_dir); + pin.store(&ed25519_blob(KEY_A)).unwrap(); + + let check = HostKeyCheck::for_session(&published(""), &TARGET).unwrap(); + + assert_eq!(fs::read_to_string(pin.path()).unwrap(), PIN_HEADER); + assert_eq!( + check.unverified_warning("my-sb").unwrap(), + "warning: SSH host key of sandbox 'my-sb' is NOT verified: the gateway published no fingerprint. \ + Upgrade a gateway that predates sandbox SSH identities; otherwise stop and start the sandbox." + ); + assert_eq!(check.proxy_flags()[..2], ["--host-key", "unverified"]); + }); + } + + /// Other connections to the sandbox start while one stores the key and + /// hands the reply to `ssh`, which must then find the key in the pin. + #[test] + fn check_for_relay_keeps_the_key_another_connection_just_stored() { + use std::sync::atomic::{AtomicBool, Ordering}; + + struct StopOnDrop<'a>(&'a AtomicBool); + impl Drop for StopOnDrop<'_> { + fn drop(&mut self) { + self.0.store(true, Ordering::Relaxed); + } + } + + let config_dir = tempfile::tempdir().unwrap(); + let pin = pin_in(config_dir.path()); + let stream = curve25519_exchange(KEY_A).concat(); + let stop = AtomicBool::new(false); + pin.forget_unless(None).unwrap(); + + std::thread::scope(|scope| { + let _stop_others = StopOnDrop(&stop); + for _ in 0..4 { + scope.spawn(|| { + while !stop.load(Ordering::Relaxed) { + gate_in(config_dir.path(), FINGERPRINT_A); + } + }); + } + for connection in 0..500 { + pin.forget_unless(None).unwrap(); + let mut gate = gate_in(config_dir.path(), FINGERPRINT_A); + + assert_eq!(gate.push(&stream).unwrap(), stream, "{connection}"); + assert_eq!( + fs::read_to_string(pin.path()).unwrap(), + pin_file(KNOWN_HOSTS_KEY_A), + "{connection}" + ); + } + }); + } + + /// Asserts that `stream` is refused as `is_expected` says, that nothing + /// past `before` is released and that the pin file is left as `pin`, + /// however `stream` is split. + fn assert_refused( + name: &str, + expectation: &str, + before: &[u8], + stream: &[u8], + is_expected: impl Fn(&HostKeyError) -> bool, + pin: &str, + ) { + for chunks in every_split(stream) { + let at = chunks[0].len(); + let (released, result, kept) = relay(expectation, chunks); + + assert!( + result.as_ref().is_err_and(&is_expected), + "{name} split at {at}: {result:?}" + ); + assert!(before.starts_with(&released), "{name} split at {at}"); + assert_eq!(kept.as_deref(), Some(pin), "{name} split at {at}"); + } + } + + #[test] + fn gate_relays_an_exchange_unchanged_and_pins_its_key() { + let curve = curve25519_exchange(KEY_A).concat(); + let gex = group_exchange(KEY_A).concat(); + let other = curve25519_exchange(KEY_B).concat(); + let greeted = [&b"Welcome\r\nnotice: maintenance at noon\n"[..], &curve].concat(); + for (name, expectation, stream, key) in [ + ("curve25519", FINGERPRINT_A, &curve, KNOWN_HOSTS_KEY_A), + ("group exchange", FINGERPRINT_A, &gex, KNOWN_HOSTS_KEY_A), + ("unverified", "unverified", &other, KNOWN_HOSTS_KEY_B), + ("greeting", FINGERPRINT_A, &greeted, KNOWN_HOSTS_KEY_A), + ] { + for chunks in every_split(stream) { + let at = chunks[0].len(); + let (released, result, pin) = relay(expectation, chunks); + + assert!(result.is_ok(), "{name} split at {at}"); + assert_eq!(&released, stream, "{name} split at {at}"); + assert_eq!(pin, Some(pin_file(key)), "{name} split at {at}"); + } + } + } + + #[test] + fn gate_holds_the_reply_until_its_key_is_pinned() { + let [before, reply, after] = curve25519_exchange(KEY_A); + let (reply_head, reply_last_byte) = reply.split_at(reply.len() - 1); + let config_dir = tempfile::tempdir().unwrap(); + let pin = pin_in(config_dir.path()); + let mut gate = gate_in(config_dir.path(), FINGERPRINT_A); + + assert_eq!(gate.push(&before).unwrap(), before); + assert_eq!(gate.push(reply_head).unwrap(), b""); + assert_eq!(fs::read_to_string(pin.path()).unwrap(), PIN_HEADER); + + assert_eq!(gate.push(reply_last_byte).unwrap(), reply); + assert_eq!( + fs::read_to_string(pin.path()).unwrap(), + pin_file(KNOWN_HOSTS_KEY_A) + ); + assert_eq!(gate.push(&after).unwrap(), after); + } + + #[test] + fn gate_withholds_a_reply_carrying_another_key() { + for exchange in [curve25519_exchange(KEY_B), group_exchange(KEY_B)] { + assert_refused( + "another key", + FINGERPRINT_A, + &exchange[0], + &exchange.concat(), + |error| { + matches!( + error, + HostKeyError::Mismatch { expected, presented, .. } + if *expected == fingerprint(FINGERPRINT_A) + && *presented == fingerprint(FINGERPRINT_B) + ) + }, + PIN_HEADER, + ); + } + } + + #[test] + fn gate_fails_when_new_keys_come_before_an_ed25519_host_key() { + let rsa = [string(b"ssh-rsa"), string(&[1, 0, 1]), string(&[0x7f; 257])].concat(); + let short = [string(b"ssh-ed25519"), string(&KEY_A[..31])].concat(); + let truncated = ed25519_blob(KEY_A)[..50].to_vec(); + let trailing = [ed25519_blob(KEY_A), vec![0]].concat(); + let mut befores = vec![ + [BANNER, &kexinit()].concat(), + [BANNER, &kexinit(), &group()].concat(), + ]; + befores.extend( + [rsa, short, truncated, trailing, Vec::new()] + .map(|host_key| [BANNER, &kexinit(), &kex_reply(31, &host_key)].concat()), + ); + for before in befores { + let stream = [before.as_slice(), &newkeys(), &ENCRYPTED].concat(); + for expectation in [FINGERPRINT_A, "unverified"] { + assert_refused( + "no host key", + expectation, + &before, + &stream, + |error| matches!(error, HostKeyError::Malformed(NO_HOST_KEY)), + PIN_HEADER, + ); + } + } + } + + const NO_HOST_KEY: &str = "key exchange finished without an Ed25519 host key"; + const OUT_OF_ORDER: &str = "packet outside the key exchange order"; + + /// `ssh` discards a decoy, a packet it does not expect or was told to + /// skip, and would act on the reply behind it. + #[test] + fn gate_rejects_a_packet_outside_the_key_exchange_order() { + let ignore = packet(&[2, 0, 0, 0, 0]); + let reply = kex_reply(31, &ed25519_blob(KEY_A)); + let other = kex_reply(31, &ed25519_blob(KEY_B)); + let rsa = [string(b"ssh-rsa"), string(&[1, 0, 1]), string(&[0x7f; 257])].concat(); + let decoy_first = [reply.as_slice(), &kexinit(), &other].concat(); + let reply_gex = kex_reply(33, &ed25519_blob(KEY_A)); + let other_gex = kex_reply(33, &ed25519_blob(KEY_B)); + let rsa_gex = kex_reply(33, &rsa); + let wrong_guess = [&kexinit_ending(&[1, 0, 0, 0, 0])[..], &reply, &other].concat(); + let after_kexinit = [BANNER, &kexinit()].concat(); + let after_group = [BANNER, &kexinit(), &group()].concat(); + let after_reply = [BANNER, &kexinit(), &reply].concat(); + let after_group_reply = [BANNER, &kexinit(), &group(), &reply_gex].concat(); + let pinned = pin_file(KNOWN_HOSTS_KEY_A); + for (name, before, offending) in [ + ("decoy before KEXINIT", BANNER, &decoy_first), + ("decoy as the announced wrong guess", BANNER, &wrong_guess), + ("decoy before the reply", &after_reply, &other), + ("decoy after the group", &after_group_reply, &other_gex), + ("IGNORE first", BANNER, &ignore), + ("NEWKEYS first", BANNER, &newkeys()), + ("KEXINIT cut short", BANNER, &kexinit_ending(&[])), + ("IGNORE before the reply", &after_kexinit, &ignore), + ("second KEXINIT", &after_kexinit, &kexinit()), + ("second group", &after_group, &group()), + ( + "group exchange reply without a group", + &after_kexinit, + &reply_gex, + ), + ("plain reply after a group", &after_group, &reply), + ("non-Ed25519 group reply", &after_group, &rsa_gex), + ("IGNORE before NEWKEYS", &after_reply, &ignore), + ("second reply", &after_reply, &reply), + ] { + assert_refused( + name, + FINGERPRINT_A, + before, + &[before, offending, &newkeys(), &ENCRYPTED].concat(), + |error| matches!(error, HostKeyError::Malformed(OUT_OF_ORDER)), + if before.ends_with(&reply) || before.ends_with(&reply_gex) { + &pinned + } else { + PIN_HEADER + }, + ); + } + } + + #[test] + fn gate_stays_closed_after_a_refusal() { + let [before, reply, after] = curve25519_exchange(KEY_B); + for refused in [ + [before.as_slice(), &reply].concat(), + [BANNER, &kexinit_ending(&[1, 0, 0, 0, 0])].concat(), + ] { + let config_dir = tempfile::tempdir().unwrap(); + let mut gate = gate_in(config_dir.path(), FINGERPRINT_A); + let first = gate.push(&refused).unwrap_err().to_string(); + + for later in [after.as_slice(), b"", &curve25519_exchange(KEY_A).concat()] { + assert_eq!(gate.push(later).unwrap_err().to_string(), first); + } + assert_eq!( + fs::read_to_string(pin_in(config_dir.path()).path()).unwrap(), + PIN_HEADER + ); + } + } + + #[test] + fn gate_rejects_a_malformed_packet() { + let length = |length: u32| [&length.to_be_bytes()[..], &[0; 16]].concat(); + let padded = |padding: u8| vec![0, 0, 0, 2, padding, 31]; + let mut long_line = b"SSH-2.0-".to_vec(); + long_line.resize(255, b'a'); + for (before, rest, expected) in [ + (BANNER, length(0), "packet length is out of range"), + (BANNER, length(1), "packet length is out of range"), + (BANNER, length(262_145), "packet length is out of range"), + (BANNER, length(u32::MAX), "packet length is out of range"), + (BANNER, padded(1), "packet padding leaves no payload"), + (BANNER, padded(9), "packet padding leaves no payload"), + (b"".as_slice(), long_line, "identification line is too long"), + ] { + assert_refused( + expected, + FINGERPRINT_A, + before, + &[before, &rest].concat(), + |error| matches!(error, HostKeyError::Malformed(message) if *message == expected), + PIN_HEADER, + ); + } + } +} diff --git a/crates/openshell-tui/src/lib.rs b/crates/openshell-tui/src/lib.rs index 0e807cd452..fceb429a86 100644 --- a/crates/openshell-tui/src/lib.rs +++ b/crates/openshell-tui/src/lib.rs @@ -994,14 +994,19 @@ async fn handle_shell_connect( return Ok(()); } }; - let proxy_command = build_proxy_command( - &exe.to_string_lossy(), - &gateway_url, - &sandbox_name, - &workspace, - &session.token, - &app.gateway_name, - ); + let target = SandboxSshTarget { + gateway: &app.gateway_name, + workspace: &workspace, + sandbox: &sandbox_name, + }; + let (proxy_command, unverified_warning) = + match sandbox_proxy_for_session(&session, &exe, &gateway_url, &target) { + Ok(proxy) => proxy, + Err(refusal) => { + app.status_text = host_key_refused_status(&refusal); + return Ok(()); + } + }; // Step 5: Build the SSH command. let mut command = std::process::Command::new("ssh"); command @@ -1033,6 +1038,9 @@ async fn handle_shell_connect( disable_raw_mode().into_diagnostic()?; // Step 8: Spawn SSH as child process and wait. + if let Some(warning) = unverified_warning { + eprintln!("{warning}"); + } let status = tokio::task::spawn_blocking(move || command.status()).await; match &status { Ok(Ok(s)) if !s.success() => { @@ -1124,14 +1132,19 @@ async fn handle_exec_command( return Ok(()); } }; - let proxy_command = build_proxy_command( - &exe.to_string_lossy(), - &gateway_url, - sandbox_name, + let target = SandboxSshTarget { + gateway: &app.gateway_name, workspace, - &session.token, - &app.gateway_name, - ); + sandbox: sandbox_name, + }; + let (proxy_command, unverified_warning) = + match sandbox_proxy_for_session(&session, &exe, &gateway_url, &target) { + Ok(proxy) => proxy, + Err(refusal) => { + app.status_text = format!("exec: {}", host_key_refused_status(&refusal)); + return Ok(()); + } + }; // Step 3: Build SSH command — same flags as handle_shell_connect but with // the parsed command appended. Each argument is escaped individually so the @@ -1165,6 +1178,9 @@ async fn handle_exec_command( disable_raw_mode().into_diagnostic()?; // Step 5: Run command — blocks until user Ctrl-C's or command exits. + if let Some(warning) = unverified_warning { + eprintln!("{warning}"); + } let status = tokio::task::spawn_blocking(move || ssh.status()).await; match &status { Ok(Ok(s)) if !s.success() => { @@ -1199,9 +1215,38 @@ async fn handle_exec_command( // SSH utility functions are shared via openshell_core::forward. use openshell_core::forward::{ - build_proxy_command, format_gateway_url, resolve_ssh_gateway, sandbox_ssh_args, shell_escape, - validate_ssh_session_response, + SandboxProxyCommand, format_gateway_url, resolve_ssh_gateway, sandbox_proxy_command, + sandbox_ssh_args, shell_escape, validate_ssh_session_response, }; +use openshell_core::ssh_host_key::{HostKeyCheck, HostKeyError, SandboxSshTarget}; + +/// Decide how the sandbox's SSH host key is checked and build the +/// `ProxyCommand` that enforces it. The warning is present when the key cannot +/// be verified. +fn sandbox_proxy_for_session( + session: &openshell_core::proto::CreateSshSessionResponse, + exe: &std::path::Path, + gateway_url: &str, + target: &SandboxSshTarget<'_>, +) -> std::result::Result<(SandboxProxyCommand, Option), HostKeyError> { + let host_key = HostKeyCheck::for_session(session, target)?; + let unverified_warning = host_key.unverified_warning(target.sandbox); + let proxy_command = sandbox_proxy_command( + &exe.to_string_lossy(), + gateway_url, + target, + &session.token, + host_key, + ); + Ok((proxy_command, unverified_warning)) +} + +/// The status line shows one row, so it carries the first line of a refusal. +/// `openshell sandbox connect` prints the rest. +fn host_key_refused_status(refusal: &HostKeyError) -> String { + let refusal = refusal.to_string(); + refusal.lines().next().unwrap_or_default().to_string() +} fn build_exec_command(command: &[String]) -> String { command @@ -1636,14 +1681,20 @@ async fn start_port_forwards( return warnings; } }; - let proxy_command = build_proxy_command( - &exe.to_string_lossy(), - &gateway_url, - sandbox_name, + let target = SandboxSshTarget { + gateway: gateway_name, workspace, - &session.token, - gateway_name, - ); + sandbox: sandbox_name, + }; + let (proxy_command, unverified_warning) = + match sandbox_proxy_for_session(&session, &exe, &gateway_url, &target) { + Ok(proxy) => proxy, + Err(refusal) => { + warnings.push(host_key_refused_status(&refusal)); + return warnings; + } + }; + warnings.extend(unverified_warning); // Start a forward for each spec. for spec in specs { diff --git a/docs/how-it-works/sandboxes/overview.mdx b/docs/how-it-works/sandboxes/overview.mdx index 9f61089f13..7ff36d95d7 100644 --- a/docs/how-it-works/sandboxes/overview.mdx +++ b/docs/how-it-works/sandboxes/overview.mdx @@ -897,9 +897,15 @@ gateway, and supervisor must use the matching OpenShell release. Older runtimes can return an empty fingerprint; an empty value cannot verify an SSH server's identity. -The CLI and TUI continue to use their existing SSH connection settings. -Exposing the fingerprint does not enable automatic host-key verification in -those clients. +The CLI, the TUI, and generated SSH config entries check the sandbox's host +key against this fingerprint on every SSH connection they open. When the SSH +server presents a different key, they stop before authentication and report +`SSH host key mismatch`. + +They cannot verify a sandbox that has no published fingerprint. They connect +and print a warning on every such connection. If the gateway predates sandbox +SSH identities, upgrade it. Otherwise stop and start the sandbox so the +gateway assigns it a key. Generate an SSH config entry for a sandbox so tools like VS Code Remote-SSH can connect directly: @@ -909,6 +915,11 @@ openshell sandbox ssh-config my-sandbox Append the output to `~/.ssh/config` or use `--editor` on `sandbox create`/`sandbox connect` for automatic setup. +SSH config entries that an earlier release generated accept any host key. +They keep working and print a warning on every connection. Replace each pasted +entry with new `openshell sandbox ssh-config` output, or use `--editor` on +`sandbox connect` again for that sandbox. + ## Transfer Files Upload files from your host into the sandbox: diff --git a/examples/vscode-remote-sandbox.md b/examples/vscode-remote-sandbox.md index b5cfe1bdd2..d39581ec2f 100644 --- a/examples/vscode-remote-sandbox.md +++ b/examples/vscode-remote-sandbox.md @@ -37,19 +37,7 @@ managed SSH config include file. ### 3. Optional manual workflow -If you want to inspect the generated SSH stanza directly: - -```text -Host openshell-my-sandbox.default - User sandbox - StrictHostKeyChecking no - UserKnownHostsFile /dev/null - GlobalKnownHostsFile /dev/null - LogLevel ERROR - ProxyCommand openshell ssh-proxy --gateway --name my-sandbox -``` - -You can still print it manually with: +To inspect the generated SSH stanza, print it with: ```bash openshell sandbox ssh-config my-sandbox diff --git a/scripts/smoke-test-network-policy.sh b/scripts/smoke-test-network-policy.sh index 49376fd36a..89ad5c3f57 100755 --- a/scripts/smoke-test-network-policy.sh +++ b/scripts/smoke-test-network-policy.sh @@ -178,8 +178,6 @@ sandbox_exec() { echo "$ssh_config" > "$ssh_config_file" ssh -F "$ssh_config_file" \ - -o StrictHostKeyChecking=no \ - -o UserKnownHostsFile=/dev/null \ -o LogLevel=ERROR \ -o ConnectTimeout=15 \ "$ssh_host" "$@" 2>&1 diff --git a/skills/debug-openshell-cluster/SKILL.md b/skills/debug-openshell-cluster/SKILL.md index 578097b5ad..cd22f6e6c3 100644 --- a/skills/debug-openshell-cluster/SKILL.md +++ b/skills/debug-openshell-cluster/SKILL.md @@ -340,6 +340,7 @@ Common findings: - Docker driver cannot initialize because it cannot find `openshell-sandbox`: verify the sibling binary next to `openshell-gateway`, or that the configured `sandbox_runtime_image` contains `/openshell-sandbox`. - Sandbox never registers: check gateway logs and the supervisor's gateway endpoint. - SSH host-key startup errors: use matching gateway, compute-driver, and supervisor releases. The gateway retains each sandbox's SSH key in its configured credential store and sends it only through the supervisor bootstrap bundle. Check credential-driver availability and compare the public `host_key_fingerprint` from sandbox JSON output; never print the bootstrap bundle or private key. A missing stored key for a sandbox with a fingerprint is an error, not permission to replace its identity. See the [sandbox SSH identity documentation](https://docs.nvidia.com/openshell/latest/how-it-works/sandboxes/overview). +- Client reports `SSH host key mismatch for sandbox ''`: the SSH server reached through the gateway presented a key other than the one the gateway publishes, and the client refused it before authentication. Read the published `host_key_fingerprint` with `openshell sandbox get --output json` and compare it with the `gateway published` and `server presented` values in the error. Use matching gateway, compute-driver, and supervisor releases, then stop and start the sandbox so its supervisor restarts with the assigned key. Do not work around the check. - Calls to an external tool server fail while the sandbox is Ready: inspect `Tool server connections` in `openshell sandbox get `. For configured MCP-over-HTTP endpoints, JSON output exposes each address together with `last_result` and `last_reported_at` in `endpoint_statuses`. Select the endpoint by host, path, and ports, then check the reported failure boundary. `last_reported_at` records gateway acceptance time and can advance when retained evidence is accepted after a reset. Results do not expire or prove current availability; `HttpResponseReceived` can still contain a tool error. For token grant failures on any HTTP protocol, including failures before endpoint selection, inspect `last_token_grant_failure` in JSON output. It contains the bounded destination and cause, survives unrelated successful traffic, and clears on matching grant success or a policy, provider, or supervisor reset. If several paths share a host and port, other failures before the path is known, such as TLS failures, remain only in logs. A `CredentialUnavailable` result from a failed dynamic token grant also carries `last_failure` with a closed-set `code`, `stage`, `recovery_action`, the provider and credential names, and the `request_id` that the workload received in its `x-openshell-request-id` response header. Search `openshell logs ` for that ID: the supervisor's `Token grant failed` line carries the code and stage for every endpoint, and the gateway's `dynamic token grant failed` line appears when the gateway hop failed. Verify the actual operation when current tool availability matters. - On Docker Desktop, repeated `Policy fetch failed after 5 attempts` messages can mean the supervisor's selected network mode cannot reach the gateway. diff --git a/skills/openshell-cli/SKILL.md b/skills/openshell-cli/SKILL.md index 82e1000395..40d5cfb23c 100644 --- a/skills/openshell-cli/SKILL.md +++ b/skills/openshell-cli/SKILL.md @@ -553,6 +553,12 @@ sandbox, even under the same name, creates a different identity. See the [sandbox SSH documentation](https://docs.nvidia.com/openshell/latest/how-it-works/sandboxes/overview.md) for verification behavior and release compatibility. +The CLI, the TUI, and generated SSH config entries verify the host key against +that fingerprint on every SSH connection they open, and refuse a different key +with `SSH host key mismatch`. A `NOT verified` warning means the gateway +published no fingerprint, or the SSH config entry predates host-key +verification; the warning prints its fix. + For an infrastructure `Error` on a backend that supports restarting stopped sandboxes, fix the reported cause, run `sandbox stop`, and wait for it to succeed before running `sandbox start`. This retains the sandbox and persistent workspace but cannot recover deleted resources or storage. For a provisioning timeout, wait for cleanup to finish, then run `sandbox start` directly. ### Suspend and resume sandboxes