1422225e8SdjmThis documents OpenSSH's deviations and extensions to the published SSH 2422225e8Sdjmprotocol. 3422225e8Sdjm 438d4658eSdjmNote that OpenSSH's sftp and sftp-server implement revision 3 of the SSH 538d4658eSdjmfilexfer protocol described in: 6422225e8Sdjm 7422225e8Sdjmhttp://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt 8422225e8Sdjm 9f452f5c5SdjmNewer versions of the draft will not be supported, though some features 10f452f5c5Sdjmare individually implemented as extensions described below. 11422225e8Sdjm 12f0c9babeSdjmThe protocol used by OpenSSH's ssh-agent is described in the file 13f0c9babeSdjmPROTOCOL.agent 14f0c9babeSdjm 15f6c05033Sdjm1. Transport protocol changes 16f6c05033Sdjm 17f6c05033Sdjm1.1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com" 18422225e8Sdjm 19422225e8SdjmThis is a new transport-layer MAC method using the UMAC algorithm 20422225e8Sdjm(rfc4418). This method is identical to the "umac-64" method documented 21422225e8Sdjmin: 22422225e8Sdjm 23422225e8Sdjmhttp://www.openssh.com/txt/draft-miller-secsh-umac-01.txt 24422225e8Sdjm 25f6c05033Sdjm1.2. transport: Protocol 2 compression algorithm "zlib@openssh.com" 26422225e8Sdjm 27422225e8SdjmThis transport-layer compression method uses the zlib compression 28422225e8Sdjmalgorithm (identical to the "zlib" method in rfc4253), but delays the 29422225e8Sdjmstart of compression until after authentication has completed. This 3038d4658eSdjmavoids exposing compression code to attacks from unauthenticated users. 31422225e8Sdjm 32422225e8SdjmThe method is documented in: 33422225e8Sdjm 34422225e8Sdjmhttp://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt 35422225e8Sdjm 36f6c05033Sdjm1.3. transport: New public key algorithms "ssh-rsa-cert-v00@openssh.com", 37f6c05033Sdjm "ssh-dsa-cert-v00@openssh.com", 38f6c05033Sdjm "ecdsa-sha2-nistp256-cert-v01@openssh.com", 39f6c05033Sdjm "ecdsa-sha2-nistp384-cert-v01@openssh.com" and 40f6c05033Sdjm "ecdsa-sha2-nistp521-cert-v01@openssh.com" 41b94e498eSdjm 42f6c05033SdjmOpenSSH introduces new public key algorithms to support certificate 43b94e498eSdjmauthentication for users and hostkeys. These methods are documented in 44b94e498eSdjmthe file PROTOCOL.certkeys 45b94e498eSdjm 46f6c05033Sdjm1.4. transport: Elliptic Curve cryptography 47f6c05033Sdjm 48f6c05033SdjmOpenSSH supports ECC key exchange and public key authentication as 49f6c05033Sdjmspecified in RFC5656. Only the ecdsa-sha2-nistp256, ecdsa-sha2-nistp384 50f6c05033Sdjmand ecdsa-sha2-nistp521 curves over GF(p) are supported. Elliptic 51f6c05033Sdjmcurve points encoded using point compression are NOT accepted or 52f6c05033Sdjmgenerated. 53f6c05033Sdjm 54c2ea1f0aSmarkus1.5 transport: Protocol 2 Encrypt-then-MAC MAC algorithms 55c2ea1f0aSmarkus 56c2ea1f0aSmarkusOpenSSH supports MAC algorithms, whose names contain "-etm", that 57c2ea1f0aSmarkusperform the calculations in a different order to that defined in RFC 58c2ea1f0aSmarkus4253. These variants use the so-called "encrypt then MAC" ordering, 59c2ea1f0aSmarkuscalculating the MAC over the packet ciphertext rather than the 60c2ea1f0aSmarkusplaintext. This ordering closes a security flaw in the SSH transport 61c2ea1f0aSmarkusprotocol, where decryption of unauthenticated ciphertext provided a 62c2ea1f0aSmarkus"decryption oracle" that could, in conjunction with cipher flaws, reveal 63c2ea1f0aSmarkussession plaintext. 64c2ea1f0aSmarkus 65c2ea1f0aSmarkusSpecifically, the "-etm" MAC algorithms modify the transport protocol 66c2ea1f0aSmarkusto calculate the MAC over the packet ciphertext and to send the packet 67c2ea1f0aSmarkuslength unencrypted. This is necessary for the transport to obtain the 68c2ea1f0aSmarkuslength of the packet and location of the MAC tag so that it may be 69c2ea1f0aSmarkusverified without decrypting unauthenticated data. 70c2ea1f0aSmarkus 71c2ea1f0aSmarkusAs such, the MAC covers: 72c2ea1f0aSmarkus 734ea77511Sdjm mac = MAC(key, sequence_number || packet_length || encrypted_packet) 74c2ea1f0aSmarkus 754ea77511Sdjmwhere "packet_length" is encoded as a uint32 and "encrypted_packet" 764ea77511Sdjmcontains: 77c2ea1f0aSmarkus 78c2ea1f0aSmarkus byte padding_length 79c2ea1f0aSmarkus byte[n1] payload; n1 = packet_length - padding_length - 1 80c2ea1f0aSmarkus byte[n2] random padding; n2 = padding_length 81c2ea1f0aSmarkus 8247da1b19Smarkus1.6 transport: AES-GCM 8347da1b19Smarkus 8447da1b19SmarkusOpenSSH supports the AES-GCM algorithm as specified in RFC 5647. 8547da1b19SmarkusBecause of problems with the specification of the key exchange 8647da1b19Smarkusthe behaviour of OpenSSH differs from the RFC as follows: 8747da1b19Smarkus 8847da1b19SmarkusAES-GCM is only negotiated as the cipher algorithms 8947da1b19Smarkus"aes128-gcm@openssh.com" or "aes256-gcm@openssh.com" and never as 9047da1b19Smarkusan MAC algorithm. Additionally, if AES-GCM is selected as the cipher 9147da1b19Smarkusthe exchanged MAC algorithms are ignored and there doesn't have to be 9247da1b19Smarkusa matching MAC. 9347da1b19Smarkus 94*1edbfe23Sdjm1.7 transport: chacha20-poly1305@openssh.com authenticated encryption 95*1edbfe23Sdjm 96*1edbfe23SdjmOpenSSH supports authenticated encryption using ChaCha20 and Poly1305 97*1edbfe23Sdjmas described in PROTOCOL.chacha20poly1305. 98*1edbfe23Sdjm 99f6c05033Sdjm2. Connection protocol changes 100f6c05033Sdjm 101f6c05033Sdjm2.1. connection: Channel write close extension "eow@openssh.com" 102422225e8Sdjm 103422225e8SdjmThe SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF 104422225e8Sdjmmessage to allow an endpoint to signal its peer that it will send no 105422225e8Sdjmmore data over a channel. Unfortunately, there is no symmetric way for 106422225e8Sdjman endpoint to request that its peer should cease sending data to it 107422225e8Sdjmwhile still keeping the channel open for the endpoint to send data to 108422225e8Sdjmthe peer. 109422225e8Sdjm 11038d4658eSdjmThis is desirable, since it saves the transmission of data that would 111422225e8Sdjmotherwise need to be discarded and it allows an endpoint to signal local 112422225e8Sdjmprocesses of the condition, e.g. by closing the corresponding file 113422225e8Sdjmdescriptor. 114422225e8Sdjm 115422225e8SdjmOpenSSH implements a channel extension message to perform this 1167153c228Sdjmsignalling: "eow@openssh.com" (End Of Write). This message is sent by 1177153c228Sdjman endpoint when the local output of a session channel is closed or 1187153c228Sdjmexperiences a write error. The message is formatted as follows: 119422225e8Sdjm 120422225e8Sdjm byte SSH_MSG_CHANNEL_REQUEST 121422225e8Sdjm uint32 recipient channel 122422225e8Sdjm string "eow@openssh.com" 123422225e8Sdjm boolean FALSE 124422225e8Sdjm 125422225e8SdjmOn receiving this message, the peer SHOULD cease sending data of 126422225e8Sdjmthe channel and MAY signal the process from which the channel data 127422225e8Sdjmoriginates (e.g. by closing its read file descriptor). 128422225e8Sdjm 129422225e8SdjmAs with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does 130422225e8Sdjmremain open after a "eow@openssh.com" has been sent and more data may 131422225e8Sdjmstill be sent in the other direction. This message does not consume 132422225e8Sdjmwindow space and may be sent even if no window space is available. 133422225e8Sdjm 134e187e146SdjmNB. due to certain broken SSH implementations aborting upon receipt 135e187e146Sdjmof this message (in contravention of RFC4254 section 5.4), this 136e187e146Sdjmmessage is only sent to OpenSSH peers (identified by banner). 137e187e146SdjmOther SSH implementations may be whitelisted to receive this message 138e187e146Sdjmupon request. 139e187e146Sdjm 140f6c05033Sdjm2.2. connection: disallow additional sessions extension 14182046f86Sdjm "no-more-sessions@openssh.com" 14282046f86Sdjm 14382046f86SdjmMost SSH connections will only ever request a single session, but a 14482046f86Sdjmattacker may abuse a running ssh client to surreptitiously open 14582046f86Sdjmadditional sessions under their control. OpenSSH provides a global 14682046f86Sdjmrequest "no-more-sessions@openssh.com" to mitigate this attack. 14782046f86Sdjm 14882046f86SdjmWhen an OpenSSH client expects that it will never open another session 14982046f86Sdjm(i.e. it has been started with connection multiplexing disabled), it 15082046f86Sdjmwill send the following global request: 15182046f86Sdjm 15282046f86Sdjm byte SSH_MSG_GLOBAL_REQUEST 15382046f86Sdjm string "no-more-sessions@openssh.com" 15482046f86Sdjm char want-reply 15582046f86Sdjm 15682046f86SdjmOn receipt of such a message, an OpenSSH server will refuse to open 15782046f86Sdjmfuture channels of type "session" and instead immediately abort the 15882046f86Sdjmconnection. 15982046f86Sdjm 16082046f86SdjmNote that this is not a general defence against compromised clients 16182046f86Sdjm(that is impossible), but it thwarts a simple attack. 16282046f86Sdjm 163e187e146SdjmNB. due to certain broken SSH implementations aborting upon receipt 164e187e146Sdjmof this message, the no-more-sessions request is only sent to OpenSSH 165e187e146Sdjmservers (identified by banner). Other SSH implementations may be 166e187e146Sdjmwhitelisted to receive this message upon request. 167e187e146Sdjm 168f6c05033Sdjm2.3. connection: Tunnel forward extension "tun@openssh.com" 1690afb9521Sdjm 1706c9c8648SdjmOpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com" 1710afb9521Sdjmchannel type. This channel type supports forwarding of network packets 1726c9c8648Sdjmwith datagram boundaries intact between endpoints equipped with 1730afb9521Sdjminterfaces like the BSD tun(4) device. Tunnel forwarding channels are 1740afb9521Sdjmrequested by the client with the following packet: 1750afb9521Sdjm 1760afb9521Sdjm byte SSH_MSG_CHANNEL_OPEN 1770afb9521Sdjm string "tun@openssh.com" 1780afb9521Sdjm uint32 sender channel 1790afb9521Sdjm uint32 initial window size 1800afb9521Sdjm uint32 maximum packet size 1810afb9521Sdjm uint32 tunnel mode 1820afb9521Sdjm uint32 remote unit number 1830afb9521Sdjm 1840afb9521SdjmThe "tunnel mode" parameter specifies whether the tunnel should forward 1850afb9521Sdjmlayer 2 frames or layer 3 packets. It may take one of the following values: 1860afb9521Sdjm 1870afb9521Sdjm SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */ 1880afb9521Sdjm SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */ 1890afb9521Sdjm 1900afb9521SdjmThe "tunnel unit number" specifies the remote interface number, or may 191c880fb56Sdjmbe 0x7fffffff to allow the server to automatically chose an interface. A 192c880fb56Sdjmserver that is not willing to open a client-specified unit should refuse 193c880fb56Sdjmthe request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful 194c880fb56Sdjmopen, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS. 1950afb9521Sdjm 1960afb9521SdjmOnce established the client and server may exchange packet or frames 1970afb9521Sdjmover the tunnel channel by encapsulating them in SSH protocol strings 1980afb9521Sdjmand sending them as channel data. This ensures that packet boundaries 1990afb9521Sdjmare kept intact. Specifically, packets are transmitted using normal 2000afb9521SdjmSSH_MSG_CHANNEL_DATA packets: 2010afb9521Sdjm 2020afb9521Sdjm byte SSH_MSG_CHANNEL_DATA 2030afb9521Sdjm uint32 recipient channel 2040afb9521Sdjm string data 2050afb9521Sdjm 2060afb9521SdjmThe contents of the "data" field for layer 3 packets is: 2070afb9521Sdjm 2080afb9521Sdjm uint32 packet length 2090afb9521Sdjm uint32 address family 2100afb9521Sdjm byte[packet length - 4] packet data 2110afb9521Sdjm 2120afb9521SdjmThe "address family" field identifies the type of packet in the message. 2130afb9521SdjmIt may be one of: 2140afb9521Sdjm 2150afb9521Sdjm SSH_TUN_AF_INET 2 /* IPv4 */ 2160afb9521Sdjm SSH_TUN_AF_INET6 24 /* IPv6 */ 2170afb9521Sdjm 2180afb9521SdjmThe "packet data" field consists of the IPv4/IPv6 datagram itself 2190afb9521Sdjmwithout any link layer header. 2200afb9521Sdjm 221c880fb56SdjmThe contents of the "data" field for layer 2 packets is: 2220afb9521Sdjm 2230afb9521Sdjm uint32 packet length 2240afb9521Sdjm byte[packet length] frame 2250afb9521Sdjm 2266c9c8648SdjmThe "frame" field contains an IEEE 802.3 Ethernet frame, including 2270afb9521Sdjmheader. 2280afb9521Sdjm 229f6c05033Sdjm3. SFTP protocol changes 230f6c05033Sdjm 231f6c05033Sdjm3.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK 232422225e8Sdjm 233422225e8SdjmWhen OpenSSH's sftp-server was implemented, the order of the arguments 2346c9c8648Sdjmto the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately, 235422225e8Sdjmthe reversal was not noticed until the server was widely deployed. Since 236422225e8Sdjmfixing this to follow the specification would cause incompatibility, the 237422225e8Sdjmcurrent order was retained. For correct operation, clients should send 238422225e8SdjmSSH_FXP_SYMLINK as follows: 239422225e8Sdjm 240422225e8Sdjm uint32 id 241422225e8Sdjm string targetpath 242422225e8Sdjm string linkpath 243422225e8Sdjm 244f6c05033Sdjm3.2. sftp: Server extension announcement in SSH_FXP_VERSION 245422225e8Sdjm 246422225e8SdjmOpenSSH's sftp-server lists the extensions it supports using the 247422225e8Sdjmstandard extension announcement mechanism in the SSH_FXP_VERSION server 248422225e8Sdjmhello packet: 249422225e8Sdjm 250422225e8Sdjm uint32 3 /* protocol version */ 251422225e8Sdjm string ext1-name 252422225e8Sdjm string ext1-version 253422225e8Sdjm string ext2-name 254422225e8Sdjm string ext2-version 255422225e8Sdjm ... 256422225e8Sdjm string extN-name 257422225e8Sdjm string extN-version 258422225e8Sdjm 259422225e8SdjmEach extension reports its integer version number as an ASCII encoded 260422225e8Sdjmstring, e.g. "1". The version will be incremented if the extension is 261422225e8Sdjmever changed in an incompatible way. The server MAY advertise the same 262422225e8Sdjmextension with multiple versions (though this is unlikely). Clients MUST 2636c9c8648Sdjmcheck the version number before attempting to use the extension. 264422225e8Sdjm 265f6c05033Sdjm3.3. sftp: Extension request "posix-rename@openssh.com" 266422225e8Sdjm 267422225e8SdjmThis operation provides a rename operation with POSIX semantics, which 268422225e8Sdjmare different to those provided by the standard SSH_FXP_RENAME in 269422225e8Sdjmdraft-ietf-secsh-filexfer-02.txt. This request is implemented as a 270422225e8SdjmSSH_FXP_EXTENDED request with the following format: 271422225e8Sdjm 272422225e8Sdjm uint32 id 273422225e8Sdjm string "posix-rename@openssh.com" 274422225e8Sdjm string oldpath 275422225e8Sdjm string newpath 276422225e8Sdjm 277422225e8SdjmOn receiving this request the server will perform the POSIX operation 278422225e8Sdjmrename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message. 279422225e8SdjmThis extension is advertised in the SSH_FXP_VERSION hello with version 280422225e8Sdjm"1". 281422225e8Sdjm 282f6c05033Sdjm3.4. sftp: Extension requests "statvfs@openssh.com" and 283422225e8Sdjm "fstatvfs@openssh.com" 284422225e8Sdjm 285422225e8SdjmThese requests correspond to the statvfs and fstatvfs POSIX system 286422225e8Sdjminterfaces. The "statvfs@openssh.com" request operates on an explicit 287422225e8Sdjmpathname, and is formatted as follows: 288422225e8Sdjm 289422225e8Sdjm uint32 id 290422225e8Sdjm string "statvfs@openssh.com" 291422225e8Sdjm string path 292422225e8Sdjm 293422225e8SdjmThe "fstatvfs@openssh.com" operates on an open file handle: 294422225e8Sdjm 295422225e8Sdjm uint32 id 29638d4658eSdjm string "fstatvfs@openssh.com" 297422225e8Sdjm string handle 298422225e8Sdjm 299422225e8SdjmThese requests return a SSH_FXP_STATUS reply on failure. On success they 300422225e8Sdjmreturn the following SSH_FXP_EXTENDED_REPLY reply: 301422225e8Sdjm 302422225e8Sdjm uint32 id 303f00164cfSdtucker uint64 f_bsize /* file system block size */ 304f00164cfSdtucker uint64 f_frsize /* fundamental fs block size */ 305422225e8Sdjm uint64 f_blocks /* number of blocks (unit f_frsize) */ 306422225e8Sdjm uint64 f_bfree /* free blocks in file system */ 307422225e8Sdjm uint64 f_bavail /* free blocks for non-root */ 308422225e8Sdjm uint64 f_files /* total file inodes */ 309422225e8Sdjm uint64 f_ffree /* free file inodes */ 310422225e8Sdjm uint64 f_favail /* free file inodes for to non-root */ 31133745cbfSdjm uint64 f_fsid /* file system id */ 312f00164cfSdtucker uint64 f_flag /* bit mask of f_flag values */ 313f00164cfSdtucker uint64 f_namemax /* maximum filename length */ 314422225e8Sdjm 315422225e8SdjmThe values of the f_flag bitmask are as follows: 316422225e8Sdjm 317422225e8Sdjm #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */ 318422225e8Sdjm #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */ 319422225e8Sdjm 320fae5684aSdjmBoth the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are 321fae5684aSdjmadvertised in the SSH_FXP_VERSION hello with version "2". 32233745cbfSdjm 3239c120764Sdjm10. sftp: Extension request "hardlink@openssh.com" 3249c120764Sdjm 3259c120764SdjmThis request is for creating a hard link to a regular file. This 3269c120764Sdjmrequest is implemented as a SSH_FXP_EXTENDED request with the 3279c120764Sdjmfollowing format: 3289c120764Sdjm 3299c120764Sdjm uint32 id 3309c120764Sdjm string "hardlink@openssh.com" 3319c120764Sdjm string oldpath 3329c120764Sdjm string newpath 3339c120764Sdjm 3349c120764SdjmOn receiving this request the server will perform the operation 3359c120764Sdjmlink(oldpath, newpath) and will respond with a SSH_FXP_STATUS message. 3369c120764SdjmThis extension is advertised in the SSH_FXP_VERSION hello with version 3379c120764Sdjm"1". 3389c120764Sdjm 33994e35841Sdjm10. sftp: Extension request "fsync@openssh.com" 34094e35841Sdjm 34194e35841SdjmThis request asks the server to call fsync(2) on an open file handle. 34294e35841Sdjm 34394e35841Sdjm uint32 id 34494e35841Sdjm string "fsync@openssh.com" 34594e35841Sdjm string handle 34694e35841Sdjm 34794e35841SdjmOne receiving this request, a server will call fsync(handle_fd) and will 34894e35841Sdjmrespond with a SSH_FXP_STATUS message. 34994e35841Sdjm 35094e35841SdjmThis extension is advertised in the SSH_FXP_VERSION hello with version 35194e35841Sdjm"1". 35294e35841Sdjm 353*1edbfe23Sdjm$OpenBSD: PROTOCOL,v 1.22 2013/11/21 00:45:43 djm Exp $ 354