xref: /openbsd/usr.bin/ssh/PROTOCOL (revision 1edbfe23)
1422225e8SdjmThis documents OpenSSH's deviations and extensions to the published SSH
2422225e8Sdjmprotocol.
3422225e8Sdjm
438d4658eSdjmNote that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
538d4658eSdjmfilexfer protocol described in:
6422225e8Sdjm
7422225e8Sdjmhttp://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
8422225e8Sdjm
9f452f5c5SdjmNewer versions of the draft will not be supported, though some features
10f452f5c5Sdjmare individually implemented as extensions described below.
11422225e8Sdjm
12f0c9babeSdjmThe protocol used by OpenSSH's ssh-agent is described in the file
13f0c9babeSdjmPROTOCOL.agent
14f0c9babeSdjm
15f6c05033Sdjm1. Transport protocol changes
16f6c05033Sdjm
17f6c05033Sdjm1.1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
18422225e8Sdjm
19422225e8SdjmThis is a new transport-layer MAC method using the UMAC algorithm
20422225e8Sdjm(rfc4418). This method is identical to the "umac-64" method documented
21422225e8Sdjmin:
22422225e8Sdjm
23422225e8Sdjmhttp://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
24422225e8Sdjm
25f6c05033Sdjm1.2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
26422225e8Sdjm
27422225e8SdjmThis transport-layer compression method uses the zlib compression
28422225e8Sdjmalgorithm (identical to the "zlib" method in rfc4253), but delays the
29422225e8Sdjmstart of compression until after authentication has completed. This
3038d4658eSdjmavoids exposing compression code to attacks from unauthenticated users.
31422225e8Sdjm
32422225e8SdjmThe method is documented in:
33422225e8Sdjm
34422225e8Sdjmhttp://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
35422225e8Sdjm
36f6c05033Sdjm1.3. transport: New public key algorithms "ssh-rsa-cert-v00@openssh.com",
37f6c05033Sdjm     "ssh-dsa-cert-v00@openssh.com",
38f6c05033Sdjm     "ecdsa-sha2-nistp256-cert-v01@openssh.com",
39f6c05033Sdjm     "ecdsa-sha2-nistp384-cert-v01@openssh.com" and
40f6c05033Sdjm     "ecdsa-sha2-nistp521-cert-v01@openssh.com"
41b94e498eSdjm
42f6c05033SdjmOpenSSH introduces new public key algorithms to support certificate
43b94e498eSdjmauthentication for users and hostkeys. These methods are documented in
44b94e498eSdjmthe file PROTOCOL.certkeys
45b94e498eSdjm
46f6c05033Sdjm1.4. transport: Elliptic Curve cryptography
47f6c05033Sdjm
48f6c05033SdjmOpenSSH supports ECC key exchange and public key authentication as
49f6c05033Sdjmspecified in RFC5656. Only the ecdsa-sha2-nistp256, ecdsa-sha2-nistp384
50f6c05033Sdjmand ecdsa-sha2-nistp521 curves over GF(p) are supported. Elliptic
51f6c05033Sdjmcurve points encoded using point compression are NOT accepted or
52f6c05033Sdjmgenerated.
53f6c05033Sdjm
54c2ea1f0aSmarkus1.5 transport: Protocol 2 Encrypt-then-MAC MAC algorithms
55c2ea1f0aSmarkus
56c2ea1f0aSmarkusOpenSSH supports MAC algorithms, whose names contain "-etm", that
57c2ea1f0aSmarkusperform the calculations in a different order to that defined in RFC
58c2ea1f0aSmarkus4253. These variants use the so-called "encrypt then MAC" ordering,
59c2ea1f0aSmarkuscalculating the MAC over the packet ciphertext rather than the
60c2ea1f0aSmarkusplaintext. This ordering closes a security flaw in the SSH transport
61c2ea1f0aSmarkusprotocol, where decryption of unauthenticated ciphertext provided a
62c2ea1f0aSmarkus"decryption oracle" that could, in conjunction with cipher flaws, reveal
63c2ea1f0aSmarkussession plaintext.
64c2ea1f0aSmarkus
65c2ea1f0aSmarkusSpecifically, the "-etm" MAC algorithms modify the transport protocol
66c2ea1f0aSmarkusto calculate the MAC over the packet ciphertext and to send the packet
67c2ea1f0aSmarkuslength unencrypted. This is necessary for the transport to obtain the
68c2ea1f0aSmarkuslength of the packet and location of the MAC tag so that it may be
69c2ea1f0aSmarkusverified without decrypting unauthenticated data.
70c2ea1f0aSmarkus
71c2ea1f0aSmarkusAs such, the MAC covers:
72c2ea1f0aSmarkus
734ea77511Sdjm      mac = MAC(key, sequence_number || packet_length || encrypted_packet)
74c2ea1f0aSmarkus
754ea77511Sdjmwhere "packet_length" is encoded as a uint32 and "encrypted_packet"
764ea77511Sdjmcontains:
77c2ea1f0aSmarkus
78c2ea1f0aSmarkus      byte      padding_length
79c2ea1f0aSmarkus      byte[n1]  payload; n1 = packet_length - padding_length - 1
80c2ea1f0aSmarkus      byte[n2]  random padding; n2 = padding_length
81c2ea1f0aSmarkus
8247da1b19Smarkus1.6 transport: AES-GCM
8347da1b19Smarkus
8447da1b19SmarkusOpenSSH supports the AES-GCM algorithm as specified in RFC 5647.
8547da1b19SmarkusBecause of problems with the specification of the key exchange
8647da1b19Smarkusthe behaviour of OpenSSH differs from the RFC as follows:
8747da1b19Smarkus
8847da1b19SmarkusAES-GCM is only negotiated as the cipher algorithms
8947da1b19Smarkus"aes128-gcm@openssh.com" or "aes256-gcm@openssh.com" and never as
9047da1b19Smarkusan MAC algorithm. Additionally, if AES-GCM is selected as the cipher
9147da1b19Smarkusthe exchanged MAC algorithms are ignored and there doesn't have to be
9247da1b19Smarkusa matching MAC.
9347da1b19Smarkus
94*1edbfe23Sdjm1.7 transport: chacha20-poly1305@openssh.com authenticated encryption
95*1edbfe23Sdjm
96*1edbfe23SdjmOpenSSH supports authenticated encryption using ChaCha20 and Poly1305
97*1edbfe23Sdjmas described in PROTOCOL.chacha20poly1305.
98*1edbfe23Sdjm
99f6c05033Sdjm2. Connection protocol changes
100f6c05033Sdjm
101f6c05033Sdjm2.1. connection: Channel write close extension "eow@openssh.com"
102422225e8Sdjm
103422225e8SdjmThe SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
104422225e8Sdjmmessage to allow an endpoint to signal its peer that it will send no
105422225e8Sdjmmore data over a channel. Unfortunately, there is no symmetric way for
106422225e8Sdjman endpoint to request that its peer should cease sending data to it
107422225e8Sdjmwhile still keeping the channel open for the endpoint to send data to
108422225e8Sdjmthe peer.
109422225e8Sdjm
11038d4658eSdjmThis is desirable, since it saves the transmission of data that would
111422225e8Sdjmotherwise need to be discarded and it allows an endpoint to signal local
112422225e8Sdjmprocesses of the condition, e.g. by closing the corresponding file
113422225e8Sdjmdescriptor.
114422225e8Sdjm
115422225e8SdjmOpenSSH implements a channel extension message to perform this
1167153c228Sdjmsignalling: "eow@openssh.com" (End Of Write). This message is sent by
1177153c228Sdjman endpoint when the local output of a session channel is closed or
1187153c228Sdjmexperiences a write error. The message is formatted as follows:
119422225e8Sdjm
120422225e8Sdjm	byte		SSH_MSG_CHANNEL_REQUEST
121422225e8Sdjm	uint32		recipient channel
122422225e8Sdjm	string		"eow@openssh.com"
123422225e8Sdjm	boolean		FALSE
124422225e8Sdjm
125422225e8SdjmOn receiving this message, the peer SHOULD cease sending data of
126422225e8Sdjmthe channel and MAY signal the process from which the channel data
127422225e8Sdjmoriginates (e.g. by closing its read file descriptor).
128422225e8Sdjm
129422225e8SdjmAs with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
130422225e8Sdjmremain open after a "eow@openssh.com" has been sent and more data may
131422225e8Sdjmstill be sent in the other direction. This message does not consume
132422225e8Sdjmwindow space and may be sent even if no window space is available.
133422225e8Sdjm
134e187e146SdjmNB. due to certain broken SSH implementations aborting upon receipt
135e187e146Sdjmof this message (in contravention of RFC4254 section 5.4), this
136e187e146Sdjmmessage is only sent to OpenSSH peers (identified by banner).
137e187e146SdjmOther SSH implementations may be whitelisted to receive this message
138e187e146Sdjmupon request.
139e187e146Sdjm
140f6c05033Sdjm2.2. connection: disallow additional sessions extension
14182046f86Sdjm     "no-more-sessions@openssh.com"
14282046f86Sdjm
14382046f86SdjmMost SSH connections will only ever request a single session, but a
14482046f86Sdjmattacker may abuse a running ssh client to surreptitiously open
14582046f86Sdjmadditional sessions under their control. OpenSSH provides a global
14682046f86Sdjmrequest "no-more-sessions@openssh.com" to mitigate this attack.
14782046f86Sdjm
14882046f86SdjmWhen an OpenSSH client expects that it will never open another session
14982046f86Sdjm(i.e. it has been started with connection multiplexing disabled), it
15082046f86Sdjmwill send the following global request:
15182046f86Sdjm
15282046f86Sdjm	byte		SSH_MSG_GLOBAL_REQUEST
15382046f86Sdjm	string		"no-more-sessions@openssh.com"
15482046f86Sdjm	char		want-reply
15582046f86Sdjm
15682046f86SdjmOn receipt of such a message, an OpenSSH server will refuse to open
15782046f86Sdjmfuture channels of type "session" and instead immediately abort the
15882046f86Sdjmconnection.
15982046f86Sdjm
16082046f86SdjmNote that this is not a general defence against compromised clients
16182046f86Sdjm(that is impossible), but it thwarts a simple attack.
16282046f86Sdjm
163e187e146SdjmNB. due to certain broken SSH implementations aborting upon receipt
164e187e146Sdjmof this message, the no-more-sessions request is only sent to OpenSSH
165e187e146Sdjmservers (identified by banner). Other SSH implementations may be
166e187e146Sdjmwhitelisted to receive this message upon request.
167e187e146Sdjm
168f6c05033Sdjm2.3. connection: Tunnel forward extension "tun@openssh.com"
1690afb9521Sdjm
1706c9c8648SdjmOpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
1710afb9521Sdjmchannel type. This channel type supports forwarding of network packets
1726c9c8648Sdjmwith datagram boundaries intact between endpoints equipped with
1730afb9521Sdjminterfaces like the BSD tun(4) device. Tunnel forwarding channels are
1740afb9521Sdjmrequested by the client with the following packet:
1750afb9521Sdjm
1760afb9521Sdjm	byte		SSH_MSG_CHANNEL_OPEN
1770afb9521Sdjm	string		"tun@openssh.com"
1780afb9521Sdjm	uint32		sender channel
1790afb9521Sdjm	uint32		initial window size
1800afb9521Sdjm	uint32		maximum packet size
1810afb9521Sdjm	uint32		tunnel mode
1820afb9521Sdjm	uint32		remote unit number
1830afb9521Sdjm
1840afb9521SdjmThe "tunnel mode" parameter specifies whether the tunnel should forward
1850afb9521Sdjmlayer 2 frames or layer 3 packets. It may take one of the following values:
1860afb9521Sdjm
1870afb9521Sdjm	SSH_TUNMODE_POINTOPOINT  1		/* layer 3 packets */
1880afb9521Sdjm	SSH_TUNMODE_ETHERNET     2		/* layer 2 frames */
1890afb9521Sdjm
1900afb9521SdjmThe "tunnel unit number" specifies the remote interface number, or may
191c880fb56Sdjmbe 0x7fffffff to allow the server to automatically chose an interface. A
192c880fb56Sdjmserver that is not willing to open a client-specified unit should refuse
193c880fb56Sdjmthe request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful
194c880fb56Sdjmopen, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
1950afb9521Sdjm
1960afb9521SdjmOnce established the client and server may exchange packet or frames
1970afb9521Sdjmover the tunnel channel by encapsulating them in SSH protocol strings
1980afb9521Sdjmand sending them as channel data. This ensures that packet boundaries
1990afb9521Sdjmare kept intact. Specifically, packets are transmitted using normal
2000afb9521SdjmSSH_MSG_CHANNEL_DATA packets:
2010afb9521Sdjm
2020afb9521Sdjm	byte		SSH_MSG_CHANNEL_DATA
2030afb9521Sdjm	uint32		recipient channel
2040afb9521Sdjm	string		data
2050afb9521Sdjm
2060afb9521SdjmThe contents of the "data" field for layer 3 packets is:
2070afb9521Sdjm
2080afb9521Sdjm	uint32			packet length
2090afb9521Sdjm	uint32			address family
2100afb9521Sdjm	byte[packet length - 4]	packet data
2110afb9521Sdjm
2120afb9521SdjmThe "address family" field identifies the type of packet in the message.
2130afb9521SdjmIt may be one of:
2140afb9521Sdjm
2150afb9521Sdjm	SSH_TUN_AF_INET		2		/* IPv4 */
2160afb9521Sdjm	SSH_TUN_AF_INET6	24		/* IPv6 */
2170afb9521Sdjm
2180afb9521SdjmThe "packet data" field consists of the IPv4/IPv6 datagram itself
2190afb9521Sdjmwithout any link layer header.
2200afb9521Sdjm
221c880fb56SdjmThe contents of the "data" field for layer 2 packets is:
2220afb9521Sdjm
2230afb9521Sdjm	uint32			packet length
2240afb9521Sdjm	byte[packet length]	frame
2250afb9521Sdjm
2266c9c8648SdjmThe "frame" field contains an IEEE 802.3 Ethernet frame, including
2270afb9521Sdjmheader.
2280afb9521Sdjm
229f6c05033Sdjm3. SFTP protocol changes
230f6c05033Sdjm
231f6c05033Sdjm3.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK
232422225e8Sdjm
233422225e8SdjmWhen OpenSSH's sftp-server was implemented, the order of the arguments
2346c9c8648Sdjmto the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
235422225e8Sdjmthe reversal was not noticed until the server was widely deployed. Since
236422225e8Sdjmfixing this to follow the specification would cause incompatibility, the
237422225e8Sdjmcurrent order was retained. For correct operation, clients should send
238422225e8SdjmSSH_FXP_SYMLINK as follows:
239422225e8Sdjm
240422225e8Sdjm	uint32		id
241422225e8Sdjm	string		targetpath
242422225e8Sdjm	string		linkpath
243422225e8Sdjm
244f6c05033Sdjm3.2. sftp: Server extension announcement in SSH_FXP_VERSION
245422225e8Sdjm
246422225e8SdjmOpenSSH's sftp-server lists the extensions it supports using the
247422225e8Sdjmstandard extension announcement mechanism in the SSH_FXP_VERSION server
248422225e8Sdjmhello packet:
249422225e8Sdjm
250422225e8Sdjm	uint32		3		/* protocol version */
251422225e8Sdjm	string		ext1-name
252422225e8Sdjm	string		ext1-version
253422225e8Sdjm	string		ext2-name
254422225e8Sdjm	string		ext2-version
255422225e8Sdjm	...
256422225e8Sdjm	string		extN-name
257422225e8Sdjm	string		extN-version
258422225e8Sdjm
259422225e8SdjmEach extension reports its integer version number as an ASCII encoded
260422225e8Sdjmstring, e.g. "1". The version will be incremented if the extension is
261422225e8Sdjmever changed in an incompatible way. The server MAY advertise the same
262422225e8Sdjmextension with multiple versions (though this is unlikely). Clients MUST
2636c9c8648Sdjmcheck the version number before attempting to use the extension.
264422225e8Sdjm
265f6c05033Sdjm3.3. sftp: Extension request "posix-rename@openssh.com"
266422225e8Sdjm
267422225e8SdjmThis operation provides a rename operation with POSIX semantics, which
268422225e8Sdjmare different to those provided by the standard SSH_FXP_RENAME in
269422225e8Sdjmdraft-ietf-secsh-filexfer-02.txt. This request is implemented as a
270422225e8SdjmSSH_FXP_EXTENDED request with the following format:
271422225e8Sdjm
272422225e8Sdjm	uint32		id
273422225e8Sdjm	string		"posix-rename@openssh.com"
274422225e8Sdjm	string		oldpath
275422225e8Sdjm	string		newpath
276422225e8Sdjm
277422225e8SdjmOn receiving this request the server will perform the POSIX operation
278422225e8Sdjmrename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
279422225e8SdjmThis extension is advertised in the SSH_FXP_VERSION hello with version
280422225e8Sdjm"1".
281422225e8Sdjm
282f6c05033Sdjm3.4. sftp: Extension requests "statvfs@openssh.com" and
283422225e8Sdjm         "fstatvfs@openssh.com"
284422225e8Sdjm
285422225e8SdjmThese requests correspond to the statvfs and fstatvfs POSIX system
286422225e8Sdjminterfaces. The "statvfs@openssh.com" request operates on an explicit
287422225e8Sdjmpathname, and is formatted as follows:
288422225e8Sdjm
289422225e8Sdjm	uint32		id
290422225e8Sdjm	string		"statvfs@openssh.com"
291422225e8Sdjm	string		path
292422225e8Sdjm
293422225e8SdjmThe "fstatvfs@openssh.com" operates on an open file handle:
294422225e8Sdjm
295422225e8Sdjm	uint32		id
29638d4658eSdjm	string		"fstatvfs@openssh.com"
297422225e8Sdjm	string		handle
298422225e8Sdjm
299422225e8SdjmThese requests return a SSH_FXP_STATUS reply on failure. On success they
300422225e8Sdjmreturn the following SSH_FXP_EXTENDED_REPLY reply:
301422225e8Sdjm
302422225e8Sdjm	uint32		id
303f00164cfSdtucker	uint64		f_bsize		/* file system block size */
304f00164cfSdtucker	uint64		f_frsize	/* fundamental fs block size */
305422225e8Sdjm	uint64		f_blocks	/* number of blocks (unit f_frsize) */
306422225e8Sdjm	uint64		f_bfree		/* free blocks in file system */
307422225e8Sdjm	uint64		f_bavail	/* free blocks for non-root */
308422225e8Sdjm	uint64		f_files		/* total file inodes */
309422225e8Sdjm	uint64		f_ffree		/* free file inodes */
310422225e8Sdjm	uint64		f_favail	/* free file inodes for to non-root */
31133745cbfSdjm	uint64		f_fsid		/* file system id */
312f00164cfSdtucker	uint64		f_flag		/* bit mask of f_flag values */
313f00164cfSdtucker	uint64		f_namemax	/* maximum filename length */
314422225e8Sdjm
315422225e8SdjmThe values of the f_flag bitmask are as follows:
316422225e8Sdjm
317422225e8Sdjm	#define SSH_FXE_STATVFS_ST_RDONLY	0x1	/* read-only */
318422225e8Sdjm	#define SSH_FXE_STATVFS_ST_NOSUID	0x2	/* no setuid */
319422225e8Sdjm
320fae5684aSdjmBoth the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are
321fae5684aSdjmadvertised in the SSH_FXP_VERSION hello with version "2".
32233745cbfSdjm
3239c120764Sdjm10. sftp: Extension request "hardlink@openssh.com"
3249c120764Sdjm
3259c120764SdjmThis request is for creating a hard link to a regular file. This
3269c120764Sdjmrequest is implemented as a SSH_FXP_EXTENDED request with the
3279c120764Sdjmfollowing format:
3289c120764Sdjm
3299c120764Sdjm	uint32		id
3309c120764Sdjm	string		"hardlink@openssh.com"
3319c120764Sdjm	string		oldpath
3329c120764Sdjm	string		newpath
3339c120764Sdjm
3349c120764SdjmOn receiving this request the server will perform the operation
3359c120764Sdjmlink(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
3369c120764SdjmThis extension is advertised in the SSH_FXP_VERSION hello with version
3379c120764Sdjm"1".
3389c120764Sdjm
33994e35841Sdjm10. sftp: Extension request "fsync@openssh.com"
34094e35841Sdjm
34194e35841SdjmThis request asks the server to call fsync(2) on an open file handle.
34294e35841Sdjm
34394e35841Sdjm	uint32		id
34494e35841Sdjm	string		"fsync@openssh.com"
34594e35841Sdjm	string		handle
34694e35841Sdjm
34794e35841SdjmOne receiving this request, a server will call fsync(handle_fd) and will
34894e35841Sdjmrespond with a SSH_FXP_STATUS message.
34994e35841Sdjm
35094e35841SdjmThis extension is advertised in the SSH_FXP_VERSION hello with version
35194e35841Sdjm"1".
35294e35841Sdjm
353*1edbfe23Sdjm$OpenBSD: PROTOCOL,v 1.22 2013/11/21 00:45:43 djm Exp $
354