]>
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 | ||
12 | 1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com" | |
13 | ||
14 | This is a new transport-layer MAC method using the UMAC algorithm | |
15 | (rfc4418). This method is identical to the "umac-64" method documented | |
16 | in: | |
17 | ||
18 | http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt | |
19 | ||
20 | 2. transport: Protocol 2 compression algorithm "zlib@openssh.com" | |
21 | ||
22 | This transport-layer compression method uses the zlib compression | |
23 | algorithm (identical to the "zlib" method in rfc4253), but delays the | |
24 | start of compression until after authentication has completed. This | |
25 | avoids exposing compression code to attacks from unauthenticated users. | |
26 | ||
27 | The method is documented in: | |
28 | ||
29 | http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt | |
30 | ||
31 | 3. connection: Channel write close extension "eow@openssh.com" | |
32 | ||
33 | The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF | |
34 | message to allow an endpoint to signal its peer that it will send no | |
35 | more data over a channel. Unfortunately, there is no symmetric way for | |
36 | an endpoint to request that its peer should cease sending data to it | |
37 | while still keeping the channel open for the endpoint to send data to | |
38 | the peer. | |
39 | ||
40 | This is desirable, since it saves the transmission of data that would | |
41 | otherwise need to be discarded and it allows an endpoint to signal local | |
42 | processes of the condition, e.g. by closing the corresponding file | |
43 | descriptor. | |
44 | ||
45 | OpenSSH implements a channel extension message to perform this | |
46 | signalling: "eow@openssh.com" (End Of Write). This message is sent by an | |
47 | endpoint when the local output of a channel is closed or experiences a | |
48 | write error. The message is formatted as follows: | |
49 | ||
50 | byte SSH_MSG_CHANNEL_REQUEST | |
51 | uint32 recipient channel | |
52 | string "eow@openssh.com" | |
53 | boolean FALSE | |
54 | ||
55 | On receiving this message, the peer SHOULD cease sending data of | |
56 | the channel and MAY signal the process from which the channel data | |
57 | originates (e.g. by closing its read file descriptor). | |
58 | ||
59 | As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does | |
60 | remain open after a "eow@openssh.com" has been sent and more data may | |
61 | still be sent in the other direction. This message does not consume | |
62 | window space and may be sent even if no window space is available. | |
63 | ||
3f0444ca | 64 | 4. connection: disallow additional sessions extension |
65 | "no-more-sessions@openssh.com" | |
66 | ||
67 | Most SSH connections will only ever request a single session, but a | |
68 | attacker may abuse a running ssh client to surreptitiously open | |
69 | additional sessions under their control. OpenSSH provides a global | |
70 | request "no-more-sessions@openssh.com" to mitigate this attack. | |
71 | ||
72 | When an OpenSSH client expects that it will never open another session | |
73 | (i.e. it has been started with connection multiplexing disabled), it | |
74 | will send the following global request: | |
75 | ||
76 | byte SSH_MSG_GLOBAL_REQUEST | |
77 | string "no-more-sessions@openssh.com" | |
78 | char want-reply | |
79 | ||
80 | On receipt of such a message, an OpenSSH server will refuse to open | |
81 | future channels of type "session" and instead immediately abort the | |
82 | connection. | |
83 | ||
84 | Note that this is not a general defence against compromised clients | |
85 | (that is impossible), but it thwarts a simple attack. | |
86 | ||
87 | 5. sftp: Reversal of arguments to SSH_FXP_SYMLINK | |
8be03682 | 88 | |
89 | When OpenSSH's sftp-server was implemented, the order of the arguments | |
90 | to the SSH_FXP_SYMLINK method was inadvertendly reversed. Unfortunately, | |
91 | the reversal was not noticed until the server was widely deployed. Since | |
92 | fixing this to follow the specification would cause incompatibility, the | |
93 | current order was retained. For correct operation, clients should send | |
94 | SSH_FXP_SYMLINK as follows: | |
95 | ||
96 | uint32 id | |
97 | string targetpath | |
98 | string linkpath | |
99 | ||
3f0444ca | 100 | 6. sftp: Server extension announcement in SSH_FXP_VERSION |
8be03682 | 101 | |
102 | OpenSSH's sftp-server lists the extensions it supports using the | |
103 | standard extension announcement mechanism in the SSH_FXP_VERSION server | |
104 | hello packet: | |
105 | ||
106 | uint32 3 /* protocol version */ | |
107 | string ext1-name | |
108 | string ext1-version | |
109 | string ext2-name | |
110 | string ext2-version | |
111 | ... | |
112 | string extN-name | |
113 | string extN-version | |
114 | ||
115 | Each extension reports its integer version number as an ASCII encoded | |
116 | string, e.g. "1". The version will be incremented if the extension is | |
117 | ever changed in an incompatible way. The server MAY advertise the same | |
118 | extension with multiple versions (though this is unlikely). Clients MUST | |
119 | check the version number before attemping to use the extension. | |
120 | ||
3f0444ca | 121 | 7. sftp: Extension request "posix-rename@openssh.com" |
8be03682 | 122 | |
123 | This operation provides a rename operation with POSIX semantics, which | |
124 | are different to those provided by the standard SSH_FXP_RENAME in | |
125 | draft-ietf-secsh-filexfer-02.txt. This request is implemented as a | |
126 | SSH_FXP_EXTENDED request with the following format: | |
127 | ||
128 | uint32 id | |
129 | string "posix-rename@openssh.com" | |
130 | string oldpath | |
131 | string newpath | |
132 | ||
133 | On receiving this request the server will perform the POSIX operation | |
134 | rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message. | |
135 | This extension is advertised in the SSH_FXP_VERSION hello with version | |
136 | "1". | |
137 | ||
3f0444ca | 138 | 8. sftp: Extension requests "statvfs@openssh.com" and |
8be03682 | 139 | "fstatvfs@openssh.com" |
140 | ||
141 | These requests correspond to the statvfs and fstatvfs POSIX system | |
142 | interfaces. The "statvfs@openssh.com" request operates on an explicit | |
143 | pathname, and is formatted as follows: | |
144 | ||
145 | uint32 id | |
146 | string "statvfs@openssh.com" | |
147 | string path | |
148 | ||
149 | The "fstatvfs@openssh.com" operates on an open filehandle: | |
150 | ||
151 | uint32 id | |
152 | string "fstatvfs@openssh.com" | |
153 | string handle | |
154 | ||
155 | These requests return a SSH_FXP_STATUS reply on failure. On success they | |
156 | return the following SSH_FXP_EXTENDED_REPLY reply: | |
157 | ||
158 | uint32 id | |
f044f89e | 159 | uint64 f_bsize /* file system block size */ |
160 | uint64 f_frsize /* fundamental fs block size */ | |
8be03682 | 161 | uint64 f_blocks /* number of blocks (unit f_frsize) */ |
162 | uint64 f_bfree /* free blocks in file system */ | |
163 | uint64 f_bavail /* free blocks for non-root */ | |
164 | uint64 f_files /* total file inodes */ | |
165 | uint64 f_ffree /* free file inodes */ | |
166 | uint64 f_favail /* free file inodes for to non-root */ | |
0ad258dc | 167 | uint64 f_fsid /* file system id */ |
f044f89e | 168 | uint64 f_flag /* bit mask of f_flag values */ |
169 | uint64 f_namemax /* maximum filename length */ | |
8be03682 | 170 | |
171 | The values of the f_flag bitmask are as follows: | |
172 | ||
173 | #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */ | |
174 | #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */ | |
175 | ||
0ad258dc | 176 | This extension is advertised in the SSH_FXP_VERSION hello with version |
177 | "2". | |
178 | ||
3f0444ca | 179 | $OpenBSD: PROTOCOL,v 1.6 2008/06/10 22:15:23 djm Exp $ |
8be03682 | 180 |