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