KarpelesLab/puressh
GitHub: KarpelesLab/puressh
纯 Rust 实现的 SSH 协议库与 CLI 套件，提供无 C 依赖、无 unsafe 的安全远程访问解决方案。
Stars: 0 | Forks: 0
# puressh
[](https://github.com/KarpelesLab/puressh/actions/workflows/ci.yml)
[](https://crates.io/crates/puressh)
[](https://docs.rs/puressh)
[](LICENSE)
一个纯粹的 Rust [SSH](https://datatracker.ietf.org/doc/html/rfc4251) (Secure Shell)
协议库和 CLI 套件，秉承了 [libssh](https://www.libssh.org/) 的精神，
所有的密码学基础组件均构建于 [`purecrypto`](https://crates.io/crates/purecrypto) 之上。
依赖树中没有 C 依赖，没有 FFI，并且
库本身不包含任何 `unsafe`（可选的 `ffi` feature 是唯一出现 `unsafe` 的地方，用于 C ABI 接口）。
## 包含内容
- **库** — 无 I/O 的协议核心，以及高级 `client` / `server` API。
- **CLI 套件** — 基于该库构建的直接可用的 `ssh`、`sftp`、`scp`、`sshd` 和 `ssh-keygen` 二进制程序。
- **C ABI** — 可选的 `ffi` feature，暴露 `pcssh_*` C 接口
(`staticlib` / `cdylib`)，并为非 UTF-8 路径提供了字节路径的 SFTP 变体。
## 目标
- **纯粹的 Rust，没有 FFI 依赖。** 密码学来源于 `purecrypto`；网络功能来源于
`std::net`。没有任何东西链接 C。
- **支持 `no_std`。** 协议核心（packet 编解码、KEX、cipher/MAC
适配器、密钥解析）可以在没有 `std` 的情况下构建；只有便捷的 I/O 和
client/server/CLI 层需要它。
- **现代算法优先**，包括后量子混合 KEX
(`mlkem768x25519-sha256`)。只有在仍然有利于互操作性的情况下，才会保留遗留算法。
- **可审计的范围。** 模块小巧，公共类型精简，每个算法
标识符都能追溯至其对应的 RFC。
## 支持的算法
| 类别 | 算法 |
|-------------|------------------------------------------|
| KEX (PQ) | `mlkem768x25519-sha256` (ML-KEM-768 + X25519 混合) |
| KEX | `curve25519-sha256`, `curve25519-sha256@libssh.org` |
| KEX | `ecdh-sha2-nistp{256,384,521}` |
| KEX | `diffie-hellman-group{14,16,18}-sha{256,512}` |
| KEX | `diffie-hellman-group-exchange-sha256` |
| 主机密钥 | `ssh-ed25519` |
| 主机密钥 | `ecdsa-sha2-nistp{256,384,521}` |
| 主机密钥 | `rsa-sha2-256`, `rsa-sha2-512`, `ssh-rsa` (通过 `server-sig-algs` 自动升级) |
| 加密算法 | `chacha20-poly1305@openssh.com` |
| 加密算法 | `aes{128,256}-gcm@openssh.com` |
| 加密算法 | `aes{128,192,256}-ctr` |
| MAC | `hmac-sha2-{256,512}` (+ `-etm@openssh.com` 变体) |
| 压缩 | `none`, `zlib`, `zlib@openssh.com` (延迟) |
| 认证 | `none`, `password`, `publickey`, `keyboard-interactive`, `hostbased` |
| 扩展 | RFC 8308 `ext-info` / `server-sig-algs` |
## Cargo 特性
| 特性 | 默认 | 描述 |
|----------------|---------|--------------------------------------------------------|
| `std` | 是 | I/O 辅助、OS RNG、`std::error::Error` |
| `alloc` | 是 | 堆分配类型（由 `std` 暗示） |
| `client` | 是 | 高级客户端 API |
| `server` | 是 | 高级服务端 API |
| `compress` | 是 | 通过 `compcol` 实现 `zlib` 压缩 |
| `pam` | 是 | 用于 `sshd` 的 PAM 会话集成（仅限 Linux） |
| `multichannel` | 是 | 并发多通道客户端 (`SharedClient`, `SftpSession`) |
| `ffi` | 否 | C ABI 接口 (`pcssh_*`)；包含 `client` + `multichannel` |
为 `no_std` 禁用默认特性：
```
puressh = { version = "0.0.5", default-features = false, features = ["alloc"] }
```
## 快速开始
```
use puressh::client::{Client, Config};
fn main() -> Result<(), puressh::Error> {
// `Config::insecure()` trusts any host key — fine for a throwaway example.
// Use `Config::with_known_hosts(store)` for OpenSSH-style strict checking.
let mut c = Client::connect("example.com:22", Config::insecure())?;
c.authenticate_password("alice", "hunter2")?;
let out = c.exec("uname -a")?;
println!("{}", String::from_utf8_lossy(&out.stdout));
println!("exit: {:?}", out.exit_status);
Ok(())
}
```
对于并发通道（在一个连接上使用多个 SFTP / exec / shell / tunnel 句柄），
请使用 `multichannel` 层的 `SharedClient` 及其
`sftp()` / `exec_stream()` / `shell()` / `open_direct_tcpip()` 辅助方法。
## CLI 二进制程序
使用默认特性构建：
```
cargo build --release
```
| 二进制程序 | 用途 |
|--------------|------------------------------------------------------------|
| `ssh` | 交互式 shell / `exec`，端口转发 (`-L`/`-R`)，agent 和 X11 转发 |
| `sftp` | 交互式 SFTP 客户端 |
| `scp` | 通过 SSH 复制文件 |
| `sshd` | SSH 服务端守护进程 (PTY，Linux 上的 PAM 会话) |
| `ssh-keygen` | 密钥生成和 OpenSSH 密钥文件管理 |
它们都支持 `ssh_config`（包括 `Match` 块和 `Include`），
`known_hosts`，以及带有括号的 IPv6 主机语法 (`[2001:db8::1]:22`)。
## 模块布局
```
src/
├── lib.rs public re-exports
├── error.rs Error / Result
├── format/ SSH wire format (Reader, Writer, mpint, name-list)
├── transport/ binary packet protocol, version exchange, KEX runner
├── kex/ curve25519, ecdh-nistp*, group-DH, GEX, mlkem768x25519
├── cipher/ aes-ctr, aes-gcm, chacha20-poly1305
├── mac/ hmac-sha2-* (incl. -etm)
├── hostkey/ ed25519, ecdsa-*, rsa-*
├── auth/ userauth state machine (RFC 4252)
├── channel/ RFC 4254 channels
├── key/ OpenSSH public/private key files
├── known_hosts/ known_hosts store + verification
├── config/ ssh_config / sshd_config parsing (Match, Include)
├── compress/ zlib / zlib@openssh.com
├── forwarding/ direct-tcpip, reverse, agent, X11
├── sftp/ SFTP client + server (with OpenSSH @openssh.com extensions)
├── scp/ SCP protocol
├── agent/ ssh-agent client protocol
├── shared.rs SharedClient (multichannel layer)
├── ffi/ C ABI surface (feature `ffi`)
├── client.rs high-level client API (feature `client`)
├── server.rs high-level server API (feature `server`)
└── bin/ ssh, sftp, scp, sshd, ssh-keygen
```
## MSRV
`puressh` 遵循 `purecrypto` 的 MSRV：**Rust 1.95**。
如果 `cargo check` 失败并提示 *"rustc X is not supported … requires rustc 1.95"*，
请升级您的工具链。
## 实现状态
| 层级 | 状态 |
|-----------------------------|--------|
| 通信协议格式 (`format/`) | ✅ 读取器、写入器、mpint、name-list |
| 二进制数据包编解码器 | ✅ 加密/解密、ETM、重新生成密钥 |
| 版本交换 | ✅ |
| KEX（上述所有算法） | ✅ 包含 PQ 混合 + GEX |
| 加密算法 / MACs | ✅ |
| 主机密钥 (ed25519/ecdsa/rsa) | ✅ 包含 `server-sig-algs` 升级 |
| OpenSSH 密钥文件解析 | ✅ 包含加密密钥 (`bcrypt_pbkdf`) |
| 用户认证 (RFC 4252) | ✅ password / publickey / kbd-int / hostbased |
| OpenSSH 证书 | ✅ 主机 + 用户证书，`@cert-authority`，`TrustedUserCAKeys`，KRL (`RevokedKeys`) |
| 通道 / 会话 | ✅ |
| 客户端 API | ✅ |
| 服务端 API | ✅ |
| SFTP 客户端与服务端 | ✅ 包含 OpenSSH 扩展 |
| SCP | ✅ |
| 端口 / agent / X11 转发 | ✅ |
| `known_hosts` | ✅ |
| `ssh_config` (Match/Include) | ✅ |
| C ABI (`ffi`) | ✅ 可选 |
**非目标。** 少数 OpenSSH 指令被故意设置为不支持，并且会被严格模式拒绝，而不是被静默忽略：`PermitTunnel`（tun/tap 设备转发）和外部命令 `Subsystem` 条目。
## 安全性
这是尚未进行独立第三方审计的 1.0 版本之前的软件。
它构建于 `purecrypto` 之上，并经过了内部安全审查
（主机密钥信任处理、转发默认拒绝策略、SFTP jail
强化、机密信息清零、DoS 限制）。在任何重要的场景中，请使用严格的 `known_hosts` 策略
(`Config::with_known_hosts`)，并在部署到安全敏感的环境之前进行审查。
## 许可证
根据以下任一许可证进行双重授权
- Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) 或
)
- MIT license ([LICENSE-MIT](LICENSE-MIT) 或 )
由您选择。
标签：Rust库, SSH协议, 加密算法, 可视化界面, 网络通信, 通知系统