2026/7/19大约 3 分钟常用组件组件安全SSH远程登录
7.3.3 libSSH 组件
📚 本节导读
学习时长：约 20 分钟
难度级别：⭐⭐⭐☆☆
前置知识：第 7.3.1 节 MBED TLS、SSH 协议基础
🎯 学习目标
- 理解 libSSH 在 OneOS 中的角色和功能
- 掌握 SSH 服务的启动、停止和密码管理
- 学会通过 SSH 远程登录 OneOS 设备
- 了解 libSSH 的 Kconfig 配置和 Shell 命令
一、libSSH 概述
libSSH 是 OneOS 集成的 SSH（Secure Shell）服务端组件，基于 libssh-0.9.6 开源库，位于 components/security/libssh/。它允许用户通过 SSH 协议远程登录 OneOS 设备，进行安全的命令行操作和文件传输。
核心功能
| 功能 | 描述 |
|---|---|
| SSH 服务端 | 在设备上运行 SSH Server，接受远程连接 |
| 密码认证 | 通过用户名和密码进行身份验证 |
| 远程 Shell | 登录后获得 OneOS Shell 交互环境 |
| 密码管理 | 支持运行时修改密码，持久化存储 |
二、核心 API
2.1 服务管理
/* 启动 SSH 服务 */
os_err_t ssh_server_start(char *port);| 参数 | 说明 |
|---|---|
port | 服务端口号，字符串形式，取值范围 [1, 65535]。传 NULL 使用默认端口 22 |
| 返回 | |
OS_SUCCESS | 启动成功 |
EBUSY | 已经启动 |
OS_FAILURE | 启动失败 |
2.2 服务停止
/* 停止 SSH 服务（通过 Shell 命令调用） */
ssh_stop // Shell 命令，无参数三、Shell 命令
libSSH 提供 3 个 Shell 命令：
| 命令 | 格式 | 说明 |
|---|---|---|
ssh_start | ssh_start [port] | 启动 SSH 服务，默认端口 22 |
ssh_stop | ssh_stop | 停止 SSH 服务 |
ssh_setpassword | ssh_setpassword <old> <new> | 修改登录密码 |
使用示例
# 在 OneOS 设备 Shell 中
$ ssh_start 2222
SSH server started on port 2222
$ ssh_setpassword old_pass new_pass
Password changed successfully
$ ssh_stop
SSH server stopped从 PC 远程连接
# 在 PC 终端中
$ ssh user@192.168.1.100 -p 2222
user@192.168.1.100's password:
Welcome to OneOS Shell!
$ help
$ ls
$ exit四、Kconfig 配置
配置菜单
(Top) → Components → Security → libSSH
[*] Enable libSSH
(user) set username
(password) set password配置项说明
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
SECURITY_USING_LIBSSH | bool | n | 启用 libSSH 组件 |
LIBSSH_LOGIN_USERNAME | string | user | 默认登录用户名（1-10 字符） |
LIBSSH_LOGIN_PASSWORD | string | password | 默认登录密码（6-20 字符） |
五、密码管理
5.1 密码存储
- 初始密码通过 Kconfig 配置（
LIBSSH_LOGIN_PASSWORD） - 运行时通过
ssh_setpassword命令修改 - 修改后的密码保存在
/etc/ssh/shadow文件中 - 重新烧录固件后，密码依然有效（持久化存储）
- 删除
/etc/ssh/shadow文件后，恢复使用 Kconfig 配置的密码
5.2 密码修改示例
# 在设备端或 SSH 客户端中执行
$ ssh_setpassword old_password new_password
# 密码要求：6-20 个字符六、使用场景
6.1 远程调试
SSH 提供加密的远程 Shell 访问，比串口调试更灵活：
- 无需物理连接设备
- 支持远程固件升级和配置修改
- 安全的加密传输
6.2 设备维护
- 远程查看日志和系统状态
- 修改运行参数
- 文件传输和管理
6.3 安全注意事项
- 生产环境建议修改默认密码
- 限制 SSH 访问的 IP 地址范围
- 定期更换密码
- 不需要时关闭 SSH 服务以节省资源
📝 本节小结
本节介绍了 OneOS libSSH 组件：
- libSSH 基于 libssh-0.9.6，提供 SSH 服务端功能
- 核心 API：
ssh_server_start()启动服务，通过 Shell 命令管理 - Shell 命令：
ssh_start/ssh_stop/ssh_setpassword三个命令 - 密码管理：支持持久化存储，修改后保存在
/etc/ssh/shadow - 适用场景：远程调试、设备维护、安全 Shell 访问