//! SFTP over SSH with `russh` and `russh-sftp`, pure Rust with `ring`. //! //! The library is async; [`Sftp`] owns a single-threaded tokio runtime and //! blocks on it, so callers stay synchronous like the other transports. //! Every network wait races the job's [`Cancel`] flag (checked every 50 //! ms) and a timeout. //! //! The server's host key is checked against Lutra's known-hosts file //! before any credential is sent. Sign-in uses a password from the //! keychain, a private key file (with its passphrase from the keychain), or //! the SSH agent. use std::future::Future; use std::io::{Read, Write}; use std::path::{Path, PathBuf}; use std::sync::{Arc, Mutex, PoisonError}; use std::time::Duration; use russh::client::{self, Handle}; use russh::keys::{HashAlg, PrivateKeyWithHashAlg, PublicKeyOrCertificate}; use russh_sftp::client::SftpSession; use russh_sftp::protocol::StatusCode; use tokio::io::{AsyncReadExt, AsyncWriteExt}; use tokio::runtime::Runtime; use crate::config::{AuthKind, Server}; use crate::error::{DeployError, Result}; use crate::known_hosts::{self, HostKeyStatus}; use crate::remote::{CHUNK, Cancel, Entry, MAX_LISTING, Remote, Tick, safe_name}; use crate::secrets::Secret; /// Longest wait for the TCP connection and the SSH handshake. const CONNECT_TIMEOUT: Duration = Duration::from_secs(20); /// Longest wait for one SFTP request or chunk. const REQUEST_TIMEOUT: Duration = Duration::from_secs(60); /// The SSH client's callbacks: checks the host key. struct Client { /// `host:port`. host: String, /// Lutra's known-hosts file. known_hosts: PathBuf, /// Why the key was refused, read after the handshake failed. verdict: Arc>>, } impl Client { /// Remembers why the key was refused. fn refuse(&self, error: DeployError) -> bool { *self.verdict.lock().unwrap_or_else(PoisonError::into_inner) = Some(error); false } } impl client::Handler for Client { type Error = russh::Error; async fn check_server_key( &mut self, offered: &PublicKeyOrCertificate, ) -> std::result::Result { let PublicKeyOrCertificate::PublicKey { key, .. } = offered else { return Ok(self.refuse(DeployError::Auth(format!( "{} offered an SSH certificate as its host key; Lutra accepts plain host keys only", self.host )))); }; let fingerprint = key.fingerprint(HashAlg::Sha256).to_string(); let algorithm = key.algorithm().to_string(); Ok( match known_hosts::check(&self.known_hosts, &self.host, &fingerprint) { Ok(HostKeyStatus::Trusted) => true, Ok(HostKeyStatus::Unknown) => self.refuse(DeployError::HostKeyUnknown { host: self.host.clone(), algorithm, fingerprint, }), Ok(HostKeyStatus::Mismatch(known)) => self.refuse(DeployError::HostKeyMismatch { host: self.host.clone(), algorithm, fingerprint, known, }), Err(e) => self.refuse(e), }, ) } } /// An open SFTP session. pub struct Sftp { /// Drives the async library. runtime: Runtime, /// The SSH connection. handle: Handle, /// The SFTP channel. sftp: SftpSession, /// The job's cancel flag. cancel: Cancel, } /// Runs `fut` until it ends, `limit` passes or `cancel` is set. async fn bounded>( cancel: &Cancel, limit: Duration, what: &str, fut: F, ) -> Result { let watch = async { loop { if cancel.is_cancelled() { return; } tokio::time::sleep(Duration::from_millis(50)).await; } }; tokio::select! { out = tokio::time::timeout(limit, fut) => out.map_err(|_| { DeployError::Transfer(format!("{what} timed out after {} s", limit.as_secs())) }), () = watch => Err(DeployError::Cancelled), } } /// An SFTP library error as a transfer error. fn sftp_error(what: &str, path: &str, e: &russh_sftp::client::error::Error) -> DeployError { DeployError::Transfer(format!("{what} {path}: {e}")) } /// Whether `e` says the path does not exist. fn is_missing(e: &russh_sftp::client::error::Error) -> bool { matches!(e, russh_sftp::client::error::Error::Status(s) if s.status_code == StatusCode::NoSuchFile) } impl Sftp { /// Connects to `server`, checks its host key against `known_hosts`, /// signs in and opens the SFTP subsystem. /// /// # Errors /// [`DeployError::HostKeyUnknown`] or [`DeployError::HostKeyMismatch`] /// before any credential is sent; [`DeployError::MissingSecret`] when a /// password is needed but `secret` is `None`; [`DeployError::Auth`] /// when the server refuses; [`DeployError::Connect`] when it cannot be /// reached; [`DeployError::Cancelled`]. pub fn connect( server: &Server, secret: Option<&Secret>, known_hosts: &Path, cancel: &Cancel, ) -> Result { let runtime = tokio::runtime::Builder::new_current_thread() .enable_all() .build() .map_err(|e| DeployError::Transfer(format!("cannot start the SSH runtime: {e}")))?; let host = server.address(); let verdict = Arc::new(Mutex::new(None)); let handler = Client { host: host.clone(), known_hosts: known_hosts.to_path_buf(), verdict: Arc::clone(&verdict), }; let config = Arc::new(client::Config { inactivity_timeout: Some(Duration::from_secs(120)), ..Default::default() }); let target = (server.host.clone(), server.effective_port()); let connected = runtime.block_on(bounded( cancel, CONNECT_TIMEOUT, "connecting", client::connect(config, target, handler), ))?; let mut handle = match connected { Ok(handle) => handle, Err(e) => { if let Some(refusal) = verdict .lock() .unwrap_or_else(PoisonError::into_inner) .take() { return Err(refusal); } return Err(DeployError::Connect { host, message: e.to_string(), }); } }; let signed_in = runtime.block_on(bounded( cancel, CONNECT_TIMEOUT, "signing in", authenticate(&mut handle, server, secret), ))??; if !signed_in { let how = match server.auth { AuthKind::Password => "the user name or password", AuthKind::Key => "the user name or the key", AuthKind::Agent => "the user name or the keys in the SSH agent", }; return Err(DeployError::Auth(format!( "{host} refused the sign-in; check {how}" ))); } let sftp = runtime .block_on(bounded(cancel, CONNECT_TIMEOUT, "opening SFTP", async { let channel = handle.channel_open_session().await?; channel.request_subsystem(true, "sftp").await?; Ok::<_, russh::Error>(channel.into_stream()) }))? .map_err(|e| DeployError::Connect { host: host.clone(), message: format!("the server offers no SFTP: {e}"), })?; let sftp = runtime .block_on(bounded( cancel, CONNECT_TIMEOUT, "opening SFTP", SftpSession::new(sftp), ))? .map_err(|e| DeployError::Connect { host, message: format!("the SFTP session failed: {e}"), })?; Ok(Self { runtime, handle, sftp, cancel: cancel.clone(), }) } /// Runs one request with the request timeout and the cancel flag. fn run>(&self, what: &str, fut: F) -> Result { self.runtime .block_on(bounded(&self.cancel, REQUEST_TIMEOUT, what, fut)) } } /// Signs in on `handle` the way `server` says. Returns whether the server /// accepted. async fn authenticate( handle: &mut Handle, server: &Server, secret: Option<&Secret>, ) -> Result { let user = server.user.clone(); let auth_error = |e: russh::Error| DeployError::Auth(format!("signing in failed: {e}")); match server.auth { AuthKind::Password => { let Some(secret) = secret else { return Err(DeployError::MissingSecret { server: server.name.clone(), kind: "password".into(), }); }; let result = handle .authenticate_password(user, secret.expose()) .await .map_err(auth_error)?; Ok(result.success()) } AuthKind::Key => { let path = server.key_path.clone().unwrap_or_default(); let key = match russh::keys::load_secret_key(&path, secret.map(Secret::expose)) { Ok(key) => key, Err(russh::keys::Error::KeyIsEncrypted) if secret.is_none() => { return Err(DeployError::MissingSecret { server: server.name.clone(), kind: "passphrase".into(), }); } Err(e) => { return Err(DeployError::Auth(format!( "cannot read the private key {path}: {e}" ))); } }; let hash = handle .best_supported_rsa_hash() .await .map_err(auth_error)? .flatten(); let result = handle .authenticate_publickey(user, PrivateKeyWithHashAlg::new(Arc::new(key), hash)) .await .map_err(auth_error)?; Ok(result.success()) } AuthKind::Agent => agent(handle, &user).await, } } /// Tries every key of the SSH agent. #[cfg(windows)] async fn agent(handle: &mut Handle, user: &str) -> Result { use russh::keys::agent::client::AgentClient; if let Ok(client) = AgentClient::connect_named_pipe(r"\\.\pipe\openssh-ssh-agent").await { return agent_keys(handle, user, client).await; } match AgentClient::connect_pageant().await { Ok(client) => agent_keys(handle, user, client).await, Err(_) => Err(DeployError::Auth( "no SSH agent is running: start the OpenSSH Authentication Agent service or Pageant and add your key".into(), )), } } /// Tries every key of the SSH agent. #[cfg(unix)] async fn agent(handle: &mut Handle, user: &str) -> Result { use russh::keys::agent::client::AgentClient; match AgentClient::connect_env().await { Ok(client) => agent_keys(handle, user, client).await, Err(_) => Err(DeployError::Auth( "no SSH agent is reachable through SSH_AUTH_SOCK: start one and add your key (ssh-add)" .into(), )), } } /// Tries each key the agent holds until the server accepts one. async fn agent_keys( handle: &mut Handle, user: &str, mut client: russh::keys::agent::client::AgentClient, ) -> Result where S: tokio::io::AsyncRead + tokio::io::AsyncWrite + Unpin + Send + 'static, { let identities = client .request_identities() .await .map_err(|e| DeployError::Auth(format!("the SSH agent did not answer: {e}")))?; let hash = handle .best_supported_rsa_hash() .await .ok() .flatten() .flatten(); for identity in identities { let russh::keys::agent::AgentIdentity::PublicKey { key, .. } = identity else { continue; }; if let Ok(result) = handle .authenticate_publickey_with(user, key, hash, &mut client) .await && result.success() { return Ok(true); } } Ok(false) } impl Remote for Sftp { fn mkdir_all(&mut self, dir: &str) -> Result<()> { let absolute = dir.starts_with('/'); let mut path = String::new(); for part in dir.split('/').filter(|p| !p.is_empty()) { if absolute || !path.is_empty() { path.push('/'); } path.push_str(part); let exists = self .run("checking a folder", self.sftp.try_exists(path.clone()))? .map_err(|e| sftp_error("cannot check", &path, &e))?; if !exists { self.run("creating a folder", self.sftp.create_dir(path.clone()))? .map_err(|e| sftp_error("cannot create the folder", &path, &e))?; } } Ok(()) } fn put(&mut self, path: &str, data: &mut dyn Read, tick: Tick<'_>) -> Result<()> { let mut file = self .run("opening a file", self.sftp.create(path.to_string()))? .map_err(|e| sftp_error("cannot write", path, &e))?; let mut buf = vec![0u8; CHUNK]; loop { let n = data .read(&mut buf) .map_err(|e| DeployError::Transfer(format!("read failed: {e}")))?; if n == 0 { break; } let chunk = buf.get(..n).unwrap_or_default(); self.run("uploading", file.write_all(chunk))? .map_err(|e| DeployError::Transfer(format!("cannot write {path}: {e}")))?; tick(n as u64)?; } self.run("closing a file", file.shutdown())? .map_err(|e| DeployError::Transfer(format!("cannot finish {path}: {e}"))) } fn get(&mut self, path: &str, out: &mut dyn Write, tick: Tick<'_>) -> Result<()> { let mut file = self .run("opening a file", self.sftp.open(path.to_string()))? .map_err(|e| sftp_error("cannot read", path, &e))?; let mut buf = vec![0u8; CHUNK]; loop { let n = self .run("downloading", file.read(&mut buf))? .map_err(|e| DeployError::Transfer(format!("cannot read {path}: {e}")))?; if n == 0 { break; } out.write_all(buf.get(..n).unwrap_or_default()) .map_err(|e| DeployError::Transfer(format!("write failed: {e}")))?; tick(n as u64)?; } Ok(()) } fn kind(&mut self, path: &str) -> Result> { let target = if path.is_empty() { "." } else { path }; match self.run("checking a path", self.sftp.metadata(target.to_string()))? { Ok(meta) => Ok(Some(meta.is_dir())), Err(e) if is_missing(&e) => Ok(None), Err(e) => Err(sftp_error("cannot check", path, &e)), } } fn list(&mut self, path: &str) -> Result> { let target = if path.is_empty() { "." } else { path }; let dir = self .run("listing a folder", self.sftp.read_dir(target.to_string()))? .map_err(|e| sftp_error("cannot list", path, &e))?; let mut entries: Vec = dir .filter(|e| safe_name(&e.file_name())) .take(MAX_LISTING) .map(|e| { let meta = e.metadata(); Entry { name: e.file_name(), is_dir: meta.is_dir(), size: meta.size, } }) .collect(); entries.sort_by(|a, b| a.name.cmp(&b.name)); Ok(entries) } fn remove_file(&mut self, path: &str) -> Result<()> { self.run("removing a file", self.sftp.remove_file(path.to_string()))? .map_err(|e| sftp_error("cannot remove", path, &e)) } fn remove_dir(&mut self, path: &str) -> Result<()> { self.run("removing a folder", self.sftp.remove_dir(path.to_string()))? .map_err(|e| sftp_error("cannot remove the folder", path, &e)) } fn rename(&mut self, from: &str, to: &str) -> Result<()> { self.run( "renaming", self.sftp.rename(from.to_string(), to.to_string()), )? .map_err(|e| sftp_error(&format!("cannot rename to {to}:"), from, &e)) } /// Closes the SFTP channel and the connection. Failures are ignored: /// the connection is dropped right after. fn close(&mut self) { let _ = self.run("closing", self.sftp.close()); let _ = self.run( "disconnecting", self.handle .disconnect(russh::Disconnect::ByApplication, "", "en"), ); } }