Expand description
Server and client SSH asynchronous library, based on tokio/futures.
The normal way to use this library, both for clients and for
servers, is by creating handlers, i.e. types that implement
client::Handler for clients and server::Handler for
servers.
§Using non-socket IO / writing tunnels
The easy way to implement SSH tunnels, like ProxyCommand for
OpenSSH, is to use the russh-config crate, and use the
Stream::tcp_connect or Stream::proxy_command methods of that
crate. That crate is a very lightweight layer above Russh, only
implementing for external commands the traits used for sockets.
§The SSH protocol
If we exclude the key exchange and authentication phases, handled
by Russh behind the scenes, the rest of the SSH protocol is
relatively simple: clients and servers open channels, which are
just integers used to handle multiple requests in parallel in a
single connection. Once a client has obtained a ChannelId by
calling one of the many channel_open_… methods of
client::Connection, the client may send exec requests and data
to the server.
A simple client just asking the server to run one command will
usually start by calling
client::Connection::channel_open_session, then
client::Connection::exec, then possibly
client::Connection::data a number of times to send data to the
command’s standard input, and finally Connection::channel_eof
and Connection::channel_close.
§Design principles
The main goal of this library is conciseness, and reduced size and readability of the library’s code.
One non-goal is to implement all possible cryptographic algorithms published since the initial release of SSH. Technical debt is easily acquired, and we would need a very strong reason to go against this principle. If you are designing a system from scratch, we urge you to consider recent cryptographic primitives such as Ed25519 for public key cryptography, and Chacha20-Poly1305 for symmetric cryptography and MAC.
§Internal details of the event loop
It might seem a little odd that the read/write methods for server
or client sessions often return neither Result nor
Future. This is because the data sent to the remote side is
buffered, because it needs to be encrypted first, and encryption
works on buffers, and for many algorithms, not in place.
Hence, the event loop keeps waiting for incoming packets, reacts
to them by calling the provided Handler, which fills some
buffers. If the buffers are non-empty, the event loop then sends
them to the socket, flushes the socket, empties the buffers and
starts again. In the special case of the server, unsollicited
messages sent through a server::Handle are processed when there
is no incoming packet to read.
Modules§
- cipher
- Cipher names
- client
- Client side of this library.
- compression
- Compression algorithm names
- kex
- Key exchange algorithm names
- keys
- This crate contains methods to deal with SSH keys, as defined in crate Russh. This includes in particular various functions for opening key files, deciphering encrypted keys, and dealing with agents.
- mac
- MAC algorithm names
- server
- Server side of this library.
Structs§
- Channel
- A handle to a session channel.
- Channel
Id - The identifier of a channel.
- Channel
Read Half - A handle to the reading part of a session channel.
- Channel
Stream - AsyncRead/AsyncWrite wrapper for SSH Channels
- Channel
Write Half - A handle to the writing part of a session channel.
- Crypto
Vec - A buffer which zeroes its memory on
.clear(),.resize(), and reallocations, to avoid copying secrets around. - Limits
- The number of bytes read/written, and the number of seconds before a key re-exchange is requested.
- Method
Set - An ordered set of authentication methods.
- Preferred
- Lists of preferred algorithms. This is normally hard-coded into implementations.
- Send
Error
Enums§
- Agent
Auth Error - Algorithm
Kind - Channel
Msg - Possible messages that Channel::wait can receive.
- Channel
Open Failure - Reason for not being able to open a channel.
- Disconnect
- A reason for disconnection.
- Error
- Method
Kind - Pty
- Standard pseudo-terminal codes.
- Sig
- The type of signals that can be sent to a remote process. If you plan to use custom signals, read the RFC to understand the encoding.
- SshId
- The SSH client/server identification string.