Codebase list libnet-sftp-foreign-perl / 275c015f-0685-46a8-b73a-02d44ba8378a/main
New upstream snapshot. Debian Janitor 2 years ago
10 changed file(s) with 8556 addition(s) and 4 deletion(s). Raw diff Collapse all Expand all
+2
-2
META.json less more
33 "Salvador Fandino <sfandino@yahoo.com>"
44 ],
55 "dynamic_config" : 1,
6 "generated_by" : "ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010",
6 "generated_by" : "ExtUtils::MakeMaker version 7.44, CPAN::Meta::Converter version 2.150010",
77 "license" : [
88 "perl_5"
99 ],
4848 }
4949 },
5050 "version" : "1.93",
51 "x_serialization_backend" : "JSON::PP version 4.02"
51 "x_serialization_backend" : "JSON::PP version 4.04"
5252 }
+1
-1
META.yml less more
66 configure_requires:
77 ExtUtils::MakeMaker: '0'
88 dynamic_config: 1
9 generated_by: 'ExtUtils::MakeMaker version 7.34, CPAN::Meta::Converter version 2.150010'
9 generated_by: 'ExtUtils::MakeMaker version 7.44, CPAN::Meta::Converter version 2.150010'
1010 license: perl
1111 meta-spec:
1212 url: http://module-build.sourceforge.net/META-spec-v1.4.html
+6
-0
debian/changelog less more
0 libnet-sftp-foreign-perl (1.93+dfsg+git20210121.1.3a3ab3c-1) UNRELEASED; urgency=low
1
2 * New upstream snapshot.
3
4 -- Debian Janitor <janitor@jelmer.uk> Fri, 12 Nov 2021 22:09:23 -0000
5
06 libnet-sftp-foreign-perl (1.93+dfsg-1) unstable; urgency=medium
17
28 [ Debian Janitor ]
+359
-0
rfc/OpenSSH-protocol-deviations.txt less more
0 This documents OpenSSH's deviations and extensions to the published SSH
1 protocol.
2
3 Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
4 filexfer protocol described in:
5
6 http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
7
8 Newer versions of the draft will not be supported, though some features
9 are individually implemented as extensions described below.
10
11 The protocol used by OpenSSH's ssh-agent is described in the file
12 PROTOCOL.agent
13
14 1. Transport protocol changes
15
16 1.1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
17
18 This is a new transport-layer MAC method using the UMAC algorithm
19 (rfc4418). This method is identical to the "umac-64" method documented
20 in:
21
22 http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
23
24 1.2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
25
26 This transport-layer compression method uses the zlib compression
27 algorithm (identical to the "zlib" method in rfc4253), but delays the
28 start of compression until after authentication has completed. This
29 avoids exposing compression code to attacks from unauthenticated users.
30
31 The method is documented in:
32
33 http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
34
35 1.3. transport: New public key algorithms "ssh-rsa-cert-v00@openssh.com",
36 "ssh-dsa-cert-v00@openssh.com",
37 "ecdsa-sha2-nistp256-cert-v01@openssh.com",
38 "ecdsa-sha2-nistp384-cert-v01@openssh.com" and
39 "ecdsa-sha2-nistp521-cert-v01@openssh.com"
40
41 OpenSSH introduces new public key algorithms to support certificate
42 authentication for users and hostkeys. These methods are documented in
43 the file PROTOCOL.certkeys
44
45 1.4. transport: Elliptic Curve cryptography
46
47 OpenSSH supports ECC key exchange and public key authentication as
48 specified in RFC5656. Only the ecdsa-sha2-nistp256, ecdsa-sha2-nistp384
49 and ecdsa-sha2-nistp521 curves over GF(p) are supported. Elliptic
50 curve points encoded using point compression are NOT accepted or
51 generated.
52
53 1.5 transport: Protocol 2 Encrypt-then-MAC MAC algorithms
54
55 OpenSSH supports MAC algorithms, whose names contain "-etm", that
56 perform the calculations in a different order to that defined in RFC
57 4253. These variants use the so-called "encrypt then MAC" ordering,
58 calculating the MAC over the packet ciphertext rather than the
59 plaintext. This ordering closes a security flaw in the SSH transport
60 protocol, where decryption of unauthenticated ciphertext provided a
61 "decryption oracle" that could, in conjunction with cipher flaws, reveal
62 session plaintext.
63
64 Specifically, the "-etm" MAC algorithms modify the transport protocol
65 to calculate the MAC over the packet ciphertext and to send the packet
66 length unencrypted. This is necessary for the transport to obtain the
67 length of the packet and location of the MAC tag so that it may be
68 verified without decrypting unauthenticated data.
69
70 As such, the MAC covers:
71
72 mac = MAC(key, sequence_number || packet_length || encrypted_packet)
73
74 where "packet_length" is encoded as a uint32 and "encrypted_packet"
75 contains:
76
77 byte padding_length
78 byte[n1] payload; n1 = packet_length - padding_length - 1
79 byte[n2] random padding; n2 = padding_length
80
81 1.6 transport: AES-GCM
82
83 OpenSSH supports the AES-GCM algorithm as specified in RFC 5647.
84 Because of problems with the specification of the key exchange
85 the behaviour of OpenSSH differs from the RFC as follows:
86
87 AES-GCM is only negotiated as the cipher algorithms
88 "aes128-gcm@openssh.com" or "aes256-gcm@openssh.com" and never as
89 an MAC algorithm. Additionally, if AES-GCM is selected as the cipher
90 the exchanged MAC algorithms are ignored and there doesn't have to be
91 a matching MAC.
92
93 1.7 transport: chacha20-poly1305@openssh.com authenticated encryption
94
95 OpenSSH supports authenticated encryption using ChaCha20 and Poly1305
96 as described in PROTOCOL.chacha20poly1305.
97
98 1.8 transport: curve25519-sha256@libssh.org key exchange algorithm
99
100 OpenSSH supports the use of ECDH in Curve25519 for key exchange as
101 described at:
102 http://git.libssh.org/users/aris/libssh.git/plain/doc/curve25519-sha256@libssh.org.txt?h=curve25519
103
104 2. Connection protocol changes
105
106 2.1. connection: Channel write close extension "eow@openssh.com"
107
108 The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
109 message to allow an endpoint to signal its peer that it will send no
110 more data over a channel. Unfortunately, there is no symmetric way for
111 an endpoint to request that its peer should cease sending data to it
112 while still keeping the channel open for the endpoint to send data to
113 the peer.
114
115 This is desirable, since it saves the transmission of data that would
116 otherwise need to be discarded and it allows an endpoint to signal local
117 processes of the condition, e.g. by closing the corresponding file
118 descriptor.
119
120 OpenSSH implements a channel extension message to perform this
121 signalling: "eow@openssh.com" (End Of Write). This message is sent by
122 an endpoint when the local output of a session channel is closed or
123 experiences a write error. The message is formatted as follows:
124
125 byte SSH_MSG_CHANNEL_REQUEST
126 uint32 recipient channel
127 string "eow@openssh.com"
128 boolean FALSE
129
130 On receiving this message, the peer SHOULD cease sending data of
131 the channel and MAY signal the process from which the channel data
132 originates (e.g. by closing its read file descriptor).
133
134 As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
135 remain open after a "eow@openssh.com" has been sent and more data may
136 still be sent in the other direction. This message does not consume
137 window space and may be sent even if no window space is available.
138
139 NB. due to certain broken SSH implementations aborting upon receipt
140 of this message (in contravention of RFC4254 section 5.4), this
141 message is only sent to OpenSSH peers (identified by banner).
142 Other SSH implementations may be whitelisted to receive this message
143 upon request.
144
145 2.2. connection: disallow additional sessions extension
146 "no-more-sessions@openssh.com"
147
148 Most SSH connections will only ever request a single session, but a
149 attacker may abuse a running ssh client to surreptitiously open
150 additional sessions under their control. OpenSSH provides a global
151 request "no-more-sessions@openssh.com" to mitigate this attack.
152
153 When an OpenSSH client expects that it will never open another session
154 (i.e. it has been started with connection multiplexing disabled), it
155 will send the following global request:
156
157 byte SSH_MSG_GLOBAL_REQUEST
158 string "no-more-sessions@openssh.com"
159 char want-reply
160
161 On receipt of such a message, an OpenSSH server will refuse to open
162 future channels of type "session" and instead immediately abort the
163 connection.
164
165 Note that this is not a general defence against compromised clients
166 (that is impossible), but it thwarts a simple attack.
167
168 NB. due to certain broken SSH implementations aborting upon receipt
169 of this message, the no-more-sessions request is only sent to OpenSSH
170 servers (identified by banner). Other SSH implementations may be
171 whitelisted to receive this message upon request.
172
173 2.3. connection: Tunnel forward extension "tun@openssh.com"
174
175 OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
176 channel type. This channel type supports forwarding of network packets
177 with datagram boundaries intact between endpoints equipped with
178 interfaces like the BSD tun(4) device. Tunnel forwarding channels are
179 requested by the client with the following packet:
180
181 byte SSH_MSG_CHANNEL_OPEN
182 string "tun@openssh.com"
183 uint32 sender channel
184 uint32 initial window size
185 uint32 maximum packet size
186 uint32 tunnel mode
187 uint32 remote unit number
188
189 The "tunnel mode" parameter specifies whether the tunnel should forward
190 layer 2 frames or layer 3 packets. It may take one of the following values:
191
192 SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */
193 SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */
194
195 The "tunnel unit number" specifies the remote interface number, or may
196 be 0x7fffffff to allow the server to automatically chose an interface. A
197 server that is not willing to open a client-specified unit should refuse
198 the request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful
199 open, the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
200
201 Once established the client and server may exchange packet or frames
202 over the tunnel channel by encapsulating them in SSH protocol strings
203 and sending them as channel data. This ensures that packet boundaries
204 are kept intact. Specifically, packets are transmitted using normal
205 SSH_MSG_CHANNEL_DATA packets:
206
207 byte SSH_MSG_CHANNEL_DATA
208 uint32 recipient channel
209 string data
210
211 The contents of the "data" field for layer 3 packets is:
212
213 uint32 packet length
214 uint32 address family
215 byte[packet length - 4] packet data
216
217 The "address family" field identifies the type of packet in the message.
218 It may be one of:
219
220 SSH_TUN_AF_INET 2 /* IPv4 */
221 SSH_TUN_AF_INET6 24 /* IPv6 */
222
223 The "packet data" field consists of the IPv4/IPv6 datagram itself
224 without any link layer header.
225
226 The contents of the "data" field for layer 2 packets is:
227
228 uint32 packet length
229 byte[packet length] frame
230
231 The "frame" field contains an IEEE 802.3 Ethernet frame, including
232 header.
233
234 3. SFTP protocol changes
235
236 3.1. sftp: Reversal of arguments to SSH_FXP_SYMLINK
237
238 When OpenSSH's sftp-server was implemented, the order of the arguments
239 to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
240 the reversal was not noticed until the server was widely deployed. Since
241 fixing this to follow the specification would cause incompatibility, the
242 current order was retained. For correct operation, clients should send
243 SSH_FXP_SYMLINK as follows:
244
245 uint32 id
246 string targetpath
247 string linkpath
248
249 3.2. sftp: Server extension announcement in SSH_FXP_VERSION
250
251 OpenSSH's sftp-server lists the extensions it supports using the
252 standard extension announcement mechanism in the SSH_FXP_VERSION server
253 hello packet:
254
255 uint32 3 /* protocol version */
256 string ext1-name
257 string ext1-version
258 string ext2-name
259 string ext2-version
260 ...
261 string extN-name
262 string extN-version
263
264 Each extension reports its integer version number as an ASCII encoded
265 string, e.g. "1". The version will be incremented if the extension is
266 ever changed in an incompatible way. The server MAY advertise the same
267 extension with multiple versions (though this is unlikely). Clients MUST
268 check the version number before attempting to use the extension.
269
270 3.3. sftp: Extension request "posix-rename@openssh.com"
271
272 This operation provides a rename operation with POSIX semantics, which
273 are different to those provided by the standard SSH_FXP_RENAME in
274 draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
275 SSH_FXP_EXTENDED request with the following format:
276
277 uint32 id
278 string "posix-rename@openssh.com"
279 string oldpath
280 string newpath
281
282 On receiving this request the server will perform the POSIX operation
283 rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
284 This extension is advertised in the SSH_FXP_VERSION hello with version
285 "1".
286
287 3.4. sftp: Extension requests "statvfs@openssh.com" and
288 "fstatvfs@openssh.com"
289
290 These requests correspond to the statvfs and fstatvfs POSIX system
291 interfaces. The "statvfs@openssh.com" request operates on an explicit
292 pathname, and is formatted as follows:
293
294 uint32 id
295 string "statvfs@openssh.com"
296 string path
297
298 The "fstatvfs@openssh.com" operates on an open file handle:
299
300 uint32 id
301 string "fstatvfs@openssh.com"
302 string handle
303
304 These requests return a SSH_FXP_STATUS reply on failure. On success they
305 return the following SSH_FXP_EXTENDED_REPLY reply:
306
307 uint32 id
308 uint64 f_bsize /* file system block size */
309 uint64 f_frsize /* fundamental fs block size */
310 uint64 f_blocks /* number of blocks (unit f_frsize) */
311 uint64 f_bfree /* free blocks in file system */
312 uint64 f_bavail /* free blocks for non-root */
313 uint64 f_files /* total file inodes */
314 uint64 f_ffree /* free file inodes */
315 uint64 f_favail /* free file inodes for to non-root */
316 uint64 f_fsid /* file system id */
317 uint64 f_flag /* bit mask of f_flag values */
318 uint64 f_namemax /* maximum filename length */
319
320 The values of the f_flag bitmask are as follows:
321
322 #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
323 #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
324
325 Both the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are
326 advertised in the SSH_FXP_VERSION hello with version "2".
327
328 10. sftp: Extension request "hardlink@openssh.com"
329
330 This request is for creating a hard link to a regular file. This
331 request is implemented as a SSH_FXP_EXTENDED request with the
332 following format:
333
334 uint32 id
335 string "hardlink@openssh.com"
336 string oldpath
337 string newpath
338
339 On receiving this request the server will perform the operation
340 link(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
341 This extension is advertised in the SSH_FXP_VERSION hello with version
342 "1".
343
344 10. sftp: Extension request "fsync@openssh.com"
345
346 This request asks the server to call fsync(2) on an open file handle.
347
348 uint32 id
349 string "fsync@openssh.com"
350 string handle
351
352 One receiving this request, a server will call fsync(handle_fd) and will
353 respond with a SSH_FXP_STATUS message.
354
355 This extension is advertised in the SSH_FXP_VERSION hello with version
356 "1".
357
358 $OpenBSD: PROTOCOL,v 1.23 2013/12/01 23:19:05 djm Exp $
+1626
-0
rfc/draft-ietf-secsh-filexfer-02.txt less more
0
1
2 Network Working Group T. Ylonen
3 Internet-Draft S. Lehtinen
4 Expires: April 1, 2002 SSH Communications Security Corp
5 October 2001
6
7
8 SSH File Transfer Protocol
9 draft-ietf-secsh-filexfer-02.txt
10
11 Status of this Memo
12
13 This document is an Internet-Draft and is in full conformance with
14 all provisions of Section 10 of RFC2026.
15
16 Internet-Drafts are working documents of the Internet Engineering
17 Task Force (IETF), its areas, and its working groups. Note that
18 other groups may also distribute working documents as Internet-
19 Drafts.
20
21 Internet-Drafts are draft documents valid for a maximum of six months
22 and may be updated, replaced, or obsoleted by other documents at any
23 time. It is inappropriate to use Internet-Drafts as reference
24 material or to cite them other than as "work in progress."
25
26 The list of current Internet-Drafts can be accessed at http://
27 www.ietf.org/ietf/1id-abstracts.txt.
28
29 The list of Internet-Draft Shadow Directories can be accessed at
30 http://www.ietf.org/shadow.html.
31
32 This Internet-Draft will expire on April 1, 2002.
33
34 Copyright Notice
35
36 Copyright (C) The Internet Society (2001). All Rights Reserved.
37
38 Abstract
39
40 The SSH File Transfer Protocol provides secure file transfer
41 functionality over any reliable data stream. It is the standard file
42 transfer protocol for use with the SSH2 protocol. This document
43 describes the file transfer protocol and its interface to the SSH2
44 protocol suite.
45
46
47
48
49
50
51
52
53
54 Ylonen & Lehtinen Expires April 1, 2002 [Page 1]
55
56 Internet-Draft SSH File Transfer Protocol October 2001
57
58
59 Table of Contents
60
61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
62 2. Use with the SSH Connection Protocol . . . . . . . . . . . . 4
63 3. General Packet Format . . . . . . . . . . . . . . . . . . . 5
64 4. Protocol Initialization . . . . . . . . . . . . . . . . . . 7
65 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . 8
66 6. Requests From the Client to the Server . . . . . . . . . . . 10
67 6.1 Request Synchronization and Reordering . . . . . . . . . . . 10
68 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . 11
69 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . . 11
70 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . . 13
71 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . . 14
72 6.6 Creating and Deleting Directories . . . . . . . . . . . . . 15
73 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . . 15
74 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . . 16
75 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . . 17
76 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . . 18
77 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . . 18
78 7. Responses from the Server to the Client . . . . . . . . . . 20
79 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . 24
80 9. Security Considerations . . . . . . . . . . . . . . . . . . 25
81 10. Changes from previous protocol versions . . . . . . . . . . 26
82 10.1 Changes between versions 3 and 2 . . . . . . . . . . . . . . 26
83 10.2 Changes between versions 2 and 1 . . . . . . . . . . . . . . 26
84 10.3 Changes between versions 1 and 0 . . . . . . . . . . . . . . 26
85 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 27
86 References . . . . . . . . . . . . . . . . . . . . . . . . . 28
87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28
88 Full Copyright Statement . . . . . . . . . . . . . . . . . . 29
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110 Ylonen & Lehtinen Expires April 1, 2002 [Page 2]
111
112 Internet-Draft SSH File Transfer Protocol October 2001
113
114
115 1. Introduction
116
117 This protocol provides secure file transfer (and more generally file
118 system access) functionality over a reliable data stream, such as a
119 channel in the SSH2 protocol [3].
120
121 This protocol is designed so that it could be used to implement a
122 secure remote file system service, as well as a secure file transfer
123 service.
124
125 This protocol assumes that it runs over a secure channel, and that
126 the server has already authenticated the user at the client end, and
127 that the identity of the client user is externally available to the
128 server implementation.
129
130 In general, this protocol follows a simple request-response model.
131 Each request and response contains a sequence number and multiple
132 requests may be pending simultaneously. There are a relatively large
133 number of different request messages, but a small number of possible
134 response messages. Each request has one or more response messages
135 that may be returned in result (e.g., a read either returns data or
136 reports error status).
137
138 The packet format descriptions in this specification follow the
139 notation presented in the secsh architecture draft.[3].
140
141 Even though this protocol is described in the context of the SSH2
142 protocol, this protocol is general and independent of the rest of the
143 SSH2 protocol suite. It could be used in a number of different
144 applications, such as secure file transfer over TLS RFC 2246 [1] and
145 transfer of management information in VPN applications.
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166 Ylonen & Lehtinen Expires April 1, 2002 [Page 3]
167
168 Internet-Draft SSH File Transfer Protocol October 2001
169
170
171 2. Use with the SSH Connection Protocol
172
173 When used with the SSH2 Protocol suite, this protocol is intended to
174 be used from the SSH Connection Protocol [5] as a subsystem, as
175 described in section ``Starting a Shell or a Command''. The
176 subsystem name used with this protocol is "sftp".
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222 Ylonen & Lehtinen Expires April 1, 2002 [Page 4]
223
224 Internet-Draft SSH File Transfer Protocol October 2001
225
226
227 3. General Packet Format
228
229 All packets transmitted over the secure connection are of the
230 following format:
231
232 uint32 length
233 byte type
234 byte[length - 1] data payload
235
236 That is, they are just data preceded by 32-bit length and 8-bit type
237 fields. The `length' is the length of the data area, and does not
238 include the `length' field itself. The format and interpretation of
239 the data area depends on the packet type.
240
241 All packet descriptions below only specify the packet type and the
242 data that goes into the data field. Thus, they should be prefixed by
243 the `length' and `type' fields.
244
245 The maximum size of a packet is in practice determined by the client
246 (the maximum size of read or write requests that it sends, plus a few
247 bytes of packet overhead). All servers SHOULD support packets of at
248 least 34000 bytes (where the packet size refers to the full length,
249 including the header above). This should allow for reads and writes
250 of at most 32768 bytes.
251
252 There is no limit on the number of outstanding (non-acknowledged)
253 requests that the client may send to the server. In practice this is
254 limited by the buffering available on the data stream and the queuing
255 performed by the server. If the server's queues are full, it should
256 not read any more data from the stream, and flow control will prevent
257 the client from sending more requests. Note, however, that while
258 there is no restriction on the protocol level, the client's API may
259 provide a limit in order to prevent infinite queuing of outgoing
260 requests at the client.
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278 Ylonen & Lehtinen Expires April 1, 2002 [Page 5]
279
280 Internet-Draft SSH File Transfer Protocol October 2001
281
282
283 The following values are defined for packet types.
284
285 #define SSH_FXP_INIT 1
286 #define SSH_FXP_VERSION 2
287 #define SSH_FXP_OPEN 3
288 #define SSH_FXP_CLOSE 4
289 #define SSH_FXP_READ 5
290 #define SSH_FXP_WRITE 6
291 #define SSH_FXP_LSTAT 7
292 #define SSH_FXP_FSTAT 8
293 #define SSH_FXP_SETSTAT 9
294 #define SSH_FXP_FSETSTAT 10
295 #define SSH_FXP_OPENDIR 11
296 #define SSH_FXP_READDIR 12
297 #define SSH_FXP_REMOVE 13
298 #define SSH_FXP_MKDIR 14
299 #define SSH_FXP_RMDIR 15
300 #define SSH_FXP_REALPATH 16
301 #define SSH_FXP_STAT 17
302 #define SSH_FXP_RENAME 18
303 #define SSH_FXP_READLINK 19
304 #define SSH_FXP_SYMLINK 20
305 #define SSH_FXP_STATUS 101
306 #define SSH_FXP_HANDLE 102
307 #define SSH_FXP_DATA 103
308 #define SSH_FXP_NAME 104
309 #define SSH_FXP_ATTRS 105
310 #define SSH_FXP_EXTENDED 200
311 #define SSH_FXP_EXTENDED_REPLY 201
312
313 Additional packet types should only be defined if the protocol
314 version number (see Section ``Protocol Initialization'') is
315 incremented, and their use MUST be negotiated using the version
316 number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
317 packets can be used to implement vendor-specific extensions. See
318 Section ``Vendor-Specific-Extensions'' for more details.
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334 Ylonen & Lehtinen Expires April 1, 2002 [Page 6]
335
336 Internet-Draft SSH File Transfer Protocol October 2001
337
338
339 4. Protocol Initialization
340
341 When the file transfer protocol starts, it first sends a SSH_FXP_INIT
342 (including its version number) packet to the server. The server
343 responds with a SSH_FXP_VERSION packet, supplying the lowest of its
344 own and the client's version number. Both parties should from then
345 on adhere to particular version of the protocol.
346
347 The SSH_FXP_INIT packet (from client to server) has the following
348 data:
349
350 uint32 version
351 <extension data>
352
353 The SSH_FXP_VERSION packet (from server to client) has the following
354 data:
355
356 uint32 version
357 <extension data>
358
359 The version number of the protocol specified in this document is 3.
360 The version number should be incremented for each incompatible
361 revision of this protocol.
362
363 The extension data in the above packets may be empty, or may be a
364 sequence of
365
366 string extension_name
367 string extension_data
368
369 pairs (both strings MUST always be present if one is, but the
370 `extension_data' string may be of zero length). If present, these
371 strings indicate extensions to the baseline protocol. The
372 `extension_name' field(s) identify the name of the extension. The
373 name should be of the form "name@domain", where the domain is the DNS
374 domain name of the organization defining the extension. Additional
375 names that are not of this format may be defined later by the IETF.
376 Implementations MUST silently ignore any extensions whose name they
377 do not recognize.
378
379
380
381
382
383
384
385
386
387
388
389
390 Ylonen & Lehtinen Expires April 1, 2002 [Page 7]
391
392 Internet-Draft SSH File Transfer Protocol October 2001
393
394
395 5. File Attributes
396
397 A new compound data type is defined for encoding file attributes. It
398 is basically just a combination of elementary types, but is defined
399 once because of the non-trivial description of the fields and to
400 ensure maintainability.
401
402 The same encoding is used both when returning file attributes from
403 the server and when sending file attributes to the server. When
404 sending it to the server, the flags field specifies which attributes
405 are included, and the server will use default values for the
406 remaining attributes (or will not modify the values of remaining
407 attributes). When receiving attributes from the server, the flags
408 specify which attributes are included in the returned data. The
409 server normally returns all attributes it knows about.
410
411 uint32 flags
412 uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE
413 uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID
414 uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID
415 uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
416 uint32 atime present only if flag SSH_FILEXFER_ACMODTIME
417 uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME
418 uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
419 string extended_type
420 string extended_data
421 ... more extended data (extended_type - extended_data pairs),
422 so that number of pairs equals extended_count
423
424 The `flags' specify which of the fields are present. Those fields
425 for which the corresponding flag is not set are not present (not
426 included in the packet). New flags can only be added by incrementing
427 the protocol version number (or by using the extension mechanism
428 described below).
429
430 The `size' field specifies the size of the file in bytes.
431
432 The `uid' and `gid' fields contain numeric Unix-like user and group
433 identifiers, respectively.
434
435 The `permissions' field contains a bit mask of file permissions as
436 defined by posix [1].
437
438 The `atime' and `mtime' contain the access and modification times of
439 the files, respectively. They are represented as seconds from Jan 1,
440 1970 in UTC.
441
442 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
443
444
445
446 Ylonen & Lehtinen Expires April 1, 2002 [Page 8]
447
448 Internet-Draft SSH File Transfer Protocol October 2001
449
450
451 mechanism for vendor-specific extensions. If the flag is specified,
452 then the `extended_count' field is present. It specifies the number
453 of extended_type-extended_data pairs that follow. Each of these
454 pairs specifies an extended attribute. For each of the attributes,
455 the extended_type field should be a string of the format
456 "name@domain", where "domain" is a valid, registered domain name and
457 "name" identifies the method. The IETF may later standardize certain
458 names that deviate from this format (e.g., that do not contain the
459 "@" sign). The interpretation of `extended_data' depends on the
460 type. Implementations SHOULD ignore extended data fields that they
461 do not understand.
462
463 Additional fields can be added to the attributes by either defining
464 additional bits to the flags field to indicate their presence, or by
465 defining extended attributes for them. The extended attributes
466 mechanism is recommended for most purposes; additional flags bits
467 should only be defined by an IETF standards action that also
468 increments the protocol version number. The use of such new fields
469 MUST be negotiated by the version number in the protocol exchange.
470 It is a protocol error if a packet with unsupported protocol bits is
471 received.
472
473 The flags bits are defined to have the following values:
474
475 #define SSH_FILEXFER_ATTR_SIZE 0x00000001
476 #define SSH_FILEXFER_ATTR_UIDGID 0x00000002
477 #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
478 #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008
479 #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502 Ylonen & Lehtinen Expires April 1, 2002 [Page 9]
503
504 Internet-Draft SSH File Transfer Protocol October 2001
505
506
507 6. Requests From the Client to the Server
508
509 Requests from the client to the server represent the various file
510 system operations. Each request begins with an `id' field, which is
511 a 32-bit identifier identifying the request (selected by the client).
512 The same identifier will be returned in the response to the request.
513 One possible implementation of it is a monotonically increasing
514 request sequence number (modulo 2^32).
515
516 Many operations in the protocol operate on open files. The
517 SSH_FXP_OPEN request can return a file handle (which is an opaque
518 variable-length string) which may be used to access the file later
519 (e.g. in a read operation). The client MUST NOT send requests the
520 server with bogus or closed handles. However, the server MUST
521 perform adequate checks on the handle in order to avoid security
522 risks due to fabricated handles.
523
524 This design allows either stateful and stateless server
525 implementation, as well as an implementation which caches state
526 between requests but may also flush it. The contents of the file
527 handle string are entirely up to the server and its design. The
528 client should not modify or attempt to interpret the file handle
529 strings.
530
531 The file handle strings MUST NOT be longer than 256 bytes.
532
533 6.1 Request Synchronization and Reordering
534
535 The protocol and implementations MUST process requests relating to
536 the same file in the order in which they are received. In other
537 words, if an application submits multiple requests to the server, the
538 results in the responses will be the same as if it had sent the
539 requests one at a time and waited for the response in each case. For
540 example, the server may process non-overlapping read/write requests
541 to the same file in parallel, but overlapping reads and writes cannot
542 be reordered or parallelized. However, there are no ordering
543 restrictions on the server for processing requests from two different
544 file transfer connections. The server may interleave and parallelize
545 them at will.
546
547 There are no restrictions on the order in which responses to
548 outstanding requests are delivered to the client, except that the
549 server must ensure fairness in the sense that processing of no
550 request will be indefinitely delayed even if the client is sending
551 other requests so that there are multiple outstanding requests all
552 the time.
553
554
555
556
557
558 Ylonen & Lehtinen Expires April 1, 2002 [Page 10]
559
560 Internet-Draft SSH File Transfer Protocol October 2001
561
562
563 6.2 File Names
564
565 This protocol represents file names as strings. File names are
566 assumed to use the slash ('/') character as a directory separator.
567
568 File names starting with a slash are "absolute", and are relative to
569 the root of the file system. Names starting with any other character
570 are relative to the user's default directory (home directory). Note
571 that identifying the user is assumed to take place outside of this
572 protocol.
573
574 Servers SHOULD interpret a path name component ".." as referring to
575 the parent directory, and "." as referring to the current directory.
576 If the server implementation limits access to certain parts of the
577 file system, it must be extra careful in parsing file names when
578 enforcing such restrictions. There have been numerous reported
579 security bugs where a ".." in a path name has allowed access outside
580 the intended area.
581
582 An empty path name is valid, and it refers to the user's default
583 directory (usually the user's home directory).
584
585 Otherwise, no syntax is defined for file names by this specification.
586 Clients should not make any other assumptions; however, they can
587 splice path name components returned by SSH_FXP_READDIR together
588 using a slash ('/') as the separator, and that will work as expected.
589
590 It is understood that the lack of well-defined semantics for file
591 names may cause interoperability problems between clients and servers
592 using radically different operating systems. However, this approach
593 is known to work acceptably with most systems, and alternative
594 approaches that e.g. treat file names as sequences of structured
595 components are quite complicated.
596
597 6.3 Opening, Creating, and Closing Files
598
599 Files are opened and created using the SSH_FXP_OPEN message, whose
600 data part is as follows:
601
602 uint32 id
603 string filename
604 uint32 pflags
605 ATTRS attrs
606
607 The `id' field is the request identifier as for all requests.
608
609 The `filename' field specifies the file name. See Section ``File
610 Names'' for more information.
611
612
613
614 Ylonen & Lehtinen Expires April 1, 2002 [Page 11]
615
616 Internet-Draft SSH File Transfer Protocol October 2001
617
618
619 The `pflags' field is a bitmask. The following bits have been
620 defined.
621
622 #define SSH_FXF_READ 0x00000001
623 #define SSH_FXF_WRITE 0x00000002
624 #define SSH_FXF_APPEND 0x00000004
625 #define SSH_FXF_CREAT 0x00000008
626 #define SSH_FXF_TRUNC 0x00000010
627 #define SSH_FXF_EXCL 0x00000020
628
629 These have the following meanings:
630
631 SSH_FXF_READ
632 Open the file for reading.
633
634 SSH_FXF_WRITE
635 Open the file for writing. If both this and SSH_FXF_READ are
636 specified, the file is opened for both reading and writing.
637
638 SSH_FXF_APPEND
639 Force all writes to append data at the end of the file.
640
641 SSH_FXF_CREAT
642 If this flag is specified, then a new file will be created if one
643 does not already exist (if O_TRUNC is specified, the new file will
644 be truncated to zero length if it previously exists).
645
646 SSH_FXF_TRUNC
647 Forces an existing file with the same name to be truncated to zero
648 length when creating a file by specifying SSH_FXF_CREAT.
649 SSH_FXF_CREAT MUST also be specified if this flag is used.
650
651 SSH_FXF_EXCL
652 Causes the request to fail if the named file already exists.
653 SSH_FXF_CREAT MUST also be specified if this flag is used.
654
655 The `attrs' field specifies the initial attributes for the file.
656 Default values will be used for those attributes that are not
657 specified. See Section ``File Attributes'' for more information.
658
659 Regardless the server operating system, the file will always be
660 opened in "binary" mode (i.e., no translations between different
661 character sets and newline encodings).
662
663 The response to this message will be either SSH_FXP_HANDLE (if the
664 operation is successful) or SSH_FXP_STATUS (if the operation fails).
665
666
667
668
669
670 Ylonen & Lehtinen Expires April 1, 2002 [Page 12]
671
672 Internet-Draft SSH File Transfer Protocol October 2001
673
674
675 A file is closed by using the SSH_FXP_CLOSE request. Its data field
676 has the following format:
677
678 uint32 id
679 string handle
680
681 where `id' is the request identifier, and `handle' is a handle
682 previously returned in the response to SSH_FXP_OPEN or
683 SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
684 request has been sent.
685
686 The response to this request will be a SSH_FXP_STATUS message. One
687 should note that on some server platforms even a close can fail.
688 This can happen e.g. if the server operating system caches writes,
689 and an error occurs while flushing cached writes during the close.
690
691 6.4 Reading and Writing
692
693 Once a file has been opened, it can be read using the SSH_FXP_READ
694 message, which has the following format:
695
696 uint32 id
697 string handle
698 uint64 offset
699 uint32 len
700
701 where `id' is the request identifier, `handle' is an open file handle
702 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
703 to the beginning of the file from where to start reading, and `len'
704 is the maximum number of bytes to read.
705
706 In response to this request, the server will read as many bytes as it
707 can from the file (up to `len'), and return them in a SSH_FXP_DATA
708 message. If an error occurs or EOF is encountered before reading any
709 data, the server will respond with SSH_FXP_STATUS. For normal disk
710 files, it is guaranteed that this will read the specified number of
711 bytes, or up to end of file. For e.g. device files this may return
712 fewer bytes than requested.
713
714 Writing to a file is achieved using the SSH_FXP_WRITE message, which
715 has the following format:
716
717 uint32 id
718 string handle
719 uint64 offset
720 string data
721
722 where `id' is a request identifier, `handle' is a file handle
723
724
725
726 Ylonen & Lehtinen Expires April 1, 2002 [Page 13]
727
728 Internet-Draft SSH File Transfer Protocol October 2001
729
730
731 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
732 beginning of the file where to start writing, and `data' is the data
733 to be written.
734
735 The write will extend the file if writing beyond the end of the file.
736 It is legal to write way beyond the end of the file; the semantics
737 are to write zeroes from the end of the file to the specified offset
738 and then the data. On most operating systems, such writes do not
739 allocate disk space but instead leave "holes" in the file.
740
741 The server responds to a write request with a SSH_FXP_STATUS message.
742
743 6.5 Removing and Renaming Files
744
745 Files can be removed using the SSH_FXP_REMOVE message. It has the
746 following format:
747
748 uint32 id
749 string filename
750
751 where `id' is the request identifier and `filename' is the name of
752 the file to be removed. See Section ``File Names'' for more
753 information. This request cannot be used to remove directories.
754
755 The server will respond to this request with a SSH_FXP_STATUS
756 message.
757
758 Files (and directories) can be renamed using the SSH_FXP_RENAME
759 message. Its data is as follows:
760
761 uint32 id
762 string oldpath
763 string newpath
764
765 where `id' is the request identifier, `oldpath' is the name of an
766 existing file or directory, and `newpath' is the new name for the
767 file or directory. It is an error if there already exists a file
768 with the name specified by newpath. The server may also fail rename
769 requests in other situations, for example if `oldpath' and `newpath'
770 point to different file systems on the server.
771
772 The server will respond to this request with a SSH_FXP_STATUS
773 message.
774
775
776
777
778
779
780
781
782 Ylonen & Lehtinen Expires April 1, 2002 [Page 14]
783
784 Internet-Draft SSH File Transfer Protocol October 2001
785
786
787 6.6 Creating and Deleting Directories
788
789 New directories can be created using the SSH_FXP_MKDIR request. It
790 has the following format:
791
792 uint32 id
793 string path
794 ATTRS attrs
795
796 where `id' is the request identifier, `path' and `attrs' specifies
797 the modifications to be made to its attributes. See Section ``File
798 Names'' for more information on file names. Attributes are discussed
799 in more detail in Section ``File Attributes''. specifies the
800 directory to be created. An error will be returned if a file or
801 directory with the specified path already exists. The server will
802 respond to this request with a SSH_FXP_STATUS message.
803
804 Directories can be removed using the SSH_FXP_RMDIR request, which
805 has the following format:
806
807 uint32 id
808 string path
809
810 where `id' is the request identifier, and `path' specifies the
811 directory to be removed. See Section ``File Names'' for more
812 information on file names. An error will be returned if no directory
813 with the specified path exists, or if the specified directory is not
814 empty, or if the path specified a file system object other than a
815 directory. The server responds to this request with a SSH_FXP_STATUS
816 message.
817
818 6.7 Scanning Directories
819
820 The files in a directory can be listed using the SSH_FXP_OPENDIR and
821 SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
822 or more file names with full file attributes for each file. The
823 client should call SSH_FXP_READDIR repeatedly until it has found the
824 file it is looking for or until the server responds with a
825 SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
826 there are no more files in the directory). The client should then
827 close the handle using the SSH_FXP_CLOSE request.
828
829
830
831
832
833
834
835
836
837
838 Ylonen & Lehtinen Expires April 1, 2002 [Page 15]
839
840 Internet-Draft SSH File Transfer Protocol October 2001
841
842
843 The SSH_FXP_OPENDIR opens a directory for reading. It has the
844 following format:
845
846 uint32 id
847 string path
848
849 where `id' is the request identifier and `path' is the path name of
850 the directory to be listed (without any trailing slash). See Section
851 ``File Names'' for more information on file names. This will return
852 an error if the path does not specify a directory or if the directory
853 is not readable. The server will respond to this request with either
854 a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
855
856 Once the directory has been successfully opened, files (and
857 directories) contained in it can be listed using SSH_FXP_READDIR
858 requests. These are of the format
859
860 uint32 id
861 string handle
862
863 where `id' is the request identifier, and `handle' is a handle
864 returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
865 use an ordinary file handle returned by SSH_FXP_OPEN.)
866
867 The server responds to this request with either a SSH_FXP_NAME or a
868 SSH_FXP_STATUS message. One or more names may be returned at a time.
869 Full status information is returned for each name in order to speed
870 up typical directory listings.
871
872 When the client no longer wishes to read more names from the
873 directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
874 should be closed regardless of whether an error has occurred or not.
875
876 6.8 Retrieving File Attributes
877
878 Very often, file attributes are automatically returned by
879 SSH_FXP_READDIR. However, sometimes there is need to specifically
880 retrieve the attributes for a named file. This can be done using the
881 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
882
883 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
884 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
885 follow symbolic links. Both have the same format:
886
887 uint32 id
888 string path
889
890 where `id' is the request identifier, and `path' specifies the file
891
892
893
894 Ylonen & Lehtinen Expires April 1, 2002 [Page 16]
895
896 Internet-Draft SSH File Transfer Protocol October 2001
897
898
899 system object for which status is to be returned. The server
900 responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
901
902 SSH_FXP_FSTAT differs from the others in that it returns status
903 information for an open file (identified by the file handle). Its
904 format is as follows:
905
906 uint32 id
907 string handle
908
909 where `id' is the request identifier and `handle' is a file handle
910 returned by SSH_FXP_OPEN. The server responds to this request with
911 SSH_FXP_ATTRS or SSH_FXP_STATUS.
912
913 6.9 Setting File Attributes
914
915 File attributes may be modified using the SSH_FXP_SETSTAT and
916 SSH_FXP_FSETSTAT requests. These requests are used for operations
917 such as changing the ownership, permissions or access times, as well
918 as for truncating a file.
919
920 The SSH_FXP_SETSTAT request is of the following format:
921
922 uint32 id
923 string path
924 ATTRS attrs
925
926 where `id' is the request identifier, `path' specifies the file
927 system object (e.g. file or directory) whose attributes are to be
928 modified, and `attrs' specifies the modifications to be made to its
929 attributes. Attributes are discussed in more detail in Section
930 ``File Attributes''.
931
932 An error will be returned if the specified file system object does
933 not exist or the user does not have sufficient rights to modify the
934 specified attributes. The server responds to this request with a
935 SSH_FXP_STATUS message.
936
937 The SSH_FXP_FSETSTAT request modifies the attributes of a file which
938 is already open. It has the following format:
939
940 uint32 id
941 string handle
942 ATTRS attrs
943
944 where `id' is the request identifier, `handle' (MUST be returned by
945 SSH_FXP_OPEN) identifies the file whose attributes are to be
946 modified, and `attrs' specifies the modifications to be made to its
947
948
949
950 Ylonen & Lehtinen Expires April 1, 2002 [Page 17]
951
952 Internet-Draft SSH File Transfer Protocol October 2001
953
954
955 attributes. Attributes are discussed in more detail in Section
956 ``File Attributes''. The server will respond to this request with
957 SSH_FXP_STATUS.
958
959 6.10 Dealing with Symbolic links
960
961 The SSH_FXP_READLINK request may be used to read the target of a
962 symbolic link. It would have a data part as follows:
963
964 uint32 id
965 string path
966
967 where `id' is the request identifier and `path' specifies the path
968 name of the symlink to be read.
969
970 The server will respond with a SSH_FXP_NAME packet containing only
971 one name and a dummy attributes value. The name in the returned
972 packet contains the target of the link. If an error occurs, the
973 server may respond with SSH_FXP_STATUS.
974
975 The SSH_FXP_SYMLINK request will create a symbolic link on the
976 server. It is of the following format
977
978 uint32 id
979 string linkpath
980 string targetpath
981
982 where `id' is the request identifier, `linkpath' specifies the path
983 name of the symlink to be created and `targetpath' specifies the
984 target of the symlink. The server shall respond with a
985 SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
986 condition.
987
988 6.11 Canonicalizing the Server-Side Path Name
989
990 The SSH_FXP_REALPATH request can be used to have the server
991 canonicalize any given path name to an absolute path. This is useful
992 for converting path names containing ".." components or relative
993 pathnames without a leading slash into absolute paths. The format of
994 the request is as follows:
995
996 uint32 id
997 string path
998
999 where `id' is the request identifier and `path' specifies the path
1000 name to be canonicalized. The server will respond with a
1001 SSH_FXP_NAME packet containing only one name and a dummy attributes
1002 value. The name is the returned packet will be in canonical form.
1003
1004
1005
1006 Ylonen & Lehtinen Expires April 1, 2002 [Page 18]
1007
1008 Internet-Draft SSH File Transfer Protocol October 2001
1009
1010
1011 If an error occurs, the server may also respond with SSH_FXP_STATUS.
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062 Ylonen & Lehtinen Expires April 1, 2002 [Page 19]
1063
1064 Internet-Draft SSH File Transfer Protocol October 2001
1065
1066
1067 7. Responses from the Server to the Client
1068
1069 The server responds to the client using one of a few response
1070 packets. All requests can return a SSH_FXP_STATUS response upon
1071 failure. When the operation is successful, any of the responses may
1072 be returned (depending on the operation). If no data needs to be
1073 returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
1074 status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
1075 to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
1076 requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
1077 SSH_FXP_NAME is used to return one or more file names from a
1078 SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
1079 used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
1080 SSH_FXP_FSTAT requests.
1081
1082 Exactly one response will be returned for each request. Each
1083 response packet contains a request identifier which can be used to
1084 match each response with the corresponding request. Note that it is
1085 legal to have several requests outstanding simultaneously, and the
1086 server is allowed to send responses to them in a different order from
1087 the order in which the requests were sent (the result of their
1088 execution, however, is guaranteed to be as if they had been processed
1089 one at a time in the order in which the requests were sent).
1090
1091 Response packets are of the same general format as request packets.
1092 Each response packet begins with the request identifier.
1093
1094 The format of the data portion of the SSH_FXP_STATUS response is as
1095 follows:
1096
1097 uint32 id
1098 uint32 error/status code
1099 string error message (ISO-10646 UTF-8 [RFC-2279])
1100 string language tag (as defined in [RFC-1766])
1101
1102 where `id' is the request identifier, and `error/status code'
1103 indicates the result of the requested operation. The value SSH_FX_OK
1104 indicates success, and all other values indicate failure.
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118 Ylonen & Lehtinen Expires April 1, 2002 [Page 20]
1119
1120 Internet-Draft SSH File Transfer Protocol October 2001
1121
1122
1123 Currently, the following values are defined (other values may be
1124 defined by future versions of this protocol):
1125
1126 #define SSH_FX_OK 0
1127 #define SSH_FX_EOF 1
1128 #define SSH_FX_NO_SUCH_FILE 2
1129 #define SSH_FX_PERMISSION_DENIED 3
1130 #define SSH_FX_FAILURE 4
1131 #define SSH_FX_BAD_MESSAGE 5
1132 #define SSH_FX_NO_CONNECTION 6
1133 #define SSH_FX_CONNECTION_LOST 7
1134 #define SSH_FX_OP_UNSUPPORTED 8
1135
1136 SSH_FX_OK
1137 Indicates successful completion of the operation.
1138
1139 SSH_FX_EOF
1140 indicates end-of-file condition; for SSH_FX_READ it means that no
1141 more data is available in the file, and for SSH_FX_READDIR it
1142 indicates that no more files are contained in the directory.
1143
1144 SSH_FX_NO_SUCH_FILE
1145 is returned when a reference is made to a file which should exist
1146 but doesn't.
1147
1148 SSH_FX_PERMISSION_DENIED
1149 is returned when the authenticated user does not have sufficient
1150 permissions to perform the operation.
1151
1152 SSH_FX_FAILURE
1153 is a generic catch-all error message; it should be returned if an
1154 error occurs for which there is no more specific error code
1155 defined.
1156
1157 SSH_FX_BAD_MESSAGE
1158 may be returned if a badly formatted packet or protocol
1159 incompatibility is detected.
1160
1161 SSH_FX_NO_CONNECTION
1162 is a pseudo-error which indicates that the client has no
1163 connection to the server (it can only be generated locally by the
1164 client, and MUST NOT be returned by servers).
1165
1166 SSH_FX_CONNECTION_LOST
1167 is a pseudo-error which indicates that the connection to the
1168 server has been lost (it can only be generated locally by the
1169 client, and MUST NOT be returned by servers).
1170
1171
1172
1173
1174 Ylonen & Lehtinen Expires April 1, 2002 [Page 21]
1175
1176 Internet-Draft SSH File Transfer Protocol October 2001
1177
1178
1179 SSH_FX_OP_UNSUPPORTED
1180 indicates that an attempt was made to perform an operation which
1181 is not supported for the server (it may be generated locally by
1182 the client if e.g. the version number exchange indicates that a
1183 required feature is not supported by the server, or it may be
1184 returned by the server if the server does not implement an
1185 operation).
1186
1187 The SSH_FXP_HANDLE response has the following format:
1188
1189 uint32 id
1190 string handle
1191
1192 where `id' is the request identifier, and `handle' is an arbitrary
1193 string that identifies an open file or directory on the server. The
1194 handle is opaque to the client; the client MUST NOT attempt to
1195 interpret or modify it in any way. The length of the handle string
1196 MUST NOT exceed 256 data bytes.
1197
1198 The SSH_FXP_DATA response has the following format:
1199
1200 uint32 id
1201 string data
1202
1203 where `id' is the request identifier, and `data' is an arbitrary byte
1204 string containing the requested data. The data string may be at most
1205 the number of bytes requested in a SSH_FXP_READ request, but may also
1206 be shorter if end of file is reached or if the read is from something
1207 other than a regular file.
1208
1209 The SSH_FXP_NAME response has the following format:
1210
1211 uint32 id
1212 uint32 count
1213 repeats count times:
1214 string filename
1215 string longname
1216 ATTRS attrs
1217
1218 where `id' is the request identifier, `count' is the number of names
1219 returned in this response, and the remaining fields repeat `count'
1220 times (so that all three fields are first included for the first
1221 file, then for the second file, etc). In the repeated part,
1222 `filename' is a file name being returned (for SSH_FXP_READDIR, it
1223 will be a relative name within the directory, without any path
1224 components; for SSH_FXP_REALPATH it will be an absolute path name),
1225 `longname' is an expanded format for the file name, similar to what
1226 is returned by "ls -l" on Unix systems, and `attrs' is the attributes
1227
1228
1229
1230 Ylonen & Lehtinen Expires April 1, 2002 [Page 22]
1231
1232 Internet-Draft SSH File Transfer Protocol October 2001
1233
1234
1235 of the file as described in Section ``File Attributes''.
1236
1237 The format of the `longname' field is unspecified by this protocol.
1238 It MUST be suitable for use in the output of a directory listing
1239 command (in fact, the recommended operation for a directory listing
1240 command is to simply display this data). However, clients SHOULD NOT
1241 attempt to parse the longname field for file attributes; they SHOULD
1242 use the attrs field instead.
1243
1244 The recommended format for the longname field is as follows:
1245
1246 -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer
1247 1234567890 123 12345678 12345678 12345678 123456789012
1248
1249 Here, the first line is sample output, and the second field indicates
1250 widths of the various fields. Fields are separated by spaces. The
1251 first field lists file permissions for user, group, and others; the
1252 second field is link count; the third field is the name of the user
1253 who owns the file; the fourth field is the name of the group that
1254 owns the file; the fifth field is the size of the file in bytes; the
1255 sixth field (which actually may contain spaces, but is fixed to 12
1256 characters) is the file modification time, and the seventh field is
1257 the file name. Each field is specified to be a minimum of certain
1258 number of character positions (indicated by the second line above),
1259 but may also be longer if the data does not fit in the specified
1260 length.
1261
1262 The SSH_FXP_ATTRS response has the following format:
1263
1264 uint32 id
1265 ATTRS attrs
1266
1267 where `id' is the request identifier, and `attrs' is the returned
1268 file attributes as described in Section ``File Attributes''.
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286 Ylonen & Lehtinen Expires April 1, 2002 [Page 23]
1287
1288 Internet-Draft SSH File Transfer Protocol October 2001
1289
1290
1291 8. Vendor-Specific Extensions
1292
1293 The SSH_FXP_EXTENDED request provides a generic extension mechanism
1294 for adding vendor-specific commands. The request has the following
1295 format:
1296
1297 uint32 id
1298 string extended-request
1299 ... any request-specific data ...
1300
1301 where `id' is the request identifier, and `extended-request' is a
1302 string of the format "name@domain", where domain is an internet
1303 domain name of the vendor defining the request. The rest of the
1304 request is completely vendor-specific, and servers should only
1305 attempt to interpret it if they recognize the `extended-request'
1306 name.
1307
1308 The server may respond to such requests using any of the response
1309 packets defined in Section ``Responses from the Server to the
1310 Client''. Additionally, the server may also respond with a
1311 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
1312 not recognize the `extended-request' name, then the server MUST
1313 respond with SSH_FXP_STATUS with error/status set to
1314 SSH_FX_OP_UNSUPPORTED.
1315
1316 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
1317 extension-specific data from the server to the client. It is of the
1318 following format:
1319
1320 uint32 id
1321 ... any request-specific data ...
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342 Ylonen & Lehtinen Expires April 1, 2002 [Page 24]
1343
1344 Internet-Draft SSH File Transfer Protocol October 2001
1345
1346
1347 9. Security Considerations
1348
1349 This protocol assumes that it is run over a secure channel and that
1350 the endpoints of the channel have been authenticated. Thus, this
1351 protocol assumes that it is externally protected from network-level
1352 attacks.
1353
1354 This protocol provides file system access to arbitrary files on the
1355 server (only constrained by the server implementation). It is the
1356 responsibility of the server implementation to enforce any access
1357 controls that may be required to limit the access allowed for any
1358 particular user (the user being authenticated externally to this
1359 protocol, typically using the SSH User Authentication Protocol [6].
1360
1361 Care must be taken in the server implementation to check the validity
1362 of received file handle strings. The server should not rely on them
1363 directly; it MUST check the validity of each handle before relying on
1364 it.
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398 Ylonen & Lehtinen Expires April 1, 2002 [Page 25]
1399
1400 Internet-Draft SSH File Transfer Protocol October 2001
1401
1402
1403 10. Changes from previous protocol versions
1404
1405 The SSH File Transfer Protocol has changed over time, before it's
1406 standardization. The following is a description of the incompatible
1407 changes between different versions.
1408
1409 10.1 Changes between versions 3 and 2
1410
1411 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
1412
1413 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
1414 added.
1415
1416 o The SSH_FXP_STATUS message was changed to include fields `error
1417 message' and `language tag'.
1418
1419
1420 10.2 Changes between versions 2 and 1
1421
1422 o The SSH_FXP_RENAME message was added.
1423
1424
1425 10.3 Changes between versions 1 and 0
1426
1427 o Implementation changes, no actual protocol changes.
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454 Ylonen & Lehtinen Expires April 1, 2002 [Page 26]
1455
1456 Internet-Draft SSH File Transfer Protocol October 2001
1457
1458
1459 11. Trademark Issues
1460
1461 "ssh" is a registered trademark of SSH Communications Security Corp
1462 in the United States and/or other countries.
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510 Ylonen & Lehtinen Expires April 1, 2002 [Page 27]
1511
1512 Internet-Draft SSH File Transfer Protocol October 2001
1513
1514
1515 References
1516
1517 [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
1518 P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
1519 1999.
1520
1521 [2] Institute of Electrical and Electronics Engineers, "Information
1522 Technology - Portable Operating System Interface (POSIX) - Part
1523 1: System Application Program Interface (API) [C Language]",
1524 IEEE Standard 1003.2, 1996.
1525
1526 [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1527 Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-
1528 architecture-09 (work in progress), July 2001.
1529
1530 [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1531 Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-
1532 architecture-09 (work in progress), July 2001.
1533
1534 [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1535 Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-11
1536 (work in progress), July 2001.
1537
1538 [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1539 Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-
1540 userauth-11 (work in progress), July 2001.
1541
1542
1543 Authors' Addresses
1544
1545 Tatu Ylonen
1546 SSH Communications Security Corp
1547 Fredrikinkatu 42
1548 HELSINKI FIN-00100
1549 Finland
1550
1551 EMail: ylo@ssh.com
1552
1553
1554 Sami Lehtinen
1555 SSH Communications Security Corp
1556 Fredrikinkatu 42
1557 HELSINKI FIN-00100
1558 Finland
1559
1560 EMail: sjl@ssh.com
1561
1562
1563
1564
1565
1566 Ylonen & Lehtinen Expires April 1, 2002 [Page 28]
1567
1568 Internet-Draft SSH File Transfer Protocol October 2001
1569
1570
1571 Full Copyright Statement
1572
1573 Copyright (C) The Internet Society (2001). All Rights Reserved.
1574
1575 This document and translations of it may be copied and furnished to
1576 others, and derivative works that comment on or otherwise explain it
1577 or assist in its implementation may be prepared, copied, published
1578 and distributed, in whole or in part, without restriction of any
1579 kind, provided that the above copyright notice and this paragraph are
1580 included on all such copies and derivative works. However, this
1581 document itself may not be modified in any way, such as by removing
1582 the copyright notice or references to the Internet Society or other
1583 Internet organizations, except as needed for the purpose of
1584 developing Internet standards in which case the procedures for
1585 copyrights defined in the Internet Standards process must be
1586 followed, or as required to translate it into languages other than
1587 English.
1588
1589 The limited permissions granted above are perpetual and will not be
1590 revoked by the Internet Society or its successors or assigns.
1591
1592 This document and the information contained herein is provided on an
1593 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1594 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1595 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1596 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1597 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1598
1599 Acknowledgement
1600
1601 Funding for the RFC Editor function is currently provided by the
1602 Internet Society.
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622 Ylonen & Lehtinen Expires April 1, 2002 [Page 29]
1623
1624
1625
+1962
-0
rfc/draft-ietf-secsh-filexfer-03.txt less more
0
1
2
3 Secure Shell Working Group J. Galbraith
4 Internet-Draft VanDyke Software
5 Expires: April 16, 2003 T. Ylonen
6 S. Lehtinen
7 SSH Communications Security Corp
8 October 16, 2002
9
10
11 SSH File Transfer Protocol
12 draft-ietf-secsh-filexfer-03.txt
13
14 Status of this Memo
15
16 This document is an Internet-Draft and is in full conformance with
17 all provisions of Section 10 of RFC2026.
18
19 Internet-Drafts are working documents of the Internet Engineering
20 Task Force (IETF), its areas, and its working groups. Note that
21 other groups may also distribute working documents as Internet-
22 Drafts.
23
24 Internet-Drafts are draft documents valid for a maximum of six months
25 and may be updated, replaced, or obsoleted by other documents at any
26 time. It is inappropriate to use Internet-Drafts as reference
27 material or to cite them other than as "work in progress."
28
29 The list of current Internet-Drafts can be accessed at http://
30 www.ietf.org/ietf/1id-abstracts.txt.
31
32 The list of Internet-Draft Shadow Directories can be accessed at
33 http://www.ietf.org/shadow.html.
34
35 This Internet-Draft will expire on April 16, 2003.
36
37 Copyright Notice
38
39 Copyright (C) The Internet Society (2002). All Rights Reserved.
40
41 Abstract
42
43 The SSH File Transfer Protocol provides secure file transfer
44 functionality over any reliable data stream. It is the standard file
45 transfer protocol for use with the SSH2 protocol. This document
46 describes the file transfer protocol and its interface to the SSH2
47 protocol suite.
48
49
50
51
52
53
54
55 Galbraith, et al. Expires April 16, 2003 [Page 1]
56
57 Internet-Draft SSH File Transfer Protocol October 2002
58
59
60 Table of Contents
61
62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3
63 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4
64 3. General Packet Format . . . . . . . . . . . . . . . . . . 5
65 4. Protocol Initialization . . . . . . . . . . . . . . . . . 7
66 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 7
67 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 7
68 4.3 Determining Server Newline Convention . . . . . . . . . . 8
69 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 9
70 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9
71 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
72 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
73 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 10
74 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 11
75 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 11
76 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
77 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 12
78 6. Requests From the Client to the Server . . . . . . . . . . 13
79 6.1 Request Synchronization and Reordering . . . . . . . . . . 13
80 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 14
81 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 14
82 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 17
83 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 18
84 6.6 Creating and Deleting Directories . . . . . . . . . . . . 19
85 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 19
86 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 20
87 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 21
88 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 22
89 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 23
90 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 23
91 7. Responses from the Server to the Client . . . . . . . . . 24
92 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 28
93 9. Security Considerations . . . . . . . . . . . . . . . . . 29
94 10. Changes from previous protocol versions . . . . . . . . . 30
95 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 30
96 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 31
97 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 31
98 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 31
99 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 32
100 References . . . . . . . . . . . . . . . . . . . . . . . . 33
101 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 33
102 Full Copyright Statement . . . . . . . . . . . . . . . . . 35
103
104
105
106
107
108
109
110
111 Galbraith, et al. Expires April 16, 2003 [Page 2]
112
113 Internet-Draft SSH File Transfer Protocol October 2002
114
115
116 1. Introduction
117
118 This protocol provides secure file transfer (and more generally file
119 system access) functionality over a reliable data stream, such as a
120 channel in the SSH2 protocol [5].
121
122 This protocol is designed so that it could be used to implement a
123 secure remote file system service, as well as a secure file transfer
124 service.
125
126 This protocol assumes that it runs over a secure channel, and that
127 the server has already authenticated the user at the client end, and
128 that the identity of the client user is externally available to the
129 server implementation.
130
131 In general, this protocol follows a simple request-response model.
132 Each request and response contains a sequence number and multiple
133 requests may be pending simultaneously. There are a relatively large
134 number of different request messages, but a small number of possible
135 response messages. Each request has one or more response messages
136 that may be returned in result (e.g., a read either returns data or
137 reports error status).
138
139 The packet format descriptions in this specification follow the
140 notation presented in the secsh architecture draft. [5]
141
142 Even though this protocol is described in the context of the SSH2
143 protocol, this protocol is general and independent of the rest of the
144 SSH2 protocol suite. It could be used in a number of different
145 applications, such as secure file transfer over TLS RFC 2246 [1] and
146 transfer of management information in VPN applications.
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167 Galbraith, et al. Expires April 16, 2003 [Page 3]
168
169 Internet-Draft SSH File Transfer Protocol October 2002
170
171
172 2. Use with the SSH Connection Protocol
173
174 When used with the SSH2 Protocol suite, this protocol is intended to
175 be used from the SSH Connection Protocol [7] as a subsystem, as
176 described in section ``Starting a Shell or a Command''. The
177 subsystem name used with this protocol is "sftp".
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223 Galbraith, et al. Expires April 16, 2003 [Page 4]
224
225 Internet-Draft SSH File Transfer Protocol October 2002
226
227
228 3. General Packet Format
229
230 All packets transmitted over the secure connection are of the
231 following format:
232
233 uint32 length
234 byte type
235 byte[length - 1] data payload
236
237 That is, they are just data preceded by 32-bit length and 8-bit type
238 fields. The `length' is the length of the data area, and does not
239 include the `length' field itself. The format and interpretation of
240 the data area depends on the packet type.
241
242 All packet descriptions below only specify the packet type and the
243 data that goes into the data field. Thus, they should be prefixed by
244 the `length' and `type' fields.
245
246 The maximum size of a packet is in practice determined by the client
247 (the maximum size of read or write requests that it sends, plus a few
248 bytes of packet overhead). All servers SHOULD support packets of at
249 least 34000 bytes (where the packet size refers to the full length,
250 including the header above). This should allow for reads and writes
251 of at most 32768 bytes.
252
253 There is no limit on the number of outstanding (non-acknowledged)
254 requests that the client may send to the server. In practice this is
255 limited by the buffering available on the data stream and the queuing
256 performed by the server. If the server's queues are full, it should
257 not read any more data from the stream, and flow control will prevent
258 the client from sending more requests. Note, however, that while
259 there is no restriction on the protocol level, the client's API may
260 provide a limit in order to prevent infinite queuing of outgoing
261 requests at the client.
262
263 The following values are defined for packet types.
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279 Galbraith, et al. Expires April 16, 2003 [Page 5]
280
281 Internet-Draft SSH File Transfer Protocol October 2002
282
283
284 #define SSH_FXP_INIT 1
285 #define SSH_FXP_VERSION 2
286 #define SSH_FXP_OPEN 3
287 #define SSH_FXP_CLOSE 4
288 #define SSH_FXP_READ 5
289 #define SSH_FXP_WRITE 6
290 #define SSH_FXP_LSTAT 7
291 #define SSH_FXP_FSTAT 8
292 #define SSH_FXP_SETSTAT 9
293 #define SSH_FXP_FSETSTAT 10
294 #define SSH_FXP_OPENDIR 11
295 #define SSH_FXP_READDIR 12
296 #define SSH_FXP_REMOVE 13
297 #define SSH_FXP_MKDIR 14
298 #define SSH_FXP_RMDIR 15
299 #define SSH_FXP_REALPATH 16
300 #define SSH_FXP_STAT 17
301 #define SSH_FXP_RENAME 18
302 #define SSH_FXP_READLINK 19
303 #define SSH_FXP_SYMLINK 20
304
305 #define SSH_FXP_STATUS 101
306 #define SSH_FXP_HANDLE 102
307 #define SSH_FXP_DATA 103
308 #define SSH_FXP_NAME 104
309 #define SSH_FXP_ATTRS 105
310
311 #define SSH_FXP_EXTENDED 200
312 #define SSH_FXP_EXTENDED_REPLY 201
313
314 RESERVED_FOR_EXTENSIONS 210-255
315
316 Additional packet types should only be defined if the protocol
317 version number (see Section ``Protocol Initialization'') is
318 incremented, and their use MUST be negotiated using the version
319 number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY
320 packets can be used to implement vendor-specific extensions. See
321 Section ``Vendor-Specific-Extensions'' for more details.
322
323
324
325
326
327
328
329
330
331
332
333
334
335 Galbraith, et al. Expires April 16, 2003 [Page 6]
336
337 Internet-Draft SSH File Transfer Protocol October 2002
338
339
340 4. Protocol Initialization
341
342 When the file transfer protocol starts, the client first sends a
343 SSH_FXP_INIT (including its version number) packet to the server.
344 The server responds with a SSH_FXP_VERSION packet, supplying the
345 lowest of its own and the client's version number. Both parties
346 should from then on adhere to particular version of the protocol.
347
348 The version number of the protocol specified in this document is 4.
349 The version number should be incremented for each incompatible
350 revision of this protocol.
351
352 4.1 Client Initialization
353
354 The SSH_FXP_INIT packet (from client to server) has the following
355 data:
356
357 uint32 version
358
359 Version 3 of this protocol allowed clients to include extensions in
360 the SSH_FXP_INIT packet; however, this can cause interoperability
361 problems with version 1 and version 2 servers because the client must
362 send this packet before knowing the servers version.
363
364 In this version of the protocol, clients MUST use the
365 SSH_FXP_EXTENDED packet to send extensions to the server after
366 version exchange has completed. Clients MUST NOT include extensions
367 in the version packet. This will prevent interoperability problems
368 with older servers
369
370 4.2 Server Initialization
371
372 The SSH_FXP_VERSION packet (from server to client) has the following
373 data:
374
375 uint32 version
376 <extension data>
377
378 'version' is the lower of the protocol version supported by the
379 server and the version number received from the client.
380
381 The extension data may be empty, or may be a sequence of
382
383 string extension_name
384 string extension_data
385
386 pairs (both strings MUST always be present if one is, but the
387 `extension_data' string may be of zero length). If present, these
388
389
390
391 Galbraith, et al. Expires April 16, 2003 [Page 7]
392
393 Internet-Draft SSH File Transfer Protocol October 2002
394
395
396 strings indicate extensions to the baseline protocol. The
397 `extension_name' field(s) identify the name of the extension. The
398 name should be of the form "name@domain", where the domain is the DNS
399 domain name of the organization defining the extension. Additional
400 names that are not of this format may be defined later by the IETF.
401 Implementations MUST silently ignore any extensions whose name they
402 do not recognize.
403
404 4.3 Determining Server Newline Convention
405
406 In order to correctly process text files in a cross platform
407 compatible way, the newline convention must be converted from that of
408 the server to that of the client, or, during an upload, from that of
409 the client to that of the server.
410
411 Versions 3 and prior of this protocol made no provisions for
412 processing text files. Many clients implemented some sort of
413 conversion algorithm, but without either a 'canonical' on the wire
414 format or knowledge of the servers newline convention, correct
415 conversion was not always possible.
416
417 Starting with Version 4, the SSH_FXF_TEXT file open flag (Section
418 6.3) makes it possible to request that the server translate a file to
419 a 'canonical' on the wire format. This format uses \r\n as the line
420 separator.
421
422 Servers for systems using multiple newline characters (for example,
423 Mac OS X or VMS) or systems using counted records, MUST translate to
424 the canonical form.
425
426 However, to ease the burden of implementation on servers that use a
427 single, simple separator sequence, the following extension allows the
428 canonical format to be changed.
429
430 string "newline"
431 string new-canonical-separator (usually "\r" or "\n" or "\r\n")
432
433 All clients MUST support this extension.
434
435 When processing text files, clients SHOULD NOT translate any
436 character or sequence that is not an exact match of the servers
437 newline separator.
438
439 In particular, if the newline sequence being used is the canonical
440 "\r\n" sequence, a lone \r or a lone \n SHOULD be written through
441 without change.
442
443
444
445
446
447 Galbraith, et al. Expires April 16, 2003 [Page 8]
448
449 Internet-Draft SSH File Transfer Protocol October 2002
450
451
452 5. File Attributes
453
454 A new compound data type is defined for encoding file attributes.
455 The same encoding is used both when returning file attributes from
456 the server and when sending file attributes to the server. When
457 sending it to the server, the flags field specifies which attributes
458 are included, and the server will use default values for the
459 remaining attributes (or will not modify the values of remaining
460 attributes). When receiving attributes from the server, the flags
461 specify which attributes are included in the returned data. The
462 server normally returns all attributes it knows about.
463
464 uint32 flags
465 byte type always present
466 uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE
467 string owner present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
468 string group present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
469 uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
470 uint32 atime present only if flag SSH_FILEXFER_ATTR_ACCESSTIME
471 uint32 createtime present only if flag SSH_FILEXFER_ATTR_CREATETIME
472 uint32 mtime present only if flag SSH_FILEXFER_ATTR_MODIFYTIME
473 string acl present only if flag SSH_FILEXFER_ATTR_ACL
474 uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
475 string extended_type
476 string extended_data
477 ... more extended data (extended_type - extended_data pairs),
478 so that number of pairs equals extended_count
479
480
481 5.1 Flags
482
483 The `flags' specify which of the fields are present. Those fields
484 for which the corresponding flag is not set are not present (not
485 included in the packet). New flags can only be added by incrementing
486 the protocol version number (or by using the extension mechanism
487 described below).
488
489 The flags bits are defined to have the following values:
490
491 #define SSH_FILEXFER_ATTR_SIZE 0x00000001
492 #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
493 #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
494 #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010
495 #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
496 #define SSH_FILEXFER_ATTR_ACL 0x00000040
497 #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
498 #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000
499
500
501
502
503 Galbraith, et al. Expires April 16, 2003 [Page 9]
504
505 Internet-Draft SSH File Transfer Protocol October 2002
506
507
508 In previous versions of this protocol flags value 0x00000002 was
509 SSH_FILEXFER_ATTR_UIDGID. This value is now unused, and OWNERGROUP
510 was given a new value in order to ease implementation burden.
511 0x00000002 MUST NOT appear in the mask. Some future version of this
512 protocol may reuse flag 0x00000002.
513
514 5.2 Type
515
516 The type field is always present. The following types are defined:
517
518 #define SSH_FILEXFER_TYPE_REGULAR 1
519 #define SSH_FILEXFER_TYPE_DIRECTORY 2
520 #define SSH_FILEXFER_TYPE_SYMLINK 3
521 #define SSH_FILEXFER_TYPE_SPECIAL 4
522 #define SSH_FILEXFER_TYPE_UNKNOWN 5
523
524 On a POSIX system, these values would be derived from the permission
525 field.
526
527 5.3 Size
528
529 The `size' field specifies the size of the file on disk, in bytes.
530 If it is present during file creation, it should be considered a hint
531 as to the files eventual size.
532
533 Files opened with the SSH_FXF_TEXT flag may have a size that is
534 greater or less than the value of the size field.
535
536 5.4 Owner and Group
537
538 The `owner' and `group' fields are represented as UTF-8 strings; this
539 is the form used by NFS v4. See NFS version 4 Protocol. [3] The
540 following text is selected quotations from section 5.6.
541
542 To avoid a representation that is tied to a particular underlying
543 implementation at the client or server, the use of UTF-8 strings has
544 been chosen. The string should be of the form user@dns_domain".
545 This will allow for a client and server that do not use the same
546 local representation the ability to translate to a common syntax that
547 can be interpreted by both. In the case where there is no
548 translation available to the client or server, the attribute value
549 must be constructed without the "@". Therefore, the absence of the @
550 from the owner or owner_group attribute signifies that no translation
551 was available and the receiver of the attribute should not place any
552 special meaning with the attribute value. Even though the attribute
553 value can not be translated, it may still be useful. In the case of
554 a client, the attribute string may be used for local display of
555 ownership.
556
557
558
559 Galbraith, et al. Expires April 16, 2003 [Page 10]
560
561 Internet-Draft SSH File Transfer Protocol October 2002
562
563
564 5.5 Permissions
565
566 The `permissions' field contains a bit mask of file permissions as
567 defined by POSIX [1].
568
569 5.6 Times
570
571 The 'atime', 'createtime', and 'mtime' contain the access, creation,
572 and modification times of the files, respectively. They are
573 represented as seconds from Jan 1, 1970 in UTC.
574
575 5.7 ACL
576
577 The 'ACL' field contains an ACL similar to that defined in section
578 5.9 of NFS version 4 Protocol [3].
579
580 uint32 ace-count
581
582 repeated ace-count time:
583 uint32 ace-type
584 uint32 ace-flag
585 uint32 ace-mask
586 string who [UTF-8]
587
588 ace-type is one of the following four values (taken from NFS Version
589 4 Protocol [3]:
590
591 const ACE4_ACCESS_ALLOWED_ACE_TYPE = 0x00000000;
592 const ACE4_ACCESS_DENIED_ACE_TYPE = 0x00000001;
593 const ACE4_SYSTEM_AUDIT_ACE_TYPE = 0x00000002;
594 const ACE4_SYSTEM_ALARM_ACE_TYPE = 0x00000003;
595
596 ace-flag is a combination of the following flag values. See NFS
597 Version 4 Protocol [3] section 5.9.2:
598
599 const ACE4_FILE_INHERIT_ACE = 0x00000001;
600 const ACE4_DIRECTORY_INHERIT_ACE = 0x00000002;
601 const ACE4_NO_PROPAGATE_INHERIT_ACE = 0x00000004;
602 const ACE4_INHERIT_ONLY_ACE = 0x00000008;
603 const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG = 0x00000010;
604 const ACE4_FAILED_ACCESS_ACE_FLAG = 0x00000020;
605 const ACE4_IDENTIFIER_GROUP = 0x00000040;
606
607 ace-mask is any combination of the following flags (taken from NFS
608 Version 4 Protocol [3] section 5.9.3:
609
610
611
612
613
614
615 Galbraith, et al. Expires April 16, 2003 [Page 11]
616
617 Internet-Draft SSH File Transfer Protocol October 2002
618
619
620 const ACE4_READ_DATA = 0x00000001;
621 const ACE4_LIST_DIRECTORY = 0x00000001;
622 const ACE4_WRITE_DATA = 0x00000002;
623 const ACE4_ADD_FILE = 0x00000002;
624 const ACE4_APPEND_DATA = 0x00000004;
625 const ACE4_ADD_SUBDIRECTORY = 0x00000004;
626 const ACE4_READ_NAMED_ATTRS = 0x00000008;
627 const ACE4_WRITE_NAMED_ATTRS = 0x00000010;
628 const ACE4_EXECUTE = 0x00000020;
629 const ACE4_DELETE_CHILD = 0x00000040;
630 const ACE4_READ_ATTRIBUTES = 0x00000080;
631 const ACE4_WRITE_ATTRIBUTES = 0x00000100;
632 const ACE4_DELETE = 0x00010000;
633 const ACE4_READ_ACL = 0x00020000;
634 const ACE4_WRITE_ACL = 0x00040000;
635 const ACE4_WRITE_OWNER = 0x00080000;
636 const ACE4_SYNCHRONIZE = 0x00100000;
637
638 who is a UTF-8 string of the form described in 'Owner and Group'
639 (Section 5.4)
640
641 5.8 Extended attributes
642
643 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
644 mechanism for vendor-specific extensions. If the flag is specified,
645 then the `extended_count' field is present. It specifies the number
646 of extended_type-extended_data pairs that follow. Each of these
647 pairs specifies an extended attribute. For each of the attributes,
648 the extended_type field should be a string of the format
649 "name@domain", where "domain" is a valid, registered domain name and
650 "name" identifies the method. The IETF may later standardize certain
651 names that deviate from this format (e.g., that do not contain the
652 "@" sign). The interpretation of `extended_data' depends on the
653 type. Implementations SHOULD ignore extended data fields that they
654 do not understand.
655
656 Additional fields can be added to the attributes by either defining
657 additional bits to the flags field to indicate their presence, or by
658 defining extended attributes for them. The extended attributes
659 mechanism is recommended for most purposes; additional flags bits
660 should only be defined by an IETF standards action that also
661 increments the protocol version number. The use of such new fields
662 MUST be negotiated by the version number in the protocol exchange.
663 It is a protocol error if a packet with unsupported protocol bits is
664 received.
665
666
667
668
669
670
671 Galbraith, et al. Expires April 16, 2003 [Page 12]
672
673 Internet-Draft SSH File Transfer Protocol October 2002
674
675
676 6. Requests From the Client to the Server
677
678 Requests from the client to the server represent the various file
679 system operations. Each request begins with an `id' field, which is
680 a 32-bit identifier identifying the request (selected by the client).
681 The same identifier will be returned in the response to the request.
682 One possible implementation is a monotonically increasing request
683 sequence number (modulo 2^32).
684
685 Many operations in the protocol operate on open files. The
686 SSH_FXP_OPEN request can return a file handle (which is an opaque
687 variable-length string) which may be used to access the file later
688 (e.g. in a read operation). The client MUST NOT send requests the
689 server with bogus or closed handles. However, the server MUST
690 perform adequate checks on the handle in order to avoid security
691 risks due to fabricated handles.
692
693 This design allows either stateful and stateless server
694 implementation, as well as an implementation which caches state
695 between requests but may also flush it. The contents of the file
696 handle string are entirely up to the server and its design. The
697 client should not modify or attempt to interpret the file handle
698 strings.
699
700 The file handle strings MUST NOT be longer than 256 bytes.
701
702 6.1 Request Synchronization and Reordering
703
704 The protocol and implementations MUST process requests relating to
705 the same file in the order in which they are received. In other
706 words, if an application submits multiple requests to the server, the
707 results in the responses will be the same as if it had sent the
708 requests one at a time and waited for the response in each case. For
709 example, the server may process non-overlapping read/write requests
710 to the same file in parallel, but overlapping reads and writes cannot
711 be reordered or parallelized. However, there are no ordering
712 restrictions on the server for processing requests from two different
713 file transfer connections. The server may interleave and parallelize
714 them at will.
715
716 There are no restrictions on the order in which responses to
717 outstanding requests are delivered to the client, except that the
718 server must ensure fairness in the sense that processing of no
719 request will be indefinitely delayed even if the client is sending
720 other requests so that there are multiple outstanding requests all
721 the time.
722
723
724
725
726
727 Galbraith, et al. Expires April 16, 2003 [Page 13]
728
729 Internet-Draft SSH File Transfer Protocol October 2002
730
731
732 6.2 File Names
733
734 This protocol represents file names as strings. File names are
735 assumed to use the slash ('/') character as a directory separator.
736
737 File names starting with a slash are "absolute", and are relative to
738 the root of the file system. Names starting with any other character
739 are relative to the user's default directory (home directory). Note
740 that identifying the user is assumed to take place outside of this
741 protocol.
742
743 Servers SHOULD interpret a path name component ".." as referring to
744 the parent directory, and "." as referring to the current directory.
745 If the server implementation limits access to certain parts of the
746 file system, it must be extra careful in parsing file names when
747 enforcing such restrictions. There have been numerous reported
748 security bugs where a ".." in a path name has allowed access outside
749 the intended area.
750
751 An empty path name is valid, and it refers to the user's default
752 directory (usually the user's home directory).
753
754 Otherwise, no syntax is defined for file names by this specification.
755 Clients should not make any other assumptions; however, they can
756 splice path name components returned by SSH_FXP_READDIR together
757 using a slash ('/') as the separator, and that will work as expected.
758
759 In order to comply with IETF Policy on Character Sets and Languages
760 [2], all filenames are to be encoded in UTF-8. The shortest valid
761 UTF-8 encoding of the UNICODE data MUST be used. The server is
762 responsible for converting the UNICODE data to whatever canonical
763 form it requires.
764
765 For example, if the server requires that precomposed characters
766 always be used, the server MUST NOT assume the filename as sent by
767 the client has this attribute, but must do this normalization itself.
768
769 It is understood that the lack of well-defined semantics for file
770 names may cause interoperability problems between clients and servers
771 using radically different operating systems. However, this approach
772 is known to work acceptably with most systems, and alternative
773 approaches that e.g. treat file names as sequences of structured
774 components are quite complicated.
775
776 6.3 Opening, Creating, and Closing Files
777
778 Files are opened and created using the SSH_FXP_OPEN message, whose
779 data part is as follows:
780
781
782
783 Galbraith, et al. Expires April 16, 2003 [Page 14]
784
785 Internet-Draft SSH File Transfer Protocol October 2002
786
787
788 uint32 id
789 string filename [UTF-8]
790 uint32 pflags
791 ATTRS attrs
792
793 The `id' field is the request identifier as for all requests.
794
795 The `filename' field specifies the file name. See Section ``File
796 Names'' for more information.
797
798 The `pflags' field is a bitmask. The following bits have been
799 defined.
800
801 #define SSH_FXF_READ 0x00000001
802 #define SSH_FXF_WRITE 0x00000002
803 #define SSH_FXF_APPEND 0x00000004
804 #define SSH_FXF_CREAT 0x00000008
805 #define SSH_FXF_TRUNC 0x00000010
806 #define SSH_FXF_EXCL 0x00000020
807 #define SSH_FXF_TEXT 0x00000040
808
809 These have the following meanings:
810
811 SSH_FXF_READ
812 Open the file for reading.
813
814 SSH_FXF_WRITE
815 Open the file for writing. If both this and SSH_FXF_READ are
816 specified, the file is opened for both reading and writing.
817
818 SSH_FXF_APPEND
819 Force all writes to append data at the end of the file. The
820 offset parameter to write will be ignored.
821
822 SSH_FXF_CREAT
823 If this flag is specified, then a new file will be created if one
824 does not already exist (if O_TRUNC is specified, the new file will
825 be truncated to zero length if it previously exists).
826
827 SSH_FXF_TRUNC
828 Forces an existing file with the same name to be truncated to zero
829 length when creating a file by specifying SSH_FXF_CREAT.
830 SSH_FXF_CREAT MUST also be specified if this flag is used.
831
832 SSH_FXF_EXCL
833 Causes the request to fail if the named file already exists.
834 SSH_FXF_CREAT MUST also be specified if this flag is used.
835
836
837
838
839 Galbraith, et al. Expires April 16, 2003 [Page 15]
840
841 Internet-Draft SSH File Transfer Protocol October 2002
842
843
844 SSH_FXF_TEXT
845 Indicates that the server should treat the file as text and
846 convert it to the canonical newline convention in use. (See
847 Determining Server Newline Convention. (Section 4.3)
848
849 When a file is opened with the FXF_TEXT flag, the offset field in
850 both the read and write function are ignored.
851
852 Servers MUST correctly process multiple parallel reads and writes
853 correctly in this mode. Naturally, it is permissible for them to
854 do this by serializing the requests. It would not be possible for
855 a client to reliably detect a server that does not implement
856 parallel writes in time to prevent damage.
857
858 Clients SHOULD use the SSH_FXF_APPEND flag to append data to a
859 text file rather then using write with a calculated offset.
860
861 To support seeks on text file the following SSH_FXP_EXTENDED
862 packet is defined.
863
864
865
866 string "text-seek"
867 string file-handle
868 uint64 line-number
869
870 line-number is the index of the line number to seek to, where byte
871 0 in the file is line number 0, and the byte directly following
872 the first newline sequence in the file is line number 1 and so on.
873
874 The response to a "text-seek" request is an SSH_FXP_STATUS
875 message.
876
877 An attempt to seek past the end-of-file should result in a
878 SSH_FX_EOF status.
879
880 Servers SHOULD support at least one "text-seek" in order to
881 support resume. However, a client MUST be prepared to receive
882 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
883 The client can then try a fall-back strategy, if it has one.
884
885 Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
886 for read or write operations that are not sequential.
887
888 The `attrs' field specifies the initial attributes for the file.
889 Default values will be used for those attributes that are not
890 specified. See Section ``File Attributes'' for more information.
891
892
893
894
895 Galbraith, et al. Expires April 16, 2003 [Page 16]
896
897 Internet-Draft SSH File Transfer Protocol October 2002
898
899
900 The response to this message will be either SSH_FXP_HANDLE (if the
901 operation is successful) or SSH_FXP_STATUS (if the operation fails).
902
903 A file is closed by using the SSH_FXP_CLOSE request. Its data field
904 has the following format:
905
906 uint32 id
907 string handle
908
909 where `id' is the request identifier, and `handle' is a handle
910 previously returned in the response to SSH_FXP_OPEN or
911 SSH_FXP_OPENDIR. The handle becomes invalid immediately after this
912 request has been sent.
913
914 The response to this request will be a SSH_FXP_STATUS message. One
915 should note that on some server platforms even a close can fail.
916 This can happen e.g. if the server operating system caches writes,
917 and an error occurs while flushing cached writes during the close.
918
919 6.4 Reading and Writing
920
921 Once a file has been opened, it can be read using the SSH_FXP_READ
922 message, which has the following format:
923
924 uint32 id
925 string handle
926 uint64 offset
927 uint32 len
928
929 where `id' is the request identifier, `handle' is an open file handle
930 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
931 to the beginning of the file from where to start reading, and `len'
932 is the maximum number of bytes to read.
933
934 In response to this request, the server will read as many bytes as it
935 can from the file (up to `len'), and return them in a SSH_FXP_DATA
936 message. If an error occurs or EOF is encountered before reading any
937 data, the server will respond with SSH_FXP_STATUS. For normal disk
938 files, it is guaranteed that this will read the specified number of
939 bytes, or up to end of file. For e.g. device files this may return
940 fewer bytes than requested.
941
942 Writing to a file is achieved using the SSH_FXP_WRITE message, which
943 has the following format:
944
945
946
947
948
949
950
951 Galbraith, et al. Expires April 16, 2003 [Page 17]
952
953 Internet-Draft SSH File Transfer Protocol October 2002
954
955
956 uint32 id
957 string handle
958 uint64 offset
959 string data
960
961 where `id' is a request identifier, `handle' is a file handle
962 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
963 beginning of the file where to start writing, and `data' is the data
964 to be written.
965
966 The write will extend the file if writing beyond the end of the file.
967 It is legal to write way beyond the end of the file; the semantics
968 are to write zeroes from the end of the file to the specified offset
969 and then the data. On most operating systems, such writes do not
970 allocate disk space but instead leave "holes" in the file.
971
972 The server responds to a write request with a SSH_FXP_STATUS message.
973
974 6.5 Removing and Renaming Files
975
976 Files can be removed using the SSH_FXP_REMOVE message. It has the
977 following format:
978
979 uint32 id
980 string filename [UTF-8]
981
982 where `id' is the request identifier and `filename' is the name of
983 the file to be removed. See Section ``File Names'' for more
984 information. This request cannot be used to remove directories.
985
986 The server will respond to this request with a SSH_FXP_STATUS
987 message.
988
989 Files (and directories) can be renamed using the SSH_FXP_RENAME
990 message. Its data is as follows:
991
992 uint32 id
993 string oldpath [UTF-8]
994 string newpath [UTF-8]
995
996 where `id' is the request identifier, `oldpath' is the name of an
997 existing file or directory, and `newpath' is the new name for the
998 file or directory. It is an error if there already exists a file
999 with the name specified by newpath. The server may also fail rename
1000 requests in other situations, for example if `oldpath' and `newpath'
1001 point to different file systems on the server.
1002
1003 The server will respond to this request with a SSH_FXP_STATUS
1004
1005
1006
1007 Galbraith, et al. Expires April 16, 2003 [Page 18]
1008
1009 Internet-Draft SSH File Transfer Protocol October 2002
1010
1011
1012 message.
1013
1014 6.6 Creating and Deleting Directories
1015
1016 New directories can be created using the SSH_FXP_MKDIR request. It
1017 has the following format:
1018
1019 uint32 id
1020 string path [UTF-8]
1021 ATTRS attrs
1022
1023 where `id' is the request identifier.
1024
1025 `path' specifies the directory to be created. See Section ``File
1026 Names'' for more information on file names.
1027
1028 `attrs' specifies the attributes that should be applied to it upon
1029 creation. Attributes are discussed in more detail in Section ``File
1030 Attributes''.
1031
1032 The server will respond to this request with a SSH_FXP_STATUS
1033 message. If a file or directory with the specified path already
1034 exists, an error will be returned.
1035
1036 Directories can be removed using the SSH_FXP_RMDIR request, which has
1037 the following format:
1038
1039 uint32 id
1040 string path [UTF-8]
1041
1042 where `id' is the request identifier, and `path' specifies the
1043 directory to be removed. See Section ``File Names'' for more
1044 information on file names.
1045
1046 The server responds to this request with a SSH_FXP_STATUS message.
1047 Errors may be returned from this operation for various reasons,
1048 including, but not limited to, the path does not exist, the path does
1049 not refer to a directory object, the directory is not empty, or the
1050 user has insufficient access or permission to perform the requested
1051 operation.
1052
1053 6.7 Scanning Directories
1054
1055 The files in a directory can be listed using the SSH_FXP_OPENDIR and
1056 SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one
1057 or more file names with full file attributes for each file. The
1058 client should call SSH_FXP_READDIR repeatedly until it has found the
1059 file it is looking for or until the server responds with a
1060
1061
1062
1063 Galbraith, et al. Expires April 16, 2003 [Page 19]
1064
1065 Internet-Draft SSH File Transfer Protocol October 2002
1066
1067
1068 SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
1069 there are no more files in the directory). The client should then
1070 close the handle using the SSH_FXP_CLOSE request.
1071
1072 The SSH_FXP_OPENDIR opens a directory for reading. It has the
1073 following format:
1074
1075 uint32 id
1076 string path [UTF-8]
1077
1078 where `id' is the request identifier and `path' is the path name of
1079 the directory to be listed (without any trailing slash). See Section
1080 ``File Names'' for more information on file names. This will return
1081 an error if the path does not specify a directory or if the directory
1082 is not readable. The server will respond to this request with either
1083 a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.
1084
1085 Once the directory has been successfully opened, files (and
1086 directories) contained in it can be listed using SSH_FXP_READDIR
1087 requests. These are of the format
1088
1089 uint32 id
1090 string handle
1091
1092 where `id' is the request identifier, and `handle' is a handle
1093 returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to
1094 use an ordinary file handle returned by SSH_FXP_OPEN.)
1095
1096 The server responds to this request with either a SSH_FXP_NAME or a
1097 SSH_FXP_STATUS message. One or more names may be returned at a time.
1098 Full status information is returned for each name in order to speed
1099 up typical directory listings.
1100
1101 If there are no more names available to be read, the server MUST
1102 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
1103
1104 When the client no longer wishes to read more names from the
1105 directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle
1106 should be closed regardless of whether an error has occurred or not.
1107
1108 6.8 Retrieving File Attributes
1109
1110 Very often, file attributes are automatically returned by
1111 SSH_FXP_READDIR. However, sometimes there is need to specifically
1112 retrieve the attributes for a named file. This can be done using the
1113 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
1114
1115 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
1116
1117
1118
1119 Galbraith, et al. Expires April 16, 2003 [Page 20]
1120
1121 Internet-Draft SSH File Transfer Protocol October 2002
1122
1123
1124 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
1125 follow symbolic links. Both have the same format:
1126
1127 uint32 id
1128 string path [UTF-8]
1129 uint32 flags
1130
1131 where `id' is the request identifier, and `path' specifies the file
1132 system object for which status is to be returned. The server
1133 responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS.
1134
1135 The flags field specify the attribute flags in which the client has
1136 particular interest. This is a hint to the server. For example,
1137 because retrieving owner / group and acl information can be an
1138 expensive operation under some operating systems, the server may
1139 choose not to retrieve this information unless the client expresses a
1140 specific interest in it.
1141
1142 The client has no guarantee the server will provide all the fields
1143 that it has expressed an interest in.
1144
1145 SSH_FXP_FSTAT differs from the others in that it returns status
1146 information for an open file (identified by the file handle). Its
1147 format is as follows:
1148
1149 uint32 id
1150 string handle
1151 uint32 flags
1152
1153 where `id' is the request identifier and `handle' is a file handle
1154 returned by SSH_FXP_OPEN. The server responds to this request with
1155 SSH_FXP_ATTRS or SSH_FXP_STATUS.
1156
1157 6.9 Setting File Attributes
1158
1159 File attributes may be modified using the SSH_FXP_SETSTAT and
1160 SSH_FXP_FSETSTAT requests. These requests are used for operations
1161 such as changing the ownership, permissions or access times, as well
1162 as for truncating a file.
1163
1164 The SSH_FXP_SETSTAT request is of the following format:
1165
1166 uint32 id
1167 string path [UTF-8]
1168 ATTRS attrs
1169
1170 where `id' is the request identifier, `path' specifies the file
1171 system object (e.g. file or directory) whose attributes are to be
1172
1173
1174
1175 Galbraith, et al. Expires April 16, 2003 [Page 21]
1176
1177 Internet-Draft SSH File Transfer Protocol October 2002
1178
1179
1180 modified, and `attrs' specifies the modifications to be made to its
1181 attributes. Attributes are discussed in more detail in Section
1182 ``File Attributes''.
1183
1184 An error will be returned if the specified file system object does
1185 not exist or the user does not have sufficient rights to modify the
1186 specified attributes. The server responds to this request with a
1187 SSH_FXP_STATUS message.
1188
1189 The SSH_FXP_FSETSTAT request modifies the attributes of a file which
1190 is already open. It has the following format:
1191
1192 uint32 id
1193 string handle
1194 ATTRS attrs
1195
1196 where `id' is the request identifier, `handle' (MUST be returned by
1197 SSH_FXP_OPEN) identifies the file whose attributes are to be
1198 modified, and `attrs' specifies the modifications to be made to its
1199 attributes. Attributes are discussed in more detail in Section
1200 ``File Attributes''. The server will respond to this request with
1201 SSH_FXP_STATUS.
1202
1203 6.10 Dealing with Symbolic links
1204
1205 The SSH_FXP_READLINK request may be used to read the target of a
1206 symbolic link. It would have a data part as follows:
1207
1208 uint32 id
1209 string path [UTF-8]
1210
1211 where `id' is the request identifier and `path' specifies the path
1212 name of the symlink to be read.
1213
1214 The server will respond with a SSH_FXP_NAME packet containing only
1215 one name and a dummy attributes value. The name in the returned
1216 packet contains the target of the link. If an error occurs, the
1217 server may respond with SSH_FXP_STATUS.
1218
1219 The SSH_FXP_SYMLINK request will create a symbolic link on the
1220 server. It is of the following format
1221
1222 uint32 id
1223 string linkpath [UTF-8]
1224 string targetpath [UTF-8]
1225
1226 where `id' is the request identifier, `linkpath' specifies the path
1227 name of the symlink to be created and `targetpath' specifies the
1228
1229
1230
1231 Galbraith, et al. Expires April 16, 2003 [Page 22]
1232
1233 Internet-Draft SSH File Transfer Protocol October 2002
1234
1235
1236 target of the symlink. The server shall respond with a
1237 SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
1238 condition.
1239
1240 6.11 Canonicalizing the Server-Side Path Name
1241
1242 The SSH_FXP_REALPATH request can be used to have the server
1243 canonicalize any given path name to an absolute path. This is useful
1244 for converting path names containing ".." components or relative
1245 pathnames without a leading slash into absolute paths. The format of
1246 the request is as follows:
1247
1248 uint32 id
1249 string path [UTF-8]
1250
1251 where `id' is the request identifier and `path' specifies the path
1252 name to be canonicalized. The server will respond with a
1253 SSH_FXP_NAME packet containing the name in canonical form and a dummy
1254 attributes value. If an error occurs, the server may also respond
1255 with SSH_FXP_STATUS.
1256
1257 6.11.1 Best practice for dealing with paths
1258
1259 The client SHOULD treat the results of SSH_FXP_REALPATH as a
1260 canonical absolute path, even if the path does not appear to be
1261 absolute. A client that use REALPATH(".") and treats the result as
1262 absolute, even if there is no leading slash, will continue to
1263 function correctly, even when talking to a Windows NT or VMS style
1264 system, where absolute paths may not begin with a slash.
1265
1266 For example, if the client wishes to change directory up, and the
1267 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
1268 "c:/x/y/z/..".
1269
1270 As a second example, if the client wishes to open the file "x.txt" in
1271 the current directory, and server has returned "dka100:/x/y/z" as the
1272 canonical path of the directory, the client SHOULD open "dka100:/x/y/
1273 z/x.txt"
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287 Galbraith, et al. Expires April 16, 2003 [Page 23]
1288
1289 Internet-Draft SSH File Transfer Protocol October 2002
1290
1291
1292 7. Responses from the Server to the Client
1293
1294 The server responds to the client using one of a few response
1295 packets. All requests can return a SSH_FXP_STATUS response upon
1296 failure. When the operation is successful, any of the responses may
1297 be returned (depending on the operation). If no data needs to be
1298 returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
1299 status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used
1300 to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
1301 requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
1302 SSH_FXP_NAME is used to return one or more file names from a
1303 SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
1304 used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
1305 SSH_FXP_FSTAT requests.
1306
1307 Exactly one response will be returned for each request. Each
1308 response packet contains a request identifier which can be used to
1309 match each response with the corresponding request. Note that it is
1310 legal to have several requests outstanding simultaneously, and the
1311 server is allowed to send responses to them in a different order from
1312 the order in which the requests were sent (the result of their
1313 execution, however, is guaranteed to be as if they had been processed
1314 one at a time in the order in which the requests were sent).
1315
1316 Response packets are of the same general format as request packets.
1317 Each response packet begins with the request identifier.
1318
1319 The format of the data portion of the SSH_FXP_STATUS response is as
1320 follows:
1321
1322 uint32 id
1323 uint32 error/status code
1324 string error message (ISO-10646 UTF-8 [RFC-2279])
1325 string language tag (as defined in [RFC-1766])
1326
1327 where `id' is the request identifier, and `error/status code'
1328 indicates the result of the requested operation. The value SSH_FX_OK
1329 indicates success, and all other values indicate failure.
1330
1331 Currently, the following values are defined (other values may be
1332 defined by future versions of this protocol):
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343 Galbraith, et al. Expires April 16, 2003 [Page 24]
1344
1345 Internet-Draft SSH File Transfer Protocol October 2002
1346
1347
1348 #define SSH_FX_OK 0
1349 #define SSH_FX_EOF 1
1350 #define SSH_FX_NO_SUCH_FILE 2
1351 #define SSH_FX_PERMISSION_DENIED 3
1352 #define SSH_FX_FAILURE 4
1353 #define SSH_FX_BAD_MESSAGE 5
1354 #define SSH_FX_NO_CONNECTION 6
1355 #define SSH_FX_CONNECTION_LOST 7
1356 #define SSH_FX_OP_UNSUPPORTED 8
1357 #define SSH_FX_INVALID_HANDLE 9
1358 #define SSH_FX_NO_SUCH_PATH 10
1359 #define SSH_FX_FILE_ALREADY_EXISTS 11
1360 #define SSH_FX_WRITE_PROTECT 12
1361
1362 SSH_FX_OK
1363 Indicates successful completion of the operation.
1364
1365 SSH_FX_EOF
1366 indicates end-of-file condition; for SSH_FX_READ it means that no
1367 more data is available in the file, and for SSH_FX_READDIR it
1368 indicates that no more files are contained in the directory.
1369
1370 SSH_FX_NO_SUCH_FILE
1371 is returned when a reference is made to a file which does not
1372 exist.
1373
1374 SSH_FX_PERMISSION_DENIED
1375 is returned when the authenticated user does not have sufficient
1376 permissions to perform the operation.
1377
1378 SSH_FX_FAILURE
1379 is a generic catch-all error message; it should be returned if an
1380 error occurs for which there is no more specific error code
1381 defined.
1382
1383 SSH_FX_BAD_MESSAGE
1384 may be returned if a badly formatted packet or protocol
1385 incompatibility is detected.
1386
1387 SSH_FX_NO_CONNECTION
1388 is a pseudo-error which indicates that the client has no
1389 connection to the server (it can only be generated locally by the
1390 client, and MUST NOT be returned by servers).
1391
1392 SSH_FX_CONNECTION_LOST
1393 is a pseudo-error which indicates that the connection to the
1394 server has been lost (it can only be generated locally by the
1395 client, and MUST NOT be returned by servers).
1396
1397
1398
1399 Galbraith, et al. Expires April 16, 2003 [Page 25]
1400
1401 Internet-Draft SSH File Transfer Protocol October 2002
1402
1403
1404 SSH_FX_OP_UNSUPPORTED
1405 indicates that an attempt was made to perform an operation which
1406 is not supported for the server (it may be generated locally by
1407 the client if e.g. the version number exchange indicates that a
1408 required feature is not supported by the server, or it may be
1409 returned by the server if the server does not implement an
1410 operation).
1411
1412 SSH_FX_INVALID_HANDLE
1413 The handle value was invalid.
1414
1415 SSH_FX_NO_SUCH_PATH
1416 The file path does not exist or is invalid.
1417
1418 SSH_FX_FILE_ALREADY_EXISTS
1419 The file already exists.
1420
1421 SSH_FX_WRITE_PROTECT
1422 The file is on read only media, or the media is write protected.
1423
1424 The SSH_FXP_HANDLE response has the following format:
1425
1426 uint32 id
1427 string handle
1428
1429 where `id' is the request identifier, and `handle' is an arbitrary
1430 string that identifies an open file or directory on the server. The
1431 handle is opaque to the client; the client MUST NOT attempt to
1432 interpret or modify it in any way. The length of the handle string
1433 MUST NOT exceed 256 data bytes.
1434
1435 The SSH_FXP_DATA response has the following format:
1436
1437 uint32 id
1438 string data
1439
1440 where `id' is the request identifier, and `data' is an arbitrary byte
1441 string containing the requested data. The data string may be at most
1442 the number of bytes requested in a SSH_FXP_READ request, but may also
1443 be shorter if end of file is reached or if the read is from something
1444 other than a regular file.
1445
1446 The SSH_FXP_NAME response has the following format:
1447
1448
1449
1450
1451
1452
1453
1454
1455 Galbraith, et al. Expires April 16, 2003 [Page 26]
1456
1457 Internet-Draft SSH File Transfer Protocol October 2002
1458
1459
1460 uint32 id
1461 uint32 count
1462 repeats count times:
1463 string filename [UTF-8]
1464 ATTRS attrs
1465
1466 where `id' is the request identifier, `count' is the number of names
1467 returned in this response, and the remaining fields repeat `count'
1468 times (so that all three fields are first included for the first
1469 file, then for the second file, etc). In the repeated part,
1470 `filename' is a file name being returned (for SSH_FXP_READDIR, it
1471 will be a relative name within the directory, without any path
1472 components; for SSH_FXP_REALPATH it will be an absolute path name),
1473 and `attrs' is the attributes of the file as described in Section
1474 ``File Attributes''.
1475
1476 The SSH_FXP_ATTRS response has the following format:
1477
1478 uint32 id
1479 ATTRS attrs
1480
1481 where `id' is the request identifier, and `attrs' is the returned
1482 file attributes as described in Section ``File Attributes''.
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511 Galbraith, et al. Expires April 16, 2003 [Page 27]
1512
1513 Internet-Draft SSH File Transfer Protocol October 2002
1514
1515
1516 8. Vendor-Specific Extensions
1517
1518 The SSH_FXP_EXTENDED request provides a generic extension mechanism
1519 for adding vendor-specific commands. The request has the following
1520 format:
1521
1522 uint32 id
1523 string extended-request
1524 ... any request-specific data ...
1525
1526 where `id' is the request identifier, and `extended-request' is a
1527 string of the format "name@domain", where domain is an internet
1528 domain name of the vendor defining the request. The rest of the
1529 request is completely vendor-specific, and servers should only
1530 attempt to interpret it if they recognize the `extended-request'
1531 name.
1532
1533 The server may respond to such requests using any of the response
1534 packets defined in Section ``Responses from the Server to the
1535 Client''. Additionally, the server may also respond with a
1536 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
1537 not recognize the `extended-request' name, then the server MUST
1538 respond with SSH_FXP_STATUS with error/status set to
1539 SSH_FX_OP_UNSUPPORTED.
1540
1541 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
1542 extension-specific data from the server to the client. It is of the
1543 following format:
1544
1545 uint32 id
1546 ... any request-specific data ...
1547
1548 There is a range of packet types reserved for use by extensions. In
1549 order to avoid collision, extensions that turn on the use of
1550 additional packet types should determine those numbers dynamically.
1551
1552 The suggested way of doing this is have an extension request from the
1553 client to the server that enables the extension; the extension
1554 response from the server to the client would specify the actual type
1555 values to use, in additional to any other data.
1556
1557 Extension authors should be mindful of the limited range of packet
1558 types available (there are only 45 values available) and avoid
1559 requiring a new packet type where possible.
1560
1561
1562
1563
1564
1565
1566
1567 Galbraith, et al. Expires April 16, 2003 [Page 28]
1568
1569 Internet-Draft SSH File Transfer Protocol October 2002
1570
1571
1572 9. Security Considerations
1573
1574 This protocol assumes that it is run over a secure channel and that
1575 the endpoints of the channel have been authenticated. Thus, this
1576 protocol assumes that it is externally protected from network-level
1577 attacks.
1578
1579 This protocol provides file system access to arbitrary files on the
1580 server (only constrained by the server implementation). It is the
1581 responsibility of the server implementation to enforce any access
1582 controls that may be required to limit the access allowed for any
1583 particular user (the user being authenticated externally to this
1584 protocol, typically using the SSH User Authentication Protocol [8].
1585
1586 Care must be taken in the server implementation to check the validity
1587 of received file handle strings. The server should not rely on them
1588 directly; it MUST check the validity of each handle before relying on
1589 it.
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623 Galbraith, et al. Expires April 16, 2003 [Page 29]
1624
1625 Internet-Draft SSH File Transfer Protocol October 2002
1626
1627
1628 10. Changes from previous protocol versions
1629
1630 The SSH File Transfer Protocol has changed over time, before it's
1631 standardization. The following is a description of the incompatible
1632 changes between different versions.
1633
1634 10.1 Changes between versions 4 and 3
1635
1636 Many of the changes between version 4 and version 3 are to the
1637 attribute structure to make it more flexible for non-unix platforms.
1638
1639 o Make all filenames UTF-8.
1640
1641 o Added 'newline' extension.
1642
1643 o Made file attribute owner and group strings so they can actually
1644 be used on disparate systems.
1645
1646 o Added createtime field, and added separate flags for atime,
1647 createtime, and mtime so they can be set separately.
1648
1649 o Split the file type out of the permissions field and into it's own
1650 field (which is always present.)
1651
1652 o Added acl attribute.
1653
1654 o Added SSH_FXF_TEXT file open flag.
1655
1656 o Added flags field to the get stat commands so that the client can
1657 specifically request information the server might not normally
1658 included for performance reasons.
1659
1660 o Removed the long filename from the names structure-- it can now be
1661 built from information available in the attrs structure.
1662
1663 o Added reserved range of packet numbers for extensions.
1664
1665 o Added several additional error codes.
1666
1667 o Change the way version negotiate works slightly. Previously, if
1668 the client version were higher than the server version, the server
1669 was supposed to 'echo back' the clients version. The server now
1670 sends it's own version and the lower of the two is considered to
1671 be the one in use.
1672
1673
1674
1675
1676
1677
1678
1679 Galbraith, et al. Expires April 16, 2003 [Page 30]
1680
1681 Internet-Draft SSH File Transfer Protocol October 2002
1682
1683
1684 10.2 Changes between versions 3 and 2
1685
1686 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added.
1687
1688 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were
1689 added.
1690
1691 o The SSH_FXP_STATUS message was changed to include fields `error
1692 message' and `language tag'.
1693
1694
1695 10.3 Changes between versions 2 and 1
1696
1697 o The SSH_FXP_RENAME message was added.
1698
1699
1700 10.4 Changes between versions 1 and 0
1701
1702 o Implementation changes, no actual protocol changes.
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735 Galbraith, et al. Expires April 16, 2003 [Page 31]
1736
1737 Internet-Draft SSH File Transfer Protocol October 2002
1738
1739
1740 11. Trademark Issues
1741
1742 "ssh" is a registered trademark of SSH Communications Security Corp
1743 in the United States and/or other countries.
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791 Galbraith, et al. Expires April 16, 2003 [Page 32]
1792
1793 Internet-Draft SSH File Transfer Protocol October 2002
1794
1795
1796 References
1797
1798 [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
1799 P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
1800 1999.
1801
1802 [2] Alvestrand, H., "IETF Policy on Character Sets and Languages",
1803 BCP 18, RFC 2277, January 1998.
1804
1805 [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame,
1806 C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC
1807 3010, December 2000.
1808
1809 [4] Institute of Electrical and Electronics Engineers, "Information
1810 Technology - Portable Operating System Interface (POSIX) - Part
1811 1: System Application Program Interface (API) [C Language]",
1812 IEEE Standard 1003.2, 1996.
1813
1814 [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1815 Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh-
1816 architecture-13 (work in progress), September 2002.
1817
1818 [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1819 Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh-
1820 transport-15 (work in progress), September 2002.
1821
1822 [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1823 Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16
1824 (work in progress), September 2002.
1825
1826 [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S.
1827 Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh-
1828 userauth-16 (work in progress), September 2002.
1829
1830
1831 Authors' Addresses
1832
1833 Joseph Galbraith
1834 VanDyke Software
1835 4848 Tramway Ridge Blvd
1836 Suite 101
1837 Albuquerque, NM 87111
1838 US
1839
1840 Phone: +1 505 332 5700
1841 EMail: galb-list@vandyke.com
1842
1843
1844
1845
1846
1847 Galbraith, et al. Expires April 16, 2003 [Page 33]
1848
1849 Internet-Draft SSH File Transfer Protocol October 2002
1850
1851
1852 Tatu Ylonen
1853 SSH Communications Security Corp
1854 Fredrikinkatu 42
1855 HELSINKI FIN-00100
1856 Finland
1857
1858 EMail: ylo@ssh.com
1859
1860
1861 Sami Lehtinen
1862 SSH Communications Security Corp
1863 Fredrikinkatu 42
1864 HELSINKI FIN-00100
1865 Finland
1866
1867 EMail: sjl@ssh.com
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903 Galbraith, et al. Expires April 16, 2003 [Page 34]
1904
1905 Internet-Draft SSH File Transfer Protocol October 2002
1906
1907
1908 Full Copyright Statement
1909
1910 Copyright (C) The Internet Society (2002). All Rights Reserved.
1911
1912 This document and translations of it may be copied and furnished to
1913 others, and derivative works that comment on or otherwise explain it
1914 or assist in its implementation may be prepared, copied, published
1915 and distributed, in whole or in part, without restriction of any
1916 kind, provided that the above copyright notice and this paragraph are
1917 included on all such copies and derivative works. However, this
1918 document itself may not be modified in any way, such as by removing
1919 the copyright notice or references to the Internet Society or other
1920 Internet organizations, except as needed for the purpose of
1921 developing Internet standards in which case the procedures for
1922 copyrights defined in the Internet Standards process must be
1923 followed, or as required to translate it into languages other than
1924 English.
1925
1926 The limited permissions granted above are perpetual and will not be
1927 revoked by the Internet Society or its successors or assigns.
1928
1929 This document and the information contained herein is provided on an
1930 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
1931 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
1932 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
1933 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
1934 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
1935
1936 Acknowledgement
1937
1938 Funding for the RFC Editor function is currently provided by the
1939 Internet Society.
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959 Galbraith, et al. Expires April 16, 2003 [Page 35]
1960
1961
+3306
-0
rfc/draft-ietf-secsh-filexfer-12.txt less more
0
1
2
3
4 Secure Shell Working Group J. Galbraith
5 Internet-Draft VanDyke Software
6 Expires: July 29, 2006 O. Saarenmaa
7 F-Secure
8 January 25, 2006
9
10
11 SSH File Transfer Protocol
12 draft-ietf-secsh-filexfer-12.txt
13
14 Status of this Memo
15
16 By submitting this Internet-Draft, each author represents that any
17 applicable patent or other IPR claims of which he or she is aware
18 have been or will be disclosed, and any of which he or she becomes
19 aware will be disclosed, in accordance with Section 6 of BCP 79.
20
21 Internet-Drafts are working documents of the Internet Engineering
22 Task Force (IETF), its areas, and its working groups. Note that
23 other groups may also distribute working documents as Internet-
24 Drafts.
25
26 Internet-Drafts are draft documents valid for a maximum of six months
27 and may be updated, replaced, or obsoleted by other documents at any
28 time. It is inappropriate to use Internet-Drafts as reference
29 material or to cite them other than as "work in progress."
30
31 The list of current Internet-Drafts can be accessed at
32 http://www.ietf.org/ietf/1id-abstracts.txt.
33
34 The list of Internet-Draft Shadow Directories can be accessed at
35 http://www.ietf.org/shadow.html.
36
37 This Internet-Draft will expire on July 29, 2006.
38
39 Copyright Notice
40
41 Copyright (C) The Internet Society (2006).
42
43 Abstract
44
45 The SSH File Transfer Protocol provides secure file transfer
46 functionality over any reliable data stream. It is the standard file
47 transfer protocol for use with the SSH2 protocol. This document
48 describes the file transfer protocol and its interface to the SSH2
49 protocol suite.
50
51
52
53
54
55 Galbraith & Saarenmaa Expires July 29, 2006 [Page 1]
56
57 Internet-Draft SSH File Transfer Protocol January 2006
58
59
60 Table of Contents
61
62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
63 2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4
64 3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4
65 3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5
66 4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5
67 4.1. Request Synchronization and Reordering . . . . . . . . . . 6
68 4.2. New data types defined by this document . . . . . . . . . 7
69 4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7
70 5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9
71 5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9
72 5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9
73 5.3. Determining Server Newline Convention . . . . . . . . . . 10
74 5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10
75 5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 13
76 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14
77 7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16
78 7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 17
79 7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
80 7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
81 7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 19
82 7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 19
83 7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 20
84 7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20
85 7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
86 7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 24
87 7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 27
88 7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 27
89 7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 27
90 7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 28
91 7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 28
92 8. Requests From the Client to the Server . . . . . . . . . . . . 28
93 8.1. Opening and Closing Files and Directories . . . . . . . . 28
94 8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 29
95 8.1.2. Opening a Directory . . . . . . . . . . . . . . . . . 35
96 8.1.3. Closing Handles . . . . . . . . . . . . . . . . . . . 35
97 8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 36
98 8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 36
99 8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 37
100 8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 37
101 8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 38
102 8.4. Creating and Deleting Directories . . . . . . . . . . . . 39
103 8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 40
104 8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 41
105 8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 42
106 8.8. Byte-range locks . . . . . . . . . . . . . . . . . . . . . 43
107 8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 44
108
109
110
111 Galbraith & Saarenmaa Expires July 29, 2006 [Page 2]
112
113 Internet-Draft SSH File Transfer Protocol January 2006
114
115
116 8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 46
117 9. Responses from the Server to the Client . . . . . . . . . . . 47
118 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 47
119 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 51
120 9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52
121 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 52
122 9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53
123 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 53
124 11. Implementation Considerations . . . . . . . . . . . . . . . . 54
125 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
126 13. Security Considerations . . . . . . . . . . . . . . . . . . . 55
127 14. Changes from Previous Protocol Versions . . . . . . . . . . . 56
128 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 56
129 15.1. Normative References . . . . . . . . . . . . . . . . . . . 56
130 15.2. Informative References . . . . . . . . . . . . . . . . . . 57
131 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58
132 Intellectual Property and Copyright Statements . . . . . . . . . . 59
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167 Galbraith & Saarenmaa Expires July 29, 2006 [Page 3]
168
169 Internet-Draft SSH File Transfer Protocol January 2006
170
171
172 1. Introduction
173
174 This protocol provides secure file transfer (and more generally file
175 system access.) It is designed so that it could be used to implement
176 a secure remote file system service, as well as a secure file
177 transfer service.
178
179 This protocol assumes that it runs over a secure channel, such as a
180 channel in [RFC4251], and that the server has already authenticated
181 the client, and that the identity of the client user is available to
182 the protocol.
183
184 In general, this protocol follows a simple request-response model.
185 Each request and response contains a sequence number and multiple
186 requests may be pending simultaneously. There are a relatively large
187 number of different request messages, but a small number of possible
188 response messages. Each request has one or more response messages
189 that may be returned in result (e.g., a read either returns data or
190 reports error status).
191
192 The packet format descriptions in this specification follow the
193 notation presented in [RFC4251].
194
195 Even though this protocol is described in the context of the SSH2
196 protocol, this protocol is general and independent of the rest of the
197 SSH2 protocol suite. It could be used in a number of different
198 applications, such as secure file transfer over TLS [RFC2246] and
199 transfer of management information in VPN applications.
200
201
202 2. Acknowledgements
203
204 This document owes it's initial creation and protocol design to Tatu
205 Ylonen and Sami Lehtinen of SSH Communications Security Corp.
206
207 We express our gratitude to them for their initial work on this
208 protocol.
209
210
211 3. Use with the SSH Connection Protocol
212
213 When used with the SSH2 Protocol suite, this protocol is intended to
214 be used as a subsystem as described in [RFC4254] in the section
215 "Starting a Shell or a Command". The subsystem name used with this
216 protocol is "sftp".
217
218
219
220
221
222
223 Galbraith & Saarenmaa Expires July 29, 2006 [Page 4]
224
225 Internet-Draft SSH File Transfer Protocol January 2006
226
227
228 3.1. The Use of 'stderr' in the server
229
230 This protocol uses stdout and stdin to transmit binary protocol data.
231 The "session" channel ([RFC4254]), which is used by the subsystem,
232 also supports the use of stderr.
233
234 Data sent on stderr by the server SHOULD be considered free format
235 debug or supplemental error information, and MAY be displayed to the
236 user.
237
238 For example, during initialization, there is no client request
239 active, so errors or warning information cannot be sent to the client
240 as part of the SFTP protocol at this early stage. However, the
241 errors or warnings MAY be sent as stderr text.
242
243
244 4. General Packet Format
245
246 All packets transmitted over the secure connection are of the
247 following format:
248
249 uint32 length
250 byte type
251 uint32 request-id
252 ... type specific fields ...
253
254 'length'
255 The length of the entire packet, excluding the length field
256 itself, such that, for example, for a packet type containing no
257 type specific fields, the length field would be 5, and 9 bytes of
258 data would be sent on the wire. (This is the packet format used
259 in [RFC4253].)
260
261 All packet descriptions in this document omit the length field for
262 brevity; the length field MUST be included in any case.
263
264 The maximum size of a packet is in practice determined by the
265 client (the maximum size of read or write requests that it sends,
266 plus a few bytes of packet overhead). All servers SHOULD support
267 packets of at least 34000 bytes (where the packet size refers to
268 the full length, including the header above). This should allow
269 for reads and writes of at most 32768 bytes.
270
271 'type'
272 The type code for the packet.
273
274
275
276
277
278
279 Galbraith & Saarenmaa Expires July 29, 2006 [Page 5]
280
281 Internet-Draft SSH File Transfer Protocol January 2006
282
283
284 'request-id'
285 Each request from the client contains a 'request-id' field. Each
286 response from the server includes that same 'request-id' from the
287 request that the server is responding to. One possible
288 implementation is for the client to us a monotonically increasing
289 request sequence number (modulo 2^32). There is, however, no
290 particular requirement the 'request-id' fields be unique.
291
292 There are two packets, INIT and VERSION, which do not use the
293 request-id.
294 Packet descriptions in this document will contain the 'request-id'
295 field, but will not redefine it.
296
297
298 Implementations MUST ignore excess data at the end of an otherwise
299 valid packet. Implementations MUST respond to unrecognized packet
300 types with an SSH_FX_OP_UNSUPPORTED error. This will allow the
301 protocol to be extended in a backwards compatible way as needed.
302
303 Additionally, when a packet has two or more optional fields, and an
304 implementation wishes to use the i-th optional field, all fields from
305 1 to i MUST be present. In other words, only fields after the last
306 field the implementation wishes to send are actually options.
307
308 There is no limit on the number of outstanding (non-acknowledged)
309 requests that the client may send to the server. In practice this is
310 limited by the buffering available on the data stream and the queuing
311 performed by the server. If the server's queues are full, it should
312 not read any more data from the stream, and flow control will prevent
313 the client from sending more requests. Note, however, that while
314 there is no restriction on the protocol level, the client's API may
315 provide a limit in order to prevent infinite queuing of outgoing
316 requests at the client.
317
318 4.1. Request Synchronization and Reordering
319
320 The protocol and implementations MUST process requests relating to
321 the same file in the order in which they are received. In other
322 words, if an application submits multiple requests to the server, the
323 results in the responses will be the same as if it had sent the
324 requests one at a time and waited for the response in each case. For
325 example, the server may process non-overlapping read/write requests
326 to the same file in parallel, but overlapping reads and writes cannot
327 be reordered or parallelized. However, there are no ordering
328 restrictions on the server for processing requests from two different
329 file transfer connections. The server may interleave and parallelize
330 them at will.
331
332
333
334
335 Galbraith & Saarenmaa Expires July 29, 2006 [Page 6]
336
337 Internet-Draft SSH File Transfer Protocol January 2006
338
339
340 There are no restrictions on the order in which responses to
341 outstanding requests are delivered to the client, except that the
342 server must ensure fairness in the sense that processing of no
343 request will be indefinitely delayed even if the client is sending
344 other requests so that there are multiple outstanding requests all
345 the time.
346
347 A client MUST be prepared to receive responses to multiple overlapped
348 requests out of order.
349
350 4.2. New data types defined by this document
351
352 This document defines these data types in addition to those defined
353 in [RFC4251].
354
355 uint16
356 Represents a 16-bit unsigned integer. Stored as 2 bytes in the
357 order of decreasing significance (network byte order).
358
359 int64
360 Represents a 64-bit signed integer. Stored using two's
361 complement, as eight bytes in the order of decreasing significance
362 (network byte order).
363
364 extension-pair
365
366 string extension-name
367 string extension-data
368
369 'extension-name' is the name of a protocol extension. Extensions
370 not defined by IETF CONSENSUS MUST follow the the DNS
371 extensibility naming convention outlined in [RFC4251].
372
373 'extension-data' is any data specific to the extension, and MAY be
374 zero length if the extension has no data.
375
376
377 4.3. Packet Types
378
379 The following values are defined for packet types.
380
381
382
383
384
385
386
387
388
389
390
391 Galbraith & Saarenmaa Expires July 29, 2006 [Page 7]
392
393 Internet-Draft SSH File Transfer Protocol January 2006
394
395
396 SSH_FXP_INIT 1
397 SSH_FXP_VERSION 2
398 SSH_FXP_OPEN 3
399 SSH_FXP_CLOSE 4
400 SSH_FXP_READ 5
401 SSH_FXP_WRITE 6
402 SSH_FXP_LSTAT 7
403 SSH_FXP_FSTAT 8
404 SSH_FXP_SETSTAT 9
405 SSH_FXP_FSETSTAT 10
406 SSH_FXP_OPENDIR 11
407 SSH_FXP_READDIR 12
408 SSH_FXP_REMOVE 13
409 SSH_FXP_MKDIR 14
410 SSH_FXP_RMDIR 15
411 SSH_FXP_REALPATH 16
412 SSH_FXP_STAT 17
413 SSH_FXP_RENAME 18
414 SSH_FXP_READLINK 19
415 SSH_FXP_LINK 21
416 SSH_FXP_BLOCK 22
417 SSH_FXP_UNBLOCK 23
418
419 SSH_FXP_STATUS 101
420 SSH_FXP_HANDLE 102
421 SSH_FXP_DATA 103
422 SSH_FXP_NAME 104
423 SSH_FXP_ATTRS 105
424
425 SSH_FXP_EXTENDED 200
426 SSH_FXP_EXTENDED_REPLY 201
427
428 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to
429 implement extensions, which can be vendor specific. See Section
430 ''Extensions'' for more details.
431
432 Values 210-255 are reserved for use in conjunction with these
433 extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the
434 meaning of these reserved types. It is suggested that the actual
435 value to be used also be negotiated, since this will prevent
436 collision among multiple uncoordinated extensions.
437
438 The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if
439 it receives a packet it does not recognize.
440
441 The use of additional packet types in the non-extension range MUST be
442 introduced through IETF consensus. New packet types to be sent from
443 the client to the server MAY be introduced without changing the
444
445
446
447 Galbraith & Saarenmaa Expires July 29, 2006 [Page 8]
448
449 Internet-Draft SSH File Transfer Protocol January 2006
450
451
452 protocol version (Section 5). Because the client has no way to
453 respond to unrecognized packet types, new packet types to be sent
454 from the server to the client the client MUST not used unless the
455 protocol version is changed or the client has negotiated to received
456 them. This negotiation MAY be explicit, through the use of
457 extensions, or MAY be implicit, by the client itself using a packet
458 type not defined above.
459
460
461 5. Protocol Initialization
462
463 When the file transfer protocol starts, the client first sends a
464 SSH_FXP_INIT (including its version number) packet to the server.
465 The server responds with a SSH_FXP_VERSION packet, supplying the
466 lowest of its own and the client's version number. Both parties
467 should from then on adhere to that particular version of the
468 protocol.
469
470 The version number of the protocol specified in this document is 6.
471 The version number should be incremented for each incompatible
472 revision of this protocol.
473
474 Note that these two packets DO NOT contain a request id. These are
475 the only such packets in the protocol.
476
477 5.1. Client Initialization
478
479 The SSH_FXP_INIT packet (from client to server) has the following
480 data:
481
482 uint32 version
483
484 'version' is the version number of the client. If the client wishes
485 to interoperate with servers that support discontinuous version
486 numbers it SHOULD send '3', and then use the 'version-select'
487 extension (see below.) Otherwise, this value is '6' for this version
488 of the protocol.
489
490 5.2. Server Initialization
491
492 The SSH_FXP_VERSION packet (from server to client) has the following
493 data:
494
495 uint32 version
496 extension-pair extensions[0..n]
497
498 'version' is the lower of the protocol version supported by the
499 server and the version number received from the client.
500
501
502
503 Galbraith & Saarenmaa Expires July 29, 2006 [Page 9]
504
505 Internet-Draft SSH File Transfer Protocol January 2006
506
507
508 'extensions' is 0 or more extension-pairs (Section 4.2).
509 Implementations MUST silently ignore any extensions whose names they
510 do not recognize.
511
512 5.3. Determining Server Newline Convention
513
514 In order to correctly process text files in a cross platform
515 compatible way, newline sequences must be converted between client
516 and server conventions.
517
518 The SSH_FXF_TEXT_MODE file open flag (Section 8.1.1) makes it
519 possible to request that the server translate a file to a 'canonical'
520 wire format. This format uses CRLF as the line separator.
521
522 Servers for systems using other conventions MUST translate to and
523 from the canonical form.
524
525 However, to ease the burden of implementation on servers that use a
526 single, simple, separator sequence the following extension allows the
527 canonical format to be changed.
528
529 string "newline"
530 string new-canonical-separator (usually CR or LF or CRLF)
531
532 All clients MUST support this extension.
533
534 When processing text files, clients SHOULD NOT translate any
535 character or sequence that is not an exact match of the server's
536 newline separator.
537
538 In particular, if the newline sequence being used is the canonical
539 CRLF sequence, a lone CR or a lone LF SHOULD be written through
540 without change.
541
542 5.4. Supported Features
543
544 The sftp protocol has grown to be very rich, and now supports a
545 number of features that may not be available on all servers.
546
547 When a server receives a request for a feature it cannot support, it
548 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise
549 specified. The following extension facilitates clients being able to
550 use the maximum available feature set, and yet not be overly burdened
551 by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST
552 include as part of their version packet.
553
554
555
556
557
558
559 Galbraith & Saarenmaa Expires July 29, 2006 [Page 10]
560
561 Internet-Draft SSH File Transfer Protocol January 2006
562
563
564 string "supported2"
565 string supported-structure
566 uint32 supported-attribute-mask
567 uint32 supported-attribute-bits
568 uint32 supported-open-flags
569 uint32 supported-access-mask
570 uint32 max-read-size
571 uint16 supported-open-block-vector
572 uint16 supported-block-vector
573 uint32 attrib-extension-count
574 string attrib-extension-names[attrib_extension-count]
575 uint32 extension-count
576 string extension-names[extension-count]
577
578 Note that the name "supported2" is used here to avoid conflict with
579 the slightly different "supported" extension that was previously
580 used.
581 supported-attribute-mask
582 This mask MAY by applied to the 'File Attributes' valid-attribute-
583 flags field (Section 7.1) to ensure that no unsupported attributes
584 are present during a operation which writes attributes.
585
586 supported-attribute-bits
587 This mask MAY by applied to the 'File Attributes' attrib-bits
588 field (Section 7.9) to ensure that no unsupported attrib-bits are
589 present during a operation which writes attributes.
590
591 supported-open-flags
592 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN
593 (Section 8.1.1) flags field.
594
595 supported-access-mask
596 This mask may be applied to the ace-mask field of an ACL.
597
598 This mask SHOULD NOT be applied to the desired-access field of the
599 SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result
600 in not requesting the access required by the client. In this
601 case, the server is responsible for translating the clients
602 requested access to a mode it supports that is sufficient to grant
603 all access requested by the client.
604
605 max-read-size
606 This is the maximum read size that the server guarantees to
607 complete. For example, certain embedded server implementations
608 complete only the first 4K of a read, even if there is additional
609 data to be read from the file.
610
611
612
613
614
615 Galbraith & Saarenmaa Expires July 29, 2006 [Page 11]
616
617 Internet-Draft SSH File Transfer Protocol January 2006
618
619
620 If the server specifies a non-zero value for max-read-size, it
621 MUST return the requested number of bytes for reads that are less
622 than or equal to the value, unless it encounters EOF or an ERROR.
623
624 The server MAY use this value to express that it is willing to
625 handle very large read requests, in excess of the standard 34000
626 bytes specified in Section 4.
627
628 supported-open-block-vector
629 supported-block-vector
630 16-bit masks specifying which combinations of blocking flags are
631 supported. Each bit corresponds to one combination of the
632 SSH_FXF_BLOCK_READ, SSH_FXF_BLOCK_WRITE, SSH_FXF_BLOCK_DELETE, and
633 SSH_FXF_BLOCK_ADVISORY bits from Section 7.1.1.3, with a set bit
634 corresponding to a supported combination and a clear bit an
635 unsupported combination. The index of a bit, bit zero being the
636 least significant bit, viewed as a four-bit number, corresponds to
637 a combination of flag bits, shifted right so that BLOCK_READ is
638 the least significant bit. The combination `no blocking flags'
639 MUST be supported, so the low bit will always be set.
640
641 For example, a server supporting only the classic advisory read
642 (shared) and write (exclusive) locks would set the bits
643 corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY,
644 0b1010, plus the always-set bit 0b0000, giving a mask value of
645 0b0000110000000001, or 0x0c01; a server supporting no locking at
646 all would set only bit zero, giving 0x0001.
647
648 'supported-open-block-masks' applies to the SSH_FXP_OPEN
649 (Section 8.1.1) flags field. 'supported-block-masks' applies to
650 the SSH_FXF_BLOCK request.
651
652 attrib-extension-count
653 Count of extension names in the attrib-extension-names array.
654
655 attrib-extension-names
656 Names of extensions that can be used in an ATTRS (Section 7.14)
657 structure.
658
659 extension-count
660 Count of extension names in the extension-names array.
661
662 extension-names
663 Names of extensions that can be used with the SSH_FXP_EXTEND
664 (Section 10) packet.
665
666
667 Naturally, if a given attribute field, attribute mask bit, open flag,
668
669
670
671 Galbraith & Saarenmaa Expires July 29, 2006 [Page 12]
672
673 Internet-Draft SSH File Transfer Protocol January 2006
674
675
676 or extension is required for correct operation, the client MUST
677 either not allow the bit to be masked off, or MUST fail the operation
678 gracefully without sending the request to the server.
679
680 The client MAY send requests that are not supported by the server;
681 however, it is not normally expected to be productive to do so. The
682 client SHOULD apply the mask even to attrib structures received from
683 the server. The server MAY include attributes or attrib-bits that
684 are not included in the mask. Such attributes or attrib-bits are
685 effectively read-only.
686
687 The supported capabilities of the acl attribute are sent using the
688 following extension.
689
690 string "acl-supported"
691 string supported-structure
692 uint32 capabilities
693
694 'capabilities' is a combination of the following bits:
695
696 SSH_ACL_CAP_ALLOW 0x00000001
697 SSH_ACL_CAP_DENY 0x00000002
698 SSH_ACL_CAP_AUDIT 0x00000004
699 SSH_ACL_CAP_ALARM 0x00000008
700 SSH_ACL_CAP_INHERIT_ACCESS 0x00000010
701 SSH_ACL_CAP_INHERIT_AUDIT_ALARM 0x00000020
702
703 SSH_ACL_CAP_ALLOW
704 SSH_ACL_CAP_DENY
705 SSH_ACL_CAP_AUDIT
706 SSH_ACL_CAP_ALARM
707 The server supports the associated ACL ACE type.
708
709 SSH_ACL_CAP_INHERIT_ACCESS
710 The server can control whether a ACL will inherit DENY and ALLOW
711 ACEs that are marked inheritable from it's parent object.
712
713 SSH_ACL_CAP_INHERIT_AUDIT_ALARM
714 The server can control whether a ACL will inherit AUDIT or ALARM
715 ACEs that are marked inheritable from it's parent object.
716
717
718 5.5. Version re-negotiation
719
720 If the server supports other versions than what was negotiated, it
721 may wish to send the 'versions' extension to inform the client of
722 this fact. The client may then optionally choose to use one of the
723 other versions supported.
724
725
726
727 Galbraith & Saarenmaa Expires July 29, 2006 [Page 13]
728
729 Internet-Draft SSH File Transfer Protocol January 2006
730
731
732 string "versions"
733 string comma-separated-versions
734
735 'comma-separated-versions' is a string of comma separated version
736 numbers. Defined versions are: "2", "3", "4", "5", "6". Any other
737 version advertised by the server must follow the DNS extensibility
738 naming convention outlined in [RFC4251].
739
740 For example: "2,3,6,private@example.com".
741
742 If the client and server have negotiated a a version greater than or
743 equal to version '3' (the version at which SSH_FXP_EXTENDED was
744 introduced) in the initial VERSION/INIT exchange, the client may
745 select a new version to use from the list the server provided using
746 the following SSH_FXP_EXTENDED request.
747
748 string "version-select"
749 string version-from-list
750
751 If the 'version-from-list' is one of the versions on the servers
752 list, the server MUST respond with SSH_FX_OK. If the server did not
753 send the "versions" extension, or the version-from-list was not
754 included, the server MAY send a status response describing the
755 failure, but MUST then close the channel without processing any
756 further requests.
757
758 The 'version-select' MUST be the first request from the client to the
759 server; if it is not, the server MUST fail the request and close the
760 channel.
761
762 Although this request does take a full round trip, no client need
763 wait for the response before continuing, because any valid request
764 MUST succeed, and any invalid request results in a channel close.
765 Since the request is the first request, it is not possible for the
766 server to have already sent responses conforming to the old version.
767
768 Typically, the client SHOULD NOT down-grade the protocol version
769 using this extension; however, it is not forbidden to do so. One
770 reason a client might do so is to work around a buggy implementation.
771
772
773 6. File Names
774
775 This protocol represents file names as strings. File names are
776 assumed to use the slash ('/') character as a directory separator.
777
778 File names starting with a slash are "absolute", and are relative to
779 the root of the file system. Names starting with any other character
780
781
782
783 Galbraith & Saarenmaa Expires July 29, 2006 [Page 14]
784
785 Internet-Draft SSH File Transfer Protocol January 2006
786
787
788 are relative to the user's default directory (home directory). Note
789 that identifying the user is assumed to take place outside of this
790 protocol.
791
792 Servers SHOULD interpret a path name component ".." (Section 13) as
793 referring to the parent directory, and "." as referring to the
794 current directory.
795
796 An empty path name is valid, and it refers to the user's default
797 directory (usually the user's home directory).
798
799 Otherwise, no syntax is defined for file names by this specification.
800 Clients should not make any other assumptions; however, they can
801 splice path name components returned by SSH_FXP_READDIR together
802 using a slash ('/') as the separator, and that will work as expected.
803
804 It is understood that the lack of well-defined semantics for file
805 names may cause interoperability problems between clients and servers
806 using radically different operating systems. However, this approach
807 is known to work acceptably with most systems, and alternative
808 approaches that e.g. treat file names as sequences of structured
809 components are quite complicated.
810
811 The preferred encoding for filenames is UTF-8. This is consistent
812 with IETF Policy on Character Sets and Languages [RFC2277] and it is
813 further supposed that the server is more likely to support any local
814 character set and be able to convert it to UTF-8.
815
816 However, because the server does not always know the encoding of
817 filenames, it is not always possible for the server to preform a
818 valid translation to UTF-8. When an invalid translation to UTF-8 is
819 preformed, it becomes impossible to manipulate the file, because the
820 translation is not reversible. Therefore, the following extensions
821 are provided in order to make it possible for the server to
822 communicate it's abilities to the client, and to allow the client to
823 control whether the server attempts the conversion.
824
825 A server MAY include the following extension with it's version
826 packet.
827
828 string "filename-charset"
829 string charset-name
830
831 A server that can always provide a valid UTF-8 translation for
832 filenames SHOULD NOT send this extension. Otherwise, the server
833 SHOULD send this extension and include the encoding most likely to be
834 used for filenames. This value will most likely be derived from the
835 LC_CTYPE on most unix-like systems.
836
837
838
839 Galbraith & Saarenmaa Expires July 29, 2006 [Page 15]
840
841 Internet-Draft SSH File Transfer Protocol January 2006
842
843
844 A server that does not send this extension MUST send all filenames
845 encoded in UTF-8. All clients MUST support UTF-8 filenames.
846
847 If the server included the 'filename-charset' extension with its
848 VERSION packet, a client MAY send the following extension to turn off
849 server translation to UTF-8.
850
851 string "filename-translation-control"
852 bool do-translate
853
854 If the client does not send this extension, the server MUST continue
855 to attempt translation to UTF-8. When a client sends this extension,
856 the server MUST enable filename translation if 'do-translate' is
857 true, or disable filename translation if it is false.
858
859 The server MUST respond with a STATUS response; if the server sent a
860 'filename-charset' extension, the status MUST be SUCCESS. Otherwise,
861 the status MUST be SSH_FX_OP_UNSUPPORTED.
862
863 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE
864 data MUST be used. The server is responsible for converting the
865 UNICODE data to whatever canonical form it requires. For example, if
866 the server requires that precomposed characters always be used, the
867 server MUST NOT assume the filename as sent by the client has this
868 attribute, but must do this normalization itself.
869
870
871 7. File Attributes
872
873 A new compound data type, 'ATTRS', is defined for encoding file
874 attributes. The same encoding is used both when returning file
875 attributes from the server and when sending file attributes to the
876 server.
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895 Galbraith & Saarenmaa Expires July 29, 2006 [Page 16]
896
897 Internet-Draft SSH File Transfer Protocol January 2006
898
899
900 uint32 valid-attribute-flags
901 byte type always present
902 uint64 size if flag SIZE
903 uint64 allocation-size if flag ALLOCATION_SIZE
904 string owner if flag OWNERGROUP
905 string group if flag OWNERGROUP
906 uint32 permissions if flag PERMISSIONS
907 int64 atime if flag ACCESSTIME
908 uint32 atime-nseconds if flag SUBSECOND_TIMES
909 int64 createtime if flag CREATETIME
910 uint32 createtime-nseconds if flag SUBSECOND_TIMES
911 int64 mtime if flag MODIFYTIME
912 uint32 mtime-nseconds if flag SUBSECOND_TIMES
913 int64 ctime if flag CTIME
914 uint32 ctime-nseconds if flag SUBSECOND_TIMES
915 string acl if flag ACL
916 uint32 attrib-bits if flag BITS
917 uint32 attrib-bits-valid if flag BITS
918 byte text-hint if flag TEXT_HINT
919 string mime-type if flag MIME_TYPE
920 uint32 link-count if flag LINK_COUNT
921 string untranslated-name if flag UNTRANSLATED_NAME
922 uint32 extended-count if flag EXTENDED
923 extended-pair extensions
924
925 7.1. valid-attribute-flags
926
927 The 'valid-attribute-flags' specifies which of the fields are
928 present. Those fields for which the corresponding flag is not set
929 are not present (not included in the packet).
930
931 The server generally includes all attributes it knows about; however,
932 it may exclude attributes that are overly expensive to retrieve
933 unless the client explicitly requests them.
934
935 When writing attributes, the server SHOULD NOT modify attributes that
936 are not present in the structure. However, if necessary, the server
937 MAY use a default value for an absent attribute.
938
939 In general, unless otherwise specified, if a server cannot support
940 writing an attribute requested, it must fail the setstat operation.
941 In this case, none of the attributes SHOULD be changed.
942
943 New fields can only be added by incrementing the protocol version
944 number (or by using the extension mechanism described below).
945
946 The following values are defined:
947
948
949
950
951 Galbraith & Saarenmaa Expires July 29, 2006 [Page 17]
952
953 Internet-Draft SSH File Transfer Protocol January 2006
954
955
956 SSH_FILEXFER_ATTR_SIZE 0x00000001
957 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
958 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
959 SSH_FILEXFER_ATTR_CREATETIME 0x00000010
960 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
961 SSH_FILEXFER_ATTR_ACL 0x00000040
962 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080
963 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100
964 SSH_FILEXFER_ATTR_BITS 0x00000200
965 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400
966 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800
967 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000
968 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000
969 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000
970 SSH_FILEXFER_ATTR_CTIME 0x00008000
971 SSH_FILEXFER_ATTR_EXTENDED 0x80000000
972
973 0x00000002 was used in a previous version of this protocol. It is
974 now a reserved value and MUST NOT appear in the mask. Some future
975 version of this protocol may reuse this value.
976
977 7.2. Type
978
979 The type field is always present. The following types are defined:
980
981 SSH_FILEXFER_TYPE_REGULAR 1
982 SSH_FILEXFER_TYPE_DIRECTORY 2
983 SSH_FILEXFER_TYPE_SYMLINK 3
984 SSH_FILEXFER_TYPE_SPECIAL 4
985 SSH_FILEXFER_TYPE_UNKNOWN 5
986 SSH_FILEXFER_TYPE_SOCKET 6
987 SSH_FILEXFER_TYPE_CHAR_DEVICE 7
988 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8
989 SSH_FILEXFER_TYPE_FIFO 9
990
991 On a POSIX system, these values would be derived from the mode field
992 of the stat structure. SPECIAL should be used for files that are of
993 a known type which cannot be expressed in the protocol. UNKNOWN
994 should be used if the type is not known.
995
996 7.3. Size
997
998 The 'size' field specifies the number of bytes that can be read from
999 the file, or in other words, the location of the end-of-file.
1000
1001 If this field is present during file creation, it indicates the
1002 number of bytes the client intends to transfer, but SHOULD NOT effect
1003 the creation of the file. The server can use this information to
1004
1005
1006
1007 Galbraith & Saarenmaa Expires July 29, 2006 [Page 18]
1008
1009 Internet-Draft SSH File Transfer Protocol January 2006
1010
1011
1012 determine if the client sent all the intended data and the file was
1013 transfered in it's entirity.
1014
1015 If this field is present during a setstat operation, the file MUST be
1016 extended or truncated to the specified size.
1017
1018 Files opened with the SSH_FXF_TEXT flag may have a size that is
1019 greater or less than the value of the size field. The server MAY
1020 fail setstat operations specifying size for files opened with the
1021 SSH_FXF_TEXT flag.
1022
1023 7.4. allocation-size
1024
1025 The 'allocation-size' field specifies the number of bytes that the
1026 file consumes on disk. This field MAY be less than the 'size' field
1027 if the file is 'sparse' (Section 7.9).
1028
1029 When present during file creation, the file SHOULD be created and the
1030 specified number of bytes preallocated. If the preallocation fails,
1031 the file should be removed (if it was created) and an error returned.
1032
1033 If this field is present during a setstat operation, the file SHOULD
1034 be extended or truncated to the specified size. The 'size' of the
1035 file may be affected by this operation. If the operation succeeds,
1036 the 'size' should be the minimum of the 'size' before the operation
1037 and the new 'allocation-size'.
1038
1039 Querying the 'allocation-size' after setting it MUST return a value
1040 that is greater-than or equal to the value set, but it MAY not return
1041 the precise value set.
1042
1043 If both 'size' and 'allocation-size' are set during a setstat
1044 operation, and 'allocation-size' is less than 'size', the server MUST
1045 return SSH_FX_INVALID_PARAMETER.
1046
1047 7.5. Owner and Group
1048
1049 The 'owner' and 'group' fields are represented as UTF-8 strings; this
1050 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010].
1051 The following text is selected quotations from section 5.6.
1052
1053 To avoid a representation that is tied to a particular underlying
1054 implementation at the client or server, the use of UTF-8 strings has
1055 been chosen. The string should be of the form "user@dns_domain".
1056 This will allow for a client and server that do not use the same
1057 local representation the ability to translate to a common syntax that
1058 can be interpreted by both. In the case where there is no
1059 translation available to the client or server, the attribute value
1060
1061
1062
1063 Galbraith & Saarenmaa Expires July 29, 2006 [Page 19]
1064
1065 Internet-Draft SSH File Transfer Protocol January 2006
1066
1067
1068 must be constructed without the "@". Therefore, the absence of the @
1069 from the owner or owner_group attribute signifies that no translation
1070 was available and the receiver of the attribute should not place any
1071 special meaning on the attribute value. Even though the attribute
1072 value cannot be translated, it may still be useful. In the case of a
1073 client, the attribute string may be used for local display of
1074 ownership.
1075
1076 user@localhost represents a user in the context of the server.
1077
1078 If either the owner or group field is zero length, the field should
1079 be considered absent, and no change should be made to that specific
1080 field during a modification operation.
1081
1082 7.6. Permissions
1083
1084 The 'permissions' field contains a bit mask specifying file
1085 permissions. These permissions correspond to the st_mode field of
1086 the stat structure defined by POSIX [IEEE.1003-1.1996].
1087
1088 This protocol uses the following values for the symbols declared in
1089 the POSIX standard.
1090
1091 S_IRUSR 0000400 (octal)
1092 S_IWUSR 0000200
1093 S_IXUSR 0000100
1094 S_IRGRP 0000040
1095 S_IWGRP 0000020
1096 S_IXGRP 0000010
1097 S_IROTH 0000004
1098 S_IWOTH 0000002
1099 S_IXOTH 0000001
1100 S_ISUID 0004000
1101 S_ISGID 0002000
1102 S_ISVTX 0001000
1103
1104 Implementations MUST NOT send bits that are not defined.
1105
1106 The server SHOULD NOT apply a 'umask' to the mode bits; but should
1107 set the mode bits as specified by the client. The client MUST apply
1108 an appropriate 'umask' to the mode bits before sending them.
1109
1110 7.7. Times
1111
1112 The 'atime' field contains the last access time of the file. Many
1113 operating systems either don't have this field, only optionally
1114 maintain it, or maintain it with less resolution than other fields.
1115
1116
1117
1118
1119 Galbraith & Saarenmaa Expires July 29, 2006 [Page 20]
1120
1121 Internet-Draft SSH File Transfer Protocol January 2006
1122
1123
1124 The 'mtime' contains the last time the file was written.
1125
1126 'createtime' contains the creation time of the file.
1127
1128 'ctime' contains the last time the file attributes were changed. The
1129 exact meaning of this field depends on the server.
1130
1131 All times are represented as seconds from Jan 1, 1970 in UTC. A
1132 negative value indicates number of seconds before Jan 1, 1970. In
1133 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the
1134 nseconds field is to be added to the seconds field for the final time
1135 representation. For example, if the time to be represented is one-
1136 half second before 0 hour January 1, 1970, the seconds field would
1137 have a value of negative one (-1) and the nseconds fields would have
1138 a value of one-half second (500000000). Values greater than
1139 999,999,999 for nseconds are considered invalid.
1140
1141 7.8. ACL
1142
1143 The 'ACL' field contains an ACL similar to that defined in section
1144 5.9 of NFS version 4 Protocol [RFC3010].
1145
1146 The structure of the ACL is:
1147
1148 uint32 acl-flags
1149 uint32 ace-count
1150 ACE ace[ace-count]
1151
1152 The ACE data structure is composes as follows:
1153
1154 uint32 ace-type
1155 uint32 ace-flag
1156 uint32 ace-mask
1157 string who [UTF-8]
1158
1159 acl-flags
1160
1161
1162 SFX_ACL_CONTROL_INCLUDED 0x00000001
1163 SFX_ACL_CONTROL_PRESENT 0x00000002
1164 SFX_ACL_CONTROL_INHERITED 0x00000004
1165 SFX_ACL_AUDIT_ALARM_INCLUDED 0x00000010
1166 SFX_ACL_AUDIT_ALARM_INHERITED 0x00000020
1167
1168
1169
1170
1171
1172
1173
1174
1175 Galbraith & Saarenmaa Expires July 29, 2006 [Page 21]
1176
1177 Internet-Draft SSH File Transfer Protocol January 2006
1178
1179
1180 SFX_ACL_CONTROL_INCLUDED
1181 SFX_ACL_CONTROL_PRESENT
1182 SFX_ACL_CONTROL_INHERITED
1183 If INCLUDED is set during a setstat operation, then the client
1184 intends to modify the ALLOWED/DENIED entries of the ACL.
1185 Otherwise, the client intends for these entries to be
1186 preserved.
1187
1188 If the PRESENT bit is not set, then the client wishes to remove
1189 control entries. If the server doesn't support separate
1190 control and audit information, the client MUST not clear this
1191 bit without also clearing the AUDIT_ALARM_PRESENT bit.
1192
1193 If the PRESENT bit is clear, then control of the file MAY be
1194 through the permissions mask. The server MAY also grant full
1195 access to the file.
1196
1197 If the both the INCLUDE and the PRESENT bit are set, but their
1198 are no ALLOW/DENY entries in the list, the client wishes to
1199 deny all access to the file or directory. The server may have
1200 to transform this into a ACL with a deny entry to implement it.
1201
1202 If INHERITED is set, then ALLOW/DENY ACEs MAY be inherited from
1203 the parent directory. If it is off, then they MUST not be
1204 INHERITED. If the server does not support controlling
1205 inheritance, then the client MUST clear this bit; in this case
1206 the inheritance properties of the server are undefined.
1207
1208 SFX_ACL_AUDIT_ALARM_INCLUDED
1209 SFX_ACL_AUDIT_ALARM_INHERITED
1210 If INCLUDE is set during a setstat operation, then the client
1211 intends to modify the AUDIT/ALARM entries of the ACL.
1212 Otherwise, the client intends for these entries to be
1213 preserved.
1214
1215 If INHERITED is set, then AUDIT/ALARM ACEs MAY be inherited
1216 from the parent directory. If it is off, then they MUST not be
1217 INHERITED. If the server does not support controlling
1218 inheritance, then the client MUST clear this bit; in this case
1219 the inheritance properties of the server are undefined.
1220
1221 Because some server require special permissions / privileges in
1222 order to modify the AUDIT/ALARM entries in the ACL, it is
1223 important to communicate to the server the clients intent to
1224 modify these entries. The client MUST both use the
1225 ACCESS_AUDIT_ALARM_ATTRIBUTES bit in the desired attribute of the
1226 open request and must set the SFX_ACL_AUDIT_ALARM_INCLUDED during
1227 the setstat operation.
1228
1229
1230
1231 Galbraith & Saarenmaa Expires July 29, 2006 [Page 22]
1232
1233 Internet-Draft SSH File Transfer Protocol January 2006
1234
1235
1236 Clients that do not intend specifically to modify the AUDIT or
1237 ALARM entries SHOULD NOT set SSH_FXF_ACCESS_AUDIT_ALARM_INFO in
1238 the open-flags and SHOULD NOT set the SFX_ACL_AUDIT_ALARM_INCLUDED
1239 bit because these operations are often privileged and will fail.
1240
1241 If the SFX_ACL_AUDIT_ALARM_INCLUDED is set, and the requested
1242 change can not be made, the server MUST fail the request.
1243
1244 Servers that do not seperate control and audit/alarm information
1245 may have to read the existing ACL and merge in enteries not
1246 included by the client. The server must take this into account
1247 when opening files with the ACE4_WRITE_ACL permission requested.
1248
1249 ace-type
1250 one of the following four values (taken from NFS Version 4
1251 Protocol [RFC3010]:
1252
1253
1254
1255 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000
1256 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001
1257 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002
1258 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003
1259
1260 ace-flag
1261 A combination of the following flag values. See NFS Version 4
1262 Protocol [RFC3010] section 5.9.2:
1263
1264
1265
1266 ACE4_FILE_INHERIT_ACE 0x00000001
1267 ACE4_DIRECTORY_INHERIT_ACE 0x00000002
1268 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004
1269 ACE4_INHERIT_ONLY_ACE 0x00000008
1270 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010
1271 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020
1272 ACE4_IDENTIFIER_GROUP 0x00000040
1273
1274 ace-mask
1275 Combination of the following flags (taken from [RFC3010], section
1276 5.9.3. The semantic meaning of these flags is also given in
1277 [RFC3010].
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287 Galbraith & Saarenmaa Expires July 29, 2006 [Page 23]
1288
1289 Internet-Draft SSH File Transfer Protocol January 2006
1290
1291
1292 ACE4_READ_DATA 0x00000001
1293 ACE4_LIST_DIRECTORY 0x00000001
1294 ACE4_WRITE_DATA 0x00000002
1295 ACE4_ADD_FILE 0x00000002
1296 ACE4_APPEND_DATA 0x00000004
1297 ACE4_ADD_SUBDIRECTORY 0x00000004
1298 ACE4_READ_NAMED_ATTRS 0x00000008
1299 ACE4_WRITE_NAMED_ATTRS 0x00000010
1300 ACE4_EXECUTE 0x00000020
1301 ACE4_DELETE_CHILD 0x00000040
1302 ACE4_READ_ATTRIBUTES 0x00000080
1303 ACE4_WRITE_ATTRIBUTES 0x00000100
1304 ACE4_DELETE 0x00010000
1305 ACE4_READ_ACL 0x00020000
1306 ACE4_WRITE_ACL 0x00040000
1307 ACE4_WRITE_OWNER 0x00080000
1308 ACE4_SYNCHRONIZE 0x00100000
1309
1310 who
1311 UTF-8 string of the form described in 'Owner and Group'
1312 (Section 7.5)
1313 Also, as per '5.9.4 ACE who' [RFC3010] there are several
1314 identifiers that need to be understood universally. Some of these
1315 identifiers cannot be understood when an client access the server,
1316 but have meaning when a local process accesses the file. The
1317 ability to display and modify these permissions is permitted over
1318 SFTP.
1319
1320 OWNER The owner of the file.
1321 GROUP The group associated with the file.
1322 EVERYONE The world.
1323 INTERACTIVE Accessed from an interactive terminal.
1324 NETWORK Accessed via the network.
1325 DIALUP Accessed as a dialup user to the server.
1326 BATCH Accessed from a batch job.
1327 ANONYMOUS Accessed without any authentication.
1328 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS).
1329 SERVICE Access from a system service.
1330 To avoid conflict, these special identifiers are distinguish by an
1331 appended "@". For example: ANONYMOUS@.
1332
1333 7.9. attrib-bits and attrib-bits-valid
1334
1335 These fields, taken together, reflect various attributes of the file
1336 or directory, on the server.
1337
1338 Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib-
1339 bits' field. This allows both the server and the client to
1340
1341
1342
1343 Galbraith & Saarenmaa Expires July 29, 2006 [Page 24]
1344
1345 Internet-Draft SSH File Transfer Protocol January 2006
1346
1347
1348 communicate only the bits it knows about without inadvertently
1349 twiddling bits they don't understand.
1350
1351 The following attrib-bits are defined:
1352
1353 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001
1354 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002
1355 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004
1356 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008
1357 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010
1358 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020
1359 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040
1360 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080
1361 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100
1362 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200
1363 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400
1364 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800
1365
1366 SSH_FILEXFER_ATTR_FLAGS_READONLY
1367 Advisory, read-only bit. This bit is not part of the access
1368 control information on the file, but is rather an advisory field
1369 indicating that the file should not be written.
1370
1371 SSH_FILEXFER_ATTR_FLAGS_SYSTEM
1372 The file is part of the operating system.
1373
1374 SSH_FILEXFER_ATTR_FLAGS_HIDDEN
1375 File SHOULD NOT be shown to user unless specifically requested.
1376 For example, most UNIX systems SHOULD set this bit if the filename
1377 begins with a 'period'. This bit may be read-only (Section 5.4).
1378 Most UNIX systems will not allow this to be changed.
1379
1380 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE
1381 This attribute applies only to directories. This attribute is
1382 always read-only, and cannot be modified. This attribute means
1383 that files and directory names in this directory should be
1384 compared without regard to case.
1385
1386 It is recommended that where possible, the server's filesystem be
1387 allowed to do comparisons. For example, if a client wished to
1388 prompt a user before overwriting a file, it should not compare the
1389 new name with the previously retrieved list of names in the
1390 directory. Rather, it should first try to create the new file by
1391 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and
1392 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and
1393 then retry the create specifying SSH_FXF_CREATE_TRUNCATE.
1394
1395
1396
1397
1398
1399 Galbraith & Saarenmaa Expires July 29, 2006 [Page 25]
1400
1401 Internet-Draft SSH File Transfer Protocol January 2006
1402
1403
1404 Unless otherwise specified, filenames are assumed to be case
1405 sensitive.
1406
1407 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE
1408 The file should be included in backup / archive operations.
1409
1410 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED
1411 The file is stored on disk using file-system level transparent
1412 encryption. This flag does not affect the file data on the wire
1413 (for either READ or WRITE requests.)
1414
1415 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED
1416 The file is stored on disk using file-system level transparent
1417 compression. This flag does not affect the file data on the wire.
1418
1419 SSH_FILEXFER_ATTR_FLAGS_SPARSE
1420 The file is a sparse file; this means that file blocks that have
1421 not been explicitly written are not stored on disk. For example,
1422 if a client writes a buffer at 10 M from the beginning of the
1423 file, the blocks between the previous EOF marker and the 10 M
1424 offset would not consume physical disk space.
1425
1426 Some servers may store all files as sparse files, in which case
1427 this bit will be unconditionally set. Other servers may not have
1428 a mechanism for determining if the file is sparse, and so the file
1429 MAY be stored sparse even if this flag is not set.
1430
1431 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY
1432 Opening the file without either the SSH_FXF_APPEND_DATA or the
1433 SSH_FXF_APPEND_DATA_ATOMIC flag (Section 8.1.1.3) MUST result in
1434 an SSH_FX_INVALID_PARAMETER error.
1435
1436 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE
1437 The file cannot be deleted or renamed, no hard link can be created
1438 to this file, and no data can be written to the file.
1439
1440 This bit implies a stronger level of protection than
1441 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or
1442 ACLs. Typically even the superuser cannot write to immutable
1443 files, and only the superuser can set or remove the bit.
1444
1445 SSH_FILEXFER_ATTR_FLAGS_SYNC
1446 When the file is modified, the changes are written synchronously
1447 to the disk.
1448
1449
1450
1451
1452
1453
1454
1455 Galbraith & Saarenmaa Expires July 29, 2006 [Page 26]
1456
1457 Internet-Draft SSH File Transfer Protocol January 2006
1458
1459
1460 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR
1461 The server MAY include this bit in a directory listing or realpath
1462 response. It indicates there was a failure in the translation to
1463 UTF-8. If this flag is included, the server SHOULD also include
1464 the UNTRANSLATED_NAME attribute.
1465
1466
1467 7.10. text-hint
1468
1469 The value is one of the following enumerations, and indicates what
1470 the server knows about the content of the file.
1471
1472 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00
1473 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01
1474 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02
1475 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03
1476
1477 SSH_FILEXFER_ATTR_KNOWN_TEXT
1478 The server knows the file is a text file, and should be opened
1479 using the SSH_FXF_TEXT_MODE flag.
1480
1481 SSH_FILEXFER_ATTR_GUESSED_TEXT
1482 The server has applied a heuristic or other mechanism and believes
1483 that the file should be opened with the SSH_FXF_TEXT_MODE flag.
1484
1485 SSH_FILEXFER_ATTR_KNOWN_BINARY
1486 The server knows the file has binary content.
1487
1488 SSH_FILEXFER_ATTR_GUESSED_BINARY
1489 The server has applied a heuristic or other mechanism and believes
1490 has binary content, and should not be opened with the
1491 SSH_FXF_TEXT_MODE flag.
1492
1493
1494 This flag MUST NOT be present during either a setstat or a fsetstat
1495 operation.
1496
1497 7.11. mime-type
1498
1499 The 'mime-type' field contains the mime-type [RFC1521] string. Most
1500 servers will not know this information and should not set the bit in
1501 their supported-attribute-mask.
1502
1503 7.12. link-count
1504
1505 This field contains the hard link count of the file. This attribute
1506 MUST NOT be present during a setstat operation.
1507
1508
1509
1510
1511 Galbraith & Saarenmaa Expires July 29, 2006 [Page 27]
1512
1513 Internet-Draft SSH File Transfer Protocol January 2006
1514
1515
1516 7.13. untranslated-name
1517
1518 This field contains the name before filename translation was attempt.
1519 It MUST NOT be included unless the server also set the
1520 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 7.9) bit in the
1521 attrib-bits field.
1522
1523 7.14. Extended Attributes
1524
1525 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
1526 mechanism for the attrib structure. If the flag is specified, then
1527 the 'extended_count' field is present. It specifies the number of
1528 'extension-pair' items that follow. Each of these items specifies an
1529 extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED
1530 if there are any unrecognized extensions. Clients can avoid sending
1531 unsupported extensions by examining the attrib-extension-names of the
1532 "supported2" extension attrib-extension-names (Section 5.4).
1533
1534 Additional fields can be added to the attributes by either defining
1535 additional bits to the flags field to indicate their presence, or by
1536 defining extended attributes for them. The extended attributes
1537 mechanism is recommended for most purposes; additional flags bits
1538 should be defined only by an IETF standards action that also
1539 increments the protocol version number. The use of such new fields
1540 MUST be negotiated by the version number in the protocol exchange.
1541 It is a protocol error if a packet with unsupported protocol bits is
1542 received.
1543
1544
1545 8. Requests From the Client to the Server
1546
1547 Requests from the client to the server represent the various file
1548 system operations.
1549
1550 8.1. Opening and Closing Files and Directories
1551
1552 Many operations in the protocol operate on open files. The
1553 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is
1554 an opaque, variable-length string) which may be used to access the
1555 file or directory later. The client MUST NOT send requests to the
1556 server with bogus or closed handles. However, the server MUST
1557 perform adequate checks on the handle in order to avoid security
1558 risks due to fabricated handles.
1559
1560 This design allows either stateful and stateless server
1561 implementation, as well as an implementation which caches state
1562 between requests but may also flush it. The contents of the file
1563 handle string are entirely up to the server and its design. The
1564
1565
1566
1567 Galbraith & Saarenmaa Expires July 29, 2006 [Page 28]
1568
1569 Internet-Draft SSH File Transfer Protocol January 2006
1570
1571
1572 client should not modify or attempt to interpret the file handle
1573 strings.
1574
1575 The file handle strings MUST NOT be longer than 256 bytes.
1576
1577 8.1.1. Opening a File
1578
1579 Files are opened and created using the SSH_FXP_OPEN message.
1580
1581 byte SSH_FXP_OPEN
1582 uint32 request-id
1583 string filename [UTF-8]
1584 uint32 desired-access
1585 uint32 flags
1586 ATTRS attrs
1587
1588 The response to this message will be either SSH_FXP_HANDLE (if the
1589 operation is successful) or SSH_FXP_STATUS (if the operation fails.)
1590
1591 8.1.1.1. filename
1592
1593 The 'filename' field specifies the file name. See Section ''File
1594 Names'' for more information. If 'filename' is a directory file, the
1595 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error.
1596
1597 8.1.1.2. desired-access
1598
1599 The 'desired-access' field is a bitmask containing a combination of
1600 values from the ace-mask flags (Section 7.8). Note that again, the
1601 meaning of these flags is given in [RFC3010].
1602
1603 The server MUST be prepared to translate the SFTP access flags into
1604 its local equivalents. If the server cannot grant the access
1605 desired, it MUST return SSH_FX_PERMISSION_DENIED.
1606
1607 The server MAY open the file with greater access than requested if
1608 the user has such access and the server implementation requires it.
1609 For example, a server that does not distinguish between
1610 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access
1611 to the file when the client only requested READ_ATTRIBUTE, resulting
1612 in greater access than the client originally requested.
1613
1614 In such cases, it is possible, and permissible in the protocol, that
1615 the client could open a file requesting some limited access, and then
1616 access the file in a way not permitted by that limited access and the
1617 server would permit such action. However, the server MUST NOT ever
1618 grant access to the file that the client does not actually have the
1619 rights to.
1620
1621
1622
1623 Galbraith & Saarenmaa Expires July 29, 2006 [Page 29]
1624
1625 Internet-Draft SSH File Transfer Protocol January 2006
1626
1627
1628 8.1.1.3. flags
1629
1630 The 'flags' field controls various aspects of the operation,
1631 including whether or not the file is created and the kind of locking
1632 desired.
1633
1634 The following 'flags' are defined:
1635
1636 SSH_FXF_ACCESS_DISPOSITION = 0x00000007
1637 SSH_FXF_CREATE_NEW = 0x00000000
1638 SSH_FXF_CREATE_TRUNCATE = 0x00000001
1639 SSH_FXF_OPEN_EXISTING = 0x00000002
1640 SSH_FXF_OPEN_OR_CREATE = 0x00000003
1641 SSH_FXF_TRUNCATE_EXISTING = 0x00000004
1642 SSH_FXF_APPEND_DATA = 0x00000008
1643 SSH_FXF_APPEND_DATA_ATOMIC = 0x00000010
1644 SSH_FXF_TEXT_MODE = 0x00000020
1645 SSH_FXF_BLOCK_READ = 0x00000040
1646 SSH_FXF_BLOCK_WRITE = 0x00000080
1647 SSH_FXF_BLOCK_DELETE = 0x00000100
1648 SSH_FXF_BLOCK_ADVISORY = 0x00000200
1649 SSH_FXF_NOFOLLOW = 0x00000400
1650 SSH_FXF_DELETE_ON_CLOSE = 0x00000800
1651 SSH_FXF_ACCESS_AUDIT_ALARM_INFO = 0x00001000
1652 SSH_FXF_ACCESS_BACKUP = 0x00002000
1653 SSH_FXF_BACKUP_STREAM = 0x00004000
1654 SSH_FXF_OVERRIDE_OWNER = 0x00008000
1655
1656 SSH_FXF_ACCESS_DISPOSITION
1657 Disposition is a 3 bit field that controls how the file is opened.
1658 The server MUST support these bits. Any one of the following
1659 enumeration is allowed:
1660
1661 SSH_FXF_CREATE_NEW
1662 A new file is created; if the file already exists, the server
1663 MUST return status SSH_FX_FILE_ALREADY_EXISTS.
1664
1665 SSH_FXF_CREATE_TRUNCATE
1666 A new file is created; if the file already exists, it is opened
1667 and truncated.
1668
1669 SSH_FXF_OPEN_EXISTING
1670 An existing file is opened. If the file does not exist, the
1671 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the
1672 path does not exist, the server SHOULD return
1673 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server
1674 returns SSH_FX_NO_SUCH_FILE in this case.
1675
1676
1677
1678
1679 Galbraith & Saarenmaa Expires July 29, 2006 [Page 30]
1680
1681 Internet-Draft SSH File Transfer Protocol January 2006
1682
1683
1684 SSH_FXF_OPEN_OR_CREATE
1685 If the file exists, it is opened. If the file does not exist,
1686 it is created.
1687
1688 SSH_FXF_TRUNCATE_EXISTING
1689 An existing file is opened and truncated. If the file does not
1690 exist, the server MUST return the same error codes as defined
1691 for SSH_FXF_OPEN_EXISTING.
1692
1693 SSH_FXF_APPEND_DATA
1694 Data is always written at the end of the file. The offset field
1695 of the SSH_FXP_WRITE requests are ignored.
1696
1697 Data is not required to be appended atomically. This means that
1698 if multiple writers attempt to append data simultaneously, data
1699 from the first may be lost. However, data MAY be appended
1700 atomically.
1701
1702 SSH_FXF_APPEND_DATA_ATOMIC
1703 Data is always written at the end of the file. The offset field
1704 of the SSH_FXP_WRITE requests are ignored.
1705
1706 Data MUST be written atomically so that there is no chance that
1707 multiple appenders can collide and result in data being lost.
1708
1709 If both append flags are specified, the server SHOULD use atomic
1710 append if it is available, but SHOULD use non-atomic appends
1711 otherwise. The server SHOULD NOT fail the request in this case.
1712
1713 SSH_FXF_TEXT_MODE
1714 Indicates that the server should treat the file as text and
1715 convert it to the canonical newline convention in use. (See
1716 Determining Server Newline Convention. (Section 5.3)
1717
1718 When a file is opened with this flag, the offset field in the read
1719 and write functions is ignored.
1720
1721 Servers MUST process multiple, parallel reads and writes correctly
1722 in this mode. Naturally, it is permissible for them to do this by
1723 serializing the requests.
1724
1725 Clients SHOULD use the SSH_FXF_APPEND_DATA flag to append data to
1726 a text file rather then using write with a calculated offset.
1727
1728
1729
1730
1731
1732
1733
1734
1735 Galbraith & Saarenmaa Expires July 29, 2006 [Page 31]
1736
1737 Internet-Draft SSH File Transfer Protocol January 2006
1738
1739
1740 To support seeks on text files the following SSH_FXP_EXTENDED
1741 packet is defined.
1742
1743
1744 string "text-seek"
1745 string file-handle
1746 uint64 line-number
1747
1748 line-number is the index of the line number to seek to, where byte
1749 0 in the file is line number 0, and the byte directly following
1750 the first newline sequence in the file is line number 1 and so on.
1751
1752 The response to a "text-seek" request is an SSH_FXP_STATUS
1753 message.
1754
1755 An attempt to seek past the end-of-file should result in a
1756 SSH_FX_EOF status.
1757
1758 Servers SHOULD support at least one "text-seek" in order to
1759 support resume. However, a client MUST be prepared to receive
1760 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
1761 The client can then try a fall-back strategy, if it has one.
1762
1763 SSH_FXF_BLOCK_READ
1764 The server MUST guarantee that no other handle has been opened
1765 with ACE4_READ_DATA access, and that no other handle will be
1766 opened with ACE4_READ_DATA access until the client closes the
1767 handle. (This MUST apply both to other clients and to other
1768 processes on the server.)
1769
1770 If there is a conflicting lock the server MUST return
1771 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
1772 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
1773
1774 Other handles MAY be opened for ACE4_WRITE_DATA or any other
1775 combination of accesses, as long as ACE4_READ_DATA is not included
1776 in the mask.
1777
1778 SSH_FXF_BLOCK_WRITE
1779 The server MUST guarantee that no other handle has been opened
1780 with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other
1781 handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA
1782 access until the client closes the handle. (This MUST apply both
1783 to other clients and to other processes on the server.)
1784
1785
1786
1787
1788
1789
1790
1791 Galbraith & Saarenmaa Expires July 29, 2006 [Page 32]
1792
1793 Internet-Draft SSH File Transfer Protocol January 2006
1794
1795
1796 If there is a conflicting lock the server MUST return
1797 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
1798 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
1799
1800 Other handles MAY be opened for ACE4_READ_DATA or any other
1801 combination of accesses, as long as neither ACE4_WRITE_DATA nor
1802 ACE4_APPEND_DATA are included in the mask.
1803
1804 SSH_FXF_BLOCK_DELETE
1805 The server MUST guarantee that no other handle has been opened
1806 with ACE4_DELETE access, opened with the SSH_FXF_DELETE_ON_CLOSE
1807 flag set, and that no other handle will be opened with ACE4_DELETE
1808 access or with the SSH_FXF_DELETE_ON_CLOSE flag set, and that the
1809 file itself is not deleted in any other way until the client
1810 closes the handle.
1811
1812 If there is a conflicting lock the server MUST return
1813 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking
1814 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED.
1815
1816 SSH_FXF_BLOCK_ADVISORY
1817 If this bit is set, the above BLOCK modes are advisory. In
1818 advisory mode, only other accesses that specify a BLOCK mode need
1819 be considered when determining whether the BLOCK can be granted,
1820 and the server need not prevent I/O operations that violate the
1821 block mode.
1822
1823 The server MAY perform mandatory locking even if the
1824 BLOCK_ADVISORY bit is set.
1825
1826 SSH_FXF_NOFOLLOW
1827 If the final component of the path is a symlink, then the open
1828 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned.
1829
1830 SSH_FXF_DELETE_ON_CLOSE
1831 The file should be deleted when the last handle to it is closed.
1832 (The last handle may not be an sftp-handle.) This MAY be emulated
1833 by a server if the OS doesn't support it by deleting the file when
1834 this handle is closed.
1835
1836 It is implementation specific whether the directory entry is
1837 removed immediately or when the handle is closed.
1838
1839 SSH_FXF_ACCESS_AUDIT_ALARM_INFO
1840 The client wishes the server to enable any privileges or extra
1841 capabilities that the user may have in to allow the reading and
1842 writing of AUDIT or ALARM access control entries.
1843
1844
1845
1846
1847 Galbraith & Saarenmaa Expires July 29, 2006 [Page 33]
1848
1849 Internet-Draft SSH File Transfer Protocol January 2006
1850
1851
1852 SSH_FXF_ACCESS_BACKUP
1853 The client wishes the server to enable any privileges or extra
1854 capabilities that the user may have in order to bypass normal
1855 access checks for the purpose of backing up or restoring files.
1856
1857 SSH_FXF_BACKUP_STREAM
1858 This bit indicates that the client wishes to read or write a
1859 backup stream. A backup stream is a system dependent structured
1860 data stream that encodes all the information that must be
1861 preserved in order to restore the file from backup medium.
1862
1863 The only well defined use for backup stream data read in this
1864 fashion is to write it to the same server to a file also opened
1865 using the BACKUP_STREAM flag. However, if the server has a well
1866 defined backup stream format, their may be other uses for this
1867 data outside the scope of this protocol.
1868
1869 ACCESS_OVERRIDE_OWNER
1870 This bit indicates that the client wishes the server to enable any
1871 privileges or extra capabilities that the user may have in order
1872 to gain access to the file with WRITE_OWNER permission.
1873
1874 This bit MUST always be specified in combination with
1875 ACE4_WRITE_OWNER.
1876
1877
1878 The 'attrs' field specifies the initial attributes for the file.
1879 Default values MUST be supplied by the server for those attributes
1880 that are not specified. See Section ''File Attributes'' for more
1881 information.
1882
1883 The 'attrs' field is ignored if an existing file is opened.
1884
1885 The following table is provided to assist in mapping POSIX semantics
1886 to equivalent SFTP file open parameters:
1887 O_RDONLY
1888 desired-access = READ_DATA|READ_ATTRIBUTES
1889
1890 O_WRONLY
1891 desired-access = WRITE_DATA|WRITE_ATTRIBUTES
1892
1893 O_RDWR
1894 desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA|
1895 WRITE_ATTRIBUTES
1896
1897
1898
1899
1900
1901
1902
1903 Galbraith & Saarenmaa Expires July 29, 2006 [Page 34]
1904
1905 Internet-Draft SSH File Transfer Protocol January 2006
1906
1907
1908 O_APPEND
1909 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA
1910 flags = SSH_FXF_APPEND_DATA and or SSH_FXF_APPEND_DATA_ATOMIC
1911
1912 O_CREAT
1913 flags = SSH_FXF_OPEN_OR_CREATE
1914
1915 O_TRUNC
1916 flags = SSH_FXF_TRUNCATE_EXISTING
1917
1918 O_TRUNC|O_CREATE
1919 flags = SSH_FXF_CREATE_TRUNCATE
1920
1921 8.1.2. Opening a Directory
1922
1923 To enumerate a directory, the client first obtains a handle and then
1924 issues directory read requests. When enumeration is complete, the
1925 handle MUST be closed.
1926
1927 byte SSH_FXP_OPENDIR
1928 uint32 request-id
1929 string path [UTF-8]
1930
1931 path
1932 The 'path' field is the path name of the directory to be listed
1933 (without any trailing slash). See Section 'File Names' for more
1934 information on file names.
1935
1936 If 'path' does not refer to a directory, the server MUST return
1937 SSH_FX_NOT_A_DIRECTORY.
1938
1939
1940 The response to this message will be either SSH_FXP_HANDLE (if the
1941 operation is successful) or SSH_FXP_STATUS (if the operation fails).
1942
1943 8.1.3. Closing Handles
1944
1945 A handle is closed using the following request.
1946
1947 byte SSH_FXP_CLOSE
1948 uint32 request-id
1949 string handle
1950
1951 handle
1952 'handle' is a handle previously returned in the response to
1953 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid
1954 immediately after this request has been sent.
1955
1956
1957
1958
1959 Galbraith & Saarenmaa Expires July 29, 2006 [Page 35]
1960
1961 Internet-Draft SSH File Transfer Protocol January 2006
1962
1963
1964 The response to this request will be a SSH_FXP_STATUS message. Note
1965 that on some server platforms even a close can fail. For example, if
1966 the server operating system caches writes, and an error occurs while
1967 flushing cached writes, the close operation may fail.
1968
1969 Note that the handle is invalid regardless of the SSH_FXP_STATUS
1970 result. There is no way for the client to recover a handle that
1971 fails to close. The client MUST release all resources associated
1972 with the handle regardless of the status. The server SHOULD take
1973 whatever steps it can to recover from a close failure and to ensure
1974 that all resources associated with the handle on the server are
1975 correctly released.
1976
1977 8.2. Reading and Writing
1978
1979 8.2.1. Reading Files
1980
1981 The following request can be used to read file data:
1982
1983 byte SSH_FXP_READ
1984 uint32 request-id
1985 string handle
1986 uint64 offset
1987 uint32 length
1988
1989 handle
1990 'handle' is an open file handle returned by SSH_FXP_OPEN. If
1991 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST
1992 return SSH_FX_INVALID_HANDLE.
1993
1994 offset
1995 The offset (in bytes) relative to the beginning of the file that
1996 the read MUST start at. This field is ignored if
1997 SSH_FXF_TEXT_MODE was specified during the open.
1998
1999 length
2000 'length' is the maximum number of bytes to read.
2001
2002 The server MUST not respond with more data than is specified by
2003 the 'length' parameter. However, the server MAY respond with less
2004 data if EOF is reached, an error is encountered, or the servers
2005 internal buffers can not handle such a large request.
2006
2007 If the server specified a non-zero 'max-read-size' in its
2008 'supported2' (Section 5.4) extension, then failure to return
2009 'length' bytes indicates that EOF or an error occurred.
2010
2011
2012
2013
2014
2015 Galbraith & Saarenmaa Expires July 29, 2006 [Page 36]
2016
2017 Internet-Draft SSH File Transfer Protocol January 2006
2018
2019
2020 8.2.2. Reading Directories
2021
2022 In order to retrieve a directory listing, the client issues one or
2023 more SSH_FXP_READDIR requests. In order to obtain a complete
2024 directory listing, the client MUST issue repeated SSH_FXP_READDIR
2025 requests until the server responds with an SSH_FXP_STATUS message.
2026
2027 byte SSH_FXP_READDIR
2028 uint32 request-id
2029 string handle
2030
2031 handle
2032 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is
2033 an ordinary file handle returned by SSH_FXP_OPEN, the server MUST
2034 return SSH_FX_INVALID_HANDLE.
2035
2036
2037 The server responds to this request with either a SSH_FXP_NAME or a
2038 SSH_FXP_STATUS message. One or more names may be returned at a time.
2039 Full status information is returned for each name in order to speed
2040 up typical directory listings.
2041
2042 If there are no more names available to be read, the server MUST
2043 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.
2044
2045 8.2.3. Writing Files
2046
2047 Writing to a file is achieved using the following message:
2048
2049 byte SSH_FXP_WRITE
2050 uint32 request-id
2051 string handle
2052 uint64 offset
2053 string data
2054
2055 handle
2056 'handle' is an open file handle returned by SSH_FXP_OPEN. If
2057 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST
2058 return SSH_FX_INVALID_HANDLE.
2059
2060 offset
2061 The offset (in bytes) relative to the beginning of the file that
2062 the write MUST start at. This field is ignored if
2063 SSH_FXF_TEXT_MODE was specified during the open.
2064
2065
2066
2067
2068
2069
2070
2071 Galbraith & Saarenmaa Expires July 29, 2006 [Page 37]
2072
2073 Internet-Draft SSH File Transfer Protocol January 2006
2074
2075
2076 The write will extend the file if writing beyond the end of the
2077 file. It is legal to write to an offset that extends beyond the
2078 end of the file; the semantics are to write the byte value 0x00
2079 from the end of the file to the specified offset and then the
2080 data. On most operating systems, such writes do not allocate disk
2081 space but instead create a sparse file.
2082
2083 data
2084 The data to write to the file.
2085
2086 The server responds to a write request with a SSH_FXP_STATUS message.
2087
2088 8.3. Removing and Renaming Files
2089
2090 The following request can be used to remove a file:
2091
2092 byte SSH_FXP_REMOVE
2093 uint32 request-id
2094 string filename [UTF-8]
2095
2096 filename
2097 'filename' is the name of the file to be removed. See Section
2098 'File Names' for more information.
2099
2100 If 'filename' is a symbolic link, the link is removed, not the
2101 file it points to.
2102 This request cannot be used to remove directories. The server
2103 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case.
2104
2105
2106 The server will respond to this request with a SSH_FXP_STATUS
2107 message.
2108
2109 Files (and directories) can be renamed using the SSH_FXP_RENAME
2110 message.
2111
2112 byte SSH_FXP_RENAME
2113 uint32 request-id
2114 string oldpath [UTF-8]
2115 string newpath [UTF-8]
2116 uint32 flags
2117
2118 where 'request-id' is the request identifier, 'oldpath' is the name
2119 of an existing file or directory, and 'newpath' is the new name for
2120 the file or directory.
2121
2122 'flags' is 0 or a combination of:
2123
2124
2125
2126
2127 Galbraith & Saarenmaa Expires July 29, 2006 [Page 38]
2128
2129 Internet-Draft SSH File Transfer Protocol January 2006
2130
2131
2132 SSH_FXF_RENAME_OVERWRITE 0x00000001
2133 SSH_FXF_RENAME_ATOMIC 0x00000002
2134 SSH_FXF_RENAME_NATIVE 0x00000004
2135
2136 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already
2137 exists a file with the name specified by newpath, the server MUST
2138 respond with SSH_FX_FILE_ALREADY_EXISTS.
2139
2140 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file
2141 already exists, it is replaced in an atomic fashion. I.e., there is
2142 no observable instant in time where the name does not refer to either
2143 the old or the new file. SSH_FXP_RENAME_ATOMIC implies
2144 SSH_FXP_RENAME_OVERWRITE.
2145
2146 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace
2147 the destination in an atomic fashion, then the server MUST respond
2148 with SSH_FX_OP_UNSUPPORTED.
2149
2150 Because some servers cannot provide atomic rename, clients should
2151 only specify atomic rename if correct operation requires it. If
2152 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an
2153 atomic rename even if it is not requested.
2154
2155 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the
2156 rename operation in whatever fashion it deems appropriate. Other
2157 flag values are considered hints as to desired behavior, but not
2158 requirements.
2159
2160 The server will respond to this request with a SSH_FXP_STATUS
2161 message.
2162
2163 8.4. Creating and Deleting Directories
2164
2165 New directories can be created using the SSH_FXP_MKDIR request. It
2166 has the following format:
2167
2168 byte SSH_FXP_MKDIR
2169 uint32 request-id
2170 string path [UTF-8]
2171 ATTRS attrs
2172
2173 where 'request-id' is the request identifier.
2174
2175 'path' specifies the directory to be created. See Section ''File
2176 Names'' for more information on file names.
2177
2178 'attrs' specifies the attributes that should be applied to it upon
2179 creation. Attributes are discussed in more detail in Section ''File
2180
2181
2182
2183 Galbraith & Saarenmaa Expires July 29, 2006 [Page 39]
2184
2185 Internet-Draft SSH File Transfer Protocol January 2006
2186
2187
2188 Attributes''.
2189
2190 The server will respond to this request with a SSH_FXP_STATUS
2191 message. If a file or directory with the specified path already
2192 exists, an error will be returned.
2193
2194 Directories can be removed using the SSH_FXP_RMDIR request, which has
2195 the following format:
2196
2197 byte SSH_FXP_RMDIR
2198 uint32 request-id
2199 string path [UTF-8]
2200
2201 where 'request-id' is the request identifier, and 'path' specifies
2202 the directory to be removed. See Section ''File Names'' for more
2203 information on file names.
2204
2205 The server responds to this request with a SSH_FXP_STATUS message.
2206
2207 8.5. Retrieving File Attributes
2208
2209 Very often, file attributes are automatically returned by
2210 SSH_FXP_READDIR. However, sometimes there is need to specifically
2211 retrieve the attributes for a named file. This can be done using the
2212 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests.
2213
2214 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT
2215 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not
2216 follow symbolic links. Both have the same format:
2217
2218 byte SSH_FXP_STAT or SSH_FXP_LSTAT
2219 uint32 request-id
2220 string path [UTF-8]
2221 uint32 flags
2222
2223 where 'request-id' is the request identifier, and 'path' specifies
2224 the file system object for which status is to be returned. The
2225 server responds to this request with either SSH_FXP_ATTRS or
2226 SSH_FXP_STATUS.
2227
2228 The flags field specify the attribute flags in which the client has
2229 particular interest. This is a hint to the server. For example,
2230 because retrieving owner / group and acl information can be an
2231 expensive operation under some operating systems, the server may
2232 choose not to retrieve this information unless the client expresses a
2233 specific interest in it.
2234
2235 The client has no guarantee the server will provide all the fields
2236
2237
2238
2239 Galbraith & Saarenmaa Expires July 29, 2006 [Page 40]
2240
2241 Internet-Draft SSH File Transfer Protocol January 2006
2242
2243
2244 that it has expressed an interest in.
2245
2246 SSH_FXP_FSTAT differs from the others in that it returns status
2247 information for an open file (identified by the file handle).
2248
2249 byte SSH_FXP_FSTAT
2250 uint32 request-id
2251 string handle
2252 uint32 flags
2253
2254 handle
2255 'handle' is an open file handle from either SSH_FXP_OPEN or
2256 SSH_FXP_OPENDIR.
2257
2258
2259 The server responds to this request with SSH_FXP_ATTRS or
2260 SSH_FXP_STATUS.
2261
2262 8.6. Setting File Attributes
2263
2264 File attributes may be modified using the SSH_FXP_SETSTAT and
2265 SSH_FXP_FSETSTAT requests.
2266
2267 byte SSH_FXP_SETSTAT
2268 uint32 request-id
2269 string path [UTF-8]
2270 ATTRS attrs
2271
2272
2273 byte SSH_FXP_FSETSTAT
2274 uint32 request-id
2275 string handle
2276 ATTRS attrs
2277
2278 path
2279 The file system object (e.g. file or directory) whose attributes
2280 are to be modified. If this object does not exist, or the user
2281 does not have sufficient access to write the attributes, the
2282 request MUST fail.
2283
2284 handle
2285 'handle' is an open file handle from either SSH_FXP_OPEN or
2286 SSH_FXP_OPENDIR. If the handle was not opened with sufficient
2287 access to write the requested attributes, the request MUST fail.
2288
2289
2290
2291
2292
2293
2294
2295 Galbraith & Saarenmaa Expires July 29, 2006 [Page 41]
2296
2297 Internet-Draft SSH File Transfer Protocol January 2006
2298
2299
2300 attrs
2301 Specifies the modified attributes to be applied. Attributes are
2302 discussed in more detail in Section ''File Attributes''.
2303
2304 The server will respond with a SSH_FXP_STATUS message.
2305
2306 Because some systems must use separate system calls to set various
2307 attributes, it is possible that a failure response will be returned,
2308 but yet some of the attributes may be have been successfully
2309 modified. If possible, servers SHOULD avoid this situation; however,
2310 clients MUST be aware that this is possible.
2311
2312 8.7. Dealing with Links
2313
2314 The SSH_FXP_READLINK request reads the target of a symbolic link.
2315
2316 byte SSH_FXP_READLINK
2317 uint32 request-id
2318 string path [UTF-8]
2319
2320 where 'request-id' is the request identifier and 'path' specifies the
2321 path name of the symlink to be read.
2322
2323 The server will respond with a SSH_FXP_NAME packet containing only
2324 one name and a dummy attributes value. The name in the returned
2325 packet contains the target of the link. If an error occurs, the
2326 server MAY respond with SSH_FXP_STATUS.
2327
2328 The SSH_FXP_LINK request creates a link (either hard or symbolic) on
2329 the server.
2330
2331 byte SSH_FXP_LINK
2332 uint32 request-id
2333 string new-link-path [UTF-8]
2334 string existing-path [UTF-8]
2335 bool sym-link
2336
2337 new-link-path
2338 Specifies the path name of the new link to create.
2339
2340 existing-path
2341 Specifies the path of an existing file system object to which the
2342 new-link-path will refer.
2343
2344
2345
2346
2347
2348
2349
2350
2351 Galbraith & Saarenmaa Expires July 29, 2006 [Page 42]
2352
2353 Internet-Draft SSH File Transfer Protocol January 2006
2354
2355
2356 sym-link
2357 Specifies that the link should be a symbolic link, or a special
2358 file that redirects file system parsing to the resulting path. It
2359 is generally possible to create symbolic links across device
2360 boundaries; however, it is not required that a server support
2361 this.
2362
2363 If 'sym-link' is false, the link should be a hard link, or a
2364 second directory entry referring to the same file or directory
2365 object. It is generally not possible to create hard links across
2366 devices.
2367
2368
2369 The server shall respond with a SSH_FXP_STATUS. Clients should be
2370 aware that some servers may return SSH_FX_OP_UNSUPPORTED for either
2371 the hard-link, sym-link, or both operations.
2372
2373 8.8. Byte-range locks
2374
2375 SSH_FXP_BLOCK creates a byte-range lock on the file specified by the
2376 handle. The lock can be either mandatory (meaning that the server
2377 enforces that no other process or client can perform operations in
2378 violation of the lock) or advisory (meaning that no other process can
2379 obtain a conflicting lock, but the server does not enforce that no
2380 operation violates the lock.
2381
2382 A server MAY implement an advisory lock in a mandatory fashion; in
2383 other words, the server MAY enforce that no operation violates the
2384 lock even when operating in advisory mode.
2385
2386 The result is a SSH_FXP_STATUS return.
2387
2388 byte SSH_FXP_BLOCK
2389 uint32 request-id
2390 string handle
2391 uint64 offset
2392 uint64 length
2393 uint32 uLockMask
2394
2395 handle
2396 'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR.
2397 Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the
2398 handle is a directory handle.
2399
2400
2401
2402
2403
2404
2405
2406
2407 Galbraith & Saarenmaa Expires July 29, 2006 [Page 43]
2408
2409 Internet-Draft SSH File Transfer Protocol January 2006
2410
2411
2412 offset
2413 Beginning of the byte-range to lock.
2414
2415 length
2416 Number of bytes in the range to lock. The special value 0 means
2417 lock from 'offset' to the end of the file.
2418
2419 uLockMask
2420 A bit mask of SSH_FXF_BLOCK_* values; the meanings are described
2421 in Section 8.1.1.3.
2422
2423 SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the
2424 specified handle.
2425
2426 The result is a SSH_FXP_STATUS return.
2427
2428 byte SSH_FXP_UNBLOCK
2429 uint32 request-id
2430 string handle
2431 uint64 offset
2432 uint64 length
2433
2434 handle
2435 'handle' on which a SSH_FXP_BLOCK request has previously been
2436 issued.
2437
2438 offset
2439 Beginning of the byte-range to lock.
2440
2441 length
2442 Number of bytes in the range to lock. The special value 0 means
2443 lock from 'offset' to the end of the file.
2444
2445 8.9. Canonicalizing the Server-Side Path Name
2446
2447 The SSH_FXP_REALPATH request can be used to have the server
2448 canonicalize any given path name to an absolute path. This is useful
2449 for converting path names containing ".." components or relative
2450 pathnames without a leading slash into absolute paths. The format of
2451 the request is as follows:
2452
2453 byte SSH_FXP_REALPATH
2454 uint32 request-id
2455 string original-path [UTF-8]
2456 byte control-byte [optional]
2457 string compose-path[0..n] [optional]
2458
2459
2460
2461
2462
2463 Galbraith & Saarenmaa Expires July 29, 2006 [Page 44]
2464
2465 Internet-Draft SSH File Transfer Protocol January 2006
2466
2467
2468 original-path
2469 The first component of the path which the client wishes resolved
2470 into a absolute canonical path. This may be the entire path.
2471
2472 control-byte
2473
2474 SSH_FXP_REALPATH_NO_CHECK 0x00000001
2475 SSH_FXP_REALPATH_STAT_IF 0x00000002
2476 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003
2477
2478 This field is optional, and if it is not present in the packet, it
2479 is assumed to be SSH_FXP_REALPATH_NO_CHECK.
2480
2481 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT
2482 fail the request if the path does not exist, is hidden, or the
2483 user does not have access to the path or some component thereof.
2484 In addition, the path MUST NOT resolve symbolic links. This
2485 allows paths to be composed for the SSH_FXP_REMOVE command to
2486 remove symbolic links.
2487
2488 The server MAY fail the request if the path is not syntactically
2489 valid, or for other reasons.
2490
2491 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the
2492 path if it exists and is accessible to the client. However, if
2493 the path does not exist, isn't visible, or isn't accessible, the
2494 server MUST NOT fail the request. If the stat failed, the file
2495 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to
2496 distinguish between files that are actually
2497 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will have
2498 to issue a separate stat command in this case.
2499
2500 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat
2501 the path. If the stat operation fails, the server MUST fail the
2502 request.
2503
2504 compose-path
2505 A path which the client wishes the server to compose with the
2506 original path to form the new path. This field is optional, and
2507 if it is not present in the packet, it is assumed to be a zero
2508 length string.
2509
2510 The client may specify multiple 'compose-path' elements, in which
2511 case the server should build the resultant path up by applying
2512 each compose path to the accumulated result until all 'compose-
2513 path' elements have been applied.
2514
2515
2516
2517
2518
2519 Galbraith & Saarenmaa Expires July 29, 2006 [Page 45]
2520
2521 Internet-Draft SSH File Transfer Protocol January 2006
2522
2523
2524 The server MUST take the 'original-path' and apply the 'compose-path'
2525 as a modification to it. 'compose-path' MAY be relative to 'original-
2526 path' or may be an absolute path, in which case 'original-path' will
2527 be discarded. The 'compose-path' MAY be zero length.
2528
2529 The server will respond with a SSH_FXP_NAME packet containing the
2530 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK
2531 is specified, the attributes are dummy values.
2532
2533 8.9.1. Best Practice for Dealing with Paths
2534
2535 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING
2536
2537 Previous to this version, clients typically composed new paths
2538 themselves and then called both realpath and stat on the resulting
2539 path to get its canonical name and see if it really existed and was a
2540 directory.
2541
2542 This required clients to assume certain things about how a relative
2543 vs. realpath looked. The new realpath allows clients to no longer
2544 make those assumptions and to remove one round trip from the process
2545 and get deterministic behavior from all servers.
2546
2547 END: RFCEDITOR REMOVE BEFORE PUBLISHING
2548
2549 The client SHOULD treat the results of SSH_FXP_REALPATH as a
2550 canonical absolute path, even if the path does not appear to be
2551 absolute. A client that uses REALPATH(".", "") and treats the result
2552 as absolute, even if there is no leading slash, will continue to
2553 function correctly, even when talking to a Windows NT or VMS style
2554 system, where absolute paths may not begin with a slash.
2555
2556 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so
2557 that it does not need to know when a path is absolute or relative.
2558
2559 For example, if the client wishes to change directory up, and the
2560 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
2561 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS)
2562
2563 As a second example, if the client wishes transfer local file "a" to
2564 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the
2565 canonical path of the current directory, the client SHOULD send
2566 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This
2567 call will determine the correct path to use for the open request and
2568 whether the /b/d/e represents a directory.
2569
2570
2571
2572
2573
2574
2575 Galbraith & Saarenmaa Expires July 29, 2006 [Page 46]
2576
2577 Internet-Draft SSH File Transfer Protocol January 2006
2578
2579
2580 9. Responses from the Server to the Client
2581
2582 The server responds to the client using one of a few response
2583 packets. All requests can return a SSH_FXP_STATUS response upon
2584 failure. When the operation is successful, and no data needs to be
2585 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is
2586 appropriate.
2587
2588 Exactly one response will be returned for each request. Each
2589 response packet contains a request identifier which can be used to
2590 match each response with the corresponding request. Note that it is
2591 legal to have several requests outstanding simultaneously, and the
2592 server is allowed to send responses to them in a different order from
2593 the order in which the requests were sent (the result of their
2594 execution, however, is guaranteed to be as if they had been processed
2595 one at a time in the order in which the requests were sent).
2596
2597 Response packets are of the same general format as request packets.
2598 Each response packet begins with the request identifier.
2599
2600 9.1. Status Response
2601
2602 The format of the data portion of the SSH_FXP_STATUS response is as
2603 follows:
2604
2605 byte SSH_FXP_STATUS
2606 uint32 request-id
2607 uint32 error/status code
2608 string error message (ISO-10646 UTF-8 [RFC-2279])
2609 string language tag (as defined in [RFC-1766])
2610 error-specific data
2611
2612 request-id
2613 The 'request-id' specified by the client in the request the server
2614 is responding to.
2615
2616 error/status code
2617 Machine readable status code indicating the result of the request.
2618 Error code values are defined below. The value SSH_FX_OK
2619 indicates success, and all other values indicate failure.
2620
2621 Implementations MUST be prepared to receive unexpected error codes
2622 and handle them sensibly (such as by treating them as equivalent
2623 to SSH_FX_FAILURE). Future protocol revisions will add additional
2624 error codes without changing the version number.
2625
2626
2627
2628
2629
2630
2631 Galbraith & Saarenmaa Expires July 29, 2006 [Page 47]
2632
2633 Internet-Draft SSH File Transfer Protocol January 2006
2634
2635
2636 error message
2637 Human readable description of the error.
2638
2639 language tag
2640 'language tag' specifies the language the error is in.
2641
2642 error-specific data
2643 The error-specific data may be empty, or may contain additional
2644 information about the error. For error codes that send error-
2645 specific data, the format of the data is defined below.
2646
2647 Error codes:
2648
2649 SSH_FX_OK 0
2650 SSH_FX_EOF 1
2651 SSH_FX_NO_SUCH_FILE 2
2652 SSH_FX_PERMISSION_DENIED 3
2653 SSH_FX_FAILURE 4
2654 SSH_FX_BAD_MESSAGE 5
2655 SSH_FX_NO_CONNECTION 6
2656 SSH_FX_CONNECTION_LOST 7
2657 SSH_FX_OP_UNSUPPORTED 8
2658 SSH_FX_INVALID_HANDLE 9
2659 SSH_FX_NO_SUCH_PATH 10
2660 SSH_FX_FILE_ALREADY_EXISTS 11
2661 SSH_FX_WRITE_PROTECT 12
2662 SSH_FX_NO_MEDIA 13
2663 SSH_FX_NO_SPACE_ON_FILESYSTEM 14
2664 SSH_FX_QUOTA_EXCEEDED 15
2665 SSH_FX_UNKNOWN_PRINCIPAL 16
2666 SSH_FX_LOCK_CONFLICT 17
2667 SSH_FX_DIR_NOT_EMPTY 18
2668 SSH_FX_NOT_A_DIRECTORY 19
2669 SSH_FX_INVALID_FILENAME 20
2670 SSH_FX_LINK_LOOP 21
2671 SSH_FX_CANNOT_DELETE 22
2672 SSH_FX_INVALID_PARAMETER 23
2673 SSH_FX_FILE_IS_A_DIRECTORY 24
2674 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25
2675 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26
2676 SSH_FX_DELETE_PENDING 27
2677 SSH_FX_FILE_CORRUPT 28
2678 SSH_FX_OWNER_INVALID 29
2679 SSH_FX_GROUP_INVALID 30
2680
2681
2682
2683
2684
2685
2686
2687 Galbraith & Saarenmaa Expires July 29, 2006 [Page 48]
2688
2689 Internet-Draft SSH File Transfer Protocol January 2006
2690
2691
2692 SSH_FX_OK
2693 Indicates successful completion of the operation.
2694
2695 SSH_FX_EOF
2696 An attempt to read past the end-of-file was made; or, there are no
2697 more directory entries to return.
2698
2699 SSH_FX_NO_SUCH_FILE
2700 A reference was made to a file which does not exist.
2701
2702 SSH_FX_PERMISSION_DENIED
2703 The user does not have sufficient permissions to perform the
2704 operation.
2705
2706 SSH_FX_FAILURE
2707 An error occurred, but no specific error code exists to describe
2708 the failure.
2709
2710 This error message SHOULD always have meaningful text in the the
2711 'error message' field.
2712
2713 SSH_FX_BAD_MESSAGE
2714 A badly formatted packet or other SFTP protocol incompatibility
2715 was detected.
2716
2717 SSH_FX_NO_CONNECTION
2718 There is no connection to the server. This error MAY be used
2719 locally, but MUST NOT be return by a server.
2720
2721 SSH_FX_CONNECTION_LOST
2722 The connection to the server was lost. This error MAY be used
2723 locally, but MUST NOT be return by a server.
2724
2725 SSH_FX_OP_UNSUPPORTED
2726 An attempted operation could not be completed by the server
2727 because the server does not support the operation.
2728
2729 This error MAY be generated locally by the client if e.g. the
2730 version number exchange indicates that a required feature is not
2731 supported by the server, or it may be returned by the server if
2732 the server does not implement an operation.
2733
2734 SSH_FX_INVALID_HANDLE
2735 The handle value was invalid.
2736
2737
2738
2739
2740
2741
2742
2743 Galbraith & Saarenmaa Expires July 29, 2006 [Page 49]
2744
2745 Internet-Draft SSH File Transfer Protocol January 2006
2746
2747
2748 SSH_FX_NO_SUCH_PATH
2749 The file path does not exist or is invalid.
2750
2751 SSH_FX_FILE_ALREADY_EXISTS
2752 The file already exists.
2753
2754 SSH_FX_WRITE_PROTECT
2755 The file is on read-only media, or the media is write protected.
2756
2757 SSH_FX_NO_MEDIA
2758 The requested operation cannot be completed because there is no
2759 media available in the drive.
2760
2761 SSH_FX_NO_SPACE_ON_FILESYSTEM
2762 The requested operation cannot be completed because there is no
2763 free space on the filesystem.
2764
2765 SSH_FX_QUOTA_EXCEEDED
2766 The operation cannot be completed because it would exceed the
2767 user's storage quota.
2768
2769 SSH_FX_UNKNOWN_PRINCIPAL
2770 A principal referenced by the request (either the 'owner',
2771 'group', or 'who' field of an ACL), was unknown. The error
2772 specific data contains the problematic names. The format is one
2773 or more:
2774
2775 string unknown-name
2776
2777 Each string contains the name of a principal that was unknown.
2778
2779 SSH_FX_LOCK_CONFLICT
2780 The file could not be opened because it is locked by another
2781 process.
2782
2783 SSH_FX_DIR_NOT_EMPTY
2784 The directory is not empty.
2785
2786 SSH_FX_NOT_A_DIRECTORY
2787 The specified file is not a directory.
2788
2789 SSH_FX_INVALID_FILENAME
2790 The filename is not valid.
2791
2792
2793
2794
2795
2796
2797
2798
2799 Galbraith & Saarenmaa Expires July 29, 2006 [Page 50]
2800
2801 Internet-Draft SSH File Transfer Protocol January 2006
2802
2803
2804 SSH_FX_LINK_LOOP
2805 Too many symbolic links encountered.
2806
2807 SSH_FX_CANNOT_DELETE
2808 The file cannot be deleted. One possible reason is that the
2809 advisory READONLY attribute-bit is set.
2810
2811 SSH_FX_INVALID_PARAMETER
2812 On of the parameters was out of range, or the parameters specified
2813 cannot be used together.
2814
2815 SSH_FX_FILE_IS_A_DIRECTORY
2816 The specified file was a directory in a context where a directory
2817 cannot be used.
2818
2819 SSH_FX_BYTE_RANGE_LOCK_CONFLICT
2820 A read or write operation failed because another process's
2821 mandatory byte-range lock overlaps with the request.
2822
2823 SSH_FX_BYTE_RANGE_LOCK_REFUSED
2824 A request for a byte range lock was refused.
2825
2826 SSH_FX_DELETE_PENDING
2827 An operation was attempted on a file for which a delete operation
2828 is pending.
2829
2830 SSH_FX_FILE_CORRUPT
2831 The file is corrupt; an filesystem integrity check should be run.
2832
2833 SSH_FX_OWNER_INVALID
2834 The principal specified can not be assigned as an owner of a file.
2835
2836 SSH_FX_GROUP_INVALID
2837 The principal specified can not be assigned as the primary group
2838 of a file.
2839
2840
2841 9.2. Handle Response
2842
2843 The SSH_FXP_HANDLE response has the following format:
2844
2845 byte SSH_FXP_HANDLE
2846 uint32 request-id
2847 string handle
2848
2849
2850
2851
2852
2853
2854
2855 Galbraith & Saarenmaa Expires July 29, 2006 [Page 51]
2856
2857 Internet-Draft SSH File Transfer Protocol January 2006
2858
2859
2860 'handle'
2861 An arbitrary string that identifies an open file or directory on
2862 the server. The handle is opaque to the client; the client MUST
2863 NOT attempt to interpret or modify it in any way. The length of
2864 the handle string MUST NOT exceed 256 data bytes.
2865
2866
2867 9.3. Data Response
2868
2869 The SSH_FXP_DATA response has the following format:
2870
2871 byte SSH_FXP_DATA
2872 uint32 request-id
2873 string data
2874 bool end-of-file [optional]
2875
2876 data
2877 'data' is an arbitrary byte string containing the requested data.
2878 The data string may be at most the number of bytes requested in a
2879 SSH_FXP_READ request, but may also be shorter. (See
2880 Section 8.2.1.)
2881
2882 end-of-file
2883 This field is optional. If it is present in the packet, it MUST
2884 be true, and it indicates that EOF was reached during this read.
2885 This can help the client avoid a round trip to determine whether a
2886 short read was normal (due to EOF) or some other problem (limited
2887 server buffer for example.)
2888
2889
2890 9.4. Name Response
2891
2892 The SSH_FXP_NAME response has the following format:
2893
2894 byte SSH_FXP_NAME
2895 uint32 request-id
2896 uint32 count
2897 repeats count times:
2898 string filename [UTF-8]
2899 ATTRS attrs
2900 bool end-of-list [optional]
2901
2902 count
2903 The number of names returned in this response, and the 'filename'
2904 and 'attrs' field repeat 'count' times.
2905
2906
2907
2908
2909
2910
2911 Galbraith & Saarenmaa Expires July 29, 2006 [Page 52]
2912
2913 Internet-Draft SSH File Transfer Protocol January 2006
2914
2915
2916 filename
2917 A file name being returned (for SSH_FXP_READDIR, it will be a
2918 relative name within the directory, without any path components;
2919 for SSH_FXP_REALPATH it will be an absolute path name.)
2920
2921 attrs
2922 The attributes of the file as described in Section ''File
2923 Attributes''.
2924
2925 end-of-list
2926 If this field is present and true, there are no more entries to be
2927 read.
2928
2929
2930 9.5. Attrs Response
2931
2932 The SSH_FXP_ATTRS response has the following format:
2933
2934 byte SSH_FXP_ATTRS
2935 uint32 request-id
2936 ATTRS attrs
2937
2938 attrs
2939 The returned file attributes as described in Section ''File
2940 Attributes''.
2941
2942
2943
2944 10. Extensions
2945
2946 The SSH_FXP_EXTENDED request provides a generic extension mechanism
2947 for adding additional commands.
2948
2949 byte SSH_FXP_EXTENDED
2950 uint32 request-id
2951 string extended-request
2952 ... any request-specific data ...
2953
2954 request-id
2955 Identifier to be returned from the server with the response.
2956
2957 extended-request
2958 A string naming the extension, following the the DNS extensibility
2959 naming convention outlined in [RFC4251], or defined by IETF
2960 consensus.
2961
2962
2963
2964
2965
2966
2967 Galbraith & Saarenmaa Expires July 29, 2006 [Page 53]
2968
2969 Internet-Draft SSH File Transfer Protocol January 2006
2970
2971
2972 request-specific data
2973 The rest of the request is defined by the extension; servers
2974 SHOULD NOT attempt to interpret it if they do not recognize the
2975 'extended-request' name.
2976
2977 The server may respond to such requests using any of the response
2978 packets defined in Section ''Responses from the Server to the
2979 Client''. Additionally, the server may also respond with a
2980 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does
2981 not recognize the 'extended-request' name, then the server MUST
2982 respond with SSH_FXP_STATUS with error/status set to
2983 SSH_FX_OP_UNSUPPORTED.
2984
2985 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
2986 extension-specific data from the server to the client. It is of the
2987 following format:
2988
2989 byte SSH_FXP_EXTENDED_REPLY
2990 uint32 request-id
2991 ... any request-specific data ...
2992
2993 There is a range of packet types reserved for use by extensions. In
2994 order to avoid collision, extensions that that use additional packet
2995 types should determine those numbers dynamically.
2996
2997 The suggested way of doing this is have an extension request from the
2998 client to the server that enables the extension; the extension
2999 response from the server to the client would specify the actual type
3000 values to use, in addition to any other data.
3001
3002 Extension authors should be mindful of the limited range of packet
3003 types available (there are only 45 values available) and avoid
3004 requiring a new packet type where possible.
3005
3006
3007 11. Implementation Considerations
3008
3009 In order for this protocol to perform well, especially over high
3010 latency networks, multiple read and write requests should be queued
3011 to the server.
3012
3013 The data size of requests should match the maximum packet size for
3014 the next layer up in the protocol chain.
3015
3016 When implemented over ssh, the best performance should be achieved
3017 when the data size matches the channel's max packet, and the channel
3018 window is a multiple of the channel packet size.
3019
3020
3021
3022
3023 Galbraith & Saarenmaa Expires July 29, 2006 [Page 54]
3024
3025 Internet-Draft SSH File Transfer Protocol January 2006
3026
3027
3028 Implementations MUST be aware that requests do not have to be
3029 satisfied in the order issued. (See Request Synchronization and
3030 Reordering (Section 4.1).)
3031
3032 Implementations MUST also be aware that read requests may not return
3033 all the requested data, even if the data is available.
3034
3035
3036 12. IANA Considerations
3037
3038 An IANA registry needs to be created containing:
3039 o The packet types define defined in Section 4.3
3040 o The extension specified in this draft, which are: 'text-seek',
3041 'supported2', 'acl-supported', 'newline', 'versions', 'version-
3042 select', 'filename-charset', 'filename-translation-control'
3043
3044
3045 13. Security Considerations
3046
3047 It is assumed that both ends of the connection have been
3048 authenticated and that the connection has privacy and integrity
3049 features. Such security issues are left to the underlying transport
3050 protocol, except to note that if this is not the case, an attacker
3051 could manipulate files on the server at will and thus wholly
3052 compromise the server.
3053
3054 This protocol provides file system access to arbitrary files on the
3055 server (constrained only by the server implementation). It is the
3056 responsibility of the server implementation to enforce any access
3057 controls that may be required to limit the access allowed for any
3058 particular user (the user being authenticated externally to this
3059 protocol, typically using [RFC4252].
3060
3061 Extreme care must be used when interpreting file handle strings. In
3062 particular, care must be taken that a file handle string is valid in
3063 the context of a given 'file-share' session. For example, the 'file-
3064 share' server daemon may have files which it has opened for its own
3065 purposes, and the client must not be able to access these files by
3066 specifying an arbitrary file handle string.
3067
3068 The permission field of the attrib structure (Section 7.6) may
3069 include the SUID, SGID, and SVTX (sticky) bits. Clients should use
3070 extreme caution when setting these bits on either remote or local
3071 files. (I.e., just because a file was SUID on the remote system does
3072 not necessarily imply that it should be SUID on the local system.)
3073
3074 Filesystems often contain entries for objects that are not files at
3075 all, but are rather devices. For example, it may be possible to
3076
3077
3078
3079 Galbraith & Saarenmaa Expires July 29, 2006 [Page 55]
3080
3081 Internet-Draft SSH File Transfer Protocol January 2006
3082
3083
3084 access serial ports, tape devices, or named pipes using this
3085 protocol. Servers should exercise caution when granting access to
3086 such resources. In addition to the dangers inherent in allowing
3087 access to such a device, some devices may be 'slow', and could cause
3088 denial of service by causing the server to block for a long period of
3089 time while I/O is performed to such a device.
3090
3091 Servers should take care that file-system quotas are respected for
3092 users. In addition, implementations should be aware that attacks may
3093 be possible, or facilitated, by filling a filesystem. For example,
3094 filling the filesystem where event logging and auditing occurs may,
3095 at best, cause the system to crash, or at worst, allow the attacker
3096 to take untraceable actions in the future.
3097
3098 Servers should take care that filenames are in their appropriate
3099 canonical form, and to ensure that filenames not in canonical form
3100 cannot be used to bypass access checks or controls.
3101
3102 If the server implementation limits access to certain parts of the
3103 file system, extra care must be taken in parsing file names which
3104 contain the '..' path element, and when following symbolic links,
3105 shortcuts, or other filesystem objects which might transpose the path
3106 to refer to an object outside of the restricted area. There have
3107 been numerous reported security bugs where a ".." in a path name has
3108 allowed access outside the intended area.
3109
3110
3111 14. Changes from Previous Protocol Versions
3112
3113 RFC EDITOR: PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING
3114
3115 Please refer to the following web page for pervious versions of the
3116 protocol:
3117
3118 http://tools.ietf.org/wg/secsh/draft-ietf-secsh-filexfer/
3119
3120 RFC EDITOR: END PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING
3121
3122
3123 15. References
3124
3125 15.1. Normative References
3126
3127 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R.,
3128 Beame, C., Eisler, M., and D. Noveck, "NFS version 4
3129 Protocol", RFC 3010, December 2000.
3130
3131 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
3132
3133
3134
3135 Galbraith & Saarenmaa Expires July 29, 2006 [Page 56]
3136
3137 Internet-Draft SSH File Transfer Protocol January 2006
3138
3139
3140 Protocol Architecture", RFC 4251, January 2006.
3141
3142 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
3143 Transport Layer Protocol", RFC 4253, January 2006.
3144
3145 [RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
3146 Connection Protocol", RFC 4254, January 2006.
3147
3148 [IEEE.1003-1.1996]
3149 Institute of Electrical and Electronics Engineers,
3150 "Information Technology - Portable Operating System
3151 Interface (POSIX) - Part 1: System Application Program
3152 Interface (API) [C Language]", IEEE Standard 1003.2, 1996.
3153
3154 15.2. Informative References
3155
3156 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet
3157 Mail Extensions) Part One: Mechanisms for Specifying and
3158 Describing the Format of Internet Message Bodies",
3159 RFC 1521, September 1993.
3160
3161 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
3162 RFC 2246, January 1999.
3163
3164 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
3165 Languages", BCP 18, RFC 2277, January 1998.
3166
3167 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
3168 Authentication Protocol", RFC 4252, January 2006.
3169
3170 Trademark notice
3171
3172 "ssh" is a registered trademark in the United States and/or other
3173 countries.
3174
3175
3176
3177
3178
3179
3180
3181
3182
3183
3184
3185
3186
3187
3188
3189
3190
3191 Galbraith & Saarenmaa Expires July 29, 2006 [Page 57]
3192
3193 Internet-Draft SSH File Transfer Protocol January 2006
3194
3195
3196 Authors' Addresses
3197
3198 Joseph Galbraith
3199 VanDyke Software
3200 4848 Tramway Ridge Blvd
3201 Suite 101
3202 Albuquerque, NM 87111
3203 US
3204
3205 Phone: +1 505 332 5700
3206 Email: galb-list@vandyke.com
3207
3208
3209 Oskari Saarenmaa
3210 F-Secure
3211 Tammasaarenkatu 7
3212 Helsinki 00180
3213 FI
3214
3215 Email: oskari.saarenmaa@f-secure.com
3216
3217
3218
3219
3220
3221
3222
3223
3224
3225
3226
3227
3228
3229
3230
3231
3232
3233
3234
3235
3236
3237
3238
3239
3240
3241
3242
3243
3244
3245
3246
3247 Galbraith & Saarenmaa Expires July 29, 2006 [Page 58]
3248
3249 Internet-Draft SSH File Transfer Protocol January 2006
3250
3251
3252 Intellectual Property Statement
3253
3254 The IETF takes no position regarding the validity or scope of any
3255 Intellectual Property Rights or other rights that might be claimed to
3256 pertain to the implementation or use of the technology described in
3257 this document or the extent to which any license under such rights
3258 might or might not be available; nor does it represent that it has
3259 made any independent effort to identify any such rights. Information
3260 on the procedures with respect to rights in RFC documents can be
3261 found in BCP 78 and BCP 79.
3262
3263 Copies of IPR disclosures made to the IETF Secretariat and any
3264 assurances of licenses to be made available, or the result of an
3265 attempt made to obtain a general license or permission for the use of
3266 such proprietary rights by implementers or users of this
3267 specification can be obtained from the IETF on-line IPR repository at
3268 http://www.ietf.org/ipr.
3269
3270 The IETF invites any interested party to bring to its attention any
3271 copyrights, patents or patent applications, or other proprietary
3272 rights that may cover technology that may be required to implement
3273 this standard. Please address the information to the IETF at
3274 ietf-ipr@ietf.org.
3275
3276
3277 Disclaimer of Validity
3278
3279 This document and the information contained herein are provided on an
3280 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
3281 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
3282 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
3283 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
3284 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
3285 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
3286
3287
3288 Copyright Statement
3289
3290 Copyright (C) The Internet Society (2006). This document is subject
3291 to the rights, licenses and restrictions contained in BCP 78, and
3292 except as set forth therein, the authors retain all their rights.
3293
3294
3295 Acknowledgment
3296
3297 Funding for the RFC Editor function is currently provided by the
3298 Internet Society.
3299
3300
3301
3302
3303 Galbraith & Saarenmaa Expires July 29, 2006 [Page 59]
3304
3305
+674
-0
rfc/draft-ietf-secsh-filexfer-extensions-00.txt less more
0
1
2
3
4 Secure Shell Working Group J. Galbraith
5 Internet-Draft VanDyke Software
6 Expires: July 22, 2006 O. Saarenmaa
7 F-Secure
8 January 18, 2006
9
10
11 SSH File Transfer Protocol
12 draft-ietf-secsh-filexfer-extensions-00.txt
13
14 Status of this Memo
15
16 By submitting this Internet-Draft, each author represents that any
17 applicable patent or other IPR claims of which he or she is aware
18 have been or will be disclosed, and any of which he or she becomes
19 aware will be disclosed, in accordance with Section 6 of BCP 79.
20
21 Internet-Drafts are working documents of the Internet Engineering
22 Task Force (IETF), its areas, and its working groups. Note that
23 other groups may also distribute working documents as Internet-
24 Drafts.
25
26 Internet-Drafts are draft documents valid for a maximum of six months
27 and may be updated, replaced, or obsoleted by other documents at any
28 time. It is inappropriate to use Internet-Drafts as reference
29 material or to cite them other than as "work in progress."
30
31 The list of current Internet-Drafts can be accessed at
32 http://www.ietf.org/ietf/1id-abstracts.txt.
33
34 The list of Internet-Draft Shadow Directories can be accessed at
35 http://www.ietf.org/shadow.html.
36
37 This Internet-Draft will expire on July 22, 2006.
38
39 Copyright Notice
40
41 Copyright (C) The Internet Society (2006).
42
43 Abstract
44
45 The SSH File Transfer Protocol provides a rich infrastructure for
46 sharing information about files. This document describes several
47 optional extensions that build on this infrastructure.
48
49
50
51
52
53
54
55 Galbraith & Saarenmaa Expires July 22, 2006 [Page 1]
56
57 Internet-Draft SSH File Transfer Protocol January 2006
58
59
60 Table of Contents
61
62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
63 2. Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . . . 3
64 3. File Hashing . . . . . . . . . . . . . . . . . . . . . . . . . 4
65 4. Querying Available Space . . . . . . . . . . . . . . . . . . . 6
66 5. Querying User Home Directory . . . . . . . . . . . . . . . . . 7
67 6. Copying Remote Files . . . . . . . . . . . . . . . . . . . . . 7
68 7. Copying remote data . . . . . . . . . . . . . . . . . . . . . 7
69 8. Temporary files & directories . . . . . . . . . . . . . . . . 8
70 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9
71 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9
72 10.1. Normative References . . . . . . . . . . . . . . . . . . 9
73 10.2. Informative References . . . . . . . . . . . . . . . . . 9
74 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11
75 Intellectual Property and Copyright Statements . . . . . . . . . . 12
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111 Galbraith & Saarenmaa Expires July 22, 2006 [Page 2]
112
113 Internet-Draft SSH File Transfer Protocol January 2006
114
115
116 1. Introduction
117
118 This is a collection of optional extensions to the SSH File Transfer
119 Protocol [I-D.ietf-secsh-filexfer]. This extensions make it possible
120 for clients to query the server for additional information which may
121 not be widely supported, but can increase the quality of the users
122 experience when the server can support them.
123
124
125 2. Vendor Id
126
127 It is often necessary to detect the version of the server so that
128 bugs can be worked around. This extension allows the client to do
129 so.
130
131 string "vendor-id"
132 string vendor-structure
133 string vendor-name [UTF-8]
134 string product-name [UTF-8]
135 string product-version [UTF-8]
136 uint64 product-build-number
137
138 vendor-name
139 Arbitrary name identifying the maker of the product.
140
141 product-name
142 Arbitrary name identifying the product.
143
144 product-name
145 Arbitrary string identifying the version of the product.
146
147 product-build-number
148 A build-number for the product, such that if a bug is fixed in
149 build-number 'x', it can be assumed that (barring regression in
150 the product) it is fixed in all build-numbers > 'x'.
151
152
153 This extension may also be sent by the client as a SSH_FXP_EXTENDED
154 packet; in this case the contents of the vendor-structure become the
155 extension-specific data:
156
157 byte SSH_FXP_EXTENDED
158 uint32 request-id
159 string "vendor-id"
160 string vendor-name [UTF-8]
161 string product-name [UTF-8]
162 string product-version [UTF-8]
163 uint64 product-build-number
164
165
166
167 Galbraith & Saarenmaa Expires July 22, 2006 [Page 3]
168
169 Internet-Draft SSH File Transfer Protocol January 2006
170
171
172 The server responds to this request with a SSH_FXP_STATUS message.
173 The status SHOULD be SSH_FX_OK.
174
175
176 3. File Hashing
177
178 This extension allows a client to easily check if a file (or portion
179 thereof) that it already has matches what is on the server.
180
181 byte SSH_FXP_EXTENDED
182 uint32 request-id
183 string "check-file-handle" / "check-file-name"
184 string handle / name
185 string hash-algorithm-list
186 uint64 start-offset
187 uint64 length
188 uint32 block-size
189
190 handle
191 For "check-file-handle", 'handle' is an open file handle returned
192 by SSH_FXP_OPEN. If 'handle' is not a handle returned by
193 SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. If
194 ACE4_READ_DATA was not included when the file was opened, the
195 server MUST return STATUS_PERMISSION_DENIED.
196
197 If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode,
198 the check must be performed on the data as it would be sent on the
199 wire.
200
201 name
202 For "check-file-name", 'name' is the path to the file to check.
203 If 'check-file-name' is a directory, SSH_FX_FILE_IS_A_DIRECTORY
204 SHOULD be returned. If 'check-file-name' refers to a
205 SSH_FILEXFER_TYPE_SYMLINK, the target should be opened. The
206 results are undefined file types other than
207 SSH_FILEXFER_TYPE_REGULAR.
208
209 The file MUST be opened without the SSH_FXF_ACCESS_TEXT_MODE
210 access flag (in binary mode.)
211
212 hash-algorithm-list
213 A comma separated list of hash algorithms the client is willing to
214 accept for this operation. The server MUST pick the first hash on
215 the list that it supports.
216
217
218
219
220
221
222
223 Galbraith & Saarenmaa Expires July 22, 2006 [Page 4]
224
225 Internet-Draft SSH File Transfer Protocol January 2006
226
227
228 Currently defined algorithms are "md5", "sha1", "sha224",
229 "sha256", "sha384", "sha512", and "crc32". Additional algorithms
230 may be added by following the DNS extensibility naming convention
231 outlined in [RFC4251].
232
233 MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384,
234 and SHA-512 are described in [FIPS-180-2]. [ISO.3309.1991]
235 describes crc32, and is the same algorithm used in [RFC1510]
236
237 start-offset
238 The starting offset of the data to include in the hash.
239
240 length
241 The length of data to include in the hash. If length is zero, all
242 the data from start-offset to the end-of-file should be included.
243
244 block-size
245 An independent hash MUST be computed over every block in the file.
246 The size of blocks is specified by block-size. The block-size
247 MUST NOT be smaller than 256 bytes. If the block-size is 0, then
248 only one hash, over the entire range, MUST be made.
249
250
251 The response is either a SSH_FXP_STATUS packet, indicating an error,
252 or the following extended reply packet:
253
254 This extension MUST be represented in the "supported2" extension as
255 "check-file" and both version MUST either be support or neither.
256
257 byte SSH_FXP_EXTENDED_REPLY
258 uint32 request-id
259 string hash-algo-used
260 byte hash[n][block-count]
261
262 hash-algo-used
263 The hash algorithm that was actually used.
264
265 hash
266 The computed hashes. The hash algorithm used determines the size
267 of n. The number of block-size chunks of data in the file
268 determines block-count. The hashes are placed in the packet one
269 after another, with no decoration.
270
271 Note that if the length of the range is not an even multiple of
272 block-size, the last hash will have been computed over only the
273 remainder of the range instead of a full block.
274
275
276
277
278
279 Galbraith & Saarenmaa Expires July 22, 2006 [Page 5]
280
281 Internet-Draft SSH File Transfer Protocol January 2006
282
283
284 4. Querying Available Space
285
286 The following extension provides a way to discover the available
287 space for an arbitrary path.
288
289 byte SSH_FXP_EXTENDED
290 uint32 request-id
291 string "space-available"
292 string path [UTF-8]
293
294 path
295 'path' for which the available space should be reported. This
296 'path' is not required to be the mount point path, but MAY be a
297 directory or file contained within the mount.
298
299 The reply to the request is as follows:
300
301 byte SSH_FXP_EXTENDED_REPLY
302 uint32 request-id
303 uint64 bytes-on-device
304 uint64 unused-bytes-on-device
305 uint64 bytes-available-to-user
306 uint64 unused-bytes-available-to-user
307 uint32 bytes-per-allocation-unit
308
309 bytes-on-device
310 The total number of bytes on the device which stores 'path', both
311 used and unused, or 0 if unknown.
312
313 unused-bytes-on-device
314 The total number of unused bytes available on the device which
315 stores 'path', or 0 if unknown.
316
317 bytes-available-to-user
318 The total number of bytes, both used and unused, available to the
319 authenticated user on the device which stores 'path', or 0 if
320 unknown.
321
322 unused-bytes-available-to-user
323 The total number of unused bytes available to the authenticated
324 user on the device which stores 'path', or 0 if unknown.
325
326 bytes-per-allocation-unit
327 The number of bytes in each allocation unit on the device, or in
328 other words, the minimum number of bytes that a file allocation
329 size can grow or shrink by. If the server does not know this
330 information, or the file-system in use does not use allocation
331 blocks, this value MUST be 0.
332
333
334
335 Galbraith & Saarenmaa Expires July 22, 2006 [Page 6]
336
337 Internet-Draft SSH File Transfer Protocol January 2006
338
339
340 5. Querying User Home Directory
341
342 Many users are used to being able to type '~' as an alias for their
343 home directory, or ~username as an alias for another user's home
344 directory. To support this feature, a server MAY support following
345 extension.
346
347 byte SSH_FXP_EXTENDED
348 uint32 request-id
349 string "home-directory"
350 string username [UTF-8]
351
352 username
353 Username whose home directory path is being requested. An empty
354 string implies the current user.
355
356 The reply to the request is either a SSH_FXP_STATUS packet or a
357 SSH_FXP_NAME packet containing the absolute real-path of the home
358 directory.
359
360
361 6. Copying Remote Files
362
363 byte SSH_FXP_EXTENDED
364 uint32 request-id
365 string "copy-file"
366 string source-file
367 string destination-file
368 bool overwrite-destination
369
370 This request copies a file from one location to another on the
371 server. The server responds with SSH_FXP_STATUS.
372
373
374 7. Copying remote data
375
376 byte SSH_FXP_EXTENDED
377 uint32 request-id
378 string "copy-data"
379 string read-from-handle
380 uint64 read-from-offset
381 uint64 read-data-length
382 string write-to-handle
383 uint64 write-to-offset
384
385 Copy data from one handle to another on the server. The server
386 responds with SSH_FXP_STATUS.
387
388
389
390
391 Galbraith & Saarenmaa Expires July 22, 2006 [Page 7]
392
393 Internet-Draft SSH File Transfer Protocol January 2006
394
395
396 The server MUST copy the data exactly as if the client had issued a
397 series of SSH_FXP_READ requests on the read-from-handle starting at
398 read-from-offset and totaling read-data-length bytes, and issued a
399 series of SSH_FXP_WRITE packets on the write-to-handle, starting at
400 the write-from-offset, and totaling the total number of bytes read by
401 the SSH_FXP_READ packets.
402
403 If one of the files is open using SSH_FXF_TEXT_MODE, then operation
404 on that handle honors all of the SSH_FXF_TEXT_MODE behaviors.
405
406 The server SHOULD allow 'read-from-handle' and 'write-to-handle' to
407 be the same handle as long as the range of data is not overlapping.
408 This allows data to efficiently be moved within a file. The server
409 MUST fail the request with a SSH_FX_INVALID_PARAMETER if the range is
410 overlapping and it doesn't correctly handle this case. The server is
411 not required to detect overlapping ranges if read-from-handle and
412 write-to-handle are different handles referring to the same file.
413
414 If 'data-length' is 0, this imples data should be read until EOF is
415 encountered.
416
417 There are no protocol restictions on this operation; however, the
418 server MUST ensure that the user does not exceed quota, etc. The
419 server is, as always, free to complete this operation out of order if
420 it is too large to complete immediately, or to refuse a request that
421 is too large.
422
423
424 8. Temporary files & directories
425
426 byte SSH_FXP_EXTENDED
427 uint32 request-id
428 string "get-temp-folder"
429
430 Retrieves the users preferred location for temporary files and
431 folders. The server responds with SSH_FXP_STATUS or SSH_FXP_NAME
432 containing the realpath of the preferred location.
433
434 byte SSH_FXP_EXTENDED
435 uint32 request-id
436 string "make-temp-folder"
437
438 Requests that the server create a folder in the users preferred
439 location for temporary files and folders for use by the client. The
440 server responds with SSH_FXP_STATUS or SSH_FXP_NAME containing the
441 realpath of the new folder.
442
443 It is the clients responsibility to cleanup and remove the folder
444
445
446
447 Galbraith & Saarenmaa Expires July 22, 2006 [Page 8]
448
449 Internet-Draft SSH File Transfer Protocol January 2006
450
451
452 when it is done with it. However, the server MAY remove the folder
453 and it's contents when the client closes the connection.
454
455
456 9. Security Considerations
457
458 The home directory extension could be used to discover whether a
459 given user is valid; however, since users are assumed to be
460 authenticated by the underlying protocol, this is probably not
461 significant in most situations. If a server would not normally allow
462 an authenticated user to query the existance of another user, the
463 server MUST NOT allow the "home-directory" extension.
464
465
466 10. References
467
468 10.1. Normative References
469
470 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321,
471 April 1992.
472
473 [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network
474 Authentication Service (V5)", RFC 1510, September 1993.
475
476 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
477 Protocol Architecture", RFC 4251, January 2006.
478
479 [I-D.ietf-secsh-filexfer]
480 Galbraith, J. and O. Saarenmaa, "SSH File Transfer
481 Protocol", draft-ietf-secsh-filexfer-10 (work in
482 progress), October 2005.
483
484 [FIPS-180-2]
485 National Institute of Standards and Technology, "Secure
486 Hash Standard (SHS)", Federal Information Processing
487 Standards Publication 180-2, August 2002.
488
489 [ISO.3309.1991]
490 International Organization for Standardization,
491 "Information Technology - Telecommunications and
492 information exchange between systems - High-level data
493 link control (HDLC) procedures - Frame structure",
494 ISO Standard 3309, June 1991.
495
496 10.2. Informative References
497
498 Trademark notice
499
500
501
502
503 Galbraith & Saarenmaa Expires July 22, 2006 [Page 9]
504
505 Internet-Draft SSH File Transfer Protocol January 2006
506
507
508 "ssh" is a registered trademark in the United States and/or other
509 countries.
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559 Galbraith & Saarenmaa Expires July 22, 2006 [Page 10]
560
561 Internet-Draft SSH File Transfer Protocol January 2006
562
563
564 Authors' Addresses
565
566 Joseph Galbraith
567 VanDyke Software
568 4848 Tramway Ridge Blvd
569 Suite 101
570 Albuquerque, NM 87111
571 US
572
573 Phone: +1 505 332 5700
574 Email: galb-list@vandyke.com
575
576
577 Oskari Saarenmaa
578 F-Secure
579 Tammasaarenkatu 7
580 Helsinki 00180
581 FI
582
583 Email: oskari.saarenmaa@f-secure.com
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615 Galbraith & Saarenmaa Expires July 22, 2006 [Page 11]
616
617 Internet-Draft SSH File Transfer Protocol January 2006
618
619
620 Intellectual Property Statement
621
622 The IETF takes no position regarding the validity or scope of any
623 Intellectual Property Rights or other rights that might be claimed to
624 pertain to the implementation or use of the technology described in
625 this document or the extent to which any license under such rights
626 might or might not be available; nor does it represent that it has
627 made any independent effort to identify any such rights. Information
628 on the procedures with respect to rights in RFC documents can be
629 found in BCP 78 and BCP 79.
630
631 Copies of IPR disclosures made to the IETF Secretariat and any
632 assurances of licenses to be made available, or the result of an
633 attempt made to obtain a general license or permission for the use of
634 such proprietary rights by implementers or users of this
635 specification can be obtained from the IETF on-line IPR repository at
636 http://www.ietf.org/ipr.
637
638 The IETF invites any interested party to bring to its attention any
639 copyrights, patents or patent applications, or other proprietary
640 rights that may cover technology that may be required to implement
641 this standard. Please address the information to the IETF at
642 ietf-ipr@ietf.org.
643
644
645 Disclaimer of Validity
646
647 This document and the information contained herein are provided on an
648 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
649 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
650 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
651 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
652 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
653 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
654
655
656 Copyright Statement
657
658 Copyright (C) The Internet Society (2006). This document is subject
659 to the rights, licenses and restrictions contained in BCP 78, and
660 except as set forth therein, the authors retain all their rights.
661
662
663 Acknowledgment
664
665 Funding for the RFC Editor function is currently provided by the
666 Internet Society.
667
668
669
670
671 Galbraith & Saarenmaa Expires July 22, 2006 [Page 12]
672
673
+616
-0
rfc/draft-ietf-secsh-scp-sftp-ssh-uri-04.txt less more
0
1
2
3 Network Working Group J. Salowey
4 Internet-Draft Cisco Systems
5 Expires: August 5, 2006 S. Suehring
6 February 1, 2006
7
8
9 Uniform Resource Identifier (URI) Scheme for Secure File Transfer
10 Protocol (SFTP) and Secure Shell (SSH)
11 draft-ietf-secsh-scp-sftp-ssh-uri-04.txt
12
13 Status of this Memo
14
15 By submitting this Internet-Draft, each author represents that any
16 applicable patent or other IPR claims of which he or she is aware
17 have been or will be disclosed, and any of which he or she becomes
18 aware will be disclosed, in accordance with Section 6 of BCP 79.
19
20 Internet-Drafts are working documents of the Internet Engineering
21 Task Force (IETF), its areas, and its working groups. Note that
22 other groups may also distribute working documents as Internet-
23 Drafts.
24
25 Internet-Drafts are draft documents valid for a maximum of six months
26 and may be updated, replaced, or obsoleted by other documents at any
27 time. It is inappropriate to use Internet-Drafts as reference
28 material or to cite them other than as "work in progress."
29
30 The list of current Internet-Drafts can be accessed at
31 http://www.ietf.org/ietf/1id-abstracts.txt.
32
33 The list of Internet-Draft Shadow Directories can be accessed at
34 http://www.ietf.org/shadow.html.
35
36 This Internet-Draft will expire on August 5, 2006.
37
38 Copyright Notice
39
40 Copyright (C) The Internet Society (2006).
41
42 Abstract
43
44 This document describes the Uniform Resource Identifiers used to
45 locate resources for the Secure File Transfer Protocol (SFTP) and the
46 Secure Shell (SSH) protocols. The document describes the generic
47 syntax involved in URI definitions as well as specific definitions
48 for each protocol. These specific definitions may include user
49 credentials such as username and also may include other parameters
50 such as host key fingerprint. In addition, security considerations
51
52
53
54 Salowey & Suehring Expires August 5, 2006 [Page 1]
55
56 Internet-Draft URI Scheme for SSH and SFTP February 2006
57
58
59 and examples are also provided within this document.
60
61 Table of Contents
62
63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
64 2. General Syntax . . . . . . . . . . . . . . . . . . . . . . . 3
65 3. Secure Shell (SSH) URI . . . . . . . . . . . . . . . . . . . 3
66 3.1 Scheme Name . . . . . . . . . . . . . . . . . . . . . . . 3
67 3.2 Status . . . . . . . . . . . . . . . . . . . . . . . . . . 3
68 3.3 URI Scheme Syntax . . . . . . . . . . . . . . . . . . . . 3
69 3.4 URI Semantics . . . . . . . . . . . . . . . . . . . . . . 4
70 3.5 Encoding Considerations . . . . . . . . . . . . . . . . . 4
71 3.6 Protocols using this URI scheme . . . . . . . . . . . . . 4
72 3.7 Security Considerations . . . . . . . . . . . . . . . . . 5
73 3.8 Contact . . . . . . . . . . . . . . . . . . . . . . . . . 5
74 4. Secure File Transfer Protocol (SFTP) URI . . . . . . . . . . 5
75 4.1 Scheme Name . . . . . . . . . . . . . . . . . . . . . . . 5
76 4.2 Status . . . . . . . . . . . . . . . . . . . . . . . . . . 5
77 4.3 URI Scheme Syntax . . . . . . . . . . . . . . . . . . . . 5
78 4.4 URI Semantics . . . . . . . . . . . . . . . . . . . . . . 6
79 4.5 Encoding Considerations . . . . . . . . . . . . . . . . . 6
80 4.6 Protocols using this URI scheme . . . . . . . . . . . . . 6
81 4.7 Security Considerations . . . . . . . . . . . . . . . . . 6
82 4.8 Contact . . . . . . . . . . . . . . . . . . . . . . . . . 7
83 5. Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 7
84 5.1 SSH connection parameters . . . . . . . . . . . . . . . . 7
85 5.2 SFTP Parameters . . . . . . . . . . . . . . . . . . . . . 7
86 6. Examples . . . . . . . . . . . . . . . . . . . . . . . . . . 8
87 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . 8
88 8. Security Considerations . . . . . . . . . . . . . . . . . . 9
89 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 9
90 10. References . . . . . . . . . . . . . . . . . . . . . . . . . 9
91 10.1 Normative References . . . . . . . . . . . . . . . . . . 9
92 10.2 Informative References . . . . . . . . . . . . . . . . . 10
93 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 10
94 Intellectual Property and Copyright Statements . . . . . . . 11
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110 Salowey & Suehring Expires August 5, 2006 [Page 2]
111
112 Internet-Draft URI Scheme for SSH and SFTP February 2006
113
114
115 1. Introduction
116
117 This document describes the Uniform Resource Identifiers (URIs) to be
118 used with the Secure File Transfer Protocol (SFTP) [I-D.ietf-secsh-
119 filexfer] and Secure Shell (SSH) [RFC4251] protocols.
120
121 2. General Syntax
122
123 A hierarchical URI shall consist of the scheme and the scheme
124 specific portion separated by a colon ":" followed by the
125 hierarchical part, as discussed in [RFC3986]. This specification
126 uses the definitions "port", "host", "scheme", "userinfo", "path-
127 empty", "path-abempty" and "authority" from [RFC3986]. This document
128 follows the ABNF notation defined in [RFC4234].
129
130 3. Secure Shell (SSH) URI
131
132 This section describes the SSH URI and contains the information
133 necessary to register the URI according to the template in
134 [I-D.hansen-2717bis-2718bis-uri-guidelines].
135
136 3.1 Scheme Name
137
138 The Secure Shell scheme name is "ssh".
139
140 3.2 Status
141
142 The requested status of the SSH URI is "permanent".
143
144 3.3 URI Scheme Syntax
145
146 The Secure Shell (SSH) scheme shall consist of the scheme name "ssh"
147 followed by a colon ":" followed by hier-part defined in [RFC3986].
148 The SSH URI ABNF definition follows.
149
150
151 sshURI = "ssh:" hier-part
152 hier-part = "//" authority path-abempty
153 authority = [ [ ssh-info ] "@" ] host [ ":" port ]
154 host = <as specified in [RFC3986]>
155 port = <as specified in [RFC3986]>
156 path-abempty = <as specified in [RFC3986]>
157 ssh-info = [ userinfo ] [";" c-param *("," c-param)]
158 userinfo = <as specified in [RFC3986]>
159 c-param = paramname "=" paramvalue
160 paramname = *( ALPHA / DIGIT / "-" )
161 paramvalue = *( ALPHA / DIGIT / "-" )
162
163
164
165
166 Salowey & Suehring Expires August 5, 2006 [Page 3]
167
168 Internet-Draft URI Scheme for SSH and SFTP February 2006
169
170
171 The following reserved characters from [RFC3986] are used as
172 delimiters within the SSH URI: ";", ",", ":", and "=" . They must
173 not be escaped when used as delimiters and must be escaped when the
174 appear in other uses.
175
176 3.4 URI Semantics
177
178 The intended usage of the SSH URI is to establish an interactive SSH
179 terminal session with the host defined in the authority portion of
180 the URI. The only operation defined for the URI is to establish an
181 SSH terminal session with a remote host.
182
183 If the userinfo or connection parameters are present the at-sign "@"
184 shall precede the authority section of the URI. Optionally, the
185 authority section MAY also include the port preceded by a colon ":".
186 The host SHOULD be a non-empty string. If the port is not included,
187 the default port is assumed.
188
189 The ssh-info portion of the URI MAY include credentials consisting of
190 a username followed by optional parameters. The convention of
191 including the password separated from the username by a ":" in the
192 URI is NOT RECOMMENDED and is deprecated in accordance with
193 [RFC3986].
194
195 One or more optional connection parameters (c-param) may be specified
196 within the userinfo section of the URI. These conn-parameters are
197 separated from the userinfo by a semi-colon ";". The only connection
198 parameter defined in this document is for the host-key fingerprint
199 described in Section 5.1. It is possible that additional parameters
200 be defined in the future. If a connection parameter is not
201 understood it SHOULD be ignored.
202
203 The SSH URI does not define a usage for a non-empty path element. If
204 a non-empty path element is included in an SSH URI then it SHOULD be
205 ignored.
206
207 3.5 Encoding Considerations
208
209 The encoding of the "host" portion of the URI is as defined in
210 [RFC3986]. The encoding of the connection parameters is described in
211 Section 5.1
212
213 3.6 Protocols using this URI scheme
214
215 This URI scheme is used by the SSH protocol version 2 defined in
216 [RFC4251].
217
218
219
220
221
222 Salowey & Suehring Expires August 5, 2006 [Page 4]
223
224 Internet-Draft URI Scheme for SSH and SFTP February 2006
225
226
227 3.7 Security Considerations
228
229 See Section 8.
230
231 3.8 Contact
232
233 This document is a product of the SSH working group.
234
235 4. Secure File Transfer Protocol (SFTP) URI
236
237 This section describes the Secure File Transfer protocol URI and
238 contains the information necessary to register the URI according to
239 the template in [I-D.hansen-2717bis-2718bis-uri-guidelines].
240
241 4.1 Scheme Name
242
243 The Secure File Transfer Protocol (SFTP) scheme name is "sftp".
244
245 4.2 Status
246
247 The requested status of the SFTP URI is "permanent".
248
249 4.3 URI Scheme Syntax
250
251 The SFTP URI scheme shall consist of the scheme name "sftp" followed
252 by a colon ":" followed by hier-part defined in [RFC3986]. The SFTP
253 URI ABNF definition follows.
254
255
256 sftpURI = "sftp:" hier-part
257 hier-part = "//" authority path [";" s-param *("," s-param)]
258 path = path-abempty
259 path-abempty = <as specified in [RFC3986]>
260 authority = [ ssh-info "@" ] host [ ":" port ]
261 host = <as specified in [RFC3986]>
262 port = <as specified in [RFC3986]>
263 ssh-info = [ userinfo ] [";" c-param *("," c-param)]
264 userinfo = <as specified in [RFC3986]>
265 c-param = paramname "=" paramvalue
266 paramname = *( ALPHA / DIGIT / "-" )
267 paramvalue = *( ALPHA / DIGIT / "-" )
268 s-param = paramname "=" paramvalue
269
270 The authority part is the same as that defined in the SSH scheme.
271 The following reserved characters from [RFC3986] are used as
272 delimiters within the SFTP URI: ";", ",", ":", "=" and "/". They
273 must not be escaped when used as delimiters and must be escaped when
274 the appear in other uses.
275
276
277
278 Salowey & Suehring Expires August 5, 2006 [Page 5]
279
280 Internet-Draft URI Scheme for SSH and SFTP February 2006
281
282
283 4.4 URI Semantics
284
285 The intended usage of the SFTP URI is to retrieve the contents of a
286 file or directory listing. The only operation defined for the URI is
287 this "GET" operation.
288
289 The authority portion of the SFTP URL is the same as for the SSH URL
290 defined in Section 3.4. The URIs for SFTP are hierarchical URIs
291 where each component of the path consists of path elements separated
292 by a '/'. This formatting is meant to represent the path information
293 as in Section 5 of [I-D.ietf-secsh-filexfer]. The SFTP
294 implementation determines where the root of the path in the URI is.
295 It is RECOMMENDED that path be interpreted as an absolute path from
296 the root of the file system. An implementation MAY use the tilde
297 ("~") character as the first path element in the path to denote a
298 path relative to the user's home directory. Note that dot segments
299 "." and ".." are only interpreted within the URI path hierarchy and
300 are removed as part of the URL resolution process defined in
301 [RFC3986].
302
303 Following the path additional sftp specific parameters may be
304 specified. These are described in Section 5.2. It is possible that
305 additional parameters be defined in the future. If a sftp parameter
306 is not understood it SHOULD be ignored.
307
308 4.5 Encoding Considerations
309
310 Path segments SHOULD be represented in the UTF-8 [RFC3629] character
311 set and clients SHOULD NOT disable UTF-8 translation on the server
312 with the filename-translation-control extension. The shortest valid
313 UTF-8 encoding of the UNICODE data MUST be used. The encoding of the
314 "host" portion of the URI is as defined in [RFC3986]. The encoding
315 of the connection parameters is described in Section 5.1 and the
316 encoding of SFTP parameters is described in Section 5.2.
317
318 4.6 Protocols using this URI scheme
319
320 This URI scheme is used by the SFTP protocol defined in [I-D.ietf-
321 secsh-filexfer].
322
323 4.7 Security Considerations
324
325 The SFTP URI retrieves data from a remote host. Even though the
326 connection is secured by SFTP care should be taken in handling and
327 processing data retrieved from potentially unknown sources to avoid
328 malicious content from an attacker that may have been placed on the
329 host. For additional security considerations see Section 8.
330
331
332
333
334 Salowey & Suehring Expires August 5, 2006 [Page 6]
335
336 Internet-Draft URI Scheme for SSH and SFTP February 2006
337
338
339 4.8 Contact
340
341 This document is a product of the SSH working group.
342
343 5. Parameters
344
345
346 5.1 SSH connection parameters
347
348 The following parameters are associated with an SSH connection and
349 are applicable to SSH and SFTP. All parameters are optional and MUST
350 NOT overwrite configured defaults. Individual parameters are
351 separated by a comma (",").
352
353 fingerprint
354
355 The fingerprint parameter contains the fingerprint of the host key
356 for the host specified in the URL. The fingerprint is encoded as
357 host-key-alg-fingerprint. Host-key-alg is host public key
358 algorithm defined in [RFC4253] and the fingerprint format is
359 [I-D.ietf-secsh-publickeyfile]. For use in a URI, the fingerprint
360 shall use a single dash "-" as a separator instead of the colon
361 ":" as described in [I-D.ietf-secsh-publickeyfile]. This
362 parameter MUST NOT overwrite a key that is already configured for
363 the host. The fingerprint MAY be used to validate the
364 authenticity of the host key if the URL was obtained from an
365 authenticated source with its integrity protected. If this
366 parameter is not included then the host key is validated using
367 another method. See Security Considerations section for
368 additional considerations. There MUST be only one fingerprint
369 parameter present in a given URL.
370
371 5.2 SFTP Parameters
372
373 The SFTP parameters determine how to handle the file transfer
374 character translation. Additional parameters MAY be used.
375
376 typecode
377
378 The typecode identifies the type of file which determines how it
379 will be treated. The name for the typecode attribute is "type".
380 The value "i" indicates that a file should be transmitted without
381 character conversion performed. The value "a" indicates that the
382 file should be opened with the SSH_FXF_ACCESS_TEXT_MODE flag set
383 so it is converted to the canonical newline convention in use.
384 The value "d" indicates that the path is a directory and should be
385 opened using SSH_FXP_OPENDIR.
386
387
388
389
390 Salowey & Suehring Expires August 5, 2006 [Page 7]
391
392 Internet-Draft URI Scheme for SSH and SFTP February 2006
393
394
395 6. Examples
396
397 The following section shows basic examples of URLs for each protocol.
398 This section should not be considered to include all possible
399 combinations of URLs for each protocol.
400
401 An SSH connection to the host host.example.com on the standard port
402 using username user.
403
404 ssh://user@host.example.com
405
406 An SSH connection to the host host.example.com on port 2222 using
407 username user.
408
409 ssh://user@host.example.com:2222
410
411 An SSH connection to the host having the specified host-key
412 fingerprint at host.example.com on the standard port using username
413 user.
414
415 ssh://user;fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de-6c-97-
416 77-10-d7-46-41-63-87@host.example.com
417
418 Retrieve file.txt from the user's home directory on the host at
419 host.example.com using SFTP using username user. This example
420 assumes that the implementation supports the indication of a path
421 relative to the home directory using a leading tilde.
422
423 sftp://user@host.example.com/~/file.txt
424
425 Retrieve file.txt from the absolute path /dir/path on the host at
426 host.example.com using SFTP using username user.
427
428 sftp://user@host.example.com/dir/path/file.txt
429
430 Retrieve the directory listing of user's home directory on the host
431 having the specified host-key fingerprint at host.example.com using
432 SFTP.
433
434 sftp://user;fingerprint=ssh-dss-c1-b1-30-29-d7-b8-de-6c-97-
435 77-10-d7-46-41-63-87@host.example.com:2222/;type=d
436
437 7. IANA Considerations
438
439 Section 3 and Section 4 provide the information required in the URL
440 registration template in accordance with [I-D.hansen-2717bis-2718bis-
441 uri-guidelines].
442
443
444
445
446 Salowey & Suehring Expires August 5, 2006 [Page 8]
447
448 Internet-Draft URI Scheme for SSH and SFTP February 2006
449
450
451 8. Security Considerations
452
453 Passwords SHOULD NOT be included within the URI as doing so poses a
454 security risk. URIs are usually sent in the clear with no encryption
455 or other security, any password or other credentials included in the
456 userinfo could be seen by a potential attacker.
457
458 Although the host-key fingerprint is not confidential information,
459 care must be taken in handling fingerprints associated with URIs
460 because URIs transmitted or stored without protection may be modified
461 by an attacker. In general an implementation cannot determine the
462 source of a URI so a fingerprint received in a URI should have no
463 more trust associated with it than a raw public key received in the
464 SSH protocol itself. If a locally configured key exists for the
465 server already it MUST NOT be automatically overwritten with
466 information from the URI. If the host is unknown then the
467 implementation should treat the fingerprint received with the same
468 caution that it does with any unknown public key. The client MAY
469 offer the fingerprint and URI for external validation before allowing
470 a connection based on this information. If the client chooses to
471 make a connection based on the URI information and it finds that the
472 fingerprint in the URI and the public key offered by the server do
473 not match then it SHOULD provide a warning and provide a means to
474 abort the connection. Sections 4.1 and 9.2.4 of [RFC4251] provide a
475 good discussion of handling public keys received in the SSH protocol.
476
477 9. Acknowledgements
478
479 Ben Harris, Tom Petch and the members of the SSH working group have
480 provided much useful feedback in the preparation of this document.
481
482 10. References
483
484 10.1 Normative References
485
486 [I-D.ietf-secsh-filexfer]
487 Galbraith, J. and O. Saarenmaa, "SSH File Transfer
488 Protocol", draft-ietf-secsh-filexfer-12 (work in
489 progress), January 2006.
490
491 [I-D.ietf-secsh-publickeyfile]
492 Galbraith, J. and R. Thayer, "SSH Public Key File Format",
493 draft-ietf-secsh-publickeyfile-11 (work in progress),
494 January 2006.
495
496 [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
497 10646", STD 63, RFC 3629, November 2003.
498
499
500
501
502 Salowey & Suehring Expires August 5, 2006 [Page 9]
503
504 Internet-Draft URI Scheme for SSH and SFTP February 2006
505
506
507 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
508 Resource Identifier (URI): Generic Syntax", STD 66,
509 RFC 3986, January 2005.
510
511 [RFC4234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
512 Specifications: ABNF", RFC 4234, October 2005.
513
514 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
515 Protocol Architecture", RFC 4251, January 2006.
516
517 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
518 Transport Layer Protocol", RFC 4253, January 2006.
519
520 10.2 Informative References
521
522 [I-D.hansen-2717bis-2718bis-uri-guidelines]
523 Hansen, T., "Guidelines and Registration Procedures for
524 new URI Schemes",
525 draft-hansen-2717bis-2718bis-uri-guidelines-06 (work in
526 progress), October 2005.
527
528
529 Authors' Addresses
530
531 Joseph Salowey
532 Cisco Systems
533 2901 3rd Ave
534 Seattle, WA 98121
535 US
536
537 Email: jsalowey@cisco.com
538
539
540 Steve Suehring
541 PO BOX 1033
542 Stevens Point, WI 54481
543 US
544
545 Email: suehring@braingia.com
546
547
548
549
550
551
552
553
554
555
556
557
558 Salowey & Suehring Expires August 5, 2006 [Page 10]
559
560 Internet-Draft URI Scheme for SSH and SFTP February 2006
561
562
563 Intellectual Property Statement
564
565 The IETF takes no position regarding the validity or scope of any
566 Intellectual Property Rights or other rights that might be claimed to
567 pertain to the implementation or use of the technology described in
568 this document or the extent to which any license under such rights
569 might or might not be available; nor does it represent that it has
570 made any independent effort to identify any such rights. Information
571 on the procedures with respect to rights in RFC documents can be
572 found in BCP 78 and BCP 79.
573
574 Copies of IPR disclosures made to the IETF Secretariat and any
575 assurances of licenses to be made available, or the result of an
576 attempt made to obtain a general license or permission for the use of
577 such proprietary rights by implementers or users of this
578 specification can be obtained from the IETF on-line IPR repository at
579 http://www.ietf.org/ipr.
580
581 The IETF invites any interested party to bring to its attention any
582 copyrights, patents or patent applications, or other proprietary
583 rights that may cover technology that may be required to implement
584 this standard. Please address the information to the IETF at
585 ietf-ipr@ietf.org.
586
587
588 Disclaimer of Validity
589
590 This document and the information contained herein are provided on an
591 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
592 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
593 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
594 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
595 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
596 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
597
598
599 Copyright Statement
600
601 Copyright (C) The Internet Society (2006). This document is subject
602 to the rights, licenses and restrictions contained in BCP 78, and
603 except as set forth therein, the authors retain all their rights.
604
605
606 Acknowledgment
607
608 Funding for the RFC Editor function is currently provided by the
609 Internet Society.
610
611
612
613
614 Salowey & Suehring Expires August 5, 2006 [Page 11]
615
+4
-1
t/1_run.t less more
106106
107107 ok (my $attr = $sftp->stat($drfn), "stat - $i");
108108
109 is ($attr->size, (stat($dlfn))[7], "stat - size - $i");
109 SKIP: {
110 skip "attr is undefined", 1 unless defined $attr;
111 is ($attr->size, (stat($dlfn))[7], "stat - size - $i");
112 };
110113
111114 ok (!$sftp->put($dlfn, $drfn, overwrite => 0), "no overwrite - $i");
112115 is (int $sftp->error, Net::SFTP::Foreign::Constants::SFTP_ERR_REMOTE_OPEN_FAILED(), "no overwrite - error - $i");