pub struct Session { /* private fields */ }
Expand description
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 Channel
s 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
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()))
});
Create a new channel. Channels are used to handle I/O for commands and forwarded streams.
Blocking flush of the outgoing buffer.
Disconnect from a session (client or server). The session can then be reused to open a new session.
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.
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.
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.
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.
Gets the server banner. This typically holds the server version information
Returns the user name that will be used to authenticate with the remote host
Configures the session.
You will need to set at least SshOption::Hostname
prior to
connecting, in order for libssh to know where to connect.
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.
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>
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.
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.
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.
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.
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>
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>
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.
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.
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
.
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.
Returns true
if the session is in blocking mode, false
otherwise.
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
.
Returns true
if this session is in the connected state, false
otherwise.