# ssh-rs ✨

[![Build](https://github.com/1148118271/ssh-rs/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/1148118271/ssh-rs/actions/workflows/build.yml)
[![API Docs](https://docs.rs/ssh-rs/badge.svg)](https://docs.rs/ssh-rs/latest/)
[![LICENSE](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)

[English](https://github.com/1148118271/ssh-rs/blob/main/README.md)  |  [简体中文](https://github.com/1148118271/ssh-rs/blob/main/README_ZH.md)

Rust implementation of ssh2.0 client.

If you encounter any problems in use, welcome [issues](https://github.com/1148118271/ssh-rs/issues)
or [PR](https://github.com/1148118271/ssh-rs/pulls) .

## Content

<!-- @import "[TOC]" {cmd="toc" depthFrom=1 depthTo=6 orderedList=false} -->

<!-- code_chunk_output -->

* [ssh-rs ✨](#ssh-rs)
  + [Content](#content)
  + [Connection method：](#connection-method)
    - [1. Password:](#1-password)
    - [2. Public key:](#2-public-key)
      - [1. Use key file path：](#1-use-key-file-path)
      - [2. Use key string：](#2-use-key-string)
      - [3. Use them together](#3-use-them-together)
  + [Enable global logging：](#enable-global-logging)
  + [Set timeout：](#set-timeout)
  + [How to use：](#how-to-use)
  + [Algorithm support：](#algorithm-support)
    - [1. Kex algorithms](#1-kex-algorithms)
    - [2. Server host key algorithms](#2-server-host-key-algorithms)
    - [3. Encryption algorithms (client to server)](#3-encryption-algorithms-client-to-server)
    - [4. Encryption algorithms (server to client)](#4-encryption-algorithms-server-to-client)
    - [5. Mac algorithms (client to server)](#5-mac-algorithms-client-to-server)
    - [6. Mac algorithms (server to client)](#6-mac-algorithms-server-to-client)
    - [7. Compression algorithms (client to server)](#7-compression-algorithms-client-to-server)
    - [8. Compression algorithms (server to client)](#8-compression-algorithms-server-to-client)
    - [☃️ Additional algorithms will continue to be added.](#️-additional-algorithms-will-continue-to-be-added)

<!-- /code_chunk_output -->

## Connection method：

### 1. Password:

```rust
use ssh;

let mut session = ssh::create_session()
    .username("ubuntu")
    .password("password")
    .connect("127.0.0.1:22")
    .unwrap();
```

### 2. Public key:

* **Currently, only RSA, ED25519 keys/key files are supported.**

#### 1. Use key file path：

```rust
// pem format key path -> /xxx/xxx/id_rsa
// the content of the keyfile shall begin with
//      -----BEGIN RSA PRIVATE KEY----- / -----BEGIN OPENSSH PRIVATE KEY-----
// and end with
//       -----END RSA PRIVATE KEY----- / -----END OPENSSH PRIVATE KEY-----
// simply generated by `ssh-keygen -t rsa -m PEM -b 4096`
use ssh;

let mut session = ssh::create_session()
    .username("ubuntu")
    .private_key_path("./id_rsa")
    .connect("127.0.0.1:22")
    .unwrap();
```

#### 2. Use key string：

```rust
// pem format key string:
//      -----BEGIN RSA PRIVATE KEY----- / -----BEGIN OPENSSH PRIVATE KEY-----
// and end with
//       -----END RSA PRIVATE KEY----- / -----END OPENSSH PRIVATE KEY-----
use ssh;

let mut session = ssh::create_session()
    .username("ubuntu")
    .private_key("rsa_string")
    .connect("127.0.0.1:22")
    .unwrap();
```

#### 3. Use them together

* According to the implementation of OpenSSH, it will try public key first and fallback to password. So both of them can be provided.

```Rust
use ssh;

let mut session = ssh::create_session()
    .username("username")
    .password("password")
    .private_key_path("/path/to/rsa")
    .connect("127.0.0.1:22")
    .unwrap();
```

## Enable global logging：

* This crate now uses the `log` compatible `tracing` for logging functionality

```rust
use tracing::Level;
use tracing_subscriber::FmtSubscriber;

// this will generate some basic event logs
// a builder for `FmtSubscriber`.
let subscriber = FmtSubscriber::builder()
    // all spans/events with a level higher than INFO (e.g, info, warn, etc.)
    // will be written to stdout.
    .with_max_level(Level::INFO)
    // completes the builder.
    .finish();

tracing::subscriber::set_global_default(subscriber).expect("setting default subscriber failed");
```

## Set timeout：

* Only global timeouts per r/w are currently supported.

```rust
use ssh;

let _listener = TcpListener::bind("127.0.0.1:7777").unwrap();

match ssh::create_session()
    .username("ubuntu")
    .password("password")
    .private_key_path("./id_rsa")
    .timeout(Some(std::time::Duration::from_secs(5)))
    .connect("127.0.0.1:7777")
{
    Err(e) => println!("Got error {}", e),
    _ => unreachable!(),
}
```

## How to use：

* Examples can be found under [examples](examples)

1. [Execute a command](examples/exec/src/main.rs)
2. [Scp files](examples/scp/src/main.rs)
3. [Run a shell](examples/shell/src/main.rs)
4. [Run an interactive shell](examples/shell_interactive/src/main.rs)
5. [Connect ssh server w/o a tcp stream](examples/bio/src/main.rs)
6. [Cofigure your own algorithm list](examples/customized_algorithms/src/main.rs)

## Algorithm support：

### 1. Kex algorithms

* `curve25519-sha256`
* `ecdh-sha2-nistp256`
* `diffie-hellman-group14-sha256`
* `diffie-hellman-group14-sha1`
* `diffie-hellman-group1-sha1` (behind feature "deprecated-dh-group1-sha1")

### 2. Server host key algorithms

* `ssh-ed25519`
* `rsa-sha2-256`
* `rsa-sha2-512`
* `rsa-sha` (behind feature "deprecated-rsa-sha1")
* `ssh-dss` (behind feature "deprecated-dss-sha1")


### 3. Encryption algorithms

* `chacha20-poly1305@openssh.com`
* `aes128-ctr`
* `aes192-ctr`
* `aes256-ctr`
* `aes128-cbc` (behind feature "deprecated-aes-cbc")
* `aes192-cbc` (behind feature "deprecated-aes-cbc")
* `aes256-cbc` (behind feature "deprecated-aes-cbc")
* `3des-cbc` (behind feature "deprecated-des-cbc")

### 4. Mac algorithms

* `hmac-sha2-256`
* `hmac-sha2-512`
* `hmac-sha1`

### 5. Compression algorithms

* `none`
* `zlib@openssh.com`
* `zlib` (behind feature "zlib")

---

### ☃️ Additional algorithms will continue to be added.