Struct libssh_rs::Session

pub struct Session { /* private fields */ }

A Session represents the state needed to make a connection to a remote host.

You need at least one Session per target host. A given session can open multiple Channels to perform multiple actions on a given target host.

Thread Safety

libssh doesn’t allow using anything associated with a given Session from multiple threads concurrently. These Rust bindings encapsulate the underlying Session in an internal mutex, which allows you to safely operate on the various elements of the session and even move them to other threads, but you need to be aware that calling methods on any of those structs will attempt to lock the underlying session, and this can lead to blocking in surprising situations.

Implementations

impl Session

pub fn new() -> SshResult<Self>

Create a new Session.

pub fn set_auth_callback<F>(&self, callback: F) where
    F: FnMut(&str, bool, bool, Option<String>) -> SshResult<String> + 'static, 

Sets a callback that is used by libssh when it needs to prompt for the passphrase during public key authentication. This is NOT used for password or keyboard interactive authentication. The callback has the signature:

use libssh_rs::SshResult;
fn callback(prompt: &str, echo: bool, verify: bool,
            identity: Option<String>) -> SshResult<String> {
 unimplemented!()
}

The prompt parameter is the prompt text to show to the user. The identity parameter, if not None, will hold the identity that is currently being tried by the userauth_public_key_auto method, which is helpful to show to the user so that they can input the correct passphrase.

The echo parameter, if true, means that the input entered by the user should be visible on screen. If false, it should not be shown on screen because it is deemed sensitive in some way.

The verify parameter, if true, means that the user should be prompted twice to make sure they entered the same text both times.

The function should return the user’s input as a string, or an Error indicating what went wrong.

You can use the get_input function to satisfy the auth callback:

use libssh_rs::*;
let sess = Session::new().unwrap();
sess.set_auth_callback(|prompt, echo, verify, identity| {
    let prompt = match identity {
        Some(ident) => format!("{} ({}): ", prompt, ident),
        None => prompt.to_string(),
    };
    get_input(&prompt, None, echo, verify)
        .ok_or_else(|| Error::Fatal("reading password".to_string()))
});

pub fn new_channel(&self) -> SshResult<Channel>

Create a new channel. Channels are used to handle I/O for commands and forwarded streams.

pub fn blocking_flush(&self, timeout: Option<Duration>) -> SshResult<()>

Blocking flush of the outgoing buffer.

pub fn disconnect(&self)

Disconnect from a session (client or server). The session can then be reused to open a new session.

pub fn connect(&self) -> SshResult<()>

Connect to the configured remote host

pub fn is_known_server(&self) -> SshResult<KnownHosts>

Check if the servers public key for the connected session is known. This checks if we already know the public key of the server we want to connect to. This allows to detect if there is a MITM attack going on of if there have been changes on the server we don’t know about.

pub fn update_known_hosts_file(&self) -> SshResult<()>

Add the current connected server to the user known_hosts file. This adds the currently connected server to the known_hosts file by appending a new line at the end. The global known_hosts file is considered read-only so it is not touched by this function.

pub fn options_parse_config(&self, file_name: Option<&str>) -> SshResult<()>

Parse the ssh config file. This should be the last call of all options, it may overwrite options which are already set. It requires that the SshOption::Hostname is already set. if file_name is None the default ~/.ssh/config will be used.

pub fn get_issue_banner(&self) -> SshResult<String>

Get the issue banner from the server. This is the banner showing a disclaimer to users who log in, typically their right or the fact that they will be monitored.

pub fn get_server_banner(&self) -> SshResult<String>

Gets the server banner. This typically holds the server version information

pub fn get_user_name(&self) -> SshResult<String>

Returns the user name that will be used to authenticate with the remote host

pub fn set_option(&self, option: SshOption) -> SshResult<()>

Configures the session. You will need to set at least SshOption::Hostname prior to connecting, in order for libssh to know where to connect.

pub fn get_server_public_key(&self) -> SshResult<SshKey>

This function allows you to get a hash of the public key. You can then print this hash in a human-readable form to the user so that he is able to verify it. It is very important that you verify at some moment that the hash matches a known server. If you don’t do it, cryptography wont help you at making things secure. OpenSSH uses SHA1 to print public key digests.

pub fn userauth_agent(&self, username: Option<&str>) -> SshResult<AuthStatus>

Try to authenticate using an ssh agent.

username should almost always be None to use the username as previously configured via set_option or that was loaded from the ssh configuration prior to calling connect, as most ssh server implementations do not allow changing the username during authentication.

pub fn userauth_public_key_auto(
    &self,
    username: Option<&str>,
    password: Option<&str>
) -> SshResult<AuthStatus>

Try to automatically authenticate using public key authentication.

This will attempt to use an ssh agent if available, and will then attempt to use your keys/identities from your ~/.ssh dir.

username should almost always be None to use the username as previously configured via set_option or that was loaded from the ssh configuration prior to calling connect, as most ssh server implementations do not allow changing the username during authentication.

The password parameter can be used to pre-fill a password to unlock the private key(s). Leaving it set to None will cause libssh to prompt for the passphrase if you have previously used set_auth_callback to configure a callback. If you haven’t set the callback and a key is password protected, this authentication method will fail.

pub fn userauth_none(&self, username: Option<&str>) -> SshResult<AuthStatus>

Try to perform "none" authentication.

Typically, the server will not allow none auth to succeed, but it has the side effect of informing the client which authentication methods are available, so a full-featured client will call this prior to calling userauth_list.

username should almost always be None to use the username as previously configured via set_option or that was loaded from the ssh configuration prior to calling connect, as most ssh server implementations do not allow changing the username during authentication.

pub fn userauth_list(&self, username: Option<&str>) -> SshResult<AuthMethods>

Returns the permitted AuthMethods.

The list is not available until after userauth_none has been called at least once.

The list can change in response to authentication events; for example, after successfully completing pubkey auth, the server may then require keyboard interactive auth to enter a second authentication factor.

username should almost always be None to use the username as previously configured via set_option or that was loaded from the ssh configuration prior to calling connect, as most ssh server implementations do not allow changing the username during authentication.

pub fn userauth_keyboard_interactive_info(
    &self
) -> SshResult<InteractiveAuthInfo>

After userauth_keyboard_interactive has been called and returned AuthStatus::Info, this method must be called to discover the prompts to questions that the server needs answered in order to authenticate the session.

It is then up to your application to obtain those answers and set them via userauth_keyboard_interactive_set_answers.

pub fn userauth_keyboard_interactive_set_answers(
    &self,
    answers: &[String]
) -> SshResult<()>

After userauth_keyboard_interactive_info has been called, and your application has produced the answers to the prompts, you must call this method to record those answers.

You will then need to call userauth_keyboard_interactive to present those answers to the server and discover the next stage of authentication.

pub fn userauth_keyboard_interactive(
    &self,
    username: Option<&str>,
    sub_methods: Option<&str>
) -> SshResult<AuthStatus>

Initiates keyboard-interactive authentication.

This appears similar to, but is not the same as password authentication. You should prefer using keyboard-interactive authentication over password auth.

username should almost always be None to use the username as previously configured via set_option or that was loaded from the ssh configuration prior to calling connect, as most ssh server implementations do not allow changing the username during authentication.

sub_methods is not documented in the underlying libssh and should almost always be None.

If the returned AuthStatus is Info, then your application should use userauth_keyboard_interactive_info and use the results of that method to prompt the user to answer the questions sent by the server, then userauth_keyboard_interactive_set_answers to record the answers, before again calling this method to present them to the server and determine the next steps.

pub fn userauth_password(
    &self,
    username: Option<&str>,
    password: Option<&str>
) -> SshResult<AuthStatus>

Initiates password based authentication.

This appears similar to, but is not the same as keyboard-interactive authentication. You should prefer using keyboard-interactive authentication over password auth.

username should almost always be None to use the username as previously configured via set_option or that was loaded from the ssh configuration prior to calling connect, as most ssh server implementations do not allow changing the username during authentication.

password should be a password entered by the user, or otherwise securely communicated to your application.

pub fn listen_forward(
    &self,
    bind_address: Option<&str>,
    port: u16
) -> SshResult<u16>

Sends the “tcpip-forward” global request to ask the server to begin listening for inbound connections; this is for remote (or reverse) port forwarding.

If bind_address is None then bind to all interfaces on the server side. Otherwise, bind only to the specified address. If port is 0 then the server will pick a port to bind to, otherwise, will attempt to use the requested port. Returns the bound port number.

Later in your program, you will use Session::accept_forward to wait for a forwarded connection from the address you specified.

pub fn accept_forward(&self, timeout: Duration) -> SshResult<(u16, Channel)>

Accept a remote forwarded connection. You must have called Session::listen_forward previously to set up remote port forwarding. Returns a tuple (destination_port, Channel). The destination port is so that you can distinguish between multiple remote forwards and corresponds to the port returned from listen_forward.

pub fn get_poll_state(&self) -> (bool, bool)

Returns a tuple of (read_pending, write_pending). If read_pending is true, then your OS polling mechanism should request a wakeup when the socket is readable. If write_pending is true, then your OS polling mechanism should request a wakeup when the socket is writable.

You can use the AsRawFd or AsRawSocket trait impl to obtain the socket descriptor for polling purposes.

pub fn is_blocking(&self) -> bool

Returns true if the session is in blocking mode, false otherwise.

pub fn set_blocking(&self, blocking: bool)

If blocking == true then set the session to block mode, otherwise set it to non-blocking mode. In non-blocking mode, a number of methods in the objects associated with the session can return Error::TryAgain.

pub fn is_connected(&self) -> bool

Returns true if this session is in the connected state, false otherwise.

pub fn sftp(&self) -> SshResult<Sftp>

Trait Implementations

impl AsRawFd for Session

fn as_raw_fd(&self) -> RawSocket

Extracts the raw file descriptor.