Russh

A low-level, async SSH 2.0 client and server library for Rust / Tokio.

Russh gives you direct access to the SSH protocol: channels, authentication, key exchange, port and socket forwarding. It is written in safe Rust, uses async traits, and supports a broad range of algorithms for wide scale interoperability with real-world servers and clients.

• Async-native - integrates directly with Tokio, AsyncRead/AsyncWrite channels
• Broad interoperability - safe algorithms by default, with opt-in support for legacy ones
• Safety-focused - panics, unwrap/expect and unchecked indexing are denied by default

Getting started

Add russh to your Cargo.toml, choosing a crypto backend feature (see below):

[dependencies]
russh = { version = "0.63", features = ["aws-lc-rs"] }
tokio = { version = "1", features = ["full"] }

Then have a look at the examples:

• simple client
• interactive PTY client
• server
• SFTP client
• SFTP server

API documentation is on docs.rs

Crypto backends

Russh requires exactly one crypto backend. Enable the aws-lc-rs or ring crate feature.

# aws-lc-rs (default in most setups)
russh = { version = "0.63", features = ["aws-lc-rs"] }

# or ring (keep `flate2` and `rsa` when disabling default features)
russh = { version = "0.63", default-features = false, features = ["ring", "flate2", "rsa"] }

Supported algorithms

Russh aims for broad interoperability, so it supports both algorithms currently considered safe and a set of older ones that allow connections to older switches etc. Legacy algorithms are opt in.

Key exchange

Recommended

• mlkem768x25519-sha256 (post-quantum hybrid)
• curve25519-sha256, [email protected]
• diffie-hellman-group-exchange-sha256 (GEX)
• diffie-hellman-group18-sha512, diffie-hellman-group17-sha512, diffie-hellman-group16-sha512, diffie-hellman-group15-sha512
• diffie-hellman-group14-sha256
• OpenSSH strict key exchange (Terrapin mitigation)
• Programmatic group choice support for DH-GEX

Legacy

• ecdh-sha2-nistp256, ecdh-sha2-nistp384, ecdh-sha2-nistp521
• diffie-hellman-group14-sha1
• diffie-hellman-group1-sha1
• diffie-hellman-group-exchange-sha1 (GEX)

Ciphers

Recommended

• [email protected]
• [email protected], [email protected]
• aes256-ctr, aes192-ctr, aes128-ctr

Legacy

• aes256-cbc, aes192-cbc, aes128-cbc
• 3des-cbc (requires the des crate feature)

MACs

Recommended

• [email protected], [email protected]
• hmac-sha2-256, hmac-sha2-512

Legacy

• [email protected]
• hmac-sha1

Compression

• none
• zlib, [email protected] (requires the flate2 crate feature, on by default)

Host keys & public-key authentication

Recommended

• ssh-ed25519
• ecdsa-sha2-nistp256, ecdsa-sha2-nistp384, ecdsa-sha2-nistp521
• rsa-sha2-256, rsa-sha2-512
• ssh-rsa (SHA-1)
• OpenSSH certificates

Authentication methods

• publickey
• password
• keyboard-interactive
• none
• OpenSSH certificate authentication

Features

• Local port forwarding (direct-tcpip)
• Remote port forwarding (forward-tcpip)
• Local UNIX socket forwarding (direct-streamlocal, client only)
• Remote UNIX socket forwarding (forward-streamlocal)
• AsyncRead / AsyncWrite-able channels
• OpenSSH agent forwarding channels
• OpenSSH keepalive request handling
• OpenSSH server-sig-algs extension
• PuTTY PPK key format
• Pageant support (Windows)

Safety

Russh is built to withstand malicious/misbehaving peers.

• deny(clippy::unwrap_used)
• deny(clippy::expect_used)
• deny(clippy::indexing_slicing)
• deny(clippy::panic)

Exceptions are reviewed and justified manually.

Unsafe code

• cryptovec uses unsafe for faster copying, initialization, and binding to native APIs.

Ecosystem

• russh-sftp - server-side and client-side SFTP subsystem support for russh; see russh/examples/sftp_server.rs or russh/examples/sftp_client.rs.
• async-ssh2-tokio - simple high-level API for running commands over SSH.

Adopters

• HexPatch - A binary patcher and editor written in Rust with a terminal user interface (TUI).
  • Uses russh::client and russh_sftp::client to allow remote editing of files.
• kartoffels - A game where you're given a potato and your job is to implement a firmware for it.
  • Uses russh::server to deliver the game, using ratatui as the rendering engine.
• kty - The terminal for Kubernetes.
  • Uses russh::server to deliver the ratatui based TUI and russh_sftp::server to provide scp based file management.
• lapdev - Self-hosted remote dev environment.
  • Uses russh::server to construct a proxy into your development environment.
• medusa - A fast and secure multi-protocol honeypot.
  • Uses russh::server to be the basis of the honeypot.
• rebels-in-the-sky - P2P terminal game about space pirates playing basketball across the galaxy.
  • Uses russh::server to deliver the game, using ratatui as the rendering engine.
• warpgate - Smart SSH, HTTPS and MySQL bastion that requires no additional client-side software.
  • Uses russh::server in addition to russh::client as part of the smart SSH functionality.
• Devolutions Gateway - Establish a secure entry point for internal or external segmented networks that require authorized just-in-time (JIT) access.

History

Russh began as a fork of Thrussh by Pierre-Étienne Meunier, originally extended to provide the SSH backend for Warpgate.

It has since been substantially reworked, and is maintained independently. Russh prioritises safety-by-default and broad algorithm interoperability. Thanks to Pierre-Étienne and the Thrussh contributors for the original foundation.

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!