kruton/ssh-proto
GitHub: kruton/ssh-proto
用 Kotlin 协程和声明式协议定义构建的现代 SSH 客户端库，覆盖完整的传输层协议并提供交互式 shell、多种端口转发及 Agent 转发能力。
Stars: 3 | Forks: 1
# ConnectBot SSH 客户端库 *(开发中)*
*目前这是一个正在进行中的工作，不建议在生产环境中使用。*
这是使用 Kotlin 构建的 ConnectBot SSH 库。在内部，它使用协程、协议定义文件和状态机来运行 SSH 协议。它目前可以连接到 SSH 服务器、进行身份验证，并提供交互式 shell 会话。
协议解析使用声明式 Kaitai Struct 规范，从 `.ksy` 定义自动生成代码。内部状态机在 KStateMachine 中定义，以便将协议状态与响应状态更改而运行的代码清晰地分离开来。
## 功能特性
- **SSH 客户端**：连接、身份验证、打开 shell 会话、读/写数据
- **协议解析**：完整的 SSH 传输协议覆盖（RFC 4250-4256、4419、5656、8308、8709、8731、9142）
- **通道 I/O**：带有 PTY 的交互式 shell、stdout/stderr 流、流控制
- **端口转发**：本地、远程和动态 (SOCKS5) 端口转发
- **Agent 转发**：转发 SSH agent 请求并支持会话绑定
- **传输层**：可插拔的传输层（通过 Ktor 的 TCP，或自定义）
## 算法支持
### 身份验证
- `keyboard-interactive`
- `password`
- `publickey`
### 主机密钥
- `ssh-ed25519` ([RFC 8709](https://tools.ietf.org/html/rfc8709))
- `ssh-ed448` ([RFC 8709](https://tools.ietf.org/html/rfc8709))
- `ecdsa-sha2-nistp256` ([RFC 5656](https://tools.ietf.org/html/rfc5656#section-3))
- `ecdsa-sha2-nistp384` ([RFC 5656](https://tools.ietf.org/html/rfc5656#section-3))
- `ecdsa-sha2-nistp521` ([RFC 5656](https://tools.ietf.org/html/rfc5656#section-3))
- `rsa-sha2-512` ([RFC 8332](https://tools.ietf.org/html/rfc8332#section-3))
- `rsa-sha2-256` ([RFC 8332](https://tools.ietf.org/html/rfc8332#section-3))
- `ssh-rsa` ([RFC 4253](https://tools.ietf.org/html/rfc4253#section-8.1))
### 密钥交换
- `mlkem768x25519-sha256` ([draft-ietf-sshm-mlkem-hybrid-kex](https://datatracker.ietf.org/doc/draft-ietf-sshm-mlkem-hybrid-kex/) (取决于 JEP-496 支持)
- `curve25519-sha256` ([RFC 8731](https://tools.ietf.org/html/rfc8731))
- `ecdh-sha2-nistp521` ([RFC 5656](https://tools.ietf.org/html/rfc5656#section-4))
- `ecdh-sha2-nistp384` ([RFC 5656](https://tools.ietf.org/html/rfc5656#section-4))
- `ecdh-sha2-nistp256` ([RFC 5656](https://tools.ietf.org/html/rfc5656#section-4))
- `diffie-hellman-group18-sha512` ([RFC 8268](https://tools.ietf.org/html/rfc8268))
- `diffie-hellman-group16-sha512` ([RFC 8268](https://tools.ietf.org/html/rfc8268))
- `diffie-hellman-group14-sha256` ([RFC 8268](https://tools.ietf.org/html/rfc8268))
- `diffie-hellman-group-exchange-sha256` ([RFC 4419](https://tools.ietf.org/html/rfc4419))
- `diffie-hellman-group14-sha1` ([RFC 4253](https://tools.ietf.org/html/rfc4253#section-8.1))
- `diffie-hellman-group-exchange-sha1` ([RFC 4419](https://tools.ietf.org/html/rfc4419))
- `diffie-hellman-group1-sha1` ([RFC 4253](https://tools.ietf.org/html/rfc4253#section-8.1))
### 加密
- `chacha20-poly1305@openssh.com` ([draft-ietf-sshm-chacha20-poly1305](https://datatracker.ietf.org/doc/html/draft-ietf-sshm-chacha20-poly1305))
- `aes256-gcm@openssh.com` ([draft-miller-sshm-aes-gcm](https://datatracker.ietf.org/doc/html/draft-miller-sshm-aes-gcm))
- `aes128-gcm@openssh.com` ([draft-miller-sshm-aes-gcm](https://datatracker.ietf.org/doc/html/draft-miller-sshm-aes-gcm))
- `aes256-ctr` ([RFC 4344](https://tools.ietf.org/html/rfc4344#section-4))
- `aes128-ctr` ([RFC 4344](https://tools.ietf.org/html/rfc4344#section-4))
- `aes256-cbc` ([RFC 4253](https://tools.ietf.org/html/rfc4253#section-6.3))
- `aes128-cbc` ([RFC 4253](https://tools.ietf.org/html/rfc4253#section-6.3))
- `3des-cbc` ([RFC 4253](https://datatracker.ietf.org/doc/html/rfc4253#section-6.3))
### MACs
- `hmac-sha2-512-etm@openssh.com` ([OpenSSH PROTOCOL](
https://github.com/openssh/openssh-portable/blob/60b909fb110f77c1ffd15cceb5d09b8e3f79b27e/PROTOCOL#L50))
- `hmac-sha2-256-etm@openssh.com` ([OpenSSH PROTOCOL](
https://github.com/openssh/openssh-portable/blob/60b909fb110f77c1ffd15cceb5d09b8e3f79b27e/PROTOCOL#L50))
- `hmac-sha1-etm@openssh.com` ([OpenSSH PROTOCOL](
https://github.com/openssh/openssh-portable/blob/60b909fb110f77c1ffd15cceb5d09b8e3f79b27e/PROTOCOL#L50))
- `hmac-sha2-512` ([RFC 4868](https://tools.ietf.org/html/rfc4868))
- `hmac-sha2-256` ([RFC 4868](https://tools.ietf.org/html/rfc4868))
- `hmac-sha1` ([RFC 4253](https://tools.ietf.org/html/rfc4253))
## 快速入门
### 构建
```
./gradlew build
```
### 使用测试命令行客户端
有一个“testapp”可让你通过测试客户端应用来试用该库。
你可以通过运行以下命令来使用它：
```
./gradlew :testapp:installDist
./testapp/build/install/testapp/bin/testapp user@host
./testapp/build/install/testapp/bin/testapp user@host -p 2222
# 启用更多 debug logging:
./testapp/build/install/testapp/bin/testapp -d user@host
```
### 库 API
```
val client = SshClient("example.com", 22)
client.connect()
client.authenticatePassword("user", "pass")
val session = client.openSession()
session.requestPty()
session.requestShell()
// Read/write
session.write("ls\n".toByteArray())
val output = session.read() // ByteArray? (null on EOF)
// Or use coroutine channels directly
session.stdout // ReceiveChannel
session.stderr // ReceiveChannel
// Clean up
session.close()
client.disconnect()
```
### SSH Agent 转发
启用 SSH agent 转发以允许远程服务器使用你的密钥：
```
// Implement an agent provider
class MyAgentProvider : AgentProvider {
override suspend fun getIdentities(): List {
val keyBlob = loadPublicKeyBlob()
return listOf(AgentIdentity(keyBlob, "my-key"))
}
override suspend fun signData(context: AgentSigningContext): ByteArray? {
// Show approval UI to user with session context
val approved = showSigningPrompt(
"Remote server ${context.serverHostKey.toHex()} wants to use your key",
"Session bound: ${context.isBound}"
)
return if (approved) {
signWithPrivateKey(context.publicKeyBlob, context.dataToSign)
} else {
null // Deny the request
}
}
}
// Enable agent forwarding
val client = SshClient("bastion.example.com")
client.connect()
client.authenticatePassword("user", "pass")
client.enableAgentForwarding(MyAgentProvider())
// Now remote servers can use your agent through forwarding
val session = client.openSession()
session.requestShell()
// When you SSH from bastion to another server, it can request signatures
```
## 兼容性测试
该库使用 Docker（通过 Testcontainers）针对多种 SSH 服务器实现进行了测试：
- **OpenSSH** 9.9p2 — 完整的集成测试，包括端口转发
- **AsyncSSH** (Python) — 针对加密算法、密钥交换、MAC 和公钥身份验证的兼容性测试
- **Dropbear** — 兼容性测试，包括 ML-KEM 后量子密钥交换
使用以下命令运行集成测试：`./gradlew :sshlib:test`（需要 Docker）。
## 当前局限性
- 不支持 SFTP
- 仅限客户端（无服务器实现）
## 许可证
Apache License 2.0 - 详见 LICENSE 文件
## 版权
版权所有 2019-2025，[Kenny Root](https://github.com/kruton/)
标签：Kaitai Struct, Kotlin, Kotlin库, KStateMachine, Ktor, RFC 4250, SOCKS5, SSH, SSH代理, SSH客户端, 主机密钥, 协程, 后台面板检测, 密码学, 密钥交换, 开源库, 手动系统调用, 搜索引擎爬虫, 状态机, 端口转发, 网络安全, 网络编程, 请求拦截, 远程Shell, 隐私保护