]>
Commit | Line | Data |
---|---|---|
8be03682 | 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 | Features from newer versions of the draft are not supported, unless | |
10 | explicitly implemented as extensions described below. | |
11 | ||
ab3eb078 | 12 | The protocol used by OpenSSH's ssh-agent is described in the file |
13 | PROTOCOL.agent | |
14 | ||
8be03682 | 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 | |
8fb1ddc9 | 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: | |
8be03682 | 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 | ||
3f0444ca | 67 | 4. connection: disallow additional sessions extension |
68 | "no-more-sessions@openssh.com" | |
69 | ||
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. | |
74 | ||
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: | |
78 | ||
79 | byte SSH_MSG_GLOBAL_REQUEST | |
80 | string "no-more-sessions@openssh.com" | |
81 | char want-reply | |
82 | ||
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 | |
85 | connection. | |
86 | ||
87 | Note that this is not a general defence against compromised clients | |
88 | (that is impossible), but it thwarts a simple attack. | |
89 | ||
9bcf03ce | 90 | 5. connection: Tunnel forward extension "tun@openssh.com" |
91 | ||
cda43f66 | 92 | OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com" |
9bcf03ce | 93 | channel type. This channel type supports forwarding of network packets |
cda43f66 | 94 | with datagram boundaries intact between endpoints equipped with |
9bcf03ce | 95 | interfaces like the BSD tun(4) device. Tunnel forwarding channels are |
96 | requested by the client with the following packet: | |
97 | ||
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 | |
103 | uint32 tunnel mode | |
104 | uint32 remote unit number | |
105 | ||
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: | |
108 | ||
109 | SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */ | |
110 | SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */ | |
111 | ||
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. | |
117 | ||
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: | |
123 | ||
124 | byte SSH_MSG_CHANNEL_DATA | |
125 | uint32 recipient channel | |
126 | string data | |
127 | ||
128 | The contents of the "data" field for layer 3 packets is: | |
129 | ||
130 | uint32 packet length | |
131 | uint32 address family | |
132 | byte[packet length - 4] packet data | |
133 | ||
134 | The "address family" field identifies the type of packet in the message. | |
135 | It may be one of: | |
136 | ||
137 | SSH_TUN_AF_INET 2 /* IPv4 */ | |
138 | SSH_TUN_AF_INET6 24 /* IPv6 */ | |
139 | ||
140 | The "packet data" field consists of the IPv4/IPv6 datagram itself | |
141 | without any link layer header. | |
142 | ||
143 | The contents of the "data" field for layer 3 packets is: | |
144 | ||
145 | uint32 packet length | |
146 | byte[packet length] frame | |
147 | ||
cda43f66 | 148 | The "frame" field contains an IEEE 802.3 Ethernet frame, including |
9bcf03ce | 149 | header. |
150 | ||
151 | 6. sftp: Reversal of arguments to SSH_FXP_SYMLINK | |
8be03682 | 152 | |
153 | When OpenSSH's sftp-server was implemented, the order of the arguments | |
cda43f66 | 154 | to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately, |
8be03682 | 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: | |
159 | ||
160 | uint32 id | |
161 | string targetpath | |
162 | string linkpath | |
163 | ||
9bcf03ce | 164 | 7. sftp: Server extension announcement in SSH_FXP_VERSION |
8be03682 | 165 | |
166 | OpenSSH's sftp-server lists the extensions it supports using the | |
167 | standard extension announcement mechanism in the SSH_FXP_VERSION server | |
168 | hello packet: | |
169 | ||
170 | uint32 3 /* protocol version */ | |
171 | string ext1-name | |
172 | string ext1-version | |
173 | string ext2-name | |
174 | string ext2-version | |
175 | ... | |
176 | string extN-name | |
177 | string extN-version | |
178 | ||
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 | |
cda43f66 | 183 | check the version number before attempting to use the extension. |
8be03682 | 184 | |
9bcf03ce | 185 | 8. sftp: Extension request "posix-rename@openssh.com" |
8be03682 | 186 | |
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: | |
191 | ||
192 | uint32 id | |
193 | string "posix-rename@openssh.com" | |
194 | string oldpath | |
195 | string newpath | |
196 | ||
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 | |
200 | "1". | |
201 | ||
9bcf03ce | 202 | 9. sftp: Extension requests "statvfs@openssh.com" and |
8be03682 | 203 | "fstatvfs@openssh.com" |
204 | ||
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: | |
208 | ||
209 | uint32 id | |
210 | string "statvfs@openssh.com" | |
211 | string path | |
212 | ||
cda43f66 | 213 | The "fstatvfs@openssh.com" operates on an open file handle: |
8be03682 | 214 | |
215 | uint32 id | |
216 | string "fstatvfs@openssh.com" | |
217 | string handle | |
218 | ||
219 | These requests return a SSH_FXP_STATUS reply on failure. On success they | |
220 | return the following SSH_FXP_EXTENDED_REPLY reply: | |
221 | ||
222 | uint32 id | |
f044f89e | 223 | uint64 f_bsize /* file system block size */ |
224 | uint64 f_frsize /* fundamental fs block size */ | |
8be03682 | 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 */ | |
0ad258dc | 231 | uint64 f_fsid /* file system id */ |
f044f89e | 232 | uint64 f_flag /* bit mask of f_flag values */ |
233 | uint64 f_namemax /* maximum filename length */ | |
8be03682 | 234 | |
235 | The values of the f_flag bitmask are as follows: | |
236 | ||
237 | #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */ | |
238 | #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */ | |
239 | ||
0ad258dc | 240 | This extension is advertised in the SSH_FXP_VERSION hello with version |
241 | "2". | |
242 | ||
8fb1ddc9 | 243 | $OpenBSD: PROTOCOL,v 1.10 2008/06/30 12:18:34 djm Exp $ |