1 This documents OpenSSH's deviations and extensions to the published SSH
4 Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
5 filexfer protocol described in:
7 http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
9 Features from newer versions of the draft are not supported, unless
10 explicitly implemented as extensions described below.
12 1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
14 This is a new transport-layer MAC method using the UMAC algorithm
15 (rfc4418). This method is identical to the "umac-64" method documented
18 http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
20 2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
22 This transport-layer compression method uses the zlib compression
23 algorithm (identical to the "zlib" method in rfc4253), but delays the
24 start of compression until after authentication has completed. This
25 avoids exposing compression code to attacks from unauthenticated users.
27 The method is documented in:
29 http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
31 3. connection: Channel write close extension "eow@openssh.com"
33 The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
34 message to allow an endpoint to signal its peer that it will send no
35 more data over a channel. Unfortunately, there is no symmetric way for
36 an endpoint to request that its peer should cease sending data to it
37 while still keeping the channel open for the endpoint to send data to
40 This is desirable, since it saves the transmission of data that would
41 otherwise need to be discarded and it allows an endpoint to signal local
42 processes of the condition, e.g. by closing the corresponding file
45 OpenSSH implements a channel extension message to perform this
46 signalling: "eow@openssh.com" (End Of Write). This message is sent by an
47 endpoint when the local output of a channel is closed or experiences a
48 write error. The message is formatted as follows:
50 byte SSH_MSG_CHANNEL_REQUEST
51 uint32 recipient channel
52 string "eow@openssh.com"
55 On receiving this message, the peer SHOULD cease sending data of
56 the channel and MAY signal the process from which the channel data
57 originates (e.g. by closing its read file descriptor).
59 As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
60 remain open after a "eow@openssh.com" has been sent and more data may
61 still be sent in the other direction. This message does not consume
62 window space and may be sent even if no window space is available.
64 4. connection: disallow additional sessions extension
65 "no-more-sessions@openssh.com"
67 Most SSH connections will only ever request a single session, but a
68 attacker may abuse a running ssh client to surreptitiously open
69 additional sessions under their control. OpenSSH provides a global
70 request "no-more-sessions@openssh.com" to mitigate this attack.
72 When an OpenSSH client expects that it will never open another session
73 (i.e. it has been started with connection multiplexing disabled), it
74 will send the following global request:
76 byte SSH_MSG_GLOBAL_REQUEST
77 string "no-more-sessions@openssh.com"
80 On receipt of such a message, an OpenSSH server will refuse to open
81 future channels of type "session" and instead immediately abort the
84 Note that this is not a general defence against compromised clients
85 (that is impossible), but it thwarts a simple attack.
87 5. connection: Tunnel forward extension "tun@openssh.com"
89 OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
90 channel type. This channel type supports forwarding of network packets
91 with datagram boundaries intact between endpoints equipped with
92 interfaces like the BSD tun(4) device. Tunnel forwarding channels are
93 requested by the client with the following packet:
95 byte SSH_MSG_CHANNEL_OPEN
96 string "tun@openssh.com"
98 uint32 initial window size
99 uint32 maximum packet size
101 uint32 remote unit number
103 The "tunnel mode" parameter specifies whether the tunnel should forward
104 layer 2 frames or layer 3 packets. It may take one of the following values:
106 SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */
107 SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */
109 The "tunnel unit number" specifies the remote interface number, or may
110 be zero to allow the server to automatically chose an interface. A server
111 that is not willing to open a client-specified unit should refuse the
112 request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful open,
113 the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
115 Once established the client and server may exchange packet or frames
116 over the tunnel channel by encapsulating them in SSH protocol strings
117 and sending them as channel data. This ensures that packet boundaries
118 are kept intact. Specifically, packets are transmitted using normal
119 SSH_MSG_CHANNEL_DATA packets:
121 byte SSH_MSG_CHANNEL_DATA
122 uint32 recipient channel
125 The contents of the "data" field for layer 3 packets is:
128 uint32 address family
129 byte[packet length - 4] packet data
131 The "address family" field identifies the type of packet in the message.
134 SSH_TUN_AF_INET 2 /* IPv4 */
135 SSH_TUN_AF_INET6 24 /* IPv6 */
137 The "packet data" field consists of the IPv4/IPv6 datagram itself
138 without any link layer header.
140 The contents of the "data" field for layer 3 packets is:
143 byte[packet length] frame
145 The "frame" field contains an IEEE 802.3 Ethernet frame, including
148 6. sftp: Reversal of arguments to SSH_FXP_SYMLINK
150 When OpenSSH's sftp-server was implemented, the order of the arguments
151 to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
152 the reversal was not noticed until the server was widely deployed. Since
153 fixing this to follow the specification would cause incompatibility, the
154 current order was retained. For correct operation, clients should send
155 SSH_FXP_SYMLINK as follows:
161 7. sftp: Server extension announcement in SSH_FXP_VERSION
163 OpenSSH's sftp-server lists the extensions it supports using the
164 standard extension announcement mechanism in the SSH_FXP_VERSION server
167 uint32 3 /* protocol version */
176 Each extension reports its integer version number as an ASCII encoded
177 string, e.g. "1". The version will be incremented if the extension is
178 ever changed in an incompatible way. The server MAY advertise the same
179 extension with multiple versions (though this is unlikely). Clients MUST
180 check the version number before attempting to use the extension.
182 8. sftp: Extension request "posix-rename@openssh.com"
184 This operation provides a rename operation with POSIX semantics, which
185 are different to those provided by the standard SSH_FXP_RENAME in
186 draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
187 SSH_FXP_EXTENDED request with the following format:
190 string "posix-rename@openssh.com"
194 On receiving this request the server will perform the POSIX operation
195 rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
196 This extension is advertised in the SSH_FXP_VERSION hello with version
199 9. sftp: Extension requests "statvfs@openssh.com" and
200 "fstatvfs@openssh.com"
202 These requests correspond to the statvfs and fstatvfs POSIX system
203 interfaces. The "statvfs@openssh.com" request operates on an explicit
204 pathname, and is formatted as follows:
207 string "statvfs@openssh.com"
210 The "fstatvfs@openssh.com" operates on an open file handle:
213 string "fstatvfs@openssh.com"
216 These requests return a SSH_FXP_STATUS reply on failure. On success they
217 return the following SSH_FXP_EXTENDED_REPLY reply:
220 uint64 f_bsize /* file system block size */
221 uint64 f_frsize /* fundamental fs block size */
222 uint64 f_blocks /* number of blocks (unit f_frsize) */
223 uint64 f_bfree /* free blocks in file system */
224 uint64 f_bavail /* free blocks for non-root */
225 uint64 f_files /* total file inodes */
226 uint64 f_ffree /* free file inodes */
227 uint64 f_favail /* free file inodes for to non-root */
228 uint64 f_fsid /* file system id */
229 uint64 f_flag /* bit mask of f_flag values */
230 uint64 f_namemax /* maximum filename length */
232 The values of the f_flag bitmask are as follows:
234 #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
235 #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
237 This extension is advertised in the SSH_FXP_VERSION hello with version
240 $OpenBSD: PROTOCOL,v 1.8 2008/06/28 07:25:07 djm Exp $