PROTOCOL revision 180750
11590SrgrimesThis documents OpenSSH's deviations and extensions to the published SSH 21590Srgrimesprotocol. 31590Srgrimes 41590SrgrimesNote that OpenSSH's sftp and sftp-server implement revision 3 of the SSH 51590Srgrimesfilexfer protocol described in: 61590Srgrimes 71590Srgrimeshttp://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt 81590Srgrimes 91590SrgrimesFeatures from newer versions of the draft are not supported, unless 101590Srgrimesexplicitly implemented as extensions described below. 111590Srgrimes 121590SrgrimesThe protocol used by OpenSSH's ssh-agent is described in the file 131590SrgrimesPROTOCOL.agent 141590Srgrimes 151590Srgrimes1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com" 161590Srgrimes 171590SrgrimesThis is a new transport-layer MAC method using the UMAC algorithm 181590Srgrimes(rfc4418). This method is identical to the "umac-64" method documented 191590Srgrimesin: 201590Srgrimes 211590Srgrimeshttp://www.openssh.com/txt/draft-miller-secsh-umac-01.txt 221590Srgrimes 231590Srgrimes2. transport: Protocol 2 compression algorithm "zlib@openssh.com" 241590Srgrimes 251590SrgrimesThis transport-layer compression method uses the zlib compression 261590Srgrimesalgorithm (identical to the "zlib" method in rfc4253), but delays the 271590Srgrimesstart of compression until after authentication has completed. This 281590Srgrimesavoids exposing compression code to attacks from unauthenticated users. 291590Srgrimes 301590SrgrimesThe method is documented in: 311590Srgrimes 321590Srgrimeshttp://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt 331590Srgrimes 341590Srgrimes3. connection: Channel write close extension "eow@openssh.com" 351590Srgrimes 361590SrgrimesThe SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF 371590Srgrimesmessage to allow an endpoint to signal its peer that it will send no 3841568Sarchiemore data over a channel. Unfortunately, there is no symmetric way for 391590Srgrimesan endpoint to request that its peer should cease sending data to it 401590Srgrimeswhile still keeping the channel open for the endpoint to send data to 411590Srgrimesthe peer. 421590Srgrimes 431590SrgrimesThis is desirable, since it saves the transmission of data that would 4456597Smharootherwise need to be discarded and it allows an endpoint to signal local 4541568Sarchieprocesses of the condition, e.g. by closing the corresponding file 4656597Smharodescriptor. 471590Srgrimes 4899112SobrienOpenSSH implements a channel extension message to perform this 4999112Sobriensignalling: "eow@openssh.com" (End Of Write). This message is sent by 501590Srgrimesan endpoint when the local output of a session channel is closed or 511590Srgrimesexperiences a write error. The message is formatted as follows: 5278158Sroam 531590Srgrimes byte SSH_MSG_CHANNEL_REQUEST 541590Srgrimes uint32 recipient channel 551590Srgrimes string "eow@openssh.com" 561590Srgrimes boolean FALSE 5778158Sroam 581590SrgrimesOn receiving this message, the peer SHOULD cease sending data of 5956597Smharothe channel and MAY signal the process from which the channel data 601590Srgrimesoriginates (e.g. by closing its read file descriptor). 611590Srgrimes 621590SrgrimesAs with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does 6356597Smharoremain open after a "eow@openssh.com" has been sent and more data may 6423693Speterstill be sent in the other direction. This message does not consume 651590Srgrimeswindow space and may be sent even if no window space is available. 6656597Smharo 6756597Smharo4. connection: disallow additional sessions extension 6856597Smharo "no-more-sessions@openssh.com" 6956597Smharo 7056597SmharoMost SSH connections will only ever request a single session, but a 7156597Smharoattacker may abuse a running ssh client to surreptitiously open 7256597Smharoadditional sessions under their control. OpenSSH provides a global 7356597Smharorequest "no-more-sessions@openssh.com" to mitigate this attack. 7456597Smharo 7556597SmharoWhen an OpenSSH client expects that it will never open another session 7656597Smharo(i.e. it has been started with connection multiplexing disabled), it 7756597Smharowill send the following global request: 7856597Smharo 7956597Smharo byte SSH_MSG_GLOBAL_REQUEST 8056597Smharo string "no-more-sessions@openssh.com" 8156597Smharo char want-reply 8256597Smharo 8356597SmharoOn receipt of such a message, an OpenSSH server will refuse to open 8456597Smharofuture channels of type "session" and instead immediately abort the 8556597Smharoconnection. 8656597Smharo 8756597SmharoNote that this is not a general defence against compromised clients 8856597Smharo(that is impossible), but it thwarts a simple attack. 8956597Smharo 9056597Smharo5. connection: Tunnel forward extension "tun@openssh.com" 9156597Smharo 9278158SroamOpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com" 9378158Sroamchannel type. This channel type supports forwarding of network packets 9478158Sroamwith datagram boundaries intact between endpoints equipped with 9578158Sroaminterfaces like the BSD tun(4) device. Tunnel forwarding channels are 9678158Sroamrequested by the client with the following packet: 9778158Sroam 98128772Skientzle byte SSH_MSG_CHANNEL_OPEN 9992920Simp string "tun@openssh.com" 10092920Simp uint32 sender channel 10192920Simp uint32 initial window size 10292920Simp uint32 maximum packet size 10392920Simp uint32 tunnel mode 10492920Simp uint32 remote unit number 1051590Srgrimes 1061590SrgrimesThe "tunnel mode" parameter specifies whether the tunnel should forward 107100822Sdwmalonelayer 2 frames or layer 3 packets. It may take one of the following values: 1081590Srgrimes 10932097Sjkh SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */ 11032097Sjkh SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */ 11137952Sdes 11232097SjkhThe "tunnel unit number" specifies the remote interface number, or may 11332097Sjkhbe zero to allow the server to automatically chose an interface. A server 11432097Sjkhthat is not willing to open a client-specified unit should refuse the 115108453Smikerequest with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful open, 11632097Sjkhthe server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS. 11787216Smarkm 1181590SrgrimesOnce established the client and server may exchange packet or frames 11956597Smharoover the tunnel channel by encapsulating them in SSH protocol strings 120128772Skientzleand sending them as channel data. This ensures that packet boundaries 1211590Srgrimesare kept intact. Specifically, packets are transmitted using normal 12232097SjkhSSH_MSG_CHANNEL_DATA packets: 12319120Sscrappy 12478158Sroam byte SSH_MSG_CHANNEL_DATA 125128772Skientzle uint32 recipient channel 12678158Sroam string data 1271590Srgrimes 12832097SjkhThe contents of the "data" field for layer 3 packets is: 12932097Sjkh 13032097Sjkh uint32 packet length 13178158Sroam uint32 address family 13278158Sroam byte[packet length - 4] packet data 13378158Sroam 13432097SjkhThe "address family" field identifies the type of packet in the message. 13532097SjkhIt may be one of: 13632097Sjkh 13732097Sjkh SSH_TUN_AF_INET 2 /* IPv4 */ 13832097Sjkh SSH_TUN_AF_INET6 24 /* IPv6 */ 13932097Sjkh 14032097SjkhThe "packet data" field consists of the IPv4/IPv6 datagram itself 14132097Sjkhwithout any link layer header. 14232097Sjkh 14332097SjkhThe contents of the "data" field for layer 3 packets is: 14432097Sjkh 14532097Sjkh uint32 packet length 14632097Sjkh byte[packet length] frame 14732097Sjkh 14832097SjkhThe "frame" field contains an IEEE 802.3 Ethernet frame, including 14932097Sjkhheader. 15032097Sjkh 15132097Sjkh6. sftp: Reversal of arguments to SSH_FXP_SYMLINK 15232097Sjkh 15332097SjkhWhen OpenSSH's sftp-server was implemented, the order of the arguments 15432097Sjkhto the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately, 15558601Scharnierthe reversal was not noticed until the server was widely deployed. Since 15632097Sjkhfixing this to follow the specification would cause incompatibility, the 15732097Sjkhcurrent order was retained. For correct operation, clients should send 15832097SjkhSSH_FXP_SYMLINK as follows: 15932097Sjkh 16032097Sjkh uint32 id 16132097Sjkh string targetpath 16256597Smharo string linkpath 16356597Smharo 16456597Smharo7. sftp: Server extension announcement in SSH_FXP_VERSION 16556597Smharo 16656597SmharoOpenSSH's sftp-server lists the extensions it supports using the 16756597Smharostandard extension announcement mechanism in the SSH_FXP_VERSION server 168112855Sobrienhello packet: 169112855Sobrien 17056597Smharo uint32 3 /* protocol version */ 17156597Smharo string ext1-name 17256597Smharo string ext1-version 17356597Smharo string ext2-name 17456597Smharo string ext2-version 17556597Smharo ... 17632097Sjkh string extN-name 17732097Sjkh string extN-version 17819120Sscrappy 1791590SrgrimesEach extension reports its integer version number as an ASCII encoded 18032097Sjkhstring, e.g. "1". The version will be incremented if the extension is 1811590Srgrimesever changed in an incompatible way. The server MAY advertise the same 1821590Srgrimesextension with multiple versions (though this is unlikely). Clients MUST 1831590Srgrimescheck the version number before attempting to use the extension. 1841590Srgrimes 1851590Srgrimes8. sftp: Extension request "posix-rename@openssh.com" 1861590Srgrimes 1871590SrgrimesThis operation provides a rename operation with POSIX semantics, which 1881590Srgrimesare different to those provided by the standard SSH_FXP_RENAME in 1891590Srgrimesdraft-ietf-secsh-filexfer-02.txt. This request is implemented as a 1901590SrgrimesSSH_FXP_EXTENDED request with the following format: 1911590Srgrimes 1921590Srgrimes uint32 id 1931590Srgrimes string "posix-rename@openssh.com" 1941590Srgrimes string oldpath 1951590Srgrimes string newpath 19632097Sjkh 19732097SjkhOn receiving this request the server will perform the POSIX operation 19832097Sjkhrename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message. 19932097SjkhThis extension is advertised in the SSH_FXP_VERSION hello with version 20032097Sjkh"1". 20132097Sjkh 20232097Sjkh9. sftp: Extension requests "statvfs@openssh.com" and 2031590Srgrimes "fstatvfs@openssh.com" 2041590Srgrimes 20532097SjkhThese requests correspond to the statvfs and fstatvfs POSIX system 20632097Sjkhinterfaces. The "statvfs@openssh.com" request operates on an explicit 2071590Srgrimespathname, and is formatted as follows: 2081590Srgrimes 20932097Sjkh uint32 id 21032097Sjkh string "statvfs@openssh.com" 21132097Sjkh string path 21232097Sjkh 21332097SjkhThe "fstatvfs@openssh.com" operates on an open file handle: 2141590Srgrimes 21519120Sscrappy uint32 id 2161590Srgrimes string "fstatvfs@openssh.com" 21732097Sjkh string handle 21819120Sscrappy 21919120SscrappyThese requests return a SSH_FXP_STATUS reply on failure. On success they 22019120Sscrappyreturn the following SSH_FXP_EXTENDED_REPLY reply: 22132097Sjkh 2221590Srgrimes uint32 id 2231590Srgrimes uint64 f_bsize /* file system block size */ 2241590Srgrimes uint64 f_frsize /* fundamental fs block size */ 2251590Srgrimes uint64 f_blocks /* number of blocks (unit f_frsize) */ 22687216Smarkm uint64 f_bfree /* free blocks in file system */ 2271590Srgrimes uint64 f_bavail /* free blocks for non-root */ 2281590Srgrimes uint64 f_files /* total file inodes */ 2291590Srgrimes uint64 f_ffree /* free file inodes */ 23032097Sjkh uint64 f_favail /* free file inodes for to non-root */ 2311590Srgrimes uint64 f_fsid /* file system id */ 2321590Srgrimes uint64 f_flag /* bit mask of f_flag values */ 23332097Sjkh uint64 f_namemax /* maximum filename length */ 234128772Skientzle 2351590SrgrimesThe values of the f_flag bitmask are as follows: 23632097Sjkh 2371590Srgrimes #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */ 23832097Sjkh #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */ 2391590Srgrimes 24032097SjkhBoth the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are 24178158Sroamadvertised in the SSH_FXP_VERSION hello with version "2". 24278158Sroam 2431590Srgrimes$OpenBSD: PROTOCOL,v 1.11 2008/07/05 05:16:01 djm Exp $ 24432097Sjkh