ChannelSftp

定义

ChannelSftp是JSch库中表示SFTP通道的Java类,位于com.jcraft.jsch包内,对应SSH连接协议中的sftp子系统。JSch本身是SSH2协议的纯Java实现,允许程序连接SSH服务器并进行端口转发、X11转发和文件传输,ChannelSftp则是其中专门处理文件传输的部分。

这个类集中了SFTP协议的主要文件操作能力,提供文件上传的put方法、文件下载的get方法、列目录的ls方法、进入目录的cd方法、重命名与删除操作以及创建和删除目录的mkdir、rmdir方法。其中put和get均提供多个重载形式,可按路径名、输入输出流或文件对象等不同参数组合调用^[1]。

在JSch的对象模型中,JSch为顶层入口类,Session表示一次SSH连接会话,Channel代表在该会话上执行的具体操作通道。程序先由JSch取得Session并完成认证,再调用Session的openChannel方法,传入字符串"sftp",将返回的通道对象强制转换为ChannelSftp后即可使用其文件接口。

原理

ChannelSftp的工作基础是SSH文件传输协议本身。该协议由IETF的secsh工作组起草,采用简单的请求—响应模型,每个请求和响应都带有序号,同一时刻可以有多个请求处于未应答状态。协议设计上假定运行在类似SSH的安全通道之上,服务器已经完成对客户端的认证,并能获得客户端用户的身份信息;该协议也独立于SSH2协议栈的其他部分,理论上可用于其他安全传输环境^[2]。

在SSH2协议栈中运行时,这一协议被当作子系统使用,子系统名称固定为sftp,协议数据通过标准输入和标准输出以二进制形式收发。每个报文的头部依次为长度字段、类型字段和请求标识字段,长度字段不计入自身长度,因此不含类型专属字段的报文其长度值写作5。服务器应至少支持34000字节的报文,以便单次读写最多32768字节的数据^[2]。

协议定义了一组以SSH_FXP_开头的报文类型,覆盖文件传输和文件系统访问的各个动作,例如打开、关闭、读、写、取状态、创建目录、删除目录、重命名、读取链接等,并配有STATUS、HANDLE、DATA、NAME、ATTRS等响应类型。初始化阶段由客户端发出SSH_FXP_INIT并携带版本号,服务器以SSH_FXP_VERSION回应双方共同采用的版本^[3]。ChannelSftp的各类方法最终都对应到这些报文的组织与解析,调用者无需直接处理报文编解码。

服务器端若采用OpenSSH的sftp与sftp-server模块,实现的正是filexfer协议的第3版。该模块可以配合OpenSSH服务器工作,也能与dropbear等其他SSH守护进程共用;较新的协议草案版本并未被支持,其中部分特性以扩展形式单独实现^[4]。JSch在与服务器协商后同样按相应版本交互。

在传输控制上,JSch定义了3种文件传输模式:OVERWRITE为默认模式,目标文件存在时整体覆盖;RESUME在传输中断后从断点续传;APPEND则把数据追加到已有目标文件之后。库还提供SftpProgressMonitor接口用于观察进度,其中的init方法在传输开始时调用,count方法在每传输一个数据块后被调用并给出该块的字节数,end方法在传输结束时调用^[5]。

发展历程

JSch由JCraft发布,是SSH2协议的纯Java实现库,依赖Java加密扩展,支持J2SE 1.4.0及以上版本,并为更早的版本提供兼容方案,同时另有J2ME版本以便移动设备连接服务器。ChannelSftp作为其中的文件传输通道类,随该库一同提供。

2011年11月2日发布的0.1.45版本和2012年10月12日发布的0.1.49版本是两个关键更新节点,官方稳定版本最终停在0.1.55,此后官方仓库长期没有更新。0.1.55于2018年11月26日发布^[6]。

由于原库停止维护,社区出现了以其为起点的分支版本并持续更新,该分支保持原有API与包结构,可作为直接替换使用。分支在0.1.57版本中加入rsa-sha2-256与rsa-sha2-512支持,0.1.58版本扩充算法,0.1.59与0.1.60版本修复问题并支持openssh-v1私钥格式,0.1.61版本增加对chacha20-poly1305、ssh-ed25519、ssh-ed448等算法的支持,0.1.66版本起把这些能力也提供给较旧的Java版本^[7]。

这一分支的版本号早期沿用原库的编号方式,自2.27.0起改为语义化版本。其出现的原因之一,是OpenSSH在8.8版本中默认停用ssh-rsa,应用需要能使用rsa-sha2-256和rsa-sha2-512的库;该分支同样自0.2.0版本起默认停用RSA/SHA1签名算法^[8]。多个项目因此从原库迁移到该分支。

应用

ChannelSftp常见于需要由Java程序完成远程文件收发的场景,典型用法是建立SSH会话后打开sftp通道,再以路径名、输入流或输出流的形式调用put上传文件、调用get下载文件。例如可将本地文件系统的输入流交给put方法写入远端指定文件,由此把握每次写入的数据块大小^[5]。

文件管理类操作同样通过该通道完成,包括切换目录、列出远端目录内容、重命名、删除文件与目录等;下载完成后若需清理远端文件,可在get之后调用删除方法。连接通常使用默认的22端口,认证可使用密码,也可通过加载私钥的方式完成^[9]。

该通道类还被上层组件间接使用,Apache Commons VFS在实现SFTP访问时内部就调用了JSch;使用这一途径时需要同时引入VFS与JSch两个包。除JSch之外,Java生态中还有SSHJ等同类库可供选择,它们提供文档更充分的接口^[10]。

局限

ChannelSftp对SFTP协议的暴露并不完整。协议本身含有用于打开远端文件并读写任意区段的底层命令,但JSch并未通过ChannelSftp提供全部这类能力,因此需要精细随机读写的程序可能要改用其他Java SFTP客户端库。若要在文件被追写后只读取新增内容,一种做法是周期性调用stat方法获取文件大小与修改时间,再使用带偏移量参数的get方法跳过已读部分^[11]。

加密与解密带来的开销使这类传输的效率低于不使用加密的普通文件传送方式,对网络安全性要求更高的场合才会以SFTP替代FTP^[1]。

版本维护状态也构成实际限制。原库在0.1.55之后长期未更新,较长时间内没有修复已发现的问题^[6]。此外,算法支持依赖运行环境:部分较新的密钥与加密算法需要较高的Java版本,或需在类路径中额外引入加密算法库才能启用^[12]。

配置不当会影响连接安全。库允许通过setConfig将StrictHostKeyChecking设为no以跳过主机密钥验证,这一设置会绕过对服务器身份的核对,通常只在受控环境中使用。

参见

• JSch —— ChannelSftp所属的Java SSH2协议实现库。

• SFTP —— ChannelSftp所实现的文件传输协议。

• SSH —— SFTP运行所依托的安全外壳协议。

• Apache Ant —— 曾使用这一库完成相关任务的构建工具。

• Apache Commons VFS —— 在内部调用该库实现SFTP访问的虚拟文件系统组件。