idnits 2.17.1 draft-ietf-secsh-filexfer-11.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2609. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2586. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2593. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2599. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 163: '...rr by the server SHOULD be considered ...' RFC 2119 keyword, line 164: '...information, and MAY be displayed to t...' RFC 2119 keyword, line 170: '...rors or warnings MAY be sent as stderr...' RFC 2119 keyword, line 190: '...the length field MUST be included in a...' RFC 2119 keyword, line 194: '...overhead). All servers SHOULD support...' (188 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 677 has weird spacing: '... bool do-...' == Line 706 has weird spacing: '... string owne...' == Line 707 has weird spacing: '... string grou...' == Line 717 has weird spacing: '... string acl ...' == Line 721 has weird spacing: '... string mime...' == (5 more instances...) == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The use of additional packet types in the non-extension range MUST be introduced through IETF consensus. New packet types to be sent from the client to the server MAY be introduced without changing the protocol version (Section 5). Because the client has no way to respond to unrecognized packet types, new packet types to be sent from the server to the client the client MUST not used unless the protocol version is changed or the client has negotiated to received them. This negotiation MAY be explicit, through the use of extensions, or MAY be implicit, by the client itself using a packet type not defined above. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If the PRESENT bit is not set, then the client wishes to remove control entries. If the server doesn't support separate control and audit information, the client MUST not clear this bit without also clearing the AUDIT_ALARM_PRESENT bit. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If INHERITED is set, then ALLOW/DENY ACEs MAY be inherited from the parent directory. If it is off, then they MUST not be INHERITED. If the server does not support controlling inheritance, then the client MUST clear this bit; in this case the inheritance properties of the server are undefined. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: If INHERITED is set, then AUDIT/ALARM ACEs MAY be inherited from the parent directory. If it is off, then they MUST not be INHERITED. If the server does not support controlling inheritance, then the client MUST clear this bit; in this case the inheritance properties of the server are undefined. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The server MUST not respond with more data than is specified by the 'length' parameter. However, the server MAY respond with less data if EOF is reached, an error is encountered, or the servers internal buffers can not handle such a large request. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 17, 2006) is 6667 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'UTF-8' is mentioned on line 2340, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 2108, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 2109, but not defined ** Obsolete undefined reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 3010 (Obsoleted by RFC 3530) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE.1003-1.1996' -- Obsolete informational reference (is this intentional?): RFC 1521 (Obsoleted by RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049) -- Obsolete informational reference (is this intentional?): RFC 2246 (Obsoleted by RFC 4346) Summary: 8 errors (**), 0 flaws (~~), 16 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Secure Shell Working Group J. Galbraith 3 Internet-Draft VanDyke Software 4 Expires: July 21, 2006 O. Saarenmaa 5 F-Secure 6 January 17, 2006 8 SSH File Transfer Protocol 9 draft-ietf-secsh-filexfer-11.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on July 21, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 The SSH File Transfer Protocol provides secure file transfer 43 functionality over any reliable data stream. It is the standard file 44 transfer protocol for use with the SSH2 protocol. This document 45 describes the file transfer protocol and its interface to the SSH2 46 protocol suite. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 51 2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4 52 3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 53 3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5 54 4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 55 4.1. Request Synchronization and Reordering . . . . . . . . . . 6 56 4.2. New data types defined by this document . . . . . . . . . 7 57 4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 58 5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9 59 5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9 60 5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9 61 5.3. Determining Server Newline Convention . . . . . . . . . . 10 62 5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10 63 5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 13 64 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14 65 7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16 66 7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 17 67 7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 68 7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 69 7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 19 70 7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 19 71 7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 20 72 7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20 73 7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 74 7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 24 75 7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 27 76 7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 27 77 7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 27 78 7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 28 79 7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 28 80 8. Requests From the Client to the Server . . . . . . . . . . . . 28 81 8.1. Opening and Closing Files and Directories . . . . . . . . 28 82 8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 29 83 8.1.2. Opening a Directory . . . . . . . . . . . . . . . . . 35 84 8.1.3. Closing Handles . . . . . . . . . . . . . . . . . . . 35 85 8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 36 86 8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 36 87 8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 37 88 8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 37 89 8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 38 90 8.4. Creating and Deleting Directories . . . . . . . . . . . . 39 91 8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 40 92 8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 41 93 8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 42 94 8.8. Byte-range locks . . . . . . . . . . . . . . . . . . . . . 43 95 8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 44 96 8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 46 97 9. Responses from the Server to the Client . . . . . . . . . . . 47 98 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 47 99 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 51 100 9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52 101 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 52 102 9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53 103 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 53 104 11. Implementation Considerations . . . . . . . . . . . . . . . . 54 105 12. Security Considerations . . . . . . . . . . . . . . . . . . . 55 106 13. Changes from Previous Protocol Versions . . . . . . . . . . . 56 107 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 56 108 14.1. Normative References . . . . . . . . . . . . . . . . . . . 56 109 14.2. Informative References . . . . . . . . . . . . . . . . . . 57 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 111 Intellectual Property and Copyright Statements . . . . . . . . . . 59 113 1. Introduction 115 This protocol provides secure file transfer (and more generally file 116 system access.) It is designed so that it could be used to implement 117 a secure remote file system service, as well as a secure file 118 transfer service. 120 This protocol assumes that it runs over a secure channel, such as a 121 channel in [RFC4251], and that the server has already authenticated 122 the client, and that the identity of the client user is available to 123 the protocol. 125 In general, this protocol follows a simple request-response model. 126 Each request and response contains a sequence number and multiple 127 requests may be pending simultaneously. There are a relatively large 128 number of different request messages, but a small number of possible 129 response messages. Each request has one or more response messages 130 that may be returned in result (e.g., a read either returns data or 131 reports error status). 133 The packet format descriptions in this specification follow the 134 notation presented in [RFC4251]. 136 Even though this protocol is described in the context of the SSH2 137 protocol, this protocol is general and independent of the rest of the 138 SSH2 protocol suite. It could be used in a number of different 139 applications, such as secure file transfer over TLS [RFC2246] and 140 transfer of management information in VPN applications. 142 2. Acknowledgements 144 This document owes it's initial creation and protocol design to Tatu 145 Ylonen and Sami Lehtinen of SSH Communications Security Corp. 147 We express our gratitude to them for their initial work on this 148 protocol. 150 3. Use with the SSH Connection Protocol 152 When used with the SSH2 Protocol suite, this protocol is intended to 153 be used as a subsystem as described in [RFC4254] in the section 154 "Starting a Shell or a Command". The subsystem name used with this 155 protocol is "sftp". 157 3.1. The Use of 'stderr' in the server 159 This protocol uses stdout and stdin to transmit binary protocol data. 160 The "session" channel ([RFC4254]), which is used by the subsystem, 161 also supports the use of stderr. 163 Data sent on stderr by the server SHOULD be considered free format 164 debug or supplemental error information, and MAY be displayed to the 165 user. 167 For example, during initialization, there is no client request 168 active, so errors or warning information cannot be sent to the client 169 as part of the SFTP protocol at this early stage. However, the 170 errors or warnings MAY be sent as stderr text. 172 4. General Packet Format 174 All packets transmitted over the secure connection are of the 175 following format: 177 uint32 length 178 byte type 179 uint32 request-id 180 ... type specific fields ... 182 'length' 183 The length of the entire packet, excluding the length field 184 itself, such that, for example, for a packet type containing no 185 type specific fields, the length field would be 5, and 9 bytes of 186 data would be sent on the wire. (This is the packet format used 187 in [RFC4253].) 189 All packet descriptions in this document omit the length field for 190 brevity; the length field MUST be included in any case. 192 The maximum size of a packet is in practice determined by the 193 client (the maximum size of read or write requests that it sends, 194 plus a few bytes of packet overhead). All servers SHOULD support 195 packets of at least 34000 bytes (where the packet size refers to 196 the full length, including the header above). This should allow 197 for reads and writes of at most 32768 bytes. 199 'type' 200 The type code for the packet. 202 'request-id' 203 Each request from the client contains a 'request-id' field. Each 204 response from the server includes that same 'request-id' from the 205 request that the server is responding to. One possible 206 implementation is for the client to us a monotonically increasing 207 request sequence number (modulo 2^32). There is, however, no 208 particular requirement the 'request-id' fields be unique. 210 There are two packets, INIT and VERSION, which do not use the 211 request-id. 212 Packet descriptions in this document will contain the 'request-id' 213 field, but will not redefine it. 215 Implementations MUST ignore excess data at the end of an otherwise 216 valid packet. Implementations MUST respond to unrecognized packet 217 types with an SSH_FX_OP_UNSUPPORTED error. This will allow the 218 protocol to be extended in a backwards compatible way as needed. 220 Additionally, when a packet has two or more optional fields, and an 221 implementation wishes to use the i-th optional field, all fields from 222 1 to i MUST be present. In other words, only fields after the last 223 field the implementation wishes to send are actually options. 225 There is no limit on the number of outstanding (non-acknowledged) 226 requests that the client may send to the server. In practice this is 227 limited by the buffering available on the data stream and the queuing 228 performed by the server. If the server's queues are full, it should 229 not read any more data from the stream, and flow control will prevent 230 the client from sending more requests. Note, however, that while 231 there is no restriction on the protocol level, the client's API may 232 provide a limit in order to prevent infinite queuing of outgoing 233 requests at the client. 235 4.1. Request Synchronization and Reordering 237 The protocol and implementations MUST process requests relating to 238 the same file in the order in which they are received. In other 239 words, if an application submits multiple requests to the server, the 240 results in the responses will be the same as if it had sent the 241 requests one at a time and waited for the response in each case. For 242 example, the server may process non-overlapping read/write requests 243 to the same file in parallel, but overlapping reads and writes cannot 244 be reordered or parallelized. However, there are no ordering 245 restrictions on the server for processing requests from two different 246 file transfer connections. The server may interleave and parallelize 247 them at will. 249 There are no restrictions on the order in which responses to 250 outstanding requests are delivered to the client, except that the 251 server must ensure fairness in the sense that processing of no 252 request will be indefinitely delayed even if the client is sending 253 other requests so that there are multiple outstanding requests all 254 the time. 256 A client MUST be prepared to receive responses to multiple overlapped 257 requests out of order. 259 4.2. New data types defined by this document 261 This document defines these data types in addition to those defined 262 in [RFC4251]. 264 uint16 265 Represents a 16-bit unsigned integer. Stored as 2 bytes in the 266 order of decreasing significance (network byte order). 268 int64 269 Represents a 64-bit signed integer. Stored using two's 270 complement, as eight bytes in the order of decreasing significance 271 (network byte order). 273 extension-pair 275 string extension-name 276 string extension-data 278 'extension-name' is the name of a protocol extension. Extensions 279 not defined by IETF CONSENSUS MUST follow the the DNS 280 extensibility naming convention outlined in [RFC4251]. 282 'extension-data' is any data specific to the extension, and MAY be 283 zero length if the extension has no data. 285 4.3. Packet Types 287 The following values are defined for packet types. 289 SSH_FXP_INIT 1 290 SSH_FXP_VERSION 2 291 SSH_FXP_OPEN 3 292 SSH_FXP_CLOSE 4 293 SSH_FXP_READ 5 294 SSH_FXP_WRITE 6 295 SSH_FXP_LSTAT 7 296 SSH_FXP_FSTAT 8 297 SSH_FXP_SETSTAT 9 298 SSH_FXP_FSETSTAT 10 299 SSH_FXP_OPENDIR 11 300 SSH_FXP_READDIR 12 301 SSH_FXP_REMOVE 13 302 SSH_FXP_MKDIR 14 303 SSH_FXP_RMDIR 15 304 SSH_FXP_REALPATH 16 305 SSH_FXP_STAT 17 306 SSH_FXP_RENAME 18 307 SSH_FXP_READLINK 19 308 SSH_FXP_LINK 21 309 SSH_FXP_BLOCK 22 310 SSH_FXP_UNBLOCK 23 312 SSH_FXP_STATUS 101 313 SSH_FXP_HANDLE 102 314 SSH_FXP_DATA 103 315 SSH_FXP_NAME 104 316 SSH_FXP_ATTRS 105 318 SSH_FXP_EXTENDED 200 319 SSH_FXP_EXTENDED_REPLY 201 321 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 322 implement extensions, which can be vendor specific. See Section 323 ''Extensions'' for more details. 325 Values 210-255 are reserved for use in conjunction with these 326 extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the 327 meaning of these reserved types. It is suggested that the actual 328 value to be used also be negotiated, since this will prevent 329 collision among multiple uncoordinated extensions. 331 The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if 332 it receives a packet it does not recognize. 334 The use of additional packet types in the non-extension range MUST be 335 introduced through IETF consensus. New packet types to be sent from 336 the client to the server MAY be introduced without changing the 337 protocol version (Section 5). Because the client has no way to 338 respond to unrecognized packet types, new packet types to be sent 339 from the server to the client the client MUST not used unless the 340 protocol version is changed or the client has negotiated to received 341 them. This negotiation MAY be explicit, through the use of 342 extensions, or MAY be implicit, by the client itself using a packet 343 type not defined above. 345 5. Protocol Initialization 347 When the file transfer protocol starts, the client first sends a 348 SSH_FXP_INIT (including its version number) packet to the server. 349 The server responds with a SSH_FXP_VERSION packet, supplying the 350 lowest of its own and the client's version number. Both parties 351 should from then on adhere to that particular version of the 352 protocol. 354 The version number of the protocol specified in this document is 6. 355 The version number should be incremented for each incompatible 356 revision of this protocol. 358 Note that these two packets DO NOT contain a request id. These are 359 the only such packets in the protocol. 361 5.1. Client Initialization 363 The SSH_FXP_INIT packet (from client to server) has the following 364 data: 366 uint32 version 368 'version' is the version number of the client. If the client wishes 369 to interoperate with servers that support discontinuous version 370 numbers it SHOULD send '3', and then use the 'version-select' 371 extension (see below.) Otherwise, this value is '6' for this version 372 of the protocol. 374 5.2. Server Initialization 376 The SSH_FXP_VERSION packet (from server to client) has the following 377 data: 379 uint32 version 380 extension-pair extensions[0..n] 382 'version' is the lower of the protocol version supported by the 383 server and the version number received from the client. 385 'extensions' is 0 or more extension-pairs (Section 4.2). 386 Implementations MUST silently ignore any extensions whose names they 387 do not recognize. 389 5.3. Determining Server Newline Convention 391 In order to correctly process text files in a cross platform 392 compatible way, newline sequences must be converted between client 393 and server conventions. 395 The SSH_FXF_TEXT_MODE file open flag (Section 8.1.1) makes it 396 possible to request that the server translate a file to a 'canonical' 397 wire format. This format uses CRLF as the line separator. 399 Servers for systems using other conventions MUST translate to and 400 from the canonical form. 402 However, to ease the burden of implementation on servers that use a 403 single, simple, separator sequence the following extension allows the 404 canonical format to be changed. 406 string "newline" 407 string new-canonical-separator (usually CR or LF or CRLF) 409 All clients MUST support this extension. 411 When processing text files, clients SHOULD NOT translate any 412 character or sequence that is not an exact match of the server's 413 newline separator. 415 In particular, if the newline sequence being used is the canonical 416 CRLF sequence, a lone CR or a lone LF SHOULD be written through 417 without change. 419 5.4. Supported Features 421 The sftp protocol has grown to be very rich, and now supports a 422 number of features that may not be available on all servers. 424 When a server receives a request for a feature it cannot support, it 425 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 426 specified. The following extension facilitates clients being able to 427 use the maximum available feature set, and yet not be overly burdened 428 by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST 429 include as part of their version packet. 431 string "supported2" 432 string supported-structure 433 uint32 supported-attribute-mask 434 uint32 supported-attribute-bits 435 uint32 supported-open-flags 436 uint32 supported-access-mask 437 uint32 max-read-size 438 uint16 supported-open-block-vector 439 uint16 supported-block-vector 440 uint32 attrib-extension-count 441 string attrib-extension-names[attrib_extension-count] 442 uint32 extension-count 443 string extension-names[extension-count] 445 Note that the name "supported2" is used here to avoid conflict with 446 the slightly different "supported" extension that was previously 447 used. 448 supported-attribute-mask 449 This mask MAY by applied to the 'File Attributes' valid-attribute- 450 flags field (Section 7.1) to ensure that no unsupported attributes 451 are present during a operation which writes attributes. 453 supported-attribute-bits 454 This mask MAY by applied to the 'File Attributes' attrib-bits 455 field (Section 7.9) to ensure that no unsupported attrib-bits are 456 present during a operation which writes attributes. 458 supported-open-flags 459 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN 460 (Section 8.1.1) flags field. 462 supported-access-mask 463 This mask may be applied to the ace-mask field of an ACL. 465 This mask SHOULD NOT be applied to the desired-access field of the 466 SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result 467 in not requesting the access required by the client. In this 468 case, the server is responsible for translating the clients 469 requested access to a mode it supports that is sufficient to grant 470 all access requested by the client. 472 max-read-size 473 This is the maximum read size that the server guarantees to 474 complete. For example, certain embedded server implementations 475 complete only the first 4K of a read, even if there is additional 476 data to be read from the file. 478 If the server specifies a non-zero value for max-read-size, it 479 MUST return the requested number of bytes for reads that are less 480 than or equal to the value, unless it encounters EOF or an ERROR. 482 The server MAY use this value to express that it is willing to 483 handle very large read requests, in excess of the standard 34000 484 bytes specified in Section 4. 486 supported-open-block-vector 487 supported-block-vector 488 16-bit masks specifying which combinations of blocking flags are 489 supported. Each bit corresponds to one combination of the 490 SSH_FXF_BLOCK_READ, SSH_FXF_BLOCK_WRITE, SSH_FXF_BLOCK_DELETE, and 491 SSH_FXF_BLOCK_ADVISORY bits from Section 7.1.1.3, with a set bit 492 corresponding to a supported combination and a clear bit an 493 unsupported combination. The index of a bit, bit zero being the 494 least significant bit, viewed as a four-bit number, corresponds to 495 a combination of flag bits, shifted right so that BLOCK_READ is 496 the least significant bit. The combination `no blocking flags' 497 MUST be supported, so the low bit will always be set. 499 For example, a server supporting only the classic advisory read 500 (shared) and write (exclusive) locks would set the bits 501 corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, 502 0b1010, plus the always-set bit 0b0000, giving a mask value of 503 0b0000110000000001, or 0x0c01; a server supporting no locking at 504 all would set only bit zero, giving 0x0001. 506 'supported-open-block-masks' applies to the SSH_FXP_OPEN 507 (Section 8.1.1) flags field. 'supported-block-masks' applies to 508 the SSH_FXF_BLOCK request. 510 attrib-extension-count 511 Count of extension names in the attrib-extension-names array. 513 attrib-extension-names 514 Names of extensions that can be used in an ATTRS (Section 7.14) 515 structure. 517 extension-count 518 Count of extension names in the extension-names array. 520 extension-names 521 Names of extensions that can be used with the SSH_FXP_EXTEND 522 (Section 10) packet. 524 Naturally, if a given attribute field, attribute mask bit, open flag, 525 or extension is required for correct operation, the client MUST 526 either not allow the bit to be masked off, or MUST fail the operation 527 gracefully without sending the request to the server. 529 The client MAY send requests that are not supported by the server; 530 however, it is not normally expected to be productive to do so. The 531 client SHOULD apply the mask even to attrib structures received from 532 the server. The server MAY include attributes or attrib-bits that 533 are not included in the mask. Such attributes or attrib-bits are 534 effectively read-only. 536 The supported capabilities of the acl attribute are sent using the 537 following extension. 539 string "acl-supported" 540 string supported-structure 541 uint32 capabilities 543 'capabilities' is a combination of the following bits: 545 SSH_ACL_CAP_ALLOW 0x00000001 546 SSH_ACL_CAP_DENY 0x00000002 547 SSH_ACL_CAP_AUDIT 0x00000004 548 SSH_ACL_CAP_ALARM 0x00000008 549 SSH_ACL_CAP_INHERIT_ACCESS 0x00000010 550 SSH_ACL_CAP_INHERIT_AUDIT_ALARM 0x00000020 552 SSH_ACL_CAP_ALLOW 553 SSH_ACL_CAP_DENY 554 SSH_ACL_CAP_AUDIT 555 SSH_ACL_CAP_ALARM 556 The server supports the associated ACL ACE type. 558 SSH_ACL_CAP_INHERIT_ACCESS 559 The server can control whether a ACL will inherit DENY and ALLOW 560 ACEs that are marked inheritable from it's parent object. 562 SSH_ACL_CAP_INHERIT_AUDIT_ALARM 563 The server can control whether a ACL will inherit AUDIT or ALARM 564 ACEs that are marked inheritable from it's parent object. 566 5.5. Version re-negotiation 568 If the server supports other versions than what was negotiated, it 569 may wish to send the 'versions' extension to inform the client of 570 this fact. The client may then optionally choose to use one of the 571 other versions supported. 573 string "versions" 574 string comma-separated-versions 576 'comma-separated-versions' is a string of comma separated version 577 numbers. Defined versions are: "2", "3", "4", "5", "6". Any other 578 version advertised by the server must follow the DNS extensibility 579 naming convention outlined in [RFC4251]. 581 For example: "2,3,6,private@example.com". 583 If the client and server have negotiated a a version greater than or 584 equal to version '3' (the version at which SSH_FXP_EXTENDED was 585 introduced) in the initial VERSION/INIT exchange, the client may 586 select a new version to use from the list the server provided using 587 the following SSH_FXP_EXTENDED request. 589 string "version-select" 590 string version-from-list 592 If the 'version-from-list' is one of the versions on the servers 593 list, the server MUST respond with SSH_FX_OK. If the server did not 594 send the "versions" extension, or the version-from-list was not 595 included, the server MAY send a status response describing the 596 failure, but MUST then close the channel without processing any 597 further requests. 599 The 'version-select' MUST be the first request from the client to the 600 server; if it is not, the server MUST fail the request and close the 601 channel. 603 Although this request does take a full round trip, no client need 604 wait for the response before continuing, because any valid request 605 MUST succeed, and any invalid request results in a channel close. 606 Since the request is the first request, it is not possible for the 607 server to have already sent responses conforming to the old version. 609 Typically, the client SHOULD NOT down-grade the protocol version 610 using this extension; however, it is not forbidden to do so. One 611 reason a client might do so is to work around a buggy implementation. 613 6. File Names 615 This protocol represents file names as strings. File names are 616 assumed to use the slash ('/') character as a directory separator. 618 File names starting with a slash are "absolute", and are relative to 619 the root of the file system. Names starting with any other character 620 are relative to the user's default directory (home directory). Note 621 that identifying the user is assumed to take place outside of this 622 protocol. 624 Servers SHOULD interpret a path name component ".." (Section 12) as 625 referring to the parent directory, and "." as referring to the 626 current directory. 628 An empty path name is valid, and it refers to the user's default 629 directory (usually the user's home directory). 631 Otherwise, no syntax is defined for file names by this specification. 632 Clients should not make any other assumptions; however, they can 633 splice path name components returned by SSH_FXP_READDIR together 634 using a slash ('/') as the separator, and that will work as expected. 636 It is understood that the lack of well-defined semantics for file 637 names may cause interoperability problems between clients and servers 638 using radically different operating systems. However, this approach 639 is known to work acceptably with most systems, and alternative 640 approaches that e.g. treat file names as sequences of structured 641 components are quite complicated. 643 The preferred encoding for filenames is UTF-8. This is consistent 644 with IETF Policy on Character Sets and Languages [RFC2277] and it is 645 further supposed that the server is more likely to support any local 646 character set and be able to convert it to UTF-8. 648 However, because the server does not always know the encoding of 649 filenames, it is not always possible for the server to preform a 650 valid translation to UTF-8. When an invalid translation to UTF-8 is 651 preformed, it becomes impossible to manipulate the file, because the 652 translation is not reversible. Therefore, the following extensions 653 are provided in order to make it possible for the server to 654 communicate it's abilities to the client, and to allow the client to 655 control whether the server attempts the conversion. 657 A server MAY include the following extension with it's version 658 packet. 660 string "filename-charset" 661 string charset-name 663 A server that can always provide a valid UTF-8 translation for 664 filenames SHOULD NOT send this extension. Otherwise, the server 665 SHOULD send this extension and include the encoding most likely to be 666 used for filenames. This value will most likely be derived from the 667 LC_CTYPE on most unix-like systems. 669 A server that does not send this extension MUST send all filenames 670 encoded in UTF-8. All clients MUST support UTF-8 filenames. 672 If the server included the 'filename-charset' extension with its 673 VERSION packet, a client MAY send the following extension to turn off 674 server translation to UTF-8. 676 string "filename-translation-control" 677 bool do-translate 679 If the client does not send this extension, the server MUST continue 680 to attempt translation to UTF-8. When a client sends this extension, 681 the server MUST enable filename translation if 'do-translate' is 682 true, or disable filename translation if it is false. 684 The server MUST respond with a STATUS response; if the server sent a 685 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, 686 the status MUST be SSH_FX_OP_UNSUPPORTED. 688 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE 689 data MUST be used. The server is responsible for converting the 690 UNICODE data to whatever canonical form it requires. For example, if 691 the server requires that precomposed characters always be used, the 692 server MUST NOT assume the filename as sent by the client has this 693 attribute, but must do this normalization itself. 695 7. File Attributes 697 A new compound data type, 'ATTRS', is defined for encoding file 698 attributes. The same encoding is used both when returning file 699 attributes from the server and when sending file attributes to the 700 server. 702 uint32 valid-attribute-flags 703 byte type always present 704 uint64 size if flag SIZE 705 uint64 allocation-size if flag ALLOCATION_SIZE 706 string owner if flag OWNERGROUP 707 string group if flag OWNERGROUP 708 uint32 permissions if flag PERMISSIONS 709 int64 atime if flag ACCESSTIME 710 uint32 atime-nseconds if flag SUBSECOND_TIMES 711 int64 createtime if flag CREATETIME 712 uint32 createtime-nseconds if flag SUBSECOND_TIMES 713 int64 mtime if flag MODIFYTIME 714 uint32 mtime-nseconds if flag SUBSECOND_TIMES 715 int64 ctime if flag CTIME 716 uint32 ctime-nseconds if flag SUBSECOND_TIMES 717 string acl if flag ACL 718 uint32 attrib-bits if flag BITS 719 uint32 attrib-bits-valid if flag BITS 720 byte text-hint if flag TEXT_HINT 721 string mime-type if flag MIME_TYPE 722 uint32 link-count if flag LINK_COUNT 723 string untranslated-name if flag UNTRANSLATED_NAME 724 uint32 extended-count if flag EXTENDED 725 extended-pair extensions 727 7.1. valid-attribute-flags 729 The 'valid-attribute-flags' specifies which of the fields are 730 present. Those fields for which the corresponding flag is not set 731 are not present (not included in the packet). 733 The server generally includes all attributes it knows about; however, 734 it may exclude attributes that are overly expensive to retrieve 735 unless the client explicitly requests them. 737 When writing attributes, the server SHOULD NOT modify attributes that 738 are not present in the structure. However, if necessary, the server 739 MAY use a default value for an absent attribute. 741 In general, unless otherwise specified, if a server cannot support 742 writing an attribute requested, it must fail the setstat operation. 743 In this case, none of the attributes SHOULD be changed. 745 New fields can only be added by incrementing the protocol version 746 number (or by using the extension mechanism described below). 748 The following values are defined: 750 SSH_FILEXFER_ATTR_SIZE 0x00000001 751 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 752 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 753 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 754 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 755 SSH_FILEXFER_ATTR_ACL 0x00000040 756 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 757 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 758 SSH_FILEXFER_ATTR_BITS 0x00000200 759 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 760 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 761 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 762 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 763 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 764 SSH_FILEXFER_ATTR_CTIME 0x00008000 765 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 767 0x00000002 was used in a previous version of this protocol. It is 768 now a reserved value and MUST NOT appear in the mask. Some future 769 version of this protocol may reuse this value. 771 7.2. Type 773 The type field is always present. The following types are defined: 775 SSH_FILEXFER_TYPE_REGULAR 1 776 SSH_FILEXFER_TYPE_DIRECTORY 2 777 SSH_FILEXFER_TYPE_SYMLINK 3 778 SSH_FILEXFER_TYPE_SPECIAL 4 779 SSH_FILEXFER_TYPE_UNKNOWN 5 780 SSH_FILEXFER_TYPE_SOCKET 6 781 SSH_FILEXFER_TYPE_CHAR_DEVICE 7 782 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 783 SSH_FILEXFER_TYPE_FIFO 9 785 On a POSIX system, these values would be derived from the mode field 786 of the stat structure. SPECIAL should be used for files that are of 787 a known type which cannot be expressed in the protocol. UNKNOWN 788 should be used if the type is not known. 790 7.3. Size 792 The 'size' field specifies the number of bytes that can be read from 793 the file, or in other words, the location of the end-of-file. This 794 attribute MUST NOT be present during file creation. 796 If this field is present during a setstat operation, the file MUST be 797 extended or truncated to the specified size. 799 Files opened with the SSH_FXF_TEXT flag may have a size that is 800 greater or less than the value of the size field. The server MAY 801 fail setstat operations specifying size for files opened with the 802 SSH_FXF_TEXT flag. 804 7.4. allocation-size 806 The 'allocation-size' field specifies the number of bytes that the 807 file consumes on disk. This field MAY be less than the 'size' field 808 if the file is 'sparse' (Section 7.9). 810 When present during file creation, the file SHOULD be created and the 811 specified number of bytes preallocated. If the preallocation fails, 812 the file should be removed (if it was created) and an error returned. 814 If this field is present during a setstat operation, the file SHOULD 815 be extended or truncated to the specified size. The 'size' of the 816 file may be affected by this operation. If the operation succeeds, 817 the 'size' should be the minimum of the 'size' before the operation 818 and the new 'allocation-size'. 820 Querying the 'allocation-size' after setting it MUST return a value 821 that is greater-than or equal to the value set, but it MAY not return 822 the precise value set. 824 If both 'size' and 'allocation-size' are set during a setstat 825 operation, and 'allocation-size' is less than 'size', the server MUST 826 return SSH_FX_INVALID_PARAMETER. 828 7.5. Owner and Group 830 The 'owner' and 'group' fields are represented as UTF-8 strings; this 831 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. 832 The following text is selected quotations from section 5.6. 834 To avoid a representation that is tied to a particular underlying 835 implementation at the client or server, the use of UTF-8 strings has 836 been chosen. The string should be of the form "user@dns_domain". 837 This will allow for a client and server that do not use the same 838 local representation the ability to translate to a common syntax that 839 can be interpreted by both. In the case where there is no 840 translation available to the client or server, the attribute value 841 must be constructed without the "@". Therefore, the absence of the @ 842 from the owner or owner_group attribute signifies that no translation 843 was available and the receiver of the attribute should not place any 844 special meaning on the attribute value. Even though the attribute 845 value cannot be translated, it may still be useful. In the case of a 846 client, the attribute string may be used for local display of 847 ownership. 849 user@localhost represents a user in the context of the server. 851 If either the owner or group field is zero length, the field should 852 be considered absent, and no change should be made to that specific 853 field during a modification operation. 855 7.6. Permissions 857 The 'permissions' field contains a bit mask specifying file 858 permissions. These permissions correspond to the st_mode field of 859 the stat structure defined by POSIX [IEEE.1003-1.1996]. 861 This protocol uses the following values for the symbols declared in 862 the POSIX standard. 864 S_IRUSR 0000400 (octal) 865 S_IWUSR 0000200 866 S_IXUSR 0000100 867 S_IRGRP 0000040 868 S_IWGRP 0000020 869 S_IXGRP 0000010 870 S_IROTH 0000004 871 S_IWOTH 0000002 872 S_IXOTH 0000001 873 S_ISUID 0004000 874 S_ISGID 0002000 875 S_ISVTX 0001000 877 Implementations MUST NOT send bits that are not defined. 879 The server SHOULD NOT apply a 'umask' to the mode bits; but should 880 set the mode bits as specified by the client. The client MUST apply 881 an appropriate 'umask' to the mode bits before sending them. 883 7.7. Times 885 The 'atime' field contains the last access time of the file. Many 886 operating systems either don't have this field, only optionally 887 maintain it, or maintain it with less resolution than other fields. 889 The 'mtime' contains the last time the file was written. 891 'createtime' contains the creation time of the file. 893 'ctime' contains the last time the file attributes were changed. The 894 exact meaning of this field depends on the server. 896 All times are represented as seconds from Jan 1, 1970 in UTC. A 897 negative value indicates number of seconds before Jan 1, 1970. In 898 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 899 nseconds field is to be added to the seconds field for the final time 900 representation. For example, if the time to be represented is one- 901 half second before 0 hour January 1, 1970, the seconds field would 902 have a value of negative one (-1) and the nseconds fields would have 903 a value of one-half second (500000000). Values greater than 904 999,999,999 for nseconds are considered invalid. 906 7.8. ACL 908 The 'ACL' field contains an ACL similar to that defined in section 909 5.9 of NFS version 4 Protocol [RFC3010]. 911 The structure of the ACL is: 913 uint32 acl-flags 914 uint32 ace-count 915 ACE ace[ace-count] 917 The ACE data structure is composes as follows: 919 uint32 ace-type 920 uint32 ace-flag 921 uint32 ace-mask 922 string who [UTF-8] 924 acl-flags 926 SFX_ACL_CONTROL_INCLUDED 0x00000001 927 SFX_ACL_CONTROL_PRESENT 0x00000002 928 SFX_ACL_CONTROL_INHERITED 0x00000004 929 SFX_ACL_AUDIT_ALARM_INCLUDED 0x00000010 930 SFX_ACL_AUDIT_ALARM_INHERITED 0x00000020 932 SFX_ACL_CONTROL_INCLUDED 933 SFX_ACL_CONTROL_PRESENT 934 SFX_ACL_CONTROL_INHERITED 935 If INCLUDED is set during a setstat operation, then the client 936 intends to modify the ALLOWED/DENIED entries of the ACL. 937 Otherwise, the client intends for these entries to be 938 preserved. 940 If the PRESENT bit is not set, then the client wishes to remove 941 control entries. If the server doesn't support separate 942 control and audit information, the client MUST not clear this 943 bit without also clearing the AUDIT_ALARM_PRESENT bit. 945 If the PRESENT bit is clear, then control of the file MAY be 946 through the permissions mask. The server MAY also grant full 947 access to the file. 949 If the both the INCLUDE and the PRESENT bit are set, but their 950 are no ALLOW/DENY entries in the list, the client wishes to 951 deny all access to the file or directory. The server may have 952 to transform this into a ACL with a deny entry to implement it. 954 If INHERITED is set, then ALLOW/DENY ACEs MAY be inherited from 955 the parent directory. If it is off, then they MUST not be 956 INHERITED. If the server does not support controlling 957 inheritance, then the client MUST clear this bit; in this case 958 the inheritance properties of the server are undefined. 960 SFX_ACL_AUDIT_ALARM_INCLUDED 961 SFX_ACL_AUDIT_ALARM_INHERITED 962 If INCLUDE is set during a setstat operation, then the client 963 intends to modify the AUDIT/ALARM entries of the ACL. 964 Otherwise, the client intends for these entries to be 965 preserved. 967 If INHERITED is set, then AUDIT/ALARM ACEs MAY be inherited 968 from the parent directory. If it is off, then they MUST not be 969 INHERITED. If the server does not support controlling 970 inheritance, then the client MUST clear this bit; in this case 971 the inheritance properties of the server are undefined. 973 Because some server require special permissions / privileges in 974 order to modify the AUDIT/ALARM entries in the ACL, it is 975 important to communicate to the server the clients intent to 976 modify these entries. The client MUST both use the 977 ACCESS_AUDIT_ALARM_ATTRIBUTES bit in the desired attribute of the 978 open request and must set the SFX_ACL_AUDIT_ALARM_INCLUDED during 979 the setstat operation. 981 Clients that do not intend specifically to modify the AUDIT or 982 ALARM entries SHOULD NOT set SSH_FXF_ACCESS_AUDIT_ALARM_INFO in 983 the open-flags and SHOULD NOT set the SFX_ACL_AUDIT_ALARM_INCLUDED 984 bit because these operations are often privileged and will fail. 986 If the SFX_ACL_AUDIT_ALARM_INCLUDED is set, and the requested 987 change can not be made, the server MUST fail the request. 989 Servers that do not seperate control and audit/alarm information 990 may have to read the existing ACL and merge in enteries not 991 included by the client. The server must take this into account 992 when opening files with the ACE4_WRITE_ACL permission requested. 994 ace-type 995 one of the following four values (taken from NFS Version 4 996 Protocol [RFC3010]: 998 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 999 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 1000 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 1001 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 1003 ace-flag 1004 A combination of the following flag values. See NFS Version 4 1005 Protocol [RFC3010] section 5.9.2: 1007 ACE4_FILE_INHERIT_ACE 0x00000001 1008 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 1009 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 1010 ACE4_INHERIT_ONLY_ACE 0x00000008 1011 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 1012 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 1013 ACE4_IDENTIFIER_GROUP 0x00000040 1015 ace-mask 1016 Combination of the following flags (taken from [RFC3010], section 1017 5.9.3. The semantic meaning of these flags is also given in 1018 [RFC3010]. 1020 ACE4_READ_DATA 0x00000001 1021 ACE4_LIST_DIRECTORY 0x00000001 1022 ACE4_WRITE_DATA 0x00000002 1023 ACE4_ADD_FILE 0x00000002 1024 ACE4_APPEND_DATA 0x00000004 1025 ACE4_ADD_SUBDIRECTORY 0x00000004 1026 ACE4_READ_NAMED_ATTRS 0x00000008 1027 ACE4_WRITE_NAMED_ATTRS 0x00000010 1028 ACE4_EXECUTE 0x00000020 1029 ACE4_DELETE_CHILD 0x00000040 1030 ACE4_READ_ATTRIBUTES 0x00000080 1031 ACE4_WRITE_ATTRIBUTES 0x00000100 1032 ACE4_DELETE 0x00010000 1033 ACE4_READ_ACL 0x00020000 1034 ACE4_WRITE_ACL 0x00040000 1035 ACE4_WRITE_OWNER 0x00080000 1036 ACE4_SYNCHRONIZE 0x00100000 1038 who 1039 UTF-8 string of the form described in 'Owner and Group' 1040 (Section 7.5) 1041 Also, as per '5.9.4 ACE who' [RFC3010] there are several 1042 identifiers that need to be understood universally. Some of these 1043 identifiers cannot be understood when an client access the server, 1044 but have meaning when a local process accesses the file. The 1045 ability to display and modify these permissions is permitted over 1046 SFTP. 1048 OWNER The owner of the file. 1049 GROUP The group associated with the file. 1050 EVERYONE The world. 1051 INTERACTIVE Accessed from an interactive terminal. 1052 NETWORK Accessed via the network. 1053 DIALUP Accessed as a dialup user to the server. 1054 BATCH Accessed from a batch job. 1055 ANONYMOUS Accessed without any authentication. 1056 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 1057 SERVICE Access from a system service. 1058 To avoid conflict, these special identifiers are distinguish by an 1059 appended "@". For example: ANONYMOUS@. 1061 7.9. attrib-bits and attrib-bits-valid 1063 These fields, taken together, reflect various attributes of the file 1064 or directory, on the server. 1066 Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- 1067 bits' field. This allows both the server and the client to 1068 communicate only the bits it knows about without inadvertently 1069 twiddling bits they don't understand. 1071 The following attrib-bits are defined: 1073 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 1074 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 1075 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 1076 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 1077 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 1078 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 1079 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 1080 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 1081 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 1082 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 1083 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 1084 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 1086 SSH_FILEXFER_ATTR_FLAGS_READONLY 1087 Advisory, read-only bit. This bit is not part of the access 1088 control information on the file, but is rather an advisory field 1089 indicating that the file should not be written. 1091 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 1092 The file is part of the operating system. 1094 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 1095 File SHOULD NOT be shown to user unless specifically requested. 1096 For example, most UNIX systems SHOULD set this bit if the filename 1097 begins with a 'period'. This bit may be read-only (Section 5.4). 1098 Most UNIX systems will not allow this to be changed. 1100 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 1101 This attribute applies only to directories. This attribute is 1102 always read-only, and cannot be modified. This attribute means 1103 that files and directory names in this directory should be 1104 compared without regard to case. 1106 It is recommended that where possible, the server's filesystem be 1107 allowed to do comparisons. For example, if a client wished to 1108 prompt a user before overwriting a file, it should not compare the 1109 new name with the previously retrieved list of names in the 1110 directory. Rather, it should first try to create the new file by 1111 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 1112 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 1113 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 1115 Unless otherwise specified, filenames are assumed to be case 1116 sensitive. 1118 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 1119 The file should be included in backup / archive operations. 1121 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 1122 The file is stored on disk using file-system level transparent 1123 encryption. This flag does not affect the file data on the wire 1124 (for either READ or WRITE requests.) 1126 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 1127 The file is stored on disk using file-system level transparent 1128 compression. This flag does not affect the file data on the wire. 1130 SSH_FILEXFER_ATTR_FLAGS_SPARSE 1131 The file is a sparse file; this means that file blocks that have 1132 not been explicitly written are not stored on disk. For example, 1133 if a client writes a buffer at 10 M from the beginning of the 1134 file, the blocks between the previous EOF marker and the 10 M 1135 offset would not consume physical disk space. 1137 Some servers may store all files as sparse files, in which case 1138 this bit will be unconditionally set. Other servers may not have 1139 a mechanism for determining if the file is sparse, and so the file 1140 MAY be stored sparse even if this flag is not set. 1142 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 1143 Opening the file without either the SSH_FXF_APPEND_DATA or the 1144 SSH_FXF_APPEND_DATA_ATOMIC flag (Section 8.1.1.3) MUST result in 1145 an SSH_FX_INVALID_PARAMETER error. 1147 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 1148 The file cannot be deleted or renamed, no hard link can be created 1149 to this file, and no data can be written to the file. 1151 This bit implies a stronger level of protection than 1152 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 1153 ACLs. Typically even the superuser cannot write to immutable 1154 files, and only the superuser can set or remove the bit. 1156 SSH_FILEXFER_ATTR_FLAGS_SYNC 1157 When the file is modified, the changes are written synchronously 1158 to the disk. 1160 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 1161 The server MAY include this bit in a directory listing or realpath 1162 response. It indicates there was a failure in the translation to 1163 UTF-8. If this flag is included, the server SHOULD also include 1164 the UNTRANSLATED_NAME attribute. 1166 7.10. text-hint 1168 The value is one of the following enumerations, and indicates what 1169 the server knows about the content of the file. 1171 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 1172 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 1173 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 1174 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 1176 SSH_FILEXFER_ATTR_KNOWN_TEXT 1177 The server knows the file is a text file, and should be opened 1178 using the SSH_FXF_TEXT_MODE flag. 1180 SSH_FILEXFER_ATTR_GUESSED_TEXT 1181 The server has applied a heuristic or other mechanism and believes 1182 that the file should be opened with the SSH_FXF_TEXT_MODE flag. 1184 SSH_FILEXFER_ATTR_KNOWN_BINARY 1185 The server knows the file has binary content. 1187 SSH_FILEXFER_ATTR_GUESSED_BINARY 1188 The server has applied a heuristic or other mechanism and believes 1189 has binary content, and should not be opened with the 1190 SSH_FXF_TEXT_MODE flag. 1192 This flag MUST NOT be present during either a setstat or a fsetstat 1193 operation. 1195 7.11. mime-type 1197 The 'mime-type' field contains the mime-type [RFC1521] string. Most 1198 servers will not know this information and should not set the bit in 1199 their supported-attribute-mask. 1201 7.12. link-count 1203 This field contains the hard link count of the file. This attribute 1204 MUST NOT be present during a setstat operation. 1206 7.13. untranslated-name 1208 This field contains the name before filename translation was attempt. 1209 It MUST NOT be included unless the server also set the 1210 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 7.9) bit in the 1211 attrib-bits field. 1213 7.14. Extended Attributes 1215 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 1216 mechanism for the attrib structure. If the flag is specified, then 1217 the 'extended_count' field is present. It specifies the number of 1218 'extension-pair' items that follow. Each of these items specifies an 1219 extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED 1220 if there are any unrecognized extensions. Clients can avoid sending 1221 unsupported extensions by examining the attrib-extension-names of the 1222 "supported2" extension attrib-extension-names (Section 5.4). 1224 Additional fields can be added to the attributes by either defining 1225 additional bits to the flags field to indicate their presence, or by 1226 defining extended attributes for them. The extended attributes 1227 mechanism is recommended for most purposes; additional flags bits 1228 should be defined only by an IETF standards action that also 1229 increments the protocol version number. The use of such new fields 1230 MUST be negotiated by the version number in the protocol exchange. 1231 It is a protocol error if a packet with unsupported protocol bits is 1232 received. 1234 8. Requests From the Client to the Server 1236 Requests from the client to the server represent the various file 1237 system operations. 1239 8.1. Opening and Closing Files and Directories 1241 Many operations in the protocol operate on open files. The 1242 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 1243 an opaque, variable-length string) which may be used to access the 1244 file or directory later. The client MUST NOT send requests to the 1245 server with bogus or closed handles. However, the server MUST 1246 perform adequate checks on the handle in order to avoid security 1247 risks due to fabricated handles. 1249 This design allows either stateful and stateless server 1250 implementation, as well as an implementation which caches state 1251 between requests but may also flush it. The contents of the file 1252 handle string are entirely up to the server and its design. The 1253 client should not modify or attempt to interpret the file handle 1254 strings. 1256 The file handle strings MUST NOT be longer than 256 bytes. 1258 8.1.1. Opening a File 1260 Files are opened and created using the SSH_FXP_OPEN message. 1262 byte SSH_FXP_OPEN 1263 uint32 request-id 1264 string filename [UTF-8] 1265 uint32 desired-access 1266 uint32 flags 1267 ATTRS attrs 1269 The response to this message will be either SSH_FXP_HANDLE (if the 1270 operation is successful) or SSH_FXP_STATUS (if the operation fails.) 1272 8.1.1.1. filename 1274 The 'filename' field specifies the file name. See Section ''File 1275 Names'' for more information. If 'filename' is a directory file, the 1276 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 1278 8.1.1.2. desired-access 1280 The 'desired-access' field is a bitmask containing a combination of 1281 values from the ace-mask flags (Section 7.8). Note that again, the 1282 meaning of these flags is given in [RFC3010]. 1284 The server MUST be prepared to translate the SFTP access flags into 1285 its local equivalents. If the server cannot grant the access 1286 desired, it MUST return SSH_FX_PERMISSION_DENIED. 1288 The server MAY open the file with greater access than requested if 1289 the user has such access and the server implementation requires it. 1290 For example, a server that does not distinguish between 1291 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access 1292 to the file when the client only requested READ_ATTRIBUTE, resulting 1293 in greater access than the client originally requested. 1295 In such cases, it is possible, and permissible in the protocol, that 1296 the client could open a file requesting some limited access, and then 1297 access the file in a way not permitted by that limited access and the 1298 server would permit such action. However, the server MUST NOT ever 1299 grant access to the file that the client does not actually have the 1300 rights to. 1302 8.1.1.3. flags 1304 The 'flags' field controls various aspects of the operation, 1305 including whether or not the file is created and the kind of locking 1306 desired. 1308 The following 'flags' are defined: 1310 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 1311 SSH_FXF_CREATE_NEW = 0x00000000 1312 SSH_FXF_CREATE_TRUNCATE = 0x00000001 1313 SSH_FXF_OPEN_EXISTING = 0x00000002 1314 SSH_FXF_OPEN_OR_CREATE = 0x00000003 1315 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 1316 SSH_FXF_APPEND_DATA = 0x00000008 1317 SSH_FXF_APPEND_DATA_ATOMIC = 0x00000010 1318 SSH_FXF_TEXT_MODE = 0x00000020 1319 SSH_FXF_BLOCK_READ = 0x00000040 1320 SSH_FXF_BLOCK_WRITE = 0x00000080 1321 SSH_FXF_BLOCK_DELETE = 0x00000100 1322 SSH_FXF_BLOCK_ADVISORY = 0x00000200 1323 SSH_FXF_NOFOLLOW = 0x00000400 1324 SSH_FXF_DELETE_ON_CLOSE = 0x00000800 1325 SSH_FXF_ACCESS_AUDIT_ALARM_INFO = 0x00001000 1326 SSH_FXF_ACCESS_BACKUP = 0x00002000 1327 SSH_FXF_BACKUP_STREAM = 0x00004000 1328 SSH_FXF_OVERRIDE_OWNER = 0x00008000 1330 SSH_FXF_ACCESS_DISPOSITION 1331 Disposition is a 3 bit field that controls how the file is opened. 1332 The server MUST support these bits. Any one of the following 1333 enumeration is allowed: 1335 SSH_FXF_CREATE_NEW 1336 A new file is created; if the file already exists, the server 1337 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 1339 SSH_FXF_CREATE_TRUNCATE 1340 A new file is created; if the file already exists, it is opened 1341 and truncated. 1343 SSH_FXF_OPEN_EXISTING 1344 An existing file is opened. If the file does not exist, the 1345 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 1346 path does not exist, the server SHOULD return 1347 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 1348 returns SSH_FX_NO_SUCH_FILE in this case. 1350 SSH_FXF_OPEN_OR_CREATE 1351 If the file exists, it is opened. If the file does not exist, 1352 it is created. 1354 SSH_FXF_TRUNCATE_EXISTING 1355 An existing file is opened and truncated. If the file does not 1356 exist, the server MUST return the same error codes as defined 1357 for SSH_FXF_OPEN_EXISTING. 1359 SSH_FXF_APPEND_DATA 1360 Data is always written at the end of the file. The offset field 1361 of the SSH_FXP_WRITE requests are ignored. 1363 Data is not required to be appended atomically. This means that 1364 if multiple writers attempt to append data simultaneously, data 1365 from the first may be lost. However, data MAY be appended 1366 atomically. 1368 SSH_FXF_APPEND_DATA_ATOMIC 1369 Data is always written at the end of the file. The offset field 1370 of the SSH_FXP_WRITE requests are ignored. 1372 Data MUST be written atomically so that there is no chance that 1373 multiple appenders can collide and result in data being lost. 1375 If both append flags are specified, the server SHOULD use atomic 1376 append if it is available, but SHOULD use non-atomic appends 1377 otherwise. The server SHOULD NOT fail the request in this case. 1379 SSH_FXF_TEXT_MODE 1380 Indicates that the server should treat the file as text and 1381 convert it to the canonical newline convention in use. (See 1382 Determining Server Newline Convention. (Section 5.3) 1384 When a file is opened with this flag, the offset field in the read 1385 and write functions is ignored. 1387 Servers MUST process multiple, parallel reads and writes correctly 1388 in this mode. Naturally, it is permissible for them to do this by 1389 serializing the requests. 1391 Clients SHOULD use the SSH_FXF_APPEND_DATA flag to append data to 1392 a text file rather then using write with a calculated offset. 1394 To support seeks on text files the following SSH_FXP_EXTENDED 1395 packet is defined. 1397 string "text-seek" 1398 string file-handle 1399 uint64 line-number 1401 line-number is the index of the line number to seek to, where byte 1402 0 in the file is line number 0, and the byte directly following 1403 the first newline sequence in the file is line number 1 and so on. 1405 The response to a "text-seek" request is an SSH_FXP_STATUS 1406 message. 1408 An attempt to seek past the end-of-file should result in a 1409 SSH_FX_EOF status. 1411 Servers SHOULD support at least one "text-seek" in order to 1412 support resume. However, a client MUST be prepared to receive 1413 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 1414 The client can then try a fall-back strategy, if it has one. 1416 SSH_FXF_BLOCK_READ 1417 The server MUST guarantee that no other handle has been opened 1418 with ACE4_READ_DATA access, and that no other handle will be 1419 opened with ACE4_READ_DATA access until the client closes the 1420 handle. (This MUST apply both to other clients and to other 1421 processes on the server.) 1423 If there is a conflicting lock the server MUST return 1424 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1425 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1427 Other handles MAY be opened for ACE4_WRITE_DATA or any other 1428 combination of accesses, as long as ACE4_READ_DATA is not included 1429 in the mask. 1431 SSH_FXF_BLOCK_WRITE 1432 The server MUST guarantee that no other handle has been opened 1433 with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other 1434 handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA 1435 access until the client closes the handle. (This MUST apply both 1436 to other clients and to other processes on the server.) 1437 If there is a conflicting lock the server MUST return 1438 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1439 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1441 Other handles MAY be opened for ACE4_READ_DATA or any other 1442 combination of accesses, as long as neither ACE4_WRITE_DATA nor 1443 ACE4_APPEND_DATA are included in the mask. 1445 SSH_FXF_BLOCK_DELETE 1446 The server MUST guarantee that no other handle has been opened 1447 with ACE4_DELETE access, opened with the SSH_FXF_DELETE_ON_CLOSE 1448 flag set, and that no other handle will be opened with ACE4_DELETE 1449 access or with the SSH_FXF_DELETE_ON_CLOSE flag set, and that the 1450 file itself is not deleted in any other way until the client 1451 closes the handle. 1453 If there is a conflicting lock the server MUST return 1454 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1455 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1457 SSH_FXF_BLOCK_ADVISORY 1458 If this bit is set, the above BLOCK modes are advisory. In 1459 advisory mode, only other accesses that specify a BLOCK mode need 1460 be considered when determining whether the BLOCK can be granted, 1461 and the server need not prevent I/O operations that violate the 1462 block mode. 1464 The server MAY perform mandatory locking even if the 1465 BLOCK_ADVISORY bit is set. 1467 SSH_FXF_NOFOLLOW 1468 If the final component of the path is a symlink, then the open 1469 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 1471 SSH_FXF_DELETE_ON_CLOSE 1472 The file should be deleted when the last handle to it is closed. 1473 (The last handle may not be an sftp-handle.) This MAY be emulated 1474 by a server if the OS doesn't support it by deleting the file when 1475 this handle is closed. 1477 It is implementation specific whether the directory entry is 1478 removed immediately or when the handle is closed. 1480 SSH_FXF_ACCESS_AUDIT_ALARM_INFO 1481 The client wishes the server to enable any privileges or extra 1482 capabilities that the user may have in to allow the reading and 1483 writing of AUDIT or ALARM access control entries. 1485 SSH_FXF_ACCESS_BACKUP 1486 The client wishes the server to enable any privileges or extra 1487 capabilities that the user may have in order to bypass normal 1488 access checks for the purpose of backing up or restoring files. 1490 SSH_FXF_BACKUP_STREAM 1491 This bit indicates that the client wishes to read or write a 1492 backup stream. A backup stream is a system dependent structured 1493 data stream that encodes all the information that must be 1494 preserved in order to restore the file from backup medium. 1496 The only well defined use for backup stream data read in this 1497 fashion is to write it to the same server to a file also opened 1498 using the BACKUP_STREAM flag. However, if the server has a well 1499 defined backup stream format, their may be other uses for this 1500 data outside the scope of this protocol. 1502 ACCESS_OVERRIDE_OWNER 1503 This bit indicates that the client wishes the server to enable any 1504 privileges or extra capabilities that the user may have in order 1505 to gain access to the file with WRITE_OWNER permission. 1507 This bit MUST always be specified in combination with 1508 ACE4_WRITE_OWNER. 1510 The 'attrs' field specifies the initial attributes for the file. 1511 Default values MUST be supplied by the server for those attributes 1512 that are not specified. See Section ''File Attributes'' for more 1513 information. 1515 The 'attrs' field is ignored if an existing file is opened. 1517 The following table is provided to assist in mapping POSIX semantics 1518 to equivalent SFTP file open parameters: 1519 O_RDONLY 1520 desired-access = READ_DATA|READ_ATTRIBUTES 1522 O_WRONLY 1523 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1525 O_RDWR 1526 desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA| 1527 WRITE_ATTRIBUTES 1529 O_APPEND 1530 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1531 flags = SSH_FXF_APPEND_DATA and or SSH_FXF_APPEND_DATA_ATOMIC 1533 O_CREAT 1534 flags = SSH_FXF_OPEN_OR_CREATE 1536 O_TRUNC 1537 flags = SSH_FXF_TRUNCATE_EXISTING 1539 O_TRUNC|O_CREATE 1540 flags = SSH_FXF_CREATE_TRUNCATE 1542 8.1.2. Opening a Directory 1544 To enumerate a directory, the client first obtains a handle and then 1545 issues directory read requests. When enumeration is complete, the 1546 handle MUST be closed. 1548 byte SSH_FXP_OPENDIR 1549 uint32 request-id 1550 string path [UTF-8] 1552 path 1553 The 'path' field is the path name of the directory to be listed 1554 (without any trailing slash). See Section 'File Names' for more 1555 information on file names. 1557 If 'path' does not refer to a directory, the server MUST return 1558 SSH_FX_NOT_A_DIRECTORY. 1560 The response to this message will be either SSH_FXP_HANDLE (if the 1561 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1563 8.1.3. Closing Handles 1565 A handle is closed using the following request. 1567 byte SSH_FXP_CLOSE 1568 uint32 request-id 1569 string handle 1571 handle 1572 'handle' is a handle previously returned in the response to 1573 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid 1574 immediately after this request has been sent. 1576 The response to this request will be a SSH_FXP_STATUS message. Note 1577 that on some server platforms even a close can fail. For example, if 1578 the server operating system caches writes, and an error occurs while 1579 flushing cached writes, the close operation may fail. 1581 Note that the handle is invalid regardless of the SSH_FXP_STATUS 1582 result. There is no way for the client to recover a handle that 1583 fails to close. The client MUST release all resources associated 1584 with the handle regardless of the status. The server SHOULD take 1585 whatever steps it can to recover from a close failure and to ensure 1586 that all resources associated with the handle on the server are 1587 correctly released. 1589 8.2. Reading and Writing 1591 8.2.1. Reading Files 1593 The following request can be used to read file data: 1595 byte SSH_FXP_READ 1596 uint32 request-id 1597 string handle 1598 uint64 offset 1599 uint32 length 1601 handle 1602 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1603 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1604 return SSH_FX_INVALID_HANDLE. 1606 offset 1607 The offset (in bytes) relative to the beginning of the file that 1608 the read MUST start at. This field is ignored if 1609 SSH_FXF_TEXT_MODE was specified during the open. 1611 length 1612 'length' is the maximum number of bytes to read. 1614 The server MUST not respond with more data than is specified by 1615 the 'length' parameter. However, the server MAY respond with less 1616 data if EOF is reached, an error is encountered, or the servers 1617 internal buffers can not handle such a large request. 1619 If the server specified a non-zero 'max-read-size' in its 1620 'supported2' (Section 5.4) extension, then failure to return 1621 'length' bytes indicates that EOF or an error occurred. 1623 8.2.2. Reading Directories 1625 In order to retrieve a directory listing, the client issues one or 1626 more SSH_FXP_READDIR requests. In order to obtain a complete 1627 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1628 requests until the server responds with an SSH_FXP_STATUS message. 1630 byte SSH_FXP_READDIR 1631 uint32 request-id 1632 string handle 1634 handle 1635 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is 1636 an ordinary file handle returned by SSH_FXP_OPEN, the server MUST 1637 return SSH_FX_INVALID_HANDLE. 1639 The server responds to this request with either a SSH_FXP_NAME or a 1640 SSH_FXP_STATUS message. One or more names may be returned at a time. 1641 Full status information is returned for each name in order to speed 1642 up typical directory listings. 1644 If there are no more names available to be read, the server MUST 1645 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1647 8.2.3. Writing Files 1649 Writing to a file is achieved using the following message: 1651 byte SSH_FXP_WRITE 1652 uint32 request-id 1653 string handle 1654 uint64 offset 1655 string data 1657 handle 1658 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1659 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1660 return SSH_FX_INVALID_HANDLE. 1662 offset 1663 The offset (in bytes) relative to the beginning of the file that 1664 the write MUST start at. This field is ignored if 1665 SSH_FXF_TEXT_MODE was specified during the open. 1667 The write will extend the file if writing beyond the end of the 1668 file. It is legal to write to an offset that extends beyond the 1669 end of the file; the semantics are to write the byte value 0x00 1670 from the end of the file to the specified offset and then the 1671 data. On most operating systems, such writes do not allocate disk 1672 space but instead create a sparse file. 1674 data 1675 The data to write to the file. 1677 The server responds to a write request with a SSH_FXP_STATUS message. 1679 8.3. Removing and Renaming Files 1681 The following request can be used to remove a file: 1683 byte SSH_FXP_REMOVE 1684 uint32 request-id 1685 string filename [UTF-8] 1687 filename 1688 'filename' is the name of the file to be removed. See Section 1689 'File Names' for more information. 1691 If 'filename' is a symbolic link, the link is removed, not the 1692 file it points to. 1693 This request cannot be used to remove directories. The server 1694 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. 1696 The server will respond to this request with a SSH_FXP_STATUS 1697 message. 1699 Files (and directories) can be renamed using the SSH_FXP_RENAME 1700 message. 1702 byte SSH_FXP_RENAME 1703 uint32 request-id 1704 string oldpath [UTF-8] 1705 string newpath [UTF-8] 1706 uint32 flags 1708 where 'request-id' is the request identifier, 'oldpath' is the name 1709 of an existing file or directory, and 'newpath' is the new name for 1710 the file or directory. 1712 'flags' is 0 or a combination of: 1714 SSH_FXF_RENAME_OVERWRITE 0x00000001 1715 SSH_FXF_RENAME_ATOMIC 0x00000002 1716 SSH_FXF_RENAME_NATIVE 0x00000004 1718 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1719 exists a file with the name specified by newpath, the server MUST 1720 respond with SSH_FX_FILE_ALREADY_EXISTS. 1722 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1723 already exists, it is replaced in an atomic fashion. I.e., there is 1724 no observable instant in time where the name does not refer to either 1725 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1726 SSH_FXP_RENAME_OVERWRITE. 1728 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace 1729 the destination in an atomic fashion, then the server MUST respond 1730 with SSH_FX_OP_UNSUPPORTED. 1732 Because some servers cannot provide atomic rename, clients should 1733 only specify atomic rename if correct operation requires it. If 1734 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1735 atomic rename even if it is not requested. 1737 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1738 rename operation in whatever fashion it deems appropriate. Other 1739 flag values are considered hints as to desired behavior, but not 1740 requirements. 1742 The server will respond to this request with a SSH_FXP_STATUS 1743 message. 1745 8.4. Creating and Deleting Directories 1747 New directories can be created using the SSH_FXP_MKDIR request. It 1748 has the following format: 1750 byte SSH_FXP_MKDIR 1751 uint32 request-id 1752 string path [UTF-8] 1753 ATTRS attrs 1755 where 'request-id' is the request identifier. 1757 'path' specifies the directory to be created. See Section ''File 1758 Names'' for more information on file names. 1760 'attrs' specifies the attributes that should be applied to it upon 1761 creation. Attributes are discussed in more detail in Section ''File 1762 Attributes''. 1764 The server will respond to this request with a SSH_FXP_STATUS 1765 message. If a file or directory with the specified path already 1766 exists, an error will be returned. 1768 Directories can be removed using the SSH_FXP_RMDIR request, which has 1769 the following format: 1771 byte SSH_FXP_RMDIR 1772 uint32 request-id 1773 string path [UTF-8] 1775 where 'request-id' is the request identifier, and 'path' specifies 1776 the directory to be removed. See Section ''File Names'' for more 1777 information on file names. 1779 The server responds to this request with a SSH_FXP_STATUS message. 1781 8.5. Retrieving File Attributes 1783 Very often, file attributes are automatically returned by 1784 SSH_FXP_READDIR. However, sometimes there is need to specifically 1785 retrieve the attributes for a named file. This can be done using the 1786 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1788 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1789 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1790 follow symbolic links. Both have the same format: 1792 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1793 uint32 request-id 1794 string path [UTF-8] 1795 uint32 flags 1797 where 'request-id' is the request identifier, and 'path' specifies 1798 the file system object for which status is to be returned. The 1799 server responds to this request with either SSH_FXP_ATTRS or 1800 SSH_FXP_STATUS. 1802 The flags field specify the attribute flags in which the client has 1803 particular interest. This is a hint to the server. For example, 1804 because retrieving owner / group and acl information can be an 1805 expensive operation under some operating systems, the server may 1806 choose not to retrieve this information unless the client expresses a 1807 specific interest in it. 1809 The client has no guarantee the server will provide all the fields 1810 that it has expressed an interest in. 1812 SSH_FXP_FSTAT differs from the others in that it returns status 1813 information for an open file (identified by the file handle). 1815 byte SSH_FXP_FSTAT 1816 uint32 request-id 1817 string handle 1818 uint32 flags 1820 handle 1821 'handle' is an open file handle from either SSH_FXP_OPEN or 1822 SSH_FXP_OPENDIR. 1824 The server responds to this request with SSH_FXP_ATTRS or 1825 SSH_FXP_STATUS. 1827 8.6. Setting File Attributes 1829 File attributes may be modified using the SSH_FXP_SETSTAT and 1830 SSH_FXP_FSETSTAT requests. 1832 byte SSH_FXP_SETSTAT 1833 uint32 request-id 1834 string path [UTF-8] 1835 ATTRS attrs 1837 byte SSH_FXP_FSETSTAT 1838 uint32 request-id 1839 string handle 1840 ATTRS attrs 1842 path 1843 The file system object (e.g. file or directory) whose attributes 1844 are to be modified. If this object does not exist, or the user 1845 does not have sufficient access to write the attributes, the 1846 request MUST fail. 1848 handle 1849 'handle' is an open file handle from either SSH_FXP_OPEN or 1850 SSH_FXP_OPENDIR. If the handle was not opened with sufficient 1851 access to write the requested attributes, the request MUST fail. 1853 attrs 1854 Specifies the modified attributes to be applied. Attributes are 1855 discussed in more detail in Section ''File Attributes''. 1857 The server will respond with a SSH_FXP_STATUS message. 1859 Because some systems must use separate system calls to set various 1860 attributes, it is possible that a failure response will be returned, 1861 but yet some of the attributes may be have been successfully 1862 modified. If possible, servers SHOULD avoid this situation; however, 1863 clients MUST be aware that this is possible. 1865 8.7. Dealing with Links 1867 The SSH_FXP_READLINK request reads the target of a symbolic link. 1869 byte SSH_FXP_READLINK 1870 uint32 request-id 1871 string path [UTF-8] 1873 where 'request-id' is the request identifier and 'path' specifies the 1874 path name of the symlink to be read. 1876 The server will respond with a SSH_FXP_NAME packet containing only 1877 one name and a dummy attributes value. The name in the returned 1878 packet contains the target of the link. If an error occurs, the 1879 server MAY respond with SSH_FXP_STATUS. 1881 The SSH_FXP_LINK request creates a link (either hard or symbolic) on 1882 the server. 1884 byte SSH_FXP_LINK 1885 uint32 request-id 1886 string new-link-path [UTF-8] 1887 string existing-path [UTF-8] 1888 bool sym-link 1890 new-link-path 1891 Specifies the path name of the new link to create. 1893 existing-path 1894 Specifies the path of an existing file system object to which the 1895 new-link-path will refer. 1897 sym-link 1898 Specifies that the link should be a symbolic link, or a special 1899 file that redirects file system parsing to the resulting path. It 1900 is generally possible to create symbolic links across device 1901 boundaries; however, it is not required that a server support 1902 this. 1904 If 'sym-link' is false, the link should be a hard link, or a 1905 second directory entry referring to the same file or directory 1906 object. It is generally not possible to create hard links across 1907 devices. 1909 The server shall respond with a SSH_FXP_STATUS. Clients should be 1910 aware that some servers may return SSH_FX_OP_UNSUPPORTED for either 1911 the hard-link, sym-link, or both operations. 1913 8.8. Byte-range locks 1915 SSH_FXP_BLOCK creates a byte-range lock on the file specified by the 1916 handle. The lock can be either mandatory (meaning that the server 1917 enforces that no other process or client can perform operations in 1918 violation of the lock) or advisory (meaning that no other process can 1919 obtain a conflicting lock, but the server does not enforce that no 1920 operation violates the lock. 1922 A server MAY implement an advisory lock in a mandatory fashion; in 1923 other words, the server MAY enforce that no operation violates the 1924 lock even when operating in advisory mode. 1926 The result is a SSH_FXP_STATUS return. 1928 byte SSH_FXP_BLOCK 1929 uint32 request-id 1930 string handle 1931 uint64 offset 1932 uint64 length 1933 uint32 uLockMask 1935 handle 1936 'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. 1937 Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the 1938 handle is a directory handle. 1940 offset 1941 Beginning of the byte-range to lock. 1943 length 1944 Number of bytes in the range to lock. The special value 0 means 1945 lock from 'offset' to the end of the file. 1947 uLockMask 1948 A bit mask of SSH_FXF_BLOCK_* values; the meanings are described 1949 in Section 8.1.1.3. 1951 SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the 1952 specified handle. 1954 The result is a SSH_FXP_STATUS return. 1956 byte SSH_FXP_UNBLOCK 1957 uint32 request-id 1958 string handle 1959 uint64 offset 1960 uint64 length 1962 handle 1963 'handle' on which a SSH_FXP_BLOCK request has previously been 1964 issued. 1966 offset 1967 Beginning of the byte-range to lock. 1969 length 1970 Number of bytes in the range to lock. The special value 0 means 1971 lock from 'offset' to the end of the file. 1973 8.9. Canonicalizing the Server-Side Path Name 1975 The SSH_FXP_REALPATH request can be used to have the server 1976 canonicalize any given path name to an absolute path. This is useful 1977 for converting path names containing ".." components or relative 1978 pathnames without a leading slash into absolute paths. The format of 1979 the request is as follows: 1981 byte SSH_FXP_REALPATH 1982 uint32 request-id 1983 string original-path [UTF-8] 1984 byte control-byte [optional] 1985 string compose-path[0..n] [optional] 1987 original-path 1988 The first component of the path which the client wishes resolved 1989 into a absolute canonical path. This may be the entire path. 1991 control-byte 1993 SSH_FXP_REALPATH_NO_CHECK 0x00000001 1994 SSH_FXP_REALPATH_STAT_IF 0x00000002 1995 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 1997 This field is optional, and if it is not present in the packet, it 1998 is assumed to be SSH_FXP_REALPATH_NO_CHECK. 2000 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT 2001 fail the request if the path does not exist, is hidden, or the 2002 user does not have access to the path or some component thereof. 2003 In addition, the path MUST NOT resolve symbolic links. This 2004 allows paths to be composed for the SSH_FXP_REMOVE command to 2005 remove symbolic links. 2007 The server MAY fail the request if the path is not syntactically 2008 valid, or for other reasons. 2010 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the 2011 path if it exists and is accessible to the client. However, if 2012 the path does not exist, isn't visible, or isn't accessible, the 2013 server MUST NOT fail the request. If the stat failed, the file 2014 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to 2015 distinguish between files that are actually 2016 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will have 2017 to issue a separate stat command in this case. 2019 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat 2020 the path. If the stat operation fails, the server MUST fail the 2021 request. 2023 compose-path 2024 A path which the client wishes the server to compose with the 2025 original path to form the new path. This field is optional, and 2026 if it is not present in the packet, it is assumed to be a zero 2027 length string. 2029 The client may specify multiple 'compose-path' elements, in which 2030 case the server should build the resultant path up by applying 2031 each compose path to the accumulated result until all 'compose- 2032 path' elements have been applied. 2034 The server MUST take the 'original-path' and apply the 'compose-path' 2035 as a modification to it. 'compose-path' MAY be relative to 'original- 2036 path' or may be an absolute path, in which case 'original-path' will 2037 be discarded. The 'compose-path' MAY be zero length. 2039 The server will respond with a SSH_FXP_NAME packet containing the 2040 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK 2041 is specified, the attributes are dummy values. 2043 8.9.1. Best Practice for Dealing with Paths 2045 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 2047 Previous to this version, clients typically composed new paths 2048 themselves and then called both realpath and stat on the resulting 2049 path to get its canonical name and see if it really existed and was a 2050 directory. 2052 This required clients to assume certain things about how a relative 2053 vs. realpath looked. The new realpath allows clients to no longer 2054 make those assumptions and to remove one round trip from the process 2055 and get deterministic behavior from all servers. 2057 END: RFCEDITOR REMOVE BEFORE PUBLISHING 2059 The client SHOULD treat the results of SSH_FXP_REALPATH as a 2060 canonical absolute path, even if the path does not appear to be 2061 absolute. A client that uses REALPATH(".", "") and treats the result 2062 as absolute, even if there is no leading slash, will continue to 2063 function correctly, even when talking to a Windows NT or VMS style 2064 system, where absolute paths may not begin with a slash. 2066 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so 2067 that it does not need to know when a path is absolute or relative. 2069 For example, if the client wishes to change directory up, and the 2070 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 2071 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) 2073 As a second example, if the client wishes transfer local file "a" to 2074 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the 2075 canonical path of the current directory, the client SHOULD send 2076 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This 2077 call will determine the correct path to use for the open request and 2078 whether the /b/d/e represents a directory. 2080 9. Responses from the Server to the Client 2082 The server responds to the client using one of a few response 2083 packets. All requests can return a SSH_FXP_STATUS response upon 2084 failure. When the operation is successful, and no data needs to be 2085 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 2086 appropriate. 2088 Exactly one response will be returned for each request. Each 2089 response packet contains a request identifier which can be used to 2090 match each response with the corresponding request. Note that it is 2091 legal to have several requests outstanding simultaneously, and the 2092 server is allowed to send responses to them in a different order from 2093 the order in which the requests were sent (the result of their 2094 execution, however, is guaranteed to be as if they had been processed 2095 one at a time in the order in which the requests were sent). 2097 Response packets are of the same general format as request packets. 2098 Each response packet begins with the request identifier. 2100 9.1. Status Response 2102 The format of the data portion of the SSH_FXP_STATUS response is as 2103 follows: 2105 byte SSH_FXP_STATUS 2106 uint32 request-id 2107 uint32 error/status code 2108 string error message (ISO-10646 UTF-8 [RFC-2279]) 2109 string language tag (as defined in [RFC-1766]) 2110 error-specific data 2112 request-id 2113 The 'request-id' specified by the client in the request the server 2114 is responding to. 2116 error/status code 2117 Machine readable status code indicating the result of the request. 2118 Error code values are defined below. The value SSH_FX_OK 2119 indicates success, and all other values indicate failure. 2121 Implementations MUST be prepared to receive unexpected error codes 2122 and handle them sensibly (such as by treating them as equivalent 2123 to SSH_FX_FAILURE). Future protocol revisions will add additional 2124 error codes without changing the version number. 2126 error message 2127 Human readable description of the error. 2129 language tag 2130 'language tag' specifies the language the error is in. 2132 error-specific data 2133 The error-specific data may be empty, or may contain additional 2134 information about the error. For error codes that send error- 2135 specific data, the format of the data is defined below. 2137 Error codes: 2139 SSH_FX_OK 0 2140 SSH_FX_EOF 1 2141 SSH_FX_NO_SUCH_FILE 2 2142 SSH_FX_PERMISSION_DENIED 3 2143 SSH_FX_FAILURE 4 2144 SSH_FX_BAD_MESSAGE 5 2145 SSH_FX_NO_CONNECTION 6 2146 SSH_FX_CONNECTION_LOST 7 2147 SSH_FX_OP_UNSUPPORTED 8 2148 SSH_FX_INVALID_HANDLE 9 2149 SSH_FX_NO_SUCH_PATH 10 2150 SSH_FX_FILE_ALREADY_EXISTS 11 2151 SSH_FX_WRITE_PROTECT 12 2152 SSH_FX_NO_MEDIA 13 2153 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 2154 SSH_FX_QUOTA_EXCEEDED 15 2155 SSH_FX_UNKNOWN_PRINCIPAL 16 2156 SSH_FX_LOCK_CONFLICT 17 2157 SSH_FX_DIR_NOT_EMPTY 18 2158 SSH_FX_NOT_A_DIRECTORY 19 2159 SSH_FX_INVALID_FILENAME 20 2160 SSH_FX_LINK_LOOP 21 2161 SSH_FX_CANNOT_DELETE 22 2162 SSH_FX_INVALID_PARAMETER 23 2163 SSH_FX_FILE_IS_A_DIRECTORY 24 2164 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 2165 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 2166 SSH_FX_DELETE_PENDING 27 2167 SSH_FX_FILE_CORRUPT 28 2168 SSH_FX_OWNER_INVALID 29 2169 SSH_FX_GROUP_INVALID 30 2171 SSH_FX_OK 2172 Indicates successful completion of the operation. 2174 SSH_FX_EOF 2175 An attempt to read past the end-of-file was made; or, there are no 2176 more directory entries to return. 2178 SSH_FX_NO_SUCH_FILE 2179 A reference was made to a file which does not exist. 2181 SSH_FX_PERMISSION_DENIED 2182 The user does not have sufficient permissions to perform the 2183 operation. 2185 SSH_FX_FAILURE 2186 An error occurred, but no specific error code exists to describe 2187 the failure. 2189 This error message SHOULD always have meaningful text in the the 2190 'error message' field. 2192 SSH_FX_BAD_MESSAGE 2193 A badly formatted packet or other SFTP protocol incompatibility 2194 was detected. 2196 SSH_FX_NO_CONNECTION 2197 There is no connection to the server. This error MAY be used 2198 locally, but MUST NOT be return by a server. 2200 SSH_FX_CONNECTION_LOST 2201 The connection to the server was lost. This error MAY be used 2202 locally, but MUST NOT be return by a server. 2204 SSH_FX_OP_UNSUPPORTED 2205 An attempted operation could not be completed by the server 2206 because the server does not support the operation. 2208 This error MAY be generated locally by the client if e.g. the 2209 version number exchange indicates that a required feature is not 2210 supported by the server, or it may be returned by the server if 2211 the server does not implement an operation. 2213 SSH_FX_INVALID_HANDLE 2214 The handle value was invalid. 2216 SSH_FX_NO_SUCH_PATH 2217 The file path does not exist or is invalid. 2219 SSH_FX_FILE_ALREADY_EXISTS 2220 The file already exists. 2222 SSH_FX_WRITE_PROTECT 2223 The file is on read-only media, or the media is write protected. 2225 SSH_FX_NO_MEDIA 2226 The requested operation cannot be completed because there is no 2227 media available in the drive. 2229 SSH_FX_NO_SPACE_ON_FILESYSTEM 2230 The requested operation cannot be completed because there is no 2231 free space on the filesystem. 2233 SSH_FX_QUOTA_EXCEEDED 2234 The operation cannot be completed because it would exceed the 2235 user's storage quota. 2237 SSH_FX_UNKNOWN_PRINCIPAL 2238 A principal referenced by the request (either the 'owner', 2239 'group', or 'who' field of an ACL), was unknown. The error 2240 specific data contains the problematic names. The format is one 2241 or more: 2243 string unknown-name 2245 Each string contains the name of a principal that was unknown. 2247 SSH_FX_LOCK_CONFLICT 2248 The file could not be opened because it is locked by another 2249 process. 2251 SSH_FX_DIR_NOT_EMPTY 2252 The directory is not empty. 2254 SSH_FX_NOT_A_DIRECTORY 2255 The specified file is not a directory. 2257 SSH_FX_INVALID_FILENAME 2258 The filename is not valid. 2260 SSH_FX_LINK_LOOP 2261 Too many symbolic links encountered. 2263 SSH_FX_CANNOT_DELETE 2264 The file cannot be deleted. One possible reason is that the 2265 advisory READONLY attribute-bit is set. 2267 SSH_FX_INVALID_PARAMETER 2268 On of the parameters was out of range, or the parameters specified 2269 cannot be used together. 2271 SSH_FX_FILE_IS_A_DIRECTORY 2272 The specified file was a directory in a context where a directory 2273 cannot be used. 2275 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 2276 A read or write operation failed because another process's 2277 mandatory byte-range lock overlaps with the request. 2279 SSH_FX_BYTE_RANGE_LOCK_REFUSED 2280 A request for a byte range lock was refused. 2282 SSH_FX_DELETE_PENDING 2283 An operation was attempted on a file for which a delete operation 2284 is pending. 2286 SSH_FX_FILE_CORRUPT 2287 The file is corrupt; an filesystem integrity check should be run. 2289 SSH_FX_OWNER_INVALID 2290 The principal specified can not be assigned as an owner of a file. 2292 SSH_FX_GROUP_INVALID 2293 The principal specified can not be assigned as the primary group 2294 of a file. 2296 9.2. Handle Response 2298 The SSH_FXP_HANDLE response has the following format: 2300 byte SSH_FXP_HANDLE 2301 uint32 request-id 2302 string handle 2304 'handle' 2305 An arbitrary string that identifies an open file or directory on 2306 the server. The handle is opaque to the client; the client MUST 2307 NOT attempt to interpret or modify it in any way. The length of 2308 the handle string MUST NOT exceed 256 data bytes. 2310 9.3. Data Response 2312 The SSH_FXP_DATA response has the following format: 2314 byte SSH_FXP_DATA 2315 uint32 request-id 2316 string data 2317 bool end-of-file [optional] 2319 data 2320 'data' is an arbitrary byte string containing the requested data. 2321 The data string may be at most the number of bytes requested in a 2322 SSH_FXP_READ request, but may also be shorter. (See 2323 Section 8.2.1.) 2325 end-of-file 2326 This field is optional. If it is present in the packet, it MUST 2327 be true, and it indicates that EOF was reached during this read. 2328 This can help the client avoid a round trip to determine whether a 2329 short read was normal (due to EOF) or some other problem (limited 2330 server buffer for example.) 2332 9.4. Name Response 2334 The SSH_FXP_NAME response has the following format: 2336 byte SSH_FXP_NAME 2337 uint32 request-id 2338 uint32 count 2339 repeats count times: 2340 string filename [UTF-8] 2341 ATTRS attrs 2342 bool end-of-list [optional] 2344 count 2345 The number of names returned in this response, and the 'filename' 2346 and 'attrs' field repeat 'count' times. 2348 filename 2349 A file name being returned (for SSH_FXP_READDIR, it will be a 2350 relative name within the directory, without any path components; 2351 for SSH_FXP_REALPATH it will be an absolute path name.) 2353 attrs 2354 The attributes of the file as described in Section ''File 2355 Attributes''. 2357 end-of-list 2358 If this field is present and true, there are no more entries to be 2359 read. 2361 9.5. Attrs Response 2363 The SSH_FXP_ATTRS response has the following format: 2365 byte SSH_FXP_ATTRS 2366 uint32 request-id 2367 ATTRS attrs 2369 attrs 2370 The returned file attributes as described in Section ''File 2371 Attributes''. 2373 10. Extensions 2375 The SSH_FXP_EXTENDED request provides a generic extension mechanism 2376 for adding additional commands. 2378 byte SSH_FXP_EXTENDED 2379 uint32 request-id 2380 string extended-request 2381 ... any request-specific data ... 2383 request-id 2384 Identifier to be returned from the server with the response. 2386 extended-request 2387 A string naming the extension, following the the DNS extensibility 2388 naming convention outlined in [RFC4251], or defined by IETF 2389 consensus. 2391 request-specific data 2392 The rest of the request is defined by the extension; servers 2393 SHOULD NOT attempt to interpret it if they do not recognize the 2394 'extended-request' name. 2396 The server may respond to such requests using any of the response 2397 packets defined in Section ''Responses from the Server to the 2398 Client''. Additionally, the server may also respond with a 2399 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 2400 not recognize the 'extended-request' name, then the server MUST 2401 respond with SSH_FXP_STATUS with error/status set to 2402 SSH_FX_OP_UNSUPPORTED. 2404 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 2405 extension-specific data from the server to the client. It is of the 2406 following format: 2408 byte SSH_FXP_EXTENDED_REPLY 2409 uint32 request-id 2410 ... any request-specific data ... 2412 There is a range of packet types reserved for use by extensions. In 2413 order to avoid collision, extensions that that use additional packet 2414 types should determine those numbers dynamically. 2416 The suggested way of doing this is have an extension request from the 2417 client to the server that enables the extension; the extension 2418 response from the server to the client would specify the actual type 2419 values to use, in addition to any other data. 2421 Extension authors should be mindful of the limited range of packet 2422 types available (there are only 45 values available) and avoid 2423 requiring a new packet type where possible. 2425 11. Implementation Considerations 2427 In order for this protocol to perform well, especially over high 2428 latency networks, multiple read and write requests should be queued 2429 to the server. 2431 The data size of requests should match the maximum packet size for 2432 the next layer up in the protocol chain. 2434 When implemented over ssh, the best performance should be achieved 2435 when the data size matches the channel's max packet, and the channel 2436 window is a multiple of the channel packet size. 2438 Implementations MUST be aware that requests do not have to be 2439 satisfied in the order issued. (See Request Synchronization and 2440 Reordering (Section 4.1).) 2442 Implementations MUST also be aware that read requests may not return 2443 all the requested data, even if the data is available. 2445 12. Security Considerations 2447 It is assumed that both ends of the connection have been 2448 authenticated and that the connection has privacy and integrity 2449 features. Such security issues are left to the underlying transport 2450 protocol, except to note that if this is not the case, an attacker 2451 could manipulate files on the server at will and thus wholly 2452 compromise the server. 2454 This protocol provides file system access to arbitrary files on the 2455 server (constrained only by the server implementation). It is the 2456 responsibility of the server implementation to enforce any access 2457 controls that may be required to limit the access allowed for any 2458 particular user (the user being authenticated externally to this 2459 protocol, typically using [RFC4252]. 2461 Extreme care must be used when interpreting file handle strings. In 2462 particular, care must be taken that a file handle string is valid in 2463 the context of a given 'file-share' session. For example, the 'file- 2464 share' server daemon may have files which it has opened for its own 2465 purposes, and the client must not be able to access these files by 2466 specifying an arbitrary file handle string. 2468 The permission field of the attrib structure (Section 7.6) may 2469 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 2470 extreme caution when setting these bits on either remote or local 2471 files. (I.e., just because a file was SUID on the remote system does 2472 not necessarily imply that it should be SUID on the local system.) 2474 Filesystems often contain entries for objects that are not files at 2475 all, but are rather devices. For example, it may be possible to 2476 access serial ports, tape devices, or named pipes using this 2477 protocol. Servers should exercise caution when granting access to 2478 such resources. In addition to the dangers inherent in allowing 2479 access to such a device, some devices may be 'slow', and could cause 2480 denial of service by causing the server to block for a long period of 2481 time while I/O is performed to such a device. 2483 Servers should take care that file-system quotas are respected for 2484 users. In addition, implementations should be aware that attacks may 2485 be possible, or facilitated, by filling a filesystem. For example, 2486 filling the filesystem where event logging and auditing occurs may, 2487 at best, cause the system to crash, or at worst, allow the attacker 2488 to take untraceable actions in the future. 2490 Servers should take care that filenames are in their appropriate 2491 canonical form, and to ensure that filenames not in canonical form 2492 cannot be used to bypass access checks or controls. 2494 If the server implementation limits access to certain parts of the 2495 file system, extra care must be taken in parsing file names which 2496 contain the '..' path element, and when following symbolic links, 2497 shortcuts, or other filesystem objects which might transpose the path 2498 to refer to an object outside of the restricted area. There have 2499 been numerous reported security bugs where a ".." in a path name has 2500 allowed access outside the intended area. 2502 13. Changes from Previous Protocol Versions 2504 RFC EDITOR: PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2506 Please refer to the following web page for pervious versions of the 2507 protocol: 2509 http://tools.ietf.org/wg/secsh/draft-ietf-secsh-filexfer/ 2511 RFC EDITOR: END PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2513 14. References 2515 14.1. Normative References 2517 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2518 Beame, C., Eisler, M., and D. Noveck, "NFS version 4 2519 Protocol", RFC 3010, December 2000. 2521 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2522 Protocol Architecture", RFC 4251, January 2006. 2524 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2525 Transport Layer Protocol", RFC 4253, January 2006. 2527 [RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2528 Connection Protocol", RFC 4254, January 2006. 2530 [IEEE.1003-1.1996] 2531 Institute of Electrical and Electronics Engineers, 2532 "Information Technology - Portable Operating System 2533 Interface (POSIX) - Part 1: System Application Program 2534 Interface (API) [C Language]", IEEE Standard 1003.2, 1996. 2536 14.2. Informative References 2538 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet 2539 Mail Extensions) Part One: Mechanisms for Specifying and 2540 Describing the Format of Internet Message Bodies", 2541 RFC 1521, September 1993. 2543 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2544 RFC 2246, January 1999. 2546 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2547 Languages", BCP 18, RFC 2277, January 1998. 2549 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2550 Authentication Protocol", RFC 4252, January 2006. 2552 Trademark notice 2554 "ssh" is a registered trademark in the United States and/or other 2555 countries. 2557 Authors' Addresses 2559 Joseph Galbraith 2560 VanDyke Software 2561 4848 Tramway Ridge Blvd 2562 Suite 101 2563 Albuquerque, NM 87111 2564 US 2566 Phone: +1 505 332 5700 2567 Email: galb-list@vandyke.com 2569 Oskari Saarenmaa 2570 F-Secure 2571 Tammasaarenkatu 7 2572 Helsinki 00180 2573 FI 2575 Email: oskari.saarenmaa@f-secure.com 2577 Intellectual Property Statement 2579 The IETF takes no position regarding the validity or scope of any 2580 Intellectual Property Rights or other rights that might be claimed to 2581 pertain to the implementation or use of the technology described in 2582 this document or the extent to which any license under such rights 2583 might or might not be available; nor does it represent that it has 2584 made any independent effort to identify any such rights. Information 2585 on the procedures with respect to rights in RFC documents can be 2586 found in BCP 78 and BCP 79. 2588 Copies of IPR disclosures made to the IETF Secretariat and any 2589 assurances of licenses to be made available, or the result of an 2590 attempt made to obtain a general license or permission for the use of 2591 such proprietary rights by implementers or users of this 2592 specification can be obtained from the IETF on-line IPR repository at 2593 http://www.ietf.org/ipr. 2595 The IETF invites any interested party to bring to its attention any 2596 copyrights, patents or patent applications, or other proprietary 2597 rights that may cover technology that may be required to implement 2598 this standard. Please address the information to the IETF at 2599 ietf-ipr@ietf.org. 2601 Disclaimer of Validity 2603 This document and the information contained herein are provided on an 2604 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2605 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2606 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2607 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2608 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2609 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2611 Copyright Statement 2613 Copyright (C) The Internet Society (2006). This document is subject 2614 to the rights, licenses and restrictions contained in BCP 78, and 2615 except as set forth therein, the authors retain all their rights. 2617 Acknowledgment 2619 Funding for the RFC Editor function is currently provided by the 2620 Internet Society.