PROTOCOL revision 1.22 1 1.1 christos This documents OpenSSH's deviations and extensions to the published SSH
2 1.1 christos protocol.
3 1.1 christos
4 1.1 christos Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
5 1.1 christos filexfer protocol described in:
6 1.1 christos
7 1.1 christos http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
8 1.1 christos
9 1.2 christos Newer versions of the draft will not be supported, though some features
10 1.2 christos are individually implemented as extensions described below.
11 1.1 christos
12 1.1 christos The protocol used by OpenSSH's ssh-agent is described in the file
13 1.1 christos PROTOCOL.agent
14 1.1 christos
15 1.2 christos 1. Transport protocol changes
16 1.2 christos
17 1.2 christos 1.1. transport: Protocol 2 MAC algorithm "umac-64 (a] openssh.com"
18 1.1 christos
19 1.1 christos This is a new transport-layer MAC method using the UMAC algorithm
20 1.1 christos (rfc4418). This method is identical to the "umac-64" method documented
21 1.1 christos in:
22 1.1 christos
23 1.1 christos http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
24 1.1 christos
25 1.2 christos 1.2. transport: Protocol 2 compression algorithm "zlib (a] openssh.com"
26 1.1 christos
27 1.1 christos This transport-layer compression method uses the zlib compression
28 1.1 christos algorithm (identical to the "zlib" method in rfc4253), but delays the
29 1.1 christos start of compression until after authentication has completed. This
30 1.1 christos avoids exposing compression code to attacks from unauthenticated users.
31 1.1 christos
32 1.1 christos The method is documented in:
33 1.1 christos
34 1.1 christos http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
35 1.1 christos
36 1.10 christos 1.3. transport: New public key algorithms "ssh-rsa-cert-v01 (a] openssh.com",
37 1.10 christos "ssh-dsa-cert-v01 (a] openssh.com",
38 1.2 christos "ecdsa-sha2-nistp256-cert-v01 (a] openssh.com",
39 1.2 christos "ecdsa-sha2-nistp384-cert-v01 (a] openssh.com" and
40 1.2 christos "ecdsa-sha2-nistp521-cert-v01 (a] openssh.com"
41 1.2 christos
42 1.2 christos OpenSSH introduces new public key algorithms to support certificate
43 1.5 christos authentication for users and host keys. These methods are documented
44 1.5 christos in the file PROTOCOL.certkeys
45 1.2 christos
46 1.2 christos 1.4. transport: Elliptic Curve cryptography
47 1.2 christos
48 1.2 christos OpenSSH supports ECC key exchange and public key authentication as
49 1.2 christos specified in RFC5656. Only the ecdsa-sha2-nistp256, ecdsa-sha2-nistp384
50 1.2 christos and ecdsa-sha2-nistp521 curves over GF(p) are supported. Elliptic
51 1.2 christos curve points encoded using point compression are NOT accepted or
52 1.2 christos generated.
53 1.2 christos
54 1.3 christos 1.5 transport: Protocol 2 Encrypt-then-MAC MAC algorithms
55 1.3 christos
56 1.3 christos OpenSSH supports MAC algorithms, whose names contain "-etm", that
57 1.3 christos perform the calculations in a different order to that defined in RFC
58 1.3 christos 4253. These variants use the so-called "encrypt then MAC" ordering,
59 1.3 christos calculating the MAC over the packet ciphertext rather than the
60 1.3 christos plaintext. This ordering closes a security flaw in the SSH transport
61 1.3 christos protocol, where decryption of unauthenticated ciphertext provided a
62 1.3 christos "decryption oracle" that could, in conjunction with cipher flaws, reveal
63 1.3 christos session plaintext.
64 1.3 christos
65 1.3 christos Specifically, the "-etm" MAC algorithms modify the transport protocol
66 1.3 christos to calculate the MAC over the packet ciphertext and to send the packet
67 1.3 christos length unencrypted. This is necessary for the transport to obtain the
68 1.3 christos length of the packet and location of the MAC tag so that it may be
69 1.3 christos verified without decrypting unauthenticated data.
70 1.3 christos
71 1.3 christos As such, the MAC covers:
72 1.3 christos
73 1.3 christos mac = MAC(key, sequence_number || packet_length || encrypted_packet)
74 1.3 christos
75 1.3 christos where "packet_length" is encoded as a uint32 and "encrypted_packet"
76 1.3 christos contains:
77 1.3 christos
78 1.3 christos byte padding_length
79 1.3 christos byte[n1] payload; n1 = packet_length - padding_length - 1
80 1.3 christos byte[n2] random padding; n2 = padding_length
81 1.3 christos
82 1.3 christos 1.6 transport: AES-GCM
83 1.3 christos
84 1.3 christos OpenSSH supports the AES-GCM algorithm as specified in RFC 5647.
85 1.3 christos Because of problems with the specification of the key exchange
86 1.3 christos the behaviour of OpenSSH differs from the RFC as follows:
87 1.3 christos
88 1.3 christos AES-GCM is only negotiated as the cipher algorithms
89 1.3 christos "aes128-gcm (a] openssh.com" or "aes256-gcm (a] openssh.com" and never as
90 1.3 christos an MAC algorithm. Additionally, if AES-GCM is selected as the cipher
91 1.3 christos the exchanged MAC algorithms are ignored and there doesn't have to be
92 1.3 christos a matching MAC.
93 1.3 christos
94 1.4 christos 1.7 transport: chacha20-poly1305 (a] openssh.com authenticated encryption
95 1.4 christos
96 1.4 christos OpenSSH supports authenticated encryption using ChaCha20 and Poly1305
97 1.4 christos as described in PROTOCOL.chacha20poly1305.
98 1.4 christos
99 1.4 christos 1.8 transport: curve25519-sha256 (a] libssh.org key exchange algorithm
100 1.4 christos
101 1.4 christos OpenSSH supports the use of ECDH in Curve25519 for key exchange as
102 1.4 christos described at:
103 1.4 christos http://git.libssh.org/users/aris/libssh.git/plain/doc/curve25519-sha256@libssh.org.txt?h=curve25519
104 1.4 christos
105 1.20 christos This is identical to curve25519-sha256 as later published in RFC8731.
106 1.20 christos
107 1.22 christos 1.9 transport: ping facility
108 1.22 christos
109 1.22 christos OpenSSH implements a transport level ping message SSH2_MSG_PING
110 1.22 christos and a corresponding SSH2_MSG_PONG reply.
111 1.22 christos
112 1.22 christos #define SSH2_MSG_PING 192
113 1.22 christos #define SSH2_MSG_PONG 193
114 1.22 christos
115 1.22 christos The ping message is simply:
116 1.22 christos
117 1.22 christos byte SSH_MSG_PING
118 1.22 christos string data
119 1.22 christos
120 1.22 christos The reply copies the data (which may be the empty string) from the
121 1.22 christos ping:
122 1.22 christos
123 1.22 christos byte SSH_MSG_PONG
124 1.22 christos string data
125 1.22 christos
126 1.22 christos Replies are sent in order. They are sent immediately except when rekeying
127 1.22 christos is in progress, in which case they are queued until rekeying completes.
128 1.22 christos
129 1.22 christos The server advertises support for these messages using the
130 1.22 christos SSH2_MSG_EXT_INFO mechanism (RFC8308), with the following message:
131 1.22 christos
132 1.22 christos string "ping (a] openssh.com"
133 1.22 christos string "0" (version)
134 1.22 christos
135 1.22 christos The ping/reply message is implemented at the transport layer rather
136 1.22 christos than as a named global or channel request to allow pings with very
137 1.22 christos short packet lengths, which would not be possible with other
138 1.22 christos approaches.
139 1.22 christos
140 1.2 christos 2. Connection protocol changes
141 1.2 christos
142 1.2 christos 2.1. connection: Channel write close extension "eow (a] openssh.com"
143 1.1 christos
144 1.1 christos The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
145 1.1 christos message to allow an endpoint to signal its peer that it will send no
146 1.1 christos more data over a channel. Unfortunately, there is no symmetric way for
147 1.1 christos an endpoint to request that its peer should cease sending data to it
148 1.1 christos while still keeping the channel open for the endpoint to send data to
149 1.1 christos the peer.
150 1.1 christos
151 1.1 christos This is desirable, since it saves the transmission of data that would
152 1.1 christos otherwise need to be discarded and it allows an endpoint to signal local
153 1.1 christos processes of the condition, e.g. by closing the corresponding file
154 1.1 christos descriptor.
155 1.1 christos
156 1.1 christos OpenSSH implements a channel extension message to perform this
157 1.1 christos signalling: "eow (a] openssh.com" (End Of Write). This message is sent by
158 1.1 christos an endpoint when the local output of a session channel is closed or
159 1.1 christos experiences a write error. The message is formatted as follows:
160 1.1 christos
161 1.1 christos byte SSH_MSG_CHANNEL_REQUEST
162 1.1 christos uint32 recipient channel
163 1.1 christos string "eow (a] openssh.com"
164 1.1 christos boolean FALSE
165 1.1 christos
166 1.1 christos On receiving this message, the peer SHOULD cease sending data of
167 1.1 christos the channel and MAY signal the process from which the channel data
168 1.1 christos originates (e.g. by closing its read file descriptor).
169 1.1 christos
170 1.1 christos As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
171 1.1 christos remain open after a "eow (a] openssh.com" has been sent and more data may
172 1.1 christos still be sent in the other direction. This message does not consume
173 1.1 christos window space and may be sent even if no window space is available.
174 1.1 christos
175 1.1 christos NB. due to certain broken SSH implementations aborting upon receipt
176 1.1 christos of this message (in contravention of RFC4254 section 5.4), this
177 1.1 christos message is only sent to OpenSSH peers (identified by banner).
178 1.15 christos Other SSH implementations may be listed to receive this message
179 1.1 christos upon request.
180 1.1 christos
181 1.2 christos 2.2. connection: disallow additional sessions extension
182 1.2 christos "no-more-sessions (a] openssh.com"
183 1.1 christos
184 1.1 christos Most SSH connections will only ever request a single session, but a
185 1.1 christos attacker may abuse a running ssh client to surreptitiously open
186 1.1 christos additional sessions under their control. OpenSSH provides a global
187 1.1 christos request "no-more-sessions (a] openssh.com" to mitigate this attack.
188 1.1 christos
189 1.1 christos When an OpenSSH client expects that it will never open another session
190 1.1 christos (i.e. it has been started with connection multiplexing disabled), it
191 1.1 christos will send the following global request:
192 1.1 christos
193 1.1 christos byte SSH_MSG_GLOBAL_REQUEST
194 1.1 christos string "no-more-sessions (a] openssh.com"
195 1.1 christos char want-reply
196 1.1 christos
197 1.1 christos On receipt of such a message, an OpenSSH server will refuse to open
198 1.1 christos future channels of type "session" and instead immediately abort the
199 1.1 christos connection.
200 1.1 christos
201 1.1 christos Note that this is not a general defence against compromised clients
202 1.1 christos (that is impossible), but it thwarts a simple attack.
203 1.1 christos
204 1.1 christos NB. due to certain broken SSH implementations aborting upon receipt
205 1.1 christos of this message, the no-more-sessions request is only sent to OpenSSH
206 1.1 christos servers (identified by banner). Other SSH implementations may be
207 1.15 christos listed to receive this message upon request.
208 1.1 christos
209 1.2 christos 2.3. connection: Tunnel forward extension "tun (a] openssh.com"
210 1.1 christos
211 1.1 christos OpenSSH supports layer 2 and layer 3 tunnelling via the "tun (a] openssh.com"
212 1.1 christos channel type. This channel type supports forwarding of network packets
213 1.6 christos with datagram boundaries intact between endpoints equipped with
214 1.1 christos interfaces like the BSD tun(4) device. Tunnel forwarding channels are
215 1.1 christos requested by the client with the following packet:
216 1.1 christos
217 1.1 christos byte SSH_MSG_CHANNEL_OPEN
218 1.1 christos string "tun (a] openssh.com"
219 1.1 christos uint32 sender channel
220 1.1 christos uint32 initial window size
221 1.1 christos uint32 maximum packet size
222 1.1 christos uint32 tunnel mode
223 1.1 christos uint32 remote unit number
224 1.1 christos
225 1.1 christos The "tunnel mode" parameter specifies whether the tunnel should forward
226 1.1 christos layer 2 frames or layer 3 packets. It may take one of the following values:
227 1.1 christos
228 1.1 christos SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */
229 1.1 christos SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */
230 1.1 christos
231 1.1 christos The "tunnel unit number" specifies the remote interface number, or may
232 1.14 christos be 0x7fffffff to allow the server to automatically choose an interface. A
233 1.2 christos server that is not willing to open a client-specified unit should refuse
234 1.2 christos the request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful
235 1.2 christos open, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
236 1.1 christos
237 1.1 christos Once established the client and server may exchange packet or frames
238 1.1 christos over the tunnel channel by encapsulating them in SSH protocol strings
239 1.1 christos and sending them as channel data. This ensures that packet boundaries
240 1.1 christos are kept intact. Specifically, packets are transmitted using normal
241 1.1 christos SSH_MSG_CHANNEL_DATA packets:
242 1.1 christos
243 1.1 christos byte SSH_MSG_CHANNEL_DATA
244 1.1 christos uint32 recipient channel
245 1.1 christos string data
246 1.1 christos
247 1.1 christos The contents of the "data" field for layer 3 packets is:
248 1.1 christos
249 1.1 christos uint32 packet length
250 1.1 christos uint32 address family
251 1.1 christos byte[packet length - 4] packet data
252 1.1 christos
253 1.1 christos The "address family" field identifies the type of packet in the message.
254 1.1 christos It may be one of:
255 1.1 christos
256 1.1 christos SSH_TUN_AF_INET 2 /* IPv4 */
257 1.1 christos SSH_TUN_AF_INET6 24 /* IPv6 */
258 1.1 christos
259 1.1 christos The "packet data" field consists of the IPv4/IPv6 datagram itself
260 1.1 christos without any link layer header.
261 1.1 christos
262 1.2 christos The contents of the "data" field for layer 2 packets is:
263 1.1 christos
264 1.1 christos uint32 packet length
265 1.1 christos byte[packet length] frame
266 1.1 christos
267 1.1 christos The "frame" field contains an IEEE 802.3 Ethernet frame, including
268 1.1 christos header.
269 1.1 christos
270 1.4 christos 2.4. connection: Unix domain socket forwarding
271 1.4 christos
272 1.4 christos OpenSSH supports local and remote Unix domain socket forwarding
273 1.4 christos using the "streamlocal" extension. Forwarding is initiated as per
274 1.4 christos TCP sockets but with a single path instead of a host and port.
275 1.4 christos
276 1.4 christos Similar to direct-tcpip, direct-streamlocal is sent by the client
277 1.4 christos to request that the server make a connection to a Unix domain socket.
278 1.4 christos
279 1.4 christos byte SSH_MSG_CHANNEL_OPEN
280 1.4 christos string "direct-streamlocal (a] openssh.com"
281 1.4 christos uint32 sender channel
282 1.4 christos uint32 initial window size
283 1.4 christos uint32 maximum packet size
284 1.4 christos string socket path
285 1.8 christos string reserved
286 1.8 christos uint32 reserved
287 1.4 christos
288 1.4 christos Similar to forwarded-tcpip, forwarded-streamlocal is sent by the
289 1.4 christos server when the client has previously send the server a streamlocal-forward
290 1.4 christos GLOBAL_REQUEST.
291 1.4 christos
292 1.4 christos byte SSH_MSG_CHANNEL_OPEN
293 1.4 christos string "forwarded-streamlocal (a] openssh.com"
294 1.4 christos uint32 sender channel
295 1.4 christos uint32 initial window size
296 1.4 christos uint32 maximum packet size
297 1.4 christos string socket path
298 1.4 christos string reserved for future use
299 1.4 christos
300 1.4 christos The reserved field is not currently defined and is ignored on the
301 1.4 christos remote end. It is intended to be used in the future to pass
302 1.4 christos information about the socket file, such as ownership and mode.
303 1.4 christos The client currently sends the empty string for this field.
304 1.4 christos
305 1.4 christos Similar to tcpip-forward, streamlocal-forward is sent by the client
306 1.4 christos to request remote forwarding of a Unix domain socket.
307 1.4 christos
308 1.4 christos byte SSH2_MSG_GLOBAL_REQUEST
309 1.4 christos string "streamlocal-forward (a] openssh.com"
310 1.4 christos boolean TRUE
311 1.4 christos string socket path
312 1.4 christos
313 1.4 christos Similar to cancel-tcpip-forward, cancel-streamlocal-forward is sent
314 1.4 christos by the client cancel the forwarding of a Unix domain socket.
315 1.4 christos
316 1.4 christos byte SSH2_MSG_GLOBAL_REQUEST
317 1.4 christos string "cancel-streamlocal-forward (a] openssh.com"
318 1.4 christos boolean FALSE
319 1.4 christos string socket path
320 1.4 christos
321 1.5 christos 2.5. connection: hostkey update and rotation "hostkeys-00 (a] openssh.com"
322 1.5 christos and "hostkeys-prove-00 (a] openssh.com"
323 1.5 christos
324 1.5 christos OpenSSH supports a protocol extension allowing a server to inform
325 1.5 christos a client of all its protocol v.2 host keys after user-authentication
326 1.5 christos has completed.
327 1.5 christos
328 1.5 christos byte SSH_MSG_GLOBAL_REQUEST
329 1.5 christos string "hostkeys-00 (a] openssh.com"
330 1.16 christos char 0 /* want-reply */
331 1.5 christos string[] hostkeys
332 1.5 christos
333 1.5 christos Upon receiving this message, a client should check which of the
334 1.11 christos supplied host keys are present in known_hosts.
335 1.11 christos
336 1.11 christos Note that the server may send key types that the client does not
337 1.14 christos support. The client should disregard such keys if they are received.
338 1.11 christos
339 1.11 christos If the client identifies any keys that are not present for the host,
340 1.11 christos it should send a "hostkeys-prove (a] openssh.com" message to request the
341 1.11 christos server prove ownership of the private half of the key.
342 1.5 christos
343 1.5 christos byte SSH_MSG_GLOBAL_REQUEST
344 1.5 christos string "hostkeys-prove-00 (a] openssh.com"
345 1.5 christos char 1 /* want-reply */
346 1.5 christos string[] hostkeys
347 1.5 christos
348 1.5 christos When a server receives this message, it should generate a signature
349 1.5 christos using each requested key over the following:
350 1.5 christos
351 1.5 christos string "hostkeys-prove-00 (a] openssh.com"
352 1.5 christos string session identifier
353 1.5 christos string hostkey
354 1.5 christos
355 1.5 christos These signatures should be included in the reply, in the order matching
356 1.5 christos the hostkeys in the request:
357 1.5 christos
358 1.5 christos byte SSH_MSG_REQUEST_SUCCESS
359 1.5 christos string[] signatures
360 1.5 christos
361 1.5 christos When the client receives this reply (and not a failure), it should
362 1.5 christos validate the signatures and may update its known_hosts file, adding keys
363 1.5 christos that it has not seen before and deleting keys for the server host that
364 1.5 christos are no longer offered.
365 1.5 christos
366 1.5 christos These extensions let a client learn key types that it had not previously
367 1.5 christos encountered, thereby allowing it to potentially upgrade from weaker
368 1.5 christos key algorithms to better ones. It also supports graceful key rotation:
369 1.5 christos a server may offer multiple keys of the same type for a period (to
370 1.5 christos give clients an opportunity to learn them using this extension) before
371 1.5 christos removing the deprecated key from those offered.
372 1.5 christos
373 1.13 christos 2.6. connection: SIGINFO support for "signal" channel request
374 1.13 christos
375 1.13 christos The SSH channels protocol (RFC4254 section 6.9) supports sending a
376 1.13 christos signal to a session attached to a channel. OpenSSH supports one
377 1.13 christos extension signal "INFO (a] openssh.com" that allows sending SIGINFO on
378 1.13 christos BSD-derived systems.
379 1.13 christos
380 1.18 christos 3. Authentication protocol changes
381 1.2 christos
382 1.18 christos 3.1. Host-bound public key authentication
383 1.18 christos
384 1.18 christos This is trivial change to the traditional "publickey" authentication
385 1.18 christos method. The authentication request is identical to the original method
386 1.18 christos but for the name and one additional field:
387 1.18 christos
388 1.18 christos byte SSH2_MSG_USERAUTH_REQUEST
389 1.18 christos string username
390 1.18 christos string "ssh-connection"
391 1.18 christos string "publickey-hostbound-v00 (a] openssh.com"
392 1.18 christos bool has_signature
393 1.18 christos string pkalg
394 1.18 christos string public key
395 1.18 christos string server host key
396 1.18 christos
397 1.18 christos Because the entire SSH2_MSG_USERAUTH_REQUEST message is included in
398 1.18 christos the signed data, this ensures that a binding between the destination
399 1.18 christos user, the server identity and the session identifier is visible to the
400 1.18 christos signer. OpenSSH uses this binding via signed data to implement per-key
401 1.18 christos restrictions in ssh-agent.
402 1.18 christos
403 1.18 christos A server may advertise this method using the SSH2_MSG_EXT_INFO
404 1.18 christos mechanism (RFC8308), with the following message:
405 1.18 christos
406 1.18 christos string "publickey-hostbound (a] openssh.com"
407 1.18 christos string "0" (version)
408 1.18 christos
409 1.18 christos Clients should prefer host-bound authentication when advertised by
410 1.18 christos server.
411 1.18 christos
412 1.18 christos 4. SFTP protocol changes
413 1.18 christos
414 1.18 christos 4.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK
415 1.1 christos
416 1.1 christos When OpenSSH's sftp-server was implemented, the order of the arguments
417 1.1 christos to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
418 1.1 christos the reversal was not noticed until the server was widely deployed. Since
419 1.1 christos fixing this to follow the specification would cause incompatibility, the
420 1.1 christos current order was retained. For correct operation, clients should send
421 1.1 christos SSH_FXP_SYMLINK as follows:
422 1.1 christos
423 1.1 christos uint32 id
424 1.1 christos string targetpath
425 1.1 christos string linkpath
426 1.1 christos
427 1.18 christos 4.2. sftp: Server extension announcement in SSH_FXP_VERSION
428 1.1 christos
429 1.1 christos OpenSSH's sftp-server lists the extensions it supports using the
430 1.1 christos standard extension announcement mechanism in the SSH_FXP_VERSION server
431 1.1 christos hello packet:
432 1.1 christos
433 1.1 christos uint32 3 /* protocol version */
434 1.1 christos string ext1-name
435 1.1 christos string ext1-version
436 1.1 christos string ext2-name
437 1.1 christos string ext2-version
438 1.1 christos ...
439 1.1 christos string extN-name
440 1.1 christos string extN-version
441 1.1 christos
442 1.1 christos Each extension reports its integer version number as an ASCII encoded
443 1.1 christos string, e.g. "1". The version will be incremented if the extension is
444 1.1 christos ever changed in an incompatible way. The server MAY advertise the same
445 1.1 christos extension with multiple versions (though this is unlikely). Clients MUST
446 1.1 christos check the version number before attempting to use the extension.
447 1.1 christos
448 1.18 christos 4.3. sftp: Extension request "posix-rename (a] openssh.com"
449 1.1 christos
450 1.1 christos This operation provides a rename operation with POSIX semantics, which
451 1.1 christos are different to those provided by the standard SSH_FXP_RENAME in
452 1.1 christos draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
453 1.1 christos SSH_FXP_EXTENDED request with the following format:
454 1.1 christos
455 1.1 christos uint32 id
456 1.1 christos string "posix-rename (a] openssh.com"
457 1.1 christos string oldpath
458 1.1 christos string newpath
459 1.1 christos
460 1.1 christos On receiving this request the server will perform the POSIX operation
461 1.1 christos rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
462 1.1 christos This extension is advertised in the SSH_FXP_VERSION hello with version
463 1.1 christos "1".
464 1.1 christos
465 1.18 christos 4.4. sftp: Extension requests "statvfs (a] openssh.com" and
466 1.1 christos "fstatvfs (a] openssh.com"
467 1.1 christos
468 1.1 christos These requests correspond to the statvfs and fstatvfs POSIX system
469 1.1 christos interfaces. The "statvfs (a] openssh.com" request operates on an explicit
470 1.1 christos pathname, and is formatted as follows:
471 1.1 christos
472 1.1 christos uint32 id
473 1.1 christos string "statvfs (a] openssh.com"
474 1.1 christos string path
475 1.1 christos
476 1.1 christos The "fstatvfs (a] openssh.com" operates on an open file handle:
477 1.1 christos
478 1.1 christos uint32 id
479 1.1 christos string "fstatvfs (a] openssh.com"
480 1.1 christos string handle
481 1.1 christos
482 1.1 christos These requests return a SSH_FXP_STATUS reply on failure. On success they
483 1.1 christos return the following SSH_FXP_EXTENDED_REPLY reply:
484 1.1 christos
485 1.1 christos uint32 id
486 1.1 christos uint64 f_bsize /* file system block size */
487 1.1 christos uint64 f_frsize /* fundamental fs block size */
488 1.1 christos uint64 f_blocks /* number of blocks (unit f_frsize) */
489 1.1 christos uint64 f_bfree /* free blocks in file system */
490 1.1 christos uint64 f_bavail /* free blocks for non-root */
491 1.1 christos uint64 f_files /* total file inodes */
492 1.1 christos uint64 f_ffree /* free file inodes */
493 1.1 christos uint64 f_favail /* free file inodes for to non-root */
494 1.1 christos uint64 f_fsid /* file system id */
495 1.1 christos uint64 f_flag /* bit mask of f_flag values */
496 1.1 christos uint64 f_namemax /* maximum filename length */
497 1.1 christos
498 1.1 christos The values of the f_flag bitmask are as follows:
499 1.1 christos
500 1.1 christos #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
501 1.1 christos #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
502 1.1 christos
503 1.1 christos Both the "statvfs (a] openssh.com" and "fstatvfs (a] openssh.com" extensions are
504 1.1 christos advertised in the SSH_FXP_VERSION hello with version "2".
505 1.1 christos
506 1.18 christos 4.5. sftp: Extension request "hardlink (a] openssh.com"
507 1.2 christos
508 1.2 christos This request is for creating a hard link to a regular file. This
509 1.2 christos request is implemented as a SSH_FXP_EXTENDED request with the
510 1.2 christos following format:
511 1.2 christos
512 1.2 christos uint32 id
513 1.2 christos string "hardlink (a] openssh.com"
514 1.2 christos string oldpath
515 1.2 christos string newpath
516 1.2 christos
517 1.2 christos On receiving this request the server will perform the operation
518 1.2 christos link(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
519 1.2 christos This extension is advertised in the SSH_FXP_VERSION hello with version
520 1.2 christos "1".
521 1.2 christos
522 1.18 christos 4.6. sftp: Extension request "fsync (a] openssh.com"
523 1.4 christos
524 1.4 christos This request asks the server to call fsync(2) on an open file handle.
525 1.4 christos
526 1.4 christos uint32 id
527 1.4 christos string "fsync (a] openssh.com"
528 1.4 christos string handle
529 1.4 christos
530 1.19 christos On receiving this request, a server will call fsync(handle_fd) and will
531 1.4 christos respond with a SSH_FXP_STATUS message.
532 1.4 christos
533 1.4 christos This extension is advertised in the SSH_FXP_VERSION hello with version
534 1.4 christos "1".
535 1.4 christos
536 1.18 christos 4.7. sftp: Extension request "lsetstat (a] openssh.com"
537 1.16 christos
538 1.16 christos This request is like the "setstat" command, but sets file attributes on
539 1.16 christos symlinks. It is implemented as a SSH_FXP_EXTENDED request with the
540 1.16 christos following format:
541 1.16 christos
542 1.16 christos uint32 id
543 1.16 christos string "lsetstat (a] openssh.com"
544 1.16 christos string path
545 1.16 christos ATTRS attrs
546 1.16 christos
547 1.16 christos See the "setstat" command for more details.
548 1.16 christos
549 1.16 christos This extension is advertised in the SSH_FXP_VERSION hello with version
550 1.16 christos "1".
551 1.16 christos
552 1.18 christos 4.8. sftp: Extension request "limits (a] openssh.com"
553 1.16 christos
554 1.16 christos This request is used to determine various limits the server might impose.
555 1.16 christos Clients should not attempt to exceed these limits as the server might sever
556 1.16 christos the connection immediately.
557 1.16 christos
558 1.16 christos uint32 id
559 1.16 christos string "limits (a] openssh.com"
560 1.16 christos
561 1.16 christos The server will respond with a SSH_FXP_EXTENDED_REPLY reply:
562 1.16 christos
563 1.16 christos uint32 id
564 1.16 christos uint64 max-packet-length
565 1.16 christos uint64 max-read-length
566 1.16 christos uint64 max-write-length
567 1.16 christos uint64 max-open-handles
568 1.16 christos
569 1.16 christos The 'max-packet-length' applies to the total number of bytes in a
570 1.16 christos single SFTP packet. Servers SHOULD set this at least to 34000.
571 1.16 christos
572 1.16 christos The 'max-read-length' is the largest length in a SSH_FXP_READ packet.
573 1.16 christos Even if the client requests a larger size, servers will usually respond
574 1.16 christos with a shorter SSH_FXP_DATA packet. Servers SHOULD set this at least to
575 1.16 christos 32768.
576 1.16 christos
577 1.16 christos The 'max-write-length' is the largest length in a SSH_FXP_WRITE packet
578 1.16 christos the server will accept. Servers SHOULD set this at least to 32768.
579 1.16 christos
580 1.16 christos The 'max-open-handles' is the maximum number of active handles that the
581 1.16 christos server allows (e.g. handles created by SSH_FXP_OPEN and SSH_FXP_OPENDIR
582 1.16 christos packets). Servers MAY count internal file handles against this limit
583 1.16 christos (e.g. system logging or stdout/stderr), so clients SHOULD NOT expect to
584 1.16 christos open this many handles in practice.
585 1.16 christos
586 1.16 christos If the server doesn't enforce a specific limit, then the field may be
587 1.16 christos set to 0. This implies the server relies on the OS to enforce limits
588 1.16 christos (e.g. available memory or file handles), and such limits might be
589 1.16 christos dynamic. The client SHOULD take care to not try to exceed reasonable
590 1.16 christos limits.
591 1.16 christos
592 1.16 christos This extension is advertised in the SSH_FXP_VERSION hello with version
593 1.16 christos "1".
594 1.16 christos
595 1.18 christos 4.9. sftp: Extension request "expand-path (a] openssh.com"
596 1.17 christos
597 1.17 christos This request supports canonicalisation of relative paths and
598 1.17 christos those that need tilde-expansion, i.e. "~", "~/..." and "~user/..."
599 1.17 christos These paths are expanded using shell-like rules and the resultant
600 1.17 christos path is canonicalised similarly to SSH2_FXP_REALPATH.
601 1.17 christos
602 1.17 christos It is implemented as a SSH_FXP_EXTENDED request with the following
603 1.17 christos format:
604 1.17 christos
605 1.17 christos uint32 id
606 1.17 christos string "expand-path (a] openssh.com"
607 1.17 christos string path
608 1.17 christos
609 1.17 christos Its reply is the same format as that of SSH2_FXP_REALPATH.
610 1.17 christos
611 1.17 christos This extension is advertised in the SSH_FXP_VERSION hello with version
612 1.17 christos "1".
613 1.17 christos
614 1.19 christos 4.10. sftp: Extension request "copy-data"
615 1.19 christos
616 1.19 christos This request asks the server to copy data from one open file handle and
617 1.19 christos write it to a different open file handle. This avoids needing to transfer
618 1.19 christos the data across the network twice (a download followed by an upload).
619 1.19 christos
620 1.19 christos byte SSH_FXP_EXTENDED
621 1.19 christos uint32 id
622 1.19 christos string "copy-data"
623 1.19 christos string read-from-handle
624 1.19 christos uint64 read-from-offset
625 1.19 christos uint64 read-data-length
626 1.19 christos string write-to-handle
627 1.19 christos uint64 write-to-offset
628 1.19 christos
629 1.19 christos The server will copy read-data-length bytes starting from
630 1.19 christos read-from-offset from the read-from-handle and write them to
631 1.19 christos write-to-handle starting from write-to-offset, and then respond with a
632 1.19 christos SSH_FXP_STATUS message.
633 1.19 christos
634 1.19 christos It's equivalent to issuing a series of SSH_FXP_READ requests on
635 1.19 christos read-from-handle and a series of requests of SSH_FXP_WRITE on
636 1.19 christos write-to-handle.
637 1.19 christos
638 1.19 christos If read-from-handle and write-to-handle are the same, the server will
639 1.19 christos fail the request and respond with a SSH_FX_INVALID_PARAMETER message.
640 1.19 christos
641 1.19 christos If read-data-length is 0, then the server will read data from the
642 1.19 christos read-from-handle until EOF is reached.
643 1.19 christos
644 1.19 christos This extension is advertised in the SSH_FXP_VERSION hello with version
645 1.19 christos "1".
646 1.19 christos
647 1.19 christos This request is identical to the "copy-data" request documented in:
648 1.19 christos
649 1.19 christos https://tools.ietf.org/html/draft-ietf-secsh-filexfer-extensions-00#section-7
650 1.19 christos
651 1.20 christos 4.11. sftp: Extension request "home-directory"
652 1.20 christos
653 1.20 christos This request asks the server to expand the specified user's home directory.
654 1.20 christos An empty username implies the current user. This can be used by the client
655 1.20 christos to expand ~/ type paths locally.
656 1.20 christos
657 1.20 christos byte SSH_FXP_EXTENDED
658 1.20 christos uint32 id
659 1.20 christos string "home-directory"
660 1.20 christos string username
661 1.20 christos
662 1.20 christos This extension is advertised in the SSH_FXP_VERSION hello with version
663 1.20 christos "1".
664 1.20 christos
665 1.20 christos This provides similar information as the "expand-path (a] openssh.com" extension.
666 1.20 christos
667 1.20 christos This request is identical to the "home-directory" request documented in:
668 1.20 christos
669 1.20 christos https://datatracker.ietf.org/doc/html/draft-ietf-secsh-filexfer-extensions-00#section-5
670 1.20 christos
671 1.20 christos 4.12. sftp: Extension request "users-groups-by-id (a] openssh.com"
672 1.20 christos
673 1.21 christos This request asks the server to return user and/or group names that
674 1.20 christos correspond to one or more IDs (e.g. as returned from a SSH_FXP_STAT
675 1.20 christos request). This may be used by the client to provide usernames in
676 1.20 christos directory listings.
677 1.20 christos
678 1.20 christos byte SSH_FXP_EXTENDED
679 1.20 christos uint32 id
680 1.20 christos string "users-groups-by-id (a] openssh.com"
681 1.20 christos string uids
682 1.20 christos string gids
683 1.20 christos
684 1.20 christos Where "uids" and "gids" consists of one or more integer user or group
685 1.20 christos identifiers:
686 1.20 christos
687 1.20 christos uint32 id-0
688 1.20 christos ...
689 1.20 christos
690 1.20 christos The server will reply with a SSH_FXP_EXTENDED_REPLY:
691 1.20 christos
692 1.20 christos byte SSH_FXP_EXTENDED_REPLY
693 1.20 christos string usernames
694 1.20 christos string groupnames
695 1.20 christos
696 1.20 christos Where "username" and "groupnames" consists of names in identical request
697 1.20 christos order to "uids" and "gids" respectively:
698 1.20 christos
699 1.20 christos string name-0
700 1.20 christos ...
701 1.20 christos
702 1.20 christos If a name cannot be identified for a given user or group ID, an empty
703 1.20 christos string will be returned in its place.
704 1.20 christos
705 1.20 christos It is acceptable for either "uids" or "gids" to be an empty set, in
706 1.20 christos which case the respective "usernames" or "groupnames" list will also
707 1.20 christos be empty.
708 1.20 christos
709 1.20 christos This extension is advertised in the SSH_FXP_VERSION hello with version
710 1.20 christos "1".
711 1.20 christos
712 1.18 christos 5. Miscellaneous changes
713 1.12 christos
714 1.18 christos 5.1 Public key format
715 1.12 christos
716 1.12 christos OpenSSH public keys, as generated by ssh-keygen(1) and appearing in
717 1.12 christos authorized_keys files, are formatted as a single line of text consisting
718 1.12 christos of the public key algorithm name followed by a base64-encoded key blob.
719 1.12 christos The public key blob (before base64 encoding) is the same format used for
720 1.12 christos the encoding of public keys sent on the wire: as described in RFC4253
721 1.12 christos section 6.6 for RSA and DSA keys, RFC5656 section 3.1 for ECDSA keys
722 1.12 christos and the "New public key formats" section of PROTOCOL.certkeys for the
723 1.12 christos OpenSSH certificate formats.
724 1.12 christos
725 1.18 christos 5.2 Private key format
726 1.12 christos
727 1.12 christos OpenSSH private keys, as generated by ssh-keygen(1) use the format
728 1.12 christos described in PROTOCOL.key by default. As a legacy option, PEM format
729 1.12 christos (RFC7468) private keys are also supported for RSA, DSA and ECDSA keys
730 1.12 christos and were the default format before OpenSSH 7.8.
731 1.12 christos
732 1.18 christos 5.3 KRL format
733 1.12 christos
734 1.12 christos OpenSSH supports a compact format for Key Revocation Lists (KRLs). This
735 1.12 christos format is described in the PROTOCOL.krl file.
736 1.12 christos
737 1.18 christos 5.4 Connection multiplexing
738 1.12 christos
739 1.12 christos OpenSSH's connection multiplexing uses messages as described in
740 1.12 christos PROTOCOL.mux over a Unix domain socket for communications between a
741 1.12 christos master instance and later clients.
742 1.12 christos
743 1.18 christos 5.5. Agent protocol extensions
744 1.18 christos
745 1.18 christos OpenSSH extends the usual agent protocol. These changes are documented
746 1.18 christos in the PROTOCOL.agent file.
747 1.18 christos
748 1.21 christos $OpenBSD: PROTOCOL,v 1.48 2022/11/07 01:53:01 dtucker Exp $
749 1.22 christos $OpenBSD: PROTOCOL,v 1.49 2023/08/28 03:28:43 djm Exp $
750 1.3 christos $NetBSD: PROTOCOL,v 1.22 2023/10/25 20:19:57 christos Exp $
751