]>
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 | ||
64 | 4. sftp: Reversal of arguments to SSH_FXP_SYMLINK | |
65 | ||
66 | When OpenSSH's sftp-server was implemented, the order of the arguments | |
67 | to the SSH_FXP_SYMLINK method was inadvertendly reversed. Unfortunately, | |
68 | the reversal was not noticed until the server was widely deployed. Since | |
69 | fixing this to follow the specification would cause incompatibility, the | |
70 | current order was retained. For correct operation, clients should send | |
71 | SSH_FXP_SYMLINK as follows: | |
72 | ||
73 | uint32 id | |
74 | string targetpath | |
75 | string linkpath | |
76 | ||
77 | 5. sftp: Server extension announcement in SSH_FXP_VERSION | |
78 | ||
79 | OpenSSH's sftp-server lists the extensions it supports using the | |
80 | standard extension announcement mechanism in the SSH_FXP_VERSION server | |
81 | hello packet: | |
82 | ||
83 | uint32 3 /* protocol version */ | |
84 | string ext1-name | |
85 | string ext1-version | |
86 | string ext2-name | |
87 | string ext2-version | |
88 | ... | |
89 | string extN-name | |
90 | string extN-version | |
91 | ||
92 | Each extension reports its integer version number as an ASCII encoded | |
93 | string, e.g. "1". The version will be incremented if the extension is | |
94 | ever changed in an incompatible way. The server MAY advertise the same | |
95 | extension with multiple versions (though this is unlikely). Clients MUST | |
96 | check the version number before attemping to use the extension. | |
97 | ||
98 | 6. sftp: Extension request "posix-rename@openssh.com" | |
99 | ||
100 | This operation provides a rename operation with POSIX semantics, which | |
101 | are different to those provided by the standard SSH_FXP_RENAME in | |
102 | draft-ietf-secsh-filexfer-02.txt. This request is implemented as a | |
103 | SSH_FXP_EXTENDED request with the following format: | |
104 | ||
105 | uint32 id | |
106 | string "posix-rename@openssh.com" | |
107 | string oldpath | |
108 | string newpath | |
109 | ||
110 | On receiving this request the server will perform the POSIX operation | |
111 | rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message. | |
112 | This extension is advertised in the SSH_FXP_VERSION hello with version | |
113 | "1". | |
114 | ||
115 | 7. sftp: Extension requests "statvfs@openssh.com" and | |
116 | "fstatvfs@openssh.com" | |
117 | ||
118 | These requests correspond to the statvfs and fstatvfs POSIX system | |
119 | interfaces. The "statvfs@openssh.com" request operates on an explicit | |
120 | pathname, and is formatted as follows: | |
121 | ||
122 | uint32 id | |
123 | string "statvfs@openssh.com" | |
124 | string path | |
125 | ||
126 | The "fstatvfs@openssh.com" operates on an open filehandle: | |
127 | ||
128 | uint32 id | |
129 | string "fstatvfs@openssh.com" | |
130 | string handle | |
131 | ||
132 | These requests return a SSH_FXP_STATUS reply on failure. On success they | |
133 | return the following SSH_FXP_EXTENDED_REPLY reply: | |
134 | ||
135 | uint32 id | |
f044f89e | 136 | uint64 f_bsize /* file system block size */ |
137 | uint64 f_frsize /* fundamental fs block size */ | |
8be03682 | 138 | uint64 f_blocks /* number of blocks (unit f_frsize) */ |
139 | uint64 f_bfree /* free blocks in file system */ | |
140 | uint64 f_bavail /* free blocks for non-root */ | |
141 | uint64 f_files /* total file inodes */ | |
142 | uint64 f_ffree /* free file inodes */ | |
143 | uint64 f_favail /* free file inodes for to non-root */ | |
0ad258dc | 144 | uint64 f_fsid /* file system id */ |
f044f89e | 145 | uint64 f_flag /* bit mask of f_flag values */ |
146 | uint64 f_namemax /* maximum filename length */ | |
8be03682 | 147 | |
148 | The values of the f_flag bitmask are as follows: | |
149 | ||
150 | #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */ | |
151 | #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */ | |
152 | ||
0ad258dc | 153 | This extension is advertised in the SSH_FXP_VERSION hello with version |
154 | "2". | |
155 | ||
2626070f | 156 | $OpenBSD: PROTOCOL,v 1.5 2008/06/09 13:38:46 dtucker Exp $ |
8be03682 | 157 |