]>
Commit | Line | Data |
---|---|---|
1 | This documents OpenSSH's deviations and extensions to the published SSH | |
2 | protocol. | |
3 | ||
4 | Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH | |
5 | filexfer protocol described in: | |
6 | ||
7 | http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt | |
8 | ||
9 | Newer versions of the draft will not be supported, though some features | |
10 | are individually implemented as extensions described below. | |
11 | ||
12 | The protocol used by OpenSSH's ssh-agent is described in the file | |
13 | PROTOCOL.agent | |
14 | ||
15 | 1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com" | |
16 | ||
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 | |
19 | in: | |
20 | ||
21 | http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt | |
22 | ||
23 | 2. transport: Protocol 2 compression algorithm "zlib@openssh.com" | |
24 | ||
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. | |
29 | ||
30 | The method is documented in: | |
31 | ||
32 | http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt | |
33 | ||
34 | 3. connection: Channel write close extension "eow@openssh.com" | |
35 | ||
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 | |
41 | the peer. | |
42 | ||
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 | |
46 | descriptor. | |
47 | ||
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: | |
52 | ||
53 | byte SSH_MSG_CHANNEL_REQUEST | |
54 | uint32 recipient channel | |
55 | string "eow@openssh.com" | |
56 | boolean FALSE | |
57 | ||
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). | |
61 | ||
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. | |
66 | ||
67 | NB. due to certain broken SSH implementations aborting upon receipt | |
68 | of this message (in contravention of RFC4254 section 5.4), this | |
69 | message is only sent to OpenSSH peers (identified by banner). | |
70 | Other SSH implementations may be whitelisted to receive this message | |
71 | upon request. | |
72 | ||
73 | 4. connection: disallow additional sessions extension | |
74 | "no-more-sessions@openssh.com" | |
75 | ||
76 | Most SSH connections will only ever request a single session, but a | |
77 | attacker may abuse a running ssh client to surreptitiously open | |
78 | additional sessions under their control. OpenSSH provides a global | |
79 | request "no-more-sessions@openssh.com" to mitigate this attack. | |
80 | ||
81 | When an OpenSSH client expects that it will never open another session | |
82 | (i.e. it has been started with connection multiplexing disabled), it | |
83 | will send the following global request: | |
84 | ||
85 | byte SSH_MSG_GLOBAL_REQUEST | |
86 | string "no-more-sessions@openssh.com" | |
87 | char want-reply | |
88 | ||
89 | On receipt of such a message, an OpenSSH server will refuse to open | |
90 | future channels of type "session" and instead immediately abort the | |
91 | connection. | |
92 | ||
93 | Note that this is not a general defence against compromised clients | |
94 | (that is impossible), but it thwarts a simple attack. | |
95 | ||
96 | NB. due to certain broken SSH implementations aborting upon receipt | |
97 | of this message, the no-more-sessions request is only sent to OpenSSH | |
98 | servers (identified by banner). Other SSH implementations may be | |
99 | whitelisted to receive this message upon request. | |
100 | ||
101 | 5. connection: Tunnel forward extension "tun@openssh.com" | |
102 | ||
103 | OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com" | |
104 | channel type. This channel type supports forwarding of network packets | |
105 | with datagram boundaries intact between endpoints equipped with | |
106 | interfaces like the BSD tun(4) device. Tunnel forwarding channels are | |
107 | requested by the client with the following packet: | |
108 | ||
109 | byte SSH_MSG_CHANNEL_OPEN | |
110 | string "tun@openssh.com" | |
111 | uint32 sender channel | |
112 | uint32 initial window size | |
113 | uint32 maximum packet size | |
114 | uint32 tunnel mode | |
115 | uint32 remote unit number | |
116 | ||
117 | The "tunnel mode" parameter specifies whether the tunnel should forward | |
118 | layer 2 frames or layer 3 packets. It may take one of the following values: | |
119 | ||
120 | SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */ | |
121 | SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */ | |
122 | ||
123 | The "tunnel unit number" specifies the remote interface number, or may | |
124 | be 0x7fffffff to allow the server to automatically chose an interface. A | |
125 | server that is not willing to open a client-specified unit should refuse | |
126 | the request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful | |
127 | open, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS. | |
128 | ||
129 | Once established the client and server may exchange packet or frames | |
130 | over the tunnel channel by encapsulating them in SSH protocol strings | |
131 | and sending them as channel data. This ensures that packet boundaries | |
132 | are kept intact. Specifically, packets are transmitted using normal | |
133 | SSH_MSG_CHANNEL_DATA packets: | |
134 | ||
135 | byte SSH_MSG_CHANNEL_DATA | |
136 | uint32 recipient channel | |
137 | string data | |
138 | ||
139 | The contents of the "data" field for layer 3 packets is: | |
140 | ||
141 | uint32 packet length | |
142 | uint32 address family | |
143 | byte[packet length - 4] packet data | |
144 | ||
145 | The "address family" field identifies the type of packet in the message. | |
146 | It may be one of: | |
147 | ||
148 | SSH_TUN_AF_INET 2 /* IPv4 */ | |
149 | SSH_TUN_AF_INET6 24 /* IPv6 */ | |
150 | ||
151 | The "packet data" field consists of the IPv4/IPv6 datagram itself | |
152 | without any link layer header. | |
153 | ||
154 | The contents of the "data" field for layer 2 packets is: | |
155 | ||
156 | uint32 packet length | |
157 | byte[packet length] frame | |
158 | ||
159 | The "frame" field contains an IEEE 802.3 Ethernet frame, including | |
160 | header. | |
161 | ||
162 | 6. sftp: Reversal of arguments to SSH_FXP_SYMLINK | |
163 | ||
164 | When OpenSSH's sftp-server was implemented, the order of the arguments | |
165 | to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately, | |
166 | the reversal was not noticed until the server was widely deployed. Since | |
167 | fixing this to follow the specification would cause incompatibility, the | |
168 | current order was retained. For correct operation, clients should send | |
169 | SSH_FXP_SYMLINK as follows: | |
170 | ||
171 | uint32 id | |
172 | string targetpath | |
173 | string linkpath | |
174 | ||
175 | 7. sftp: Server extension announcement in SSH_FXP_VERSION | |
176 | ||
177 | OpenSSH's sftp-server lists the extensions it supports using the | |
178 | standard extension announcement mechanism in the SSH_FXP_VERSION server | |
179 | hello packet: | |
180 | ||
181 | uint32 3 /* protocol version */ | |
182 | string ext1-name | |
183 | string ext1-version | |
184 | string ext2-name | |
185 | string ext2-version | |
186 | ... | |
187 | string extN-name | |
188 | string extN-version | |
189 | ||
190 | Each extension reports its integer version number as an ASCII encoded | |
191 | string, e.g. "1". The version will be incremented if the extension is | |
192 | ever changed in an incompatible way. The server MAY advertise the same | |
193 | extension with multiple versions (though this is unlikely). Clients MUST | |
194 | check the version number before attempting to use the extension. | |
195 | ||
196 | 8. sftp: Extension request "posix-rename@openssh.com" | |
197 | ||
198 | This operation provides a rename operation with POSIX semantics, which | |
199 | are different to those provided by the standard SSH_FXP_RENAME in | |
200 | draft-ietf-secsh-filexfer-02.txt. This request is implemented as a | |
201 | SSH_FXP_EXTENDED request with the following format: | |
202 | ||
203 | uint32 id | |
204 | string "posix-rename@openssh.com" | |
205 | string oldpath | |
206 | string newpath | |
207 | ||
208 | On receiving this request the server will perform the POSIX operation | |
209 | rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message. | |
210 | This extension is advertised in the SSH_FXP_VERSION hello with version | |
211 | "1". | |
212 | ||
213 | 9. sftp: Extension requests "statvfs@openssh.com" and | |
214 | "fstatvfs@openssh.com" | |
215 | ||
216 | These requests correspond to the statvfs and fstatvfs POSIX system | |
217 | interfaces. The "statvfs@openssh.com" request operates on an explicit | |
218 | pathname, and is formatted as follows: | |
219 | ||
220 | uint32 id | |
221 | string "statvfs@openssh.com" | |
222 | string path | |
223 | ||
224 | The "fstatvfs@openssh.com" operates on an open file handle: | |
225 | ||
226 | uint32 id | |
227 | string "fstatvfs@openssh.com" | |
228 | string handle | |
229 | ||
230 | These requests return a SSH_FXP_STATUS reply on failure. On success they | |
231 | return the following SSH_FXP_EXTENDED_REPLY reply: | |
232 | ||
233 | uint32 id | |
234 | uint64 f_bsize /* file system block size */ | |
235 | uint64 f_frsize /* fundamental fs block size */ | |
236 | uint64 f_blocks /* number of blocks (unit f_frsize) */ | |
237 | uint64 f_bfree /* free blocks in file system */ | |
238 | uint64 f_bavail /* free blocks for non-root */ | |
239 | uint64 f_files /* total file inodes */ | |
240 | uint64 f_ffree /* free file inodes */ | |
241 | uint64 f_favail /* free file inodes for to non-root */ | |
242 | uint64 f_fsid /* file system id */ | |
243 | uint64 f_flag /* bit mask of f_flag values */ | |
244 | uint64 f_namemax /* maximum filename length */ | |
245 | ||
246 | The values of the f_flag bitmask are as follows: | |
247 | ||
248 | #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */ | |
249 | #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */ | |
250 | ||
251 | Both the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are | |
252 | advertised in the SSH_FXP_VERSION hello with version "2". | |
253 | ||
254 | $OpenBSD: PROTOCOL,v 1.14 2010/01/09 00:57:10 djm Exp $ |