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_server_start）

函数原型（port/inc/ssh_server.h）：

os_err_t ssh_server_start(char *port) ;

参数	说明
port	服务端口号，字符串形式，取值范围 [1, 65535]。传 NULL 使用默认端口 22
返回
OS_SUCCESS	启动成功
EBUSY	已经启动（内部用静态标志 ssh_server_started 判断，重复启动返回 EBUSY）
OS_FAILURE	启动失败

关键理解（防重复启动）：ssh_server.c 用静态变量 ssh_server_started 记录启动状态，ssh_server_start 开头 if (1 == ssh_server_started) 则返回 EBUSY，避免重复创建服务线程；停止时（ssh_server_stop）将其清零。

2.2 服务停止（ssh_server_stop）

函数原型（port/inc/ssh_server.h）：

os_err_t ssh_server_stop(void);

Shell 命令 ssh_stop 内部即调用 ssh_server_stop（源码 ssh_server.c 第384行 SH_CMD_EXPORT(ssh_stop, ssh_server_stop, "stop ssh server")）。

关键理解：ssh_server_stop 关闭监听 Socket 并清理服务线程，同时把 ssh_server_started 清零，使后续可再次 ssh_server_start。

---

三、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 服务以节省资源

---

📝 本节小结

核心要点回顾

1. 库定位：libSSH 基于 libssh-0.9.6（components/security/libssh/libssh-0.9.6/），OneOS 适配在 port/（ssh_server.c/ssh_password.c/ssh_server.h），提供 SSH 服务端能力。
2. 核心 API：ssh_server_start(char *port)（返回 os_err_t，内部静态标志 ssh_server_started 防重复启动，返回 EBUSY）、ssh_server_stop(void)、ssh_setpassword(char *old_pd, char *new_pd)。
3. 三个 Shell 命令：ssh_start [port]（启动）、ssh_stop（停止，内部调 ssh_server_stop）、ssh_setpassword <old> <new>（改密），均用 SH_CMD_EXPORT 注册。
4. Kconfig：SECURITY_USING_LIBSSH（select OS_USING_LIBC_ADAPTER/OS_USING_PTHREADS/OS_USING_VFS/NET_USING_BSD/SECURITY_USING_MBEDTLS 等）+ LIBSSH_LOGIN_USERNAME（默认 user）+ LIBSSH_LOGIN_PASSWORD（默认 password）。
5. 密码存储：初始密码来自 Kconfig；运行时 ssh_setpassword 修改后持久化到 /etc/ssh/shadow（SSH_FOLDER "/etc/ssh/" + SHADOW_NAME "shadow"），重启固件仍有效；删除该文件则恢复 Kconfig 默认密码。
6. 依赖：libSSH 密码学依赖 MBED TLS（Kconfig 自动 select SECURITY_USING_MBEDTLS）。

关键易错点速查

易错点	正确做法
重复调用 ssh_server_start	已启动时返回 EBUSY → 先判返回，需要重启时先 ssh_server_stop
停止用 ssh_stop(...) 带参数	ssh_stop 无参数，内部调 ssh_server_stop → Shell 里直接 ssh_stop
以为停止 API 是 ssh_stop	底层函数是 ssh_server_stop()（ssh_stop 只是其 Shell 封装）
ssh_setpassword 新旧密码顺序颠倒	是 <old> <new>，先旧后新 → 严格按 ssh_setpassword old new
密码不满足长度要求	需 6~20 字符 → 修改前确认长度
改了密码但没写 shadow 文件	ssh_password.c 用 `open(...O_CREAT
删除 shadow 后密码未恢复	删除后回退 Kconfig 密码 → 需确认删除的是 /etc/ssh/shadow 且重新登录生效
忘开依赖组件	SECURITY_USING_LIBSSH 自动 select 依赖 → 但需确保 VFS、NET_USING_BSD 实际生效
生产环境用默认密码 user/password	默认弱口令有风险 → 生产务必用 ssh_setpassword 改密

下一步

• 7.4 GUI 图形界面：libSSH 已完成远程 Shell 安全访问，下一节进入 GUI 图形界面组件，掌握 OneOS 图形系统与 UI 开发。