ssh-rs 0.3.1

# 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_rs::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_rs::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_rs::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_rs::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：


* There are two APIs to enable logs, basicly `enable_log()` will set the log level to `INFO`, and `debug()` will set it to `Debug`

* But you can implement your own logger as well.

```rust
use ssh_rs::ssh;
// this will generate some basic event logs
ssh::enable_log();
// this will generate verbose logs
ssh::debug()
```

## Set timeout：


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

```rust
use ssh_rs::ssh;

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

match ssh::create_session()
    .username("ubuntu")
    .password("password")
    .private_key_path("./id_rsa")
    .timeout(5 * 1000)
    .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 "dangerous-dh-group1-sha1")

### 2. Server host key algorithms


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

### 3. Encryption algorithms (client to server)


* `chacha20-poly1305@openssh.com`
* `aes128-ctr`

### 4. Encryption algorithms (server to client)


* `chacha20-poly1305@openssh.com`
* `aes128-ctr`

### 5. Mac algorithms (client to server)


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

### 6. Mac algorithms (server to client)


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

### 7. Compression algorithms (client to server)


* `none`

### 8. Compression algorithms (server to client)


* `none`

---

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