Paramiko SSH 服务端开发指南:从 ServerInterface 到自定义 SSH 服务器的完整实现
Paramiko SSH 服务端开发指南:从 ServerInterface 到自定义 SSH 服务器的完整实现
Paramiko 是 Python 生态中原生的 SSHv2 协议库,其 server 模块 通过 ServerInterface 抽象类为开发者提供了在服务端模式下完全控制 SSH 会话行为的接口。本文将以该模块为核心,系统讲解如何基于 Paramiko 编写一个自定义 SSH 服务器:从身份认证策略(密码、公钥、keyboard-interactive、GSSAPI)到通道请求处理(pty、shell、exec、子系统、端口转发),再到 InteractiveQuery 交互认证与 SubsystemHandler 子系统扩展的完整机制,并辅以仓库内 demo_server.py 的真实示例与 Transport 的底层调用链,帮助读者掌握可运行的完整实现方案。
一、server 模块定位:服务端模式的接口契约
ServerInterface 定义于 paramiko/server.py,其核心定位是"控制 Paramiko 在服务端模式下的行为"。它是一组回调方法的集合:当 SSH 客户端发起认证、请求通道、请求端口转发等操作时,Paramiko 的主线程会调用 ServerInterface 上的对应方法,由开发者决定允许还是拒绝。
源码注释明确强调了一个重要的使用约束:这些方法由 Paramiko 的主线程调用,因此不应在其中执行耗时操作(任何阻塞或 sleep 都不合适)。实际业务逻辑应当放到通道建立后的独立处理中,例如通过 SubsystemHandler 的独立线程执行。
从设计上看,ServerInterface 是一份"安全策略清单"——所有方法的默认实现都是拒绝一切(如 check_channel_request 默认返回 OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED,check_auth_password 默认返回 AUTH_FAILED)。开发者必须显式地覆写需要开放的能力,这种"默认拒绝"的接口设计天然符合 SSH 服务器的安全最小化原则。
与 Transport 的协作关系
ServerInterface 本身不处理网络协议细节。服务端的完整生命周期由 Transport 驱动:
- 将已接受的 socket 包装为
paramiko.Transport; - 通过
Transport.add_server_key()注册主机密钥; - 通过
Transport.start_server(server=...)启动协商(transport.py),协商成功后客户端开始认证; - 认证与通道请求阶段,
Transport内部(经由AuthHandler)回调server_object上的ServerInterface方法。
从 transport.py 的源码可以看到,start_server 会将传入的 server 对象保存为 self.server_object,并将 server_mode 置为 True。若未传入 server 对象,则默认使用一个 ServerInterface() 实例——此时所有请求都会被拒绝,因此实际使用时必须传入自定义子类。
二、认证接口:控制客户端如何登录
认证是 SSH 服务端的第一个核心环节。ServerInterface 为每一种 SSH 认证方法都提供了对应的回调方法,AuthHandler(见 auth_handler.py)会在收到客户端的 userauth 请求时逐一调用。
2.1 认证结果常量
所有认证回调统一返回三个常量之一(定义于 common.py):
| 常量 | 值 | 含义 |
|---|---|---|
AUTH_SUCCESSFUL |
0 | 认证成功,完成整个认证流程 |
AUTH_PARTIALLY_SUCCESSFUL |
1 | 本次认证方法成功,但还需要继续认证(多因素认证场景) |
AUTH_FAILED |
2 | 认证失败 |
当返回 AUTH_PARTIALLY_SUCCESSFUL 时,Paramiko 会调用 get_allowed_auths 告知客户端剩余可用的认证方法,客户端可据此发起下一轮认证。
2.2 密码认证:check_auth_password
def check_auth_password(self, username, password):
"""返回 AUTH_FAILED / AUTH_SUCCESSFUL / AUTH_PARTIALLY_SUCCESSFUL"""
if username == "robey" and password == "foo":
return paramiko.AUTH_SUCCESSFUL
return paramiko.AUTH_FAILED
该回调收到客户端提交的明文密码,由服务端自行决定是否接受。AuthHandler 在 auth_handler.py 处调用它。生产环境中应当在这里接入用户库、密码哈希校验(如 bcrypt)等,切勿直接硬编码明文。
2.3 公钥认证:check_auth_publickey
def check_auth_publickey(self, username, key):
"""key 为 paramiko.PKey 对象"""
if username == "robey" and key == self.good_pub_key:
return paramiko.AUTH_SUCCESSFUL
return paramiko.AUTH_FAILED
注意一个关键设计:在该回调中无需自行验证密钥签名。如 server.py 文档所述,只要服务端愿意接受该密钥,Paramiko 会自动完成客户端签名的校验工作。回调只负责判断"这把公钥是否属于允许登录的用户"。demo 中通过 paramiko.RSAKey(data=decodebytes(data)) 构造期望的公钥对象,再与客户端提供的 key 比较。
key 参数类型为 PKey,若需要从 authorized_keys 风格的数据加载公钥,可参考 demos/demo_server.py 中 RSAKey(data=...) 的用法。
2.4 none 认证与可选方法通告
def check_auth_none(self, username):
"""是否允许免认证直接开通道;默认拒绝"""
return paramiko.AUTH_FAILED
def get_allowed_auths(self, username):
"""返回逗号分隔的认证方法名字符串,如 "password,publickey" """
return "password,publickey"
get_allowed_auths 返回的字符串会在客户端尝试认证时发送给对方,告知哪些方法可能成功。可选值包括 "password"、"publickey"、"none"(见 server.py)。demo 服务器的实现为:
def get_allowed_auths(self, username):
return "gssapi-keyex,gssapi-with-mic,password,publickey"
2.5 keyboard-interactive 交互认证
"keyboard-interactive" 是 SSH 中灵活的多轮问答式认证。ServerInterface 用两个方法配合完成:
check_auth_interactive(username, submethods):开始交互认证。返回AUTH_FAILED表示不支持;否则返回一个InteractiveQuery对象(含一系列问题)。check_auth_interactive_response(responses):接收客户端对上一轮问题的回答。返回AUTH_FAILED/AUTH_SUCCESSFUL/AUTH_PARTIALLY_SUCCESSFUL,或者再次返回一个新的InteractiveQuery继续提问——这个问答循环可以无限持续。
AuthHandler 在 auth_handler.py 和 auth_handler.py 分别调用这两个方法。
InteractiveQuery 类(server.py)的用法:
q = paramiko.InteractiveQuery(
name="auth", # 查询名称(可选)
instructions="请输入密码", # 显示给用户的说明(可选)
"Password: ", # 一个或多个提示文本
)
q.add_prompt("PIN code: ", echo=False) # echo=False 表示不回显(适合密码)
add_prompt(prompt, echo=True) 可追加多个提示;echo=False 用于密码类输入。
2.6 GSSAPI / Kerberos 认证
Paramiko 对 GSSAPI 认证提供了三个服务端回调(server.py):
| 方法 | 说明 |
|---|---|
enable_auth_gssapi() |
返回 True 启用 GSSAPI 认证,默认 False |
check_auth_gssapi_with_mic(username, gss_authenticated, cc_file) |
GSSAPI + MIC 认证结果回调 |
check_auth_gssapi_keyex(username, gss_authenticated, cc_file) |
GSSAPI 密钥交换认证结果回调 |
AuthHandler 在 auth_handler.py 首先调用 enable_auth_gssapi() 判断是否启用,随后在 auth_handler.py 与 auth_handler.py 分别调用两个 check 方法。gss_authenticated 参数携带 krb5 认证结果(AUTH_FAILED 或 AUTH_SUCCESSFUL),cc_file 是 krb5 客户端凭证缓存文件名。
源码特别提醒(server.py):Paramiko 只验证用户是合法的 krb5 principal,无法在 Python 层判断该 principal 是否有权登录本机;若在 Linux 等平台上开发 SSH 服务器,应自行调用本地 Kerberos 库的 krb5_kuserok() 做账号级授权。demo 中对应的覆写可参考 demos/demo_server.py。
三、通道请求:决定客户端能用连接做什么
认证通过后,客户端请求打开通道。check_channel_request 是通道级的总入口,随后还有一系列"通道内请求"回调,逐个决定 pty、shell、exec、子系统等能力。
3.1 通道打开与错误码
def check_channel_request(self, kind, chanid):
if kind == "session":
return paramiko.OPEN_SUCCEEDED
return paramiko.OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED
kind 通常是 "session"(交互会话、命令执行、子系统的载体)。返回值使用通道打开状态码(定义于 common.py):
| 常量 | 值 | 含义 |
|---|---|---|
OPEN_SUCCEEDED |
0 | 允许打开 |
OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED |
1 | 被管理员禁止 |
OPEN_FAILED_CONNECT_FAILED |
2 | 连接失败 |
OPEN_FAILED_UNKNOWN_CHANNEL_TYPE |
3 | 未知通道类型 |
OPEN_FAILED_RESOURCE_SHORTAGE |
4 | 资源不足 |
chanid 是通道在 Transport 内的小整数标识。需要特别注意的是:只有返回 OPEN_SUCCEEDED 后 Paramiko 才会创建 Channel 对象,之后才可通过 Channel.get_id() 获取该 ID(server.py)。
check_channel_direct_tcpip_request(chanid, origin, destination) 用于本地端口转发(-L)通道的授权,签名与返回值同上,origin 与 destination 是 (ip_address, port) 二元组,对应隧道两端的 TCP 连接(server.py)。其默认实现同样返回 OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED。
3.2 pty 与终端尺寸
def check_channel_pty_request(
self, channel, term, width, height, pixelwidth, pixelheight, modes
):
"""是否允许分配伪终端;term 如 "vt100";pixelwidth/pixelheight 未知时为 0"""
return True
check_channel_window_change_request(channel, width, height, pixelwidth, pixelheight) 则处理 pty 分配后的窗口尺寸调整请求(server.py),返回 True 表示已调整终端尺寸。这两个方法共同支撑交互式 shell 的完整体验。
3.3 shell、exec 与环境变量
check_channel_shell_request(channel):是否提供交互 shell。返回True后,应将通道与某个 shell(或模拟 shell 的 stdin/stdout)对接。check_channel_exec_request(channel, command):是否执行单条命令。返回True后,通道应连接到命令的 stdin/stdout/stderr(server.py)。check_channel_env_request(channel, name, value):是否允许客户端为通道设置环境变量。源码明确指出部分环境变量(如PATH)极其危险,盲目允许客户端设置环境变量几乎肯定不是好主意(server.py),默认实现返回False。
3.4 子系统请求:sftp 与自定义子系统
def check_channel_subsystem_request(self, channel, name):
transport = channel.get_transport()
handler_class, args, kwargs = transport._get_subsystem_handler(name)
if handler_class is None:
return False
handler = handler_class(channel, name, self, *args, **kwargs)
handler.start()
return True
check_channel_subsystem_request 处理 sftp 之类的子系统请求(如 sftp)。与其它方法不同,它的默认实现已经具备实际功能:从 Transport 的子系统表中查找通过 set_subsystem_handler 注册的处理类,找到则实例化并启动。因此大多数情况下无需覆写此方法(server.py)。
Transport.set_subsystem_handler(name, handler, *args, **kwargs) 在 transport.py 中实现,将 (handler, args, kwargs) 存入 subsystem_table;_get_subsystem_handler 在 transport.py 中加锁查找。注册示例:
transport.set_subsystem_handler("sftp", paramiko.SFTPServer, *sftp_args)
3.5 X11 与 Agent 转发
check_channel_x11_request(channel, single_connection, auth_protocol, auth_cookie, screen_number):是否提供 X11 会话。返回True后,X11 应用应通过Transport.open_x11_channel路由到新的 SSH 通道(server.py)。check_channel_forward_agent_request(channel):是否允许 SSH Agent 转发。返回True后,服务端应创建AgentServerProxy来访问 agent(server.py)。
四、全局请求与端口转发
除通道级请求外,SSH 还有不绑定通道的"全局请求"。
4.1 check_global_request
def check_global_request(self, kind, msg):
"""kind 为请求类型;msg 为 Message 对象,含请求参数"""
return False # 默认不支持任何全局请求
check_global_request 在服务端和客户端模式下都会被调用(远端发起全局请求时)。若请求成功且需要返回上下文数据,可返回一个 tuple(元素只能是字符串、整数或布尔值),该 tuple 会随成功结果回发给远端(server.py)。除端口转发外,SSH 协议几乎没有其它实用全局请求,因此通常这类请求是协议扩展。
4.2 远程端口转发
check_port_forward_request(address, port):处理远程端口转发(-R)请求。address为"0.0.0.0"表示全局地址,port为0表示不指定具体端口(通常由 OS 选择)。默认返回False拒绝;接受时应返回实际打开的监听端口号(server.py)。cancel_port_forward_request(address, port):客户端请求取消之前的转发,应关闭对应监听端口。
Transport 在 transport.py 处调用这两个方法处理 tcpip-forward / cancel-tcpip-forward 全局请求。
五、登录横幅:get_banner
get_banner() 用于在登录前向客户端显示横幅文本(server.py)。返回 (banner, language) 元组,其中 banner 可用 CRLF 分隔多行,language 遵循 RFC 3066 风格(如 "en-US");默认返回 (None, None) 表示无横幅。AuthHandler 在 auth_handler.py 处读取该返回值并发送给客户端。
六、SubsystemHandler:多线程子系统处理框架
SubsystemHandler(server.py)是 threading.Thread 的子类,为服务端子系统提供"每请求一线程"的处理框架。
6.1 工作机制
当客户端请求某子系统且 check_channel_subsystem_request 找到注册的处理类时,Paramiko 会为该请求创建一个处理对象,并在新线程中执行。核心生命周期:
__init__(channel, name, server):保存通道、名称与服务端对象。若覆写此方法,必须将channel与name传给原始__init__;start_subsystem(name, transport, channel):在新线程中被调用,子系统全部逻辑在此完成;方法返回后通道即关闭;finish_subsystem():清理钩子,默认实现直接关闭通道。
源码中的 _run 方法(server.py)展示了真实调度流程:在 try 块中调用 start_subsystem,捕获异常并记录日志,最后无论如何调用 finish_subsystem 关闭通道。
6.2 一个典型子系统示例
class MP3Handler(paramiko.SubsystemHandler):
def start_subsystem(self, name, transport, channel):
# 在这里处理 "mp3" 子系统的全部逻辑
while True:
data = channel.recv(4096)
if not data:
break
channel.send(process(data))
transport.set_subsystem_handler("mp3", MP3Handler)
文档给出了对应场景:若注册了 MP3Handler 处理 "mp3" 子系统,那么每当客户端认证成功并请求该子系统时,就会新建一个 MP3Handler 对象并从新线程调用 start_subsystem(server.py)。
重要注意事项(server.py):start_subsystem 有责任在底层 Transport 关闭时自行退出——可通过检查 Transport.is_active 或留意 Channel 的 EOF 来实现。若该方法无限循环且不检查该情况,该线程将持续运行,可能导致 Python 解释器无法退出。
七、端到端示例:基于 demo_server.py 的完整服务端
仓库中的 demos/demo_server.py 是官方提供的完整可运行服务端示例,综合了本文介绍的大部分机制。其整体流程如下:
import socket, threading, paramiko
# 1. 读取服务器主机密钥(签名用途,必须含私钥)
host_key = paramiko.RSAKey(filename="test_rsa.key")
class Server(paramiko.ServerInterface):
def __init__(self):
self.event = threading.Event() # 用于等待客户端请求 shell
def check_channel_request(self, kind, chanid):
if kind == "session":
return paramiko.OPEN_SUCCEEDED
return paramiko.OPEN_FAILED_ADMINISTRATIVELY_PROHIBITED
def check_auth_password(self, username, password):
if (username == "robey") and (password == "foo"):
return paramiko.AUTH_SUCCESSFUL
return paramiko.AUTH_FAILED
def check_channel_shell_request(self, channel):
self.event.set()
return True
def check_channel_pty_request(self, channel, term, width, height,
pixelwidth, pixelheight, modes):
return True
# 2. 监听 socket 并接受连接
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
sock.bind(("", 2200))
sock.listen(100)
client, addr = sock.accept()
# 3. 构造 Transport 并进入服务端模式
t = paramiko.Transport(client)
t.add_server_key(host_key) # 注册主机密钥
server = Server()
t.start_server(server=server) # 开始 SSH 协商与认证
# 4. 接受通道,等待 shell 请求,随后开始交互
chan = t.accept(20)
server.event.wait(10) # 等待客户端发起 shell 请求
chan.send("Welcome to my BBS!\r\n")
f = chan.makefile("rU") # 用文件接口读取客户端输入
username = f.readline().strip("\r\n")
chan.send("Hello, " + username + ".\r\n")
chan.close()
关键点解读:
t.accept(20):等待客户端打开通道,返回Channel;超时返回None;server.event.wait(10):demo 用threading.Event等待check_channel_shell_request被回调,以确认客户端确实请求了 shell,这是演示服务端与客户端握手节奏的常见模式;- 主机密钥必须包含私钥:
Transport.add_server_key的文档(transport.py)指出密钥用于在 SSH2 协商中签名,因此必须加载私钥。同类型(RSA/DSS)只保留一个;对于 RSA 密钥,Paramiko 会自动将其同时注册到rsa-sha2-256、rsa-sha2-512算法名下以支持 SHA-2 扩展; load_server_moduli()(可选):Transport.load_server_moduli(transport.py)加载素数模数文件以支持 diffie-hellman group-exchange 密钥协商;这是较冷门的选项,可安全忽略,demo 中加载失败会提示 "gex will be unsupported"。
启动后可用仓库中的客户端示例 demos/demo.py 连接测试:
python demos/demo.py robey@localhost:2200
客户端 demo 的认证逻辑(demos/demo.py)展示了与服务端 check_auth_password / check_auth_publickey 一一对应的 auth_password / auth_publickey 调用,可对照阅读理解认证握手的两端。
八、实现细节与调用链小结
为便于深入源码,将本文涉及的底层调用链整理如下:
| ServerInterface 方法 | 调用位置 | 用途 |
|---|---|---|
get_banner |
auth_handler.py | 登录前横幅 |
get_allowed_auths |
auth_handler.py | 通告可用认证方法 |
enable_auth_gssapi |
auth_handler.py | 启用 GSSAPI |
check_auth_none |
auth_handler.py | none 认证 |
check_auth_password |
auth_handler.py | 密码认证 |
check_auth_publickey |
auth_handler.py | 公钥认证 |
check_auth_interactive |
auth_handler.py | 发起交互认证 |
check_auth_gssapi_keyex |
auth_handler.py | GSSAPI 密钥交换认证 |
check_auth_interactive_response |
auth_handler.py | 交互认证应答 |
check_auth_gssapi_with_mic |
auth_handler.py | GSSAPI MIC 认证 |
check_port_forward_request |
transport.py | 远程端口转发授权 |
cancel_port_forward_request |
transport.py | 取消端口转发 |
check_global_request |
transport.py | 全局请求处理 |
认证返回码 AUTH_* 与通道打开状态码 OPEN_* 的定义位于 common.py,异常时客户端收到的描述文本映射见 CONNECTION_FAILED_CODE(common.py)。
九、总结
Paramiko 的 server 模块提供了一套"默认全拒绝、显式开放"的服务端接口框架:通过覆写 ServerInterface 的认证与通道请求方法,可以精确控制 SSH 服务器的每个行为点;借助 InteractiveQuery 可实现多轮问答认证;通过 SubsystemHandler 与 Transport.set_subsystem_handler 可以以多线程方式扩展任意协议子系统(如 SFTP)。理解 server.py 中每个回调的默认行为与调用时机,是构建安全、可控的自定义 SSH 服务器的基础——建议在动手实现前,将 demos/demo_server.py 作为最小可运行骨架,再逐步叠加认证策略与业务处理。