idnits 2.17.1 draft-ietf-secsh-filexfer-12.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 2623. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2600. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2607. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2613. ** 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 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 164: '...rr by the server SHOULD be considered ...' RFC 2119 keyword, line 165: '...information, and MAY be displayed to t...' RFC 2119 keyword, line 171: '...rors or warnings MAY be sent as stderr...' RFC 2119 keyword, line 191: '...the length field MUST be included in a...' RFC 2119 keyword, line 195: '...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 678 has weird spacing: '... bool do-...' == Line 707 has weird spacing: '... string owne...' == Line 708 has weird spacing: '... string grou...' == Line 718 has weird spacing: '... string acl ...' == Line 722 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 25, 2006) is 6666 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 2346, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 2114, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 2115, 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: 7 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 29, 2006 O. Saarenmaa 5 F-Secure 6 January 25, 2006 8 SSH File Transfer Protocol 9 draft-ietf-secsh-filexfer-12.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 29, 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. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 106 13. Security Considerations . . . . . . . . . . . . . . . . . . . 55 107 14. Changes from Previous Protocol Versions . . . . . . . . . . . 56 108 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 56 109 15.1. Normative References . . . . . . . . . . . . . . . . . . . 56 110 15.2. Informative References . . . . . . . . . . . . . . . . . . 57 111 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 112 Intellectual Property and Copyright Statements . . . . . . . . . . 59 114 1. Introduction 116 This protocol provides secure file transfer (and more generally file 117 system access.) It is designed so that it could be used to implement 118 a secure remote file system service, as well as a secure file 119 transfer service. 121 This protocol assumes that it runs over a secure channel, such as a 122 channel in [RFC4251], and that the server has already authenticated 123 the client, and that the identity of the client user is available to 124 the protocol. 126 In general, this protocol follows a simple request-response model. 127 Each request and response contains a sequence number and multiple 128 requests may be pending simultaneously. There are a relatively large 129 number of different request messages, but a small number of possible 130 response messages. Each request has one or more response messages 131 that may be returned in result (e.g., a read either returns data or 132 reports error status). 134 The packet format descriptions in this specification follow the 135 notation presented in [RFC4251]. 137 Even though this protocol is described in the context of the SSH2 138 protocol, this protocol is general and independent of the rest of the 139 SSH2 protocol suite. It could be used in a number of different 140 applications, such as secure file transfer over TLS [RFC2246] and 141 transfer of management information in VPN applications. 143 2. Acknowledgements 145 This document owes it's initial creation and protocol design to Tatu 146 Ylonen and Sami Lehtinen of SSH Communications Security Corp. 148 We express our gratitude to them for their initial work on this 149 protocol. 151 3. Use with the SSH Connection Protocol 153 When used with the SSH2 Protocol suite, this protocol is intended to 154 be used as a subsystem as described in [RFC4254] in the section 155 "Starting a Shell or a Command". The subsystem name used with this 156 protocol is "sftp". 158 3.1. The Use of 'stderr' in the server 160 This protocol uses stdout and stdin to transmit binary protocol data. 161 The "session" channel ([RFC4254]), which is used by the subsystem, 162 also supports the use of stderr. 164 Data sent on stderr by the server SHOULD be considered free format 165 debug or supplemental error information, and MAY be displayed to the 166 user. 168 For example, during initialization, there is no client request 169 active, so errors or warning information cannot be sent to the client 170 as part of the SFTP protocol at this early stage. However, the 171 errors or warnings MAY be sent as stderr text. 173 4. General Packet Format 175 All packets transmitted over the secure connection are of the 176 following format: 178 uint32 length 179 byte type 180 uint32 request-id 181 ... type specific fields ... 183 'length' 184 The length of the entire packet, excluding the length field 185 itself, such that, for example, for a packet type containing no 186 type specific fields, the length field would be 5, and 9 bytes of 187 data would be sent on the wire. (This is the packet format used 188 in [RFC4253].) 190 All packet descriptions in this document omit the length field for 191 brevity; the length field MUST be included in any case. 193 The maximum size of a packet is in practice determined by the 194 client (the maximum size of read or write requests that it sends, 195 plus a few bytes of packet overhead). All servers SHOULD support 196 packets of at least 34000 bytes (where the packet size refers to 197 the full length, including the header above). This should allow 198 for reads and writes of at most 32768 bytes. 200 'type' 201 The type code for the packet. 203 'request-id' 204 Each request from the client contains a 'request-id' field. Each 205 response from the server includes that same 'request-id' from the 206 request that the server is responding to. One possible 207 implementation is for the client to us a monotonically increasing 208 request sequence number (modulo 2^32). There is, however, no 209 particular requirement the 'request-id' fields be unique. 211 There are two packets, INIT and VERSION, which do not use the 212 request-id. 213 Packet descriptions in this document will contain the 'request-id' 214 field, but will not redefine it. 216 Implementations MUST ignore excess data at the end of an otherwise 217 valid packet. Implementations MUST respond to unrecognized packet 218 types with an SSH_FX_OP_UNSUPPORTED error. This will allow the 219 protocol to be extended in a backwards compatible way as needed. 221 Additionally, when a packet has two or more optional fields, and an 222 implementation wishes to use the i-th optional field, all fields from 223 1 to i MUST be present. In other words, only fields after the last 224 field the implementation wishes to send are actually options. 226 There is no limit on the number of outstanding (non-acknowledged) 227 requests that the client may send to the server. In practice this is 228 limited by the buffering available on the data stream and the queuing 229 performed by the server. If the server's queues are full, it should 230 not read any more data from the stream, and flow control will prevent 231 the client from sending more requests. Note, however, that while 232 there is no restriction on the protocol level, the client's API may 233 provide a limit in order to prevent infinite queuing of outgoing 234 requests at the client. 236 4.1. Request Synchronization and Reordering 238 The protocol and implementations MUST process requests relating to 239 the same file in the order in which they are received. In other 240 words, if an application submits multiple requests to the server, the 241 results in the responses will be the same as if it had sent the 242 requests one at a time and waited for the response in each case. For 243 example, the server may process non-overlapping read/write requests 244 to the same file in parallel, but overlapping reads and writes cannot 245 be reordered or parallelized. However, there are no ordering 246 restrictions on the server for processing requests from two different 247 file transfer connections. The server may interleave and parallelize 248 them at will. 250 There are no restrictions on the order in which responses to 251 outstanding requests are delivered to the client, except that the 252 server must ensure fairness in the sense that processing of no 253 request will be indefinitely delayed even if the client is sending 254 other requests so that there are multiple outstanding requests all 255 the time. 257 A client MUST be prepared to receive responses to multiple overlapped 258 requests out of order. 260 4.2. New data types defined by this document 262 This document defines these data types in addition to those defined 263 in [RFC4251]. 265 uint16 266 Represents a 16-bit unsigned integer. Stored as 2 bytes in the 267 order of decreasing significance (network byte order). 269 int64 270 Represents a 64-bit signed integer. Stored using two's 271 complement, as eight bytes in the order of decreasing significance 272 (network byte order). 274 extension-pair 276 string extension-name 277 string extension-data 279 'extension-name' is the name of a protocol extension. Extensions 280 not defined by IETF CONSENSUS MUST follow the the DNS 281 extensibility naming convention outlined in [RFC4251]. 283 'extension-data' is any data specific to the extension, and MAY be 284 zero length if the extension has no data. 286 4.3. Packet Types 288 The following values are defined for packet types. 290 SSH_FXP_INIT 1 291 SSH_FXP_VERSION 2 292 SSH_FXP_OPEN 3 293 SSH_FXP_CLOSE 4 294 SSH_FXP_READ 5 295 SSH_FXP_WRITE 6 296 SSH_FXP_LSTAT 7 297 SSH_FXP_FSTAT 8 298 SSH_FXP_SETSTAT 9 299 SSH_FXP_FSETSTAT 10 300 SSH_FXP_OPENDIR 11 301 SSH_FXP_READDIR 12 302 SSH_FXP_REMOVE 13 303 SSH_FXP_MKDIR 14 304 SSH_FXP_RMDIR 15 305 SSH_FXP_REALPATH 16 306 SSH_FXP_STAT 17 307 SSH_FXP_RENAME 18 308 SSH_FXP_READLINK 19 309 SSH_FXP_LINK 21 310 SSH_FXP_BLOCK 22 311 SSH_FXP_UNBLOCK 23 313 SSH_FXP_STATUS 101 314 SSH_FXP_HANDLE 102 315 SSH_FXP_DATA 103 316 SSH_FXP_NAME 104 317 SSH_FXP_ATTRS 105 319 SSH_FXP_EXTENDED 200 320 SSH_FXP_EXTENDED_REPLY 201 322 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 323 implement extensions, which can be vendor specific. See Section 324 ''Extensions'' for more details. 326 Values 210-255 are reserved for use in conjunction with these 327 extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the 328 meaning of these reserved types. It is suggested that the actual 329 value to be used also be negotiated, since this will prevent 330 collision among multiple uncoordinated extensions. 332 The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if 333 it receives a packet it does not recognize. 335 The use of additional packet types in the non-extension range MUST be 336 introduced through IETF consensus. New packet types to be sent from 337 the client to the server MAY be introduced without changing the 338 protocol version (Section 5). Because the client has no way to 339 respond to unrecognized packet types, new packet types to be sent 340 from the server to the client the client MUST not used unless the 341 protocol version is changed or the client has negotiated to received 342 them. This negotiation MAY be explicit, through the use of 343 extensions, or MAY be implicit, by the client itself using a packet 344 type not defined above. 346 5. Protocol Initialization 348 When the file transfer protocol starts, the client first sends a 349 SSH_FXP_INIT (including its version number) packet to the server. 350 The server responds with a SSH_FXP_VERSION packet, supplying the 351 lowest of its own and the client's version number. Both parties 352 should from then on adhere to that particular version of the 353 protocol. 355 The version number of the protocol specified in this document is 6. 356 The version number should be incremented for each incompatible 357 revision of this protocol. 359 Note that these two packets DO NOT contain a request id. These are 360 the only such packets in the protocol. 362 5.1. Client Initialization 364 The SSH_FXP_INIT packet (from client to server) has the following 365 data: 367 uint32 version 369 'version' is the version number of the client. If the client wishes 370 to interoperate with servers that support discontinuous version 371 numbers it SHOULD send '3', and then use the 'version-select' 372 extension (see below.) Otherwise, this value is '6' for this version 373 of the protocol. 375 5.2. Server Initialization 377 The SSH_FXP_VERSION packet (from server to client) has the following 378 data: 380 uint32 version 381 extension-pair extensions[0..n] 383 'version' is the lower of the protocol version supported by the 384 server and the version number received from the client. 386 'extensions' is 0 or more extension-pairs (Section 4.2). 387 Implementations MUST silently ignore any extensions whose names they 388 do not recognize. 390 5.3. Determining Server Newline Convention 392 In order to correctly process text files in a cross platform 393 compatible way, newline sequences must be converted between client 394 and server conventions. 396 The SSH_FXF_TEXT_MODE file open flag (Section 8.1.1) makes it 397 possible to request that the server translate a file to a 'canonical' 398 wire format. This format uses CRLF as the line separator. 400 Servers for systems using other conventions MUST translate to and 401 from the canonical form. 403 However, to ease the burden of implementation on servers that use a 404 single, simple, separator sequence the following extension allows the 405 canonical format to be changed. 407 string "newline" 408 string new-canonical-separator (usually CR or LF or CRLF) 410 All clients MUST support this extension. 412 When processing text files, clients SHOULD NOT translate any 413 character or sequence that is not an exact match of the server's 414 newline separator. 416 In particular, if the newline sequence being used is the canonical 417 CRLF sequence, a lone CR or a lone LF SHOULD be written through 418 without change. 420 5.4. Supported Features 422 The sftp protocol has grown to be very rich, and now supports a 423 number of features that may not be available on all servers. 425 When a server receives a request for a feature it cannot support, it 426 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 427 specified. The following extension facilitates clients being able to 428 use the maximum available feature set, and yet not be overly burdened 429 by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST 430 include as part of their version packet. 432 string "supported2" 433 string supported-structure 434 uint32 supported-attribute-mask 435 uint32 supported-attribute-bits 436 uint32 supported-open-flags 437 uint32 supported-access-mask 438 uint32 max-read-size 439 uint16 supported-open-block-vector 440 uint16 supported-block-vector 441 uint32 attrib-extension-count 442 string attrib-extension-names[attrib_extension-count] 443 uint32 extension-count 444 string extension-names[extension-count] 446 Note that the name "supported2" is used here to avoid conflict with 447 the slightly different "supported" extension that was previously 448 used. 449 supported-attribute-mask 450 This mask MAY by applied to the 'File Attributes' valid-attribute- 451 flags field (Section 7.1) to ensure that no unsupported attributes 452 are present during a operation which writes attributes. 454 supported-attribute-bits 455 This mask MAY by applied to the 'File Attributes' attrib-bits 456 field (Section 7.9) to ensure that no unsupported attrib-bits are 457 present during a operation which writes attributes. 459 supported-open-flags 460 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN 461 (Section 8.1.1) flags field. 463 supported-access-mask 464 This mask may be applied to the ace-mask field of an ACL. 466 This mask SHOULD NOT be applied to the desired-access field of the 467 SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result 468 in not requesting the access required by the client. In this 469 case, the server is responsible for translating the clients 470 requested access to a mode it supports that is sufficient to grant 471 all access requested by the client. 473 max-read-size 474 This is the maximum read size that the server guarantees to 475 complete. For example, certain embedded server implementations 476 complete only the first 4K of a read, even if there is additional 477 data to be read from the file. 479 If the server specifies a non-zero value for max-read-size, it 480 MUST return the requested number of bytes for reads that are less 481 than or equal to the value, unless it encounters EOF or an ERROR. 483 The server MAY use this value to express that it is willing to 484 handle very large read requests, in excess of the standard 34000 485 bytes specified in Section 4. 487 supported-open-block-vector 488 supported-block-vector 489 16-bit masks specifying which combinations of blocking flags are 490 supported. Each bit corresponds to one combination of the 491 SSH_FXF_BLOCK_READ, SSH_FXF_BLOCK_WRITE, SSH_FXF_BLOCK_DELETE, and 492 SSH_FXF_BLOCK_ADVISORY bits from Section 7.1.1.3, with a set bit 493 corresponding to a supported combination and a clear bit an 494 unsupported combination. The index of a bit, bit zero being the 495 least significant bit, viewed as a four-bit number, corresponds to 496 a combination of flag bits, shifted right so that BLOCK_READ is 497 the least significant bit. The combination `no blocking flags' 498 MUST be supported, so the low bit will always be set. 500 For example, a server supporting only the classic advisory read 501 (shared) and write (exclusive) locks would set the bits 502 corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, 503 0b1010, plus the always-set bit 0b0000, giving a mask value of 504 0b0000110000000001, or 0x0c01; a server supporting no locking at 505 all would set only bit zero, giving 0x0001. 507 'supported-open-block-masks' applies to the SSH_FXP_OPEN 508 (Section 8.1.1) flags field. 'supported-block-masks' applies to 509 the SSH_FXF_BLOCK request. 511 attrib-extension-count 512 Count of extension names in the attrib-extension-names array. 514 attrib-extension-names 515 Names of extensions that can be used in an ATTRS (Section 7.14) 516 structure. 518 extension-count 519 Count of extension names in the extension-names array. 521 extension-names 522 Names of extensions that can be used with the SSH_FXP_EXTEND 523 (Section 10) packet. 525 Naturally, if a given attribute field, attribute mask bit, open flag, 526 or extension is required for correct operation, the client MUST 527 either not allow the bit to be masked off, or MUST fail the operation 528 gracefully without sending the request to the server. 530 The client MAY send requests that are not supported by the server; 531 however, it is not normally expected to be productive to do so. The 532 client SHOULD apply the mask even to attrib structures received from 533 the server. The server MAY include attributes or attrib-bits that 534 are not included in the mask. Such attributes or attrib-bits are 535 effectively read-only. 537 The supported capabilities of the acl attribute are sent using the 538 following extension. 540 string "acl-supported" 541 string supported-structure 542 uint32 capabilities 544 'capabilities' is a combination of the following bits: 546 SSH_ACL_CAP_ALLOW 0x00000001 547 SSH_ACL_CAP_DENY 0x00000002 548 SSH_ACL_CAP_AUDIT 0x00000004 549 SSH_ACL_CAP_ALARM 0x00000008 550 SSH_ACL_CAP_INHERIT_ACCESS 0x00000010 551 SSH_ACL_CAP_INHERIT_AUDIT_ALARM 0x00000020 553 SSH_ACL_CAP_ALLOW 554 SSH_ACL_CAP_DENY 555 SSH_ACL_CAP_AUDIT 556 SSH_ACL_CAP_ALARM 557 The server supports the associated ACL ACE type. 559 SSH_ACL_CAP_INHERIT_ACCESS 560 The server can control whether a ACL will inherit DENY and ALLOW 561 ACEs that are marked inheritable from it's parent object. 563 SSH_ACL_CAP_INHERIT_AUDIT_ALARM 564 The server can control whether a ACL will inherit AUDIT or ALARM 565 ACEs that are marked inheritable from it's parent object. 567 5.5. Version re-negotiation 569 If the server supports other versions than what was negotiated, it 570 may wish to send the 'versions' extension to inform the client of 571 this fact. The client may then optionally choose to use one of the 572 other versions supported. 574 string "versions" 575 string comma-separated-versions 577 'comma-separated-versions' is a string of comma separated version 578 numbers. Defined versions are: "2", "3", "4", "5", "6". Any other 579 version advertised by the server must follow the DNS extensibility 580 naming convention outlined in [RFC4251]. 582 For example: "2,3,6,private@example.com". 584 If the client and server have negotiated a a version greater than or 585 equal to version '3' (the version at which SSH_FXP_EXTENDED was 586 introduced) in the initial VERSION/INIT exchange, the client may 587 select a new version to use from the list the server provided using 588 the following SSH_FXP_EXTENDED request. 590 string "version-select" 591 string version-from-list 593 If the 'version-from-list' is one of the versions on the servers 594 list, the server MUST respond with SSH_FX_OK. If the server did not 595 send the "versions" extension, or the version-from-list was not 596 included, the server MAY send a status response describing the 597 failure, but MUST then close the channel without processing any 598 further requests. 600 The 'version-select' MUST be the first request from the client to the 601 server; if it is not, the server MUST fail the request and close the 602 channel. 604 Although this request does take a full round trip, no client need 605 wait for the response before continuing, because any valid request 606 MUST succeed, and any invalid request results in a channel close. 607 Since the request is the first request, it is not possible for the 608 server to have already sent responses conforming to the old version. 610 Typically, the client SHOULD NOT down-grade the protocol version 611 using this extension; however, it is not forbidden to do so. One 612 reason a client might do so is to work around a buggy implementation. 614 6. File Names 616 This protocol represents file names as strings. File names are 617 assumed to use the slash ('/') character as a directory separator. 619 File names starting with a slash are "absolute", and are relative to 620 the root of the file system. Names starting with any other character 621 are relative to the user's default directory (home directory). Note 622 that identifying the user is assumed to take place outside of this 623 protocol. 625 Servers SHOULD interpret a path name component ".." (Section 13) as 626 referring to the parent directory, and "." as referring to the 627 current directory. 629 An empty path name is valid, and it refers to the user's default 630 directory (usually the user's home directory). 632 Otherwise, no syntax is defined for file names by this specification. 633 Clients should not make any other assumptions; however, they can 634 splice path name components returned by SSH_FXP_READDIR together 635 using a slash ('/') as the separator, and that will work as expected. 637 It is understood that the lack of well-defined semantics for file 638 names may cause interoperability problems between clients and servers 639 using radically different operating systems. However, this approach 640 is known to work acceptably with most systems, and alternative 641 approaches that e.g. treat file names as sequences of structured 642 components are quite complicated. 644 The preferred encoding for filenames is UTF-8. This is consistent 645 with IETF Policy on Character Sets and Languages [RFC2277] and it is 646 further supposed that the server is more likely to support any local 647 character set and be able to convert it to UTF-8. 649 However, because the server does not always know the encoding of 650 filenames, it is not always possible for the server to preform a 651 valid translation to UTF-8. When an invalid translation to UTF-8 is 652 preformed, it becomes impossible to manipulate the file, because the 653 translation is not reversible. Therefore, the following extensions 654 are provided in order to make it possible for the server to 655 communicate it's abilities to the client, and to allow the client to 656 control whether the server attempts the conversion. 658 A server MAY include the following extension with it's version 659 packet. 661 string "filename-charset" 662 string charset-name 664 A server that can always provide a valid UTF-8 translation for 665 filenames SHOULD NOT send this extension. Otherwise, the server 666 SHOULD send this extension and include the encoding most likely to be 667 used for filenames. This value will most likely be derived from the 668 LC_CTYPE on most unix-like systems. 670 A server that does not send this extension MUST send all filenames 671 encoded in UTF-8. All clients MUST support UTF-8 filenames. 673 If the server included the 'filename-charset' extension with its 674 VERSION packet, a client MAY send the following extension to turn off 675 server translation to UTF-8. 677 string "filename-translation-control" 678 bool do-translate 680 If the client does not send this extension, the server MUST continue 681 to attempt translation to UTF-8. When a client sends this extension, 682 the server MUST enable filename translation if 'do-translate' is 683 true, or disable filename translation if it is false. 685 The server MUST respond with a STATUS response; if the server sent a 686 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, 687 the status MUST be SSH_FX_OP_UNSUPPORTED. 689 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE 690 data MUST be used. The server is responsible for converting the 691 UNICODE data to whatever canonical form it requires. For example, if 692 the server requires that precomposed characters always be used, the 693 server MUST NOT assume the filename as sent by the client has this 694 attribute, but must do this normalization itself. 696 7. File Attributes 698 A new compound data type, 'ATTRS', is defined for encoding file 699 attributes. The same encoding is used both when returning file 700 attributes from the server and when sending file attributes to the 701 server. 703 uint32 valid-attribute-flags 704 byte type always present 705 uint64 size if flag SIZE 706 uint64 allocation-size if flag ALLOCATION_SIZE 707 string owner if flag OWNERGROUP 708 string group if flag OWNERGROUP 709 uint32 permissions if flag PERMISSIONS 710 int64 atime if flag ACCESSTIME 711 uint32 atime-nseconds if flag SUBSECOND_TIMES 712 int64 createtime if flag CREATETIME 713 uint32 createtime-nseconds if flag SUBSECOND_TIMES 714 int64 mtime if flag MODIFYTIME 715 uint32 mtime-nseconds if flag SUBSECOND_TIMES 716 int64 ctime if flag CTIME 717 uint32 ctime-nseconds if flag SUBSECOND_TIMES 718 string acl if flag ACL 719 uint32 attrib-bits if flag BITS 720 uint32 attrib-bits-valid if flag BITS 721 byte text-hint if flag TEXT_HINT 722 string mime-type if flag MIME_TYPE 723 uint32 link-count if flag LINK_COUNT 724 string untranslated-name if flag UNTRANSLATED_NAME 725 uint32 extended-count if flag EXTENDED 726 extended-pair extensions 728 7.1. valid-attribute-flags 730 The 'valid-attribute-flags' specifies which of the fields are 731 present. Those fields for which the corresponding flag is not set 732 are not present (not included in the packet). 734 The server generally includes all attributes it knows about; however, 735 it may exclude attributes that are overly expensive to retrieve 736 unless the client explicitly requests them. 738 When writing attributes, the server SHOULD NOT modify attributes that 739 are not present in the structure. However, if necessary, the server 740 MAY use a default value for an absent attribute. 742 In general, unless otherwise specified, if a server cannot support 743 writing an attribute requested, it must fail the setstat operation. 744 In this case, none of the attributes SHOULD be changed. 746 New fields can only be added by incrementing the protocol version 747 number (or by using the extension mechanism described below). 749 The following values are defined: 751 SSH_FILEXFER_ATTR_SIZE 0x00000001 752 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 753 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 754 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 755 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 756 SSH_FILEXFER_ATTR_ACL 0x00000040 757 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 758 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 759 SSH_FILEXFER_ATTR_BITS 0x00000200 760 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 761 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 762 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 763 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 764 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 765 SSH_FILEXFER_ATTR_CTIME 0x00008000 766 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 768 0x00000002 was used in a previous version of this protocol. It is 769 now a reserved value and MUST NOT appear in the mask. Some future 770 version of this protocol may reuse this value. 772 7.2. Type 774 The type field is always present. The following types are defined: 776 SSH_FILEXFER_TYPE_REGULAR 1 777 SSH_FILEXFER_TYPE_DIRECTORY 2 778 SSH_FILEXFER_TYPE_SYMLINK 3 779 SSH_FILEXFER_TYPE_SPECIAL 4 780 SSH_FILEXFER_TYPE_UNKNOWN 5 781 SSH_FILEXFER_TYPE_SOCKET 6 782 SSH_FILEXFER_TYPE_CHAR_DEVICE 7 783 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 784 SSH_FILEXFER_TYPE_FIFO 9 786 On a POSIX system, these values would be derived from the mode field 787 of the stat structure. SPECIAL should be used for files that are of 788 a known type which cannot be expressed in the protocol. UNKNOWN 789 should be used if the type is not known. 791 7.3. Size 793 The 'size' field specifies the number of bytes that can be read from 794 the file, or in other words, the location of the end-of-file. 796 If this field is present during file creation, it indicates the 797 number of bytes the client intends to transfer, but SHOULD NOT effect 798 the creation of the file. The server can use this information to 799 determine if the client sent all the intended data and the file was 800 transfered in it's entirity. 802 If this field is present during a setstat operation, the file MUST be 803 extended or truncated to the specified size. 805 Files opened with the SSH_FXF_TEXT flag may have a size that is 806 greater or less than the value of the size field. The server MAY 807 fail setstat operations specifying size for files opened with the 808 SSH_FXF_TEXT flag. 810 7.4. allocation-size 812 The 'allocation-size' field specifies the number of bytes that the 813 file consumes on disk. This field MAY be less than the 'size' field 814 if the file is 'sparse' (Section 7.9). 816 When present during file creation, the file SHOULD be created and the 817 specified number of bytes preallocated. If the preallocation fails, 818 the file should be removed (if it was created) and an error returned. 820 If this field is present during a setstat operation, the file SHOULD 821 be extended or truncated to the specified size. The 'size' of the 822 file may be affected by this operation. If the operation succeeds, 823 the 'size' should be the minimum of the 'size' before the operation 824 and the new 'allocation-size'. 826 Querying the 'allocation-size' after setting it MUST return a value 827 that is greater-than or equal to the value set, but it MAY not return 828 the precise value set. 830 If both 'size' and 'allocation-size' are set during a setstat 831 operation, and 'allocation-size' is less than 'size', the server MUST 832 return SSH_FX_INVALID_PARAMETER. 834 7.5. Owner and Group 836 The 'owner' and 'group' fields are represented as UTF-8 strings; this 837 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. 838 The following text is selected quotations from section 5.6. 840 To avoid a representation that is tied to a particular underlying 841 implementation at the client or server, the use of UTF-8 strings has 842 been chosen. The string should be of the form "user@dns_domain". 843 This will allow for a client and server that do not use the same 844 local representation the ability to translate to a common syntax that 845 can be interpreted by both. In the case where there is no 846 translation available to the client or server, the attribute value 847 must be constructed without the "@". Therefore, the absence of the @ 848 from the owner or owner_group attribute signifies that no translation 849 was available and the receiver of the attribute should not place any 850 special meaning on the attribute value. Even though the attribute 851 value cannot be translated, it may still be useful. In the case of a 852 client, the attribute string may be used for local display of 853 ownership. 855 user@localhost represents a user in the context of the server. 857 If either the owner or group field is zero length, the field should 858 be considered absent, and no change should be made to that specific 859 field during a modification operation. 861 7.6. Permissions 863 The 'permissions' field contains a bit mask specifying file 864 permissions. These permissions correspond to the st_mode field of 865 the stat structure defined by POSIX [IEEE.1003-1.1996]. 867 This protocol uses the following values for the symbols declared in 868 the POSIX standard. 870 S_IRUSR 0000400 (octal) 871 S_IWUSR 0000200 872 S_IXUSR 0000100 873 S_IRGRP 0000040 874 S_IWGRP 0000020 875 S_IXGRP 0000010 876 S_IROTH 0000004 877 S_IWOTH 0000002 878 S_IXOTH 0000001 879 S_ISUID 0004000 880 S_ISGID 0002000 881 S_ISVTX 0001000 883 Implementations MUST NOT send bits that are not defined. 885 The server SHOULD NOT apply a 'umask' to the mode bits; but should 886 set the mode bits as specified by the client. The client MUST apply 887 an appropriate 'umask' to the mode bits before sending them. 889 7.7. Times 891 The 'atime' field contains the last access time of the file. Many 892 operating systems either don't have this field, only optionally 893 maintain it, or maintain it with less resolution than other fields. 895 The 'mtime' contains the last time the file was written. 897 'createtime' contains the creation time of the file. 899 'ctime' contains the last time the file attributes were changed. The 900 exact meaning of this field depends on the server. 902 All times are represented as seconds from Jan 1, 1970 in UTC. A 903 negative value indicates number of seconds before Jan 1, 1970. In 904 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 905 nseconds field is to be added to the seconds field for the final time 906 representation. For example, if the time to be represented is one- 907 half second before 0 hour January 1, 1970, the seconds field would 908 have a value of negative one (-1) and the nseconds fields would have 909 a value of one-half second (500000000). Values greater than 910 999,999,999 for nseconds are considered invalid. 912 7.8. ACL 914 The 'ACL' field contains an ACL similar to that defined in section 915 5.9 of NFS version 4 Protocol [RFC3010]. 917 The structure of the ACL is: 919 uint32 acl-flags 920 uint32 ace-count 921 ACE ace[ace-count] 923 The ACE data structure is composes as follows: 925 uint32 ace-type 926 uint32 ace-flag 927 uint32 ace-mask 928 string who [UTF-8] 930 acl-flags 932 SFX_ACL_CONTROL_INCLUDED 0x00000001 933 SFX_ACL_CONTROL_PRESENT 0x00000002 934 SFX_ACL_CONTROL_INHERITED 0x00000004 935 SFX_ACL_AUDIT_ALARM_INCLUDED 0x00000010 936 SFX_ACL_AUDIT_ALARM_INHERITED 0x00000020 938 SFX_ACL_CONTROL_INCLUDED 939 SFX_ACL_CONTROL_PRESENT 940 SFX_ACL_CONTROL_INHERITED 941 If INCLUDED is set during a setstat operation, then the client 942 intends to modify the ALLOWED/DENIED entries of the ACL. 943 Otherwise, the client intends for these entries to be 944 preserved. 946 If the PRESENT bit is not set, then the client wishes to remove 947 control entries. If the server doesn't support separate 948 control and audit information, the client MUST not clear this 949 bit without also clearing the AUDIT_ALARM_PRESENT bit. 951 If the PRESENT bit is clear, then control of the file MAY be 952 through the permissions mask. The server MAY also grant full 953 access to the file. 955 If the both the INCLUDE and the PRESENT bit are set, but their 956 are no ALLOW/DENY entries in the list, the client wishes to 957 deny all access to the file or directory. The server may have 958 to transform this into a ACL with a deny entry to implement it. 960 If INHERITED is set, then ALLOW/DENY ACEs MAY be inherited from 961 the parent directory. If it is off, then they MUST not be 962 INHERITED. If the server does not support controlling 963 inheritance, then the client MUST clear this bit; in this case 964 the inheritance properties of the server are undefined. 966 SFX_ACL_AUDIT_ALARM_INCLUDED 967 SFX_ACL_AUDIT_ALARM_INHERITED 968 If INCLUDE is set during a setstat operation, then the client 969 intends to modify the AUDIT/ALARM entries of the ACL. 970 Otherwise, the client intends for these entries to be 971 preserved. 973 If INHERITED is set, then AUDIT/ALARM ACEs MAY be inherited 974 from the parent directory. If it is off, then they MUST not be 975 INHERITED. If the server does not support controlling 976 inheritance, then the client MUST clear this bit; in this case 977 the inheritance properties of the server are undefined. 979 Because some server require special permissions / privileges in 980 order to modify the AUDIT/ALARM entries in the ACL, it is 981 important to communicate to the server the clients intent to 982 modify these entries. The client MUST both use the 983 ACCESS_AUDIT_ALARM_ATTRIBUTES bit in the desired attribute of the 984 open request and must set the SFX_ACL_AUDIT_ALARM_INCLUDED during 985 the setstat operation. 987 Clients that do not intend specifically to modify the AUDIT or 988 ALARM entries SHOULD NOT set SSH_FXF_ACCESS_AUDIT_ALARM_INFO in 989 the open-flags and SHOULD NOT set the SFX_ACL_AUDIT_ALARM_INCLUDED 990 bit because these operations are often privileged and will fail. 992 If the SFX_ACL_AUDIT_ALARM_INCLUDED is set, and the requested 993 change can not be made, the server MUST fail the request. 995 Servers that do not seperate control and audit/alarm information 996 may have to read the existing ACL and merge in enteries not 997 included by the client. The server must take this into account 998 when opening files with the ACE4_WRITE_ACL permission requested. 1000 ace-type 1001 one of the following four values (taken from NFS Version 4 1002 Protocol [RFC3010]: 1004 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 1005 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 1006 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 1007 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 1009 ace-flag 1010 A combination of the following flag values. See NFS Version 4 1011 Protocol [RFC3010] section 5.9.2: 1013 ACE4_FILE_INHERIT_ACE 0x00000001 1014 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 1015 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 1016 ACE4_INHERIT_ONLY_ACE 0x00000008 1017 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 1018 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 1019 ACE4_IDENTIFIER_GROUP 0x00000040 1021 ace-mask 1022 Combination of the following flags (taken from [RFC3010], section 1023 5.9.3. The semantic meaning of these flags is also given in 1024 [RFC3010]. 1026 ACE4_READ_DATA 0x00000001 1027 ACE4_LIST_DIRECTORY 0x00000001 1028 ACE4_WRITE_DATA 0x00000002 1029 ACE4_ADD_FILE 0x00000002 1030 ACE4_APPEND_DATA 0x00000004 1031 ACE4_ADD_SUBDIRECTORY 0x00000004 1032 ACE4_READ_NAMED_ATTRS 0x00000008 1033 ACE4_WRITE_NAMED_ATTRS 0x00000010 1034 ACE4_EXECUTE 0x00000020 1035 ACE4_DELETE_CHILD 0x00000040 1036 ACE4_READ_ATTRIBUTES 0x00000080 1037 ACE4_WRITE_ATTRIBUTES 0x00000100 1038 ACE4_DELETE 0x00010000 1039 ACE4_READ_ACL 0x00020000 1040 ACE4_WRITE_ACL 0x00040000 1041 ACE4_WRITE_OWNER 0x00080000 1042 ACE4_SYNCHRONIZE 0x00100000 1044 who 1045 UTF-8 string of the form described in 'Owner and Group' 1046 (Section 7.5) 1047 Also, as per '5.9.4 ACE who' [RFC3010] there are several 1048 identifiers that need to be understood universally. Some of these 1049 identifiers cannot be understood when an client access the server, 1050 but have meaning when a local process accesses the file. The 1051 ability to display and modify these permissions is permitted over 1052 SFTP. 1054 OWNER The owner of the file. 1055 GROUP The group associated with the file. 1056 EVERYONE The world. 1057 INTERACTIVE Accessed from an interactive terminal. 1058 NETWORK Accessed via the network. 1059 DIALUP Accessed as a dialup user to the server. 1060 BATCH Accessed from a batch job. 1061 ANONYMOUS Accessed without any authentication. 1062 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 1063 SERVICE Access from a system service. 1064 To avoid conflict, these special identifiers are distinguish by an 1065 appended "@". For example: ANONYMOUS@. 1067 7.9. attrib-bits and attrib-bits-valid 1069 These fields, taken together, reflect various attributes of the file 1070 or directory, on the server. 1072 Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- 1073 bits' field. This allows both the server and the client to 1074 communicate only the bits it knows about without inadvertently 1075 twiddling bits they don't understand. 1077 The following attrib-bits are defined: 1079 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 1080 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 1081 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 1082 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 1083 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 1084 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 1085 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 1086 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 1087 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 1088 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 1089 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 1090 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 1092 SSH_FILEXFER_ATTR_FLAGS_READONLY 1093 Advisory, read-only bit. This bit is not part of the access 1094 control information on the file, but is rather an advisory field 1095 indicating that the file should not be written. 1097 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 1098 The file is part of the operating system. 1100 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 1101 File SHOULD NOT be shown to user unless specifically requested. 1102 For example, most UNIX systems SHOULD set this bit if the filename 1103 begins with a 'period'. This bit may be read-only (Section 5.4). 1104 Most UNIX systems will not allow this to be changed. 1106 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 1107 This attribute applies only to directories. This attribute is 1108 always read-only, and cannot be modified. This attribute means 1109 that files and directory names in this directory should be 1110 compared without regard to case. 1112 It is recommended that where possible, the server's filesystem be 1113 allowed to do comparisons. For example, if a client wished to 1114 prompt a user before overwriting a file, it should not compare the 1115 new name with the previously retrieved list of names in the 1116 directory. Rather, it should first try to create the new file by 1117 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 1118 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 1119 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 1121 Unless otherwise specified, filenames are assumed to be case 1122 sensitive. 1124 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 1125 The file should be included in backup / archive operations. 1127 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 1128 The file is stored on disk using file-system level transparent 1129 encryption. This flag does not affect the file data on the wire 1130 (for either READ or WRITE requests.) 1132 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 1133 The file is stored on disk using file-system level transparent 1134 compression. This flag does not affect the file data on the wire. 1136 SSH_FILEXFER_ATTR_FLAGS_SPARSE 1137 The file is a sparse file; this means that file blocks that have 1138 not been explicitly written are not stored on disk. For example, 1139 if a client writes a buffer at 10 M from the beginning of the 1140 file, the blocks between the previous EOF marker and the 10 M 1141 offset would not consume physical disk space. 1143 Some servers may store all files as sparse files, in which case 1144 this bit will be unconditionally set. Other servers may not have 1145 a mechanism for determining if the file is sparse, and so the file 1146 MAY be stored sparse even if this flag is not set. 1148 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 1149 Opening the file without either the SSH_FXF_APPEND_DATA or the 1150 SSH_FXF_APPEND_DATA_ATOMIC flag (Section 8.1.1.3) MUST result in 1151 an SSH_FX_INVALID_PARAMETER error. 1153 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 1154 The file cannot be deleted or renamed, no hard link can be created 1155 to this file, and no data can be written to the file. 1157 This bit implies a stronger level of protection than 1158 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 1159 ACLs. Typically even the superuser cannot write to immutable 1160 files, and only the superuser can set or remove the bit. 1162 SSH_FILEXFER_ATTR_FLAGS_SYNC 1163 When the file is modified, the changes are written synchronously 1164 to the disk. 1166 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 1167 The server MAY include this bit in a directory listing or realpath 1168 response. It indicates there was a failure in the translation to 1169 UTF-8. If this flag is included, the server SHOULD also include 1170 the UNTRANSLATED_NAME attribute. 1172 7.10. text-hint 1174 The value is one of the following enumerations, and indicates what 1175 the server knows about the content of the file. 1177 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 1178 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 1179 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 1180 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 1182 SSH_FILEXFER_ATTR_KNOWN_TEXT 1183 The server knows the file is a text file, and should be opened 1184 using the SSH_FXF_TEXT_MODE flag. 1186 SSH_FILEXFER_ATTR_GUESSED_TEXT 1187 The server has applied a heuristic or other mechanism and believes 1188 that the file should be opened with the SSH_FXF_TEXT_MODE flag. 1190 SSH_FILEXFER_ATTR_KNOWN_BINARY 1191 The server knows the file has binary content. 1193 SSH_FILEXFER_ATTR_GUESSED_BINARY 1194 The server has applied a heuristic or other mechanism and believes 1195 has binary content, and should not be opened with the 1196 SSH_FXF_TEXT_MODE flag. 1198 This flag MUST NOT be present during either a setstat or a fsetstat 1199 operation. 1201 7.11. mime-type 1203 The 'mime-type' field contains the mime-type [RFC1521] string. Most 1204 servers will not know this information and should not set the bit in 1205 their supported-attribute-mask. 1207 7.12. link-count 1209 This field contains the hard link count of the file. This attribute 1210 MUST NOT be present during a setstat operation. 1212 7.13. untranslated-name 1214 This field contains the name before filename translation was attempt. 1215 It MUST NOT be included unless the server also set the 1216 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 7.9) bit in the 1217 attrib-bits field. 1219 7.14. Extended Attributes 1221 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 1222 mechanism for the attrib structure. If the flag is specified, then 1223 the 'extended_count' field is present. It specifies the number of 1224 'extension-pair' items that follow. Each of these items specifies an 1225 extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED 1226 if there are any unrecognized extensions. Clients can avoid sending 1227 unsupported extensions by examining the attrib-extension-names of the 1228 "supported2" extension attrib-extension-names (Section 5.4). 1230 Additional fields can be added to the attributes by either defining 1231 additional bits to the flags field to indicate their presence, or by 1232 defining extended attributes for them. The extended attributes 1233 mechanism is recommended for most purposes; additional flags bits 1234 should be defined only by an IETF standards action that also 1235 increments the protocol version number. The use of such new fields 1236 MUST be negotiated by the version number in the protocol exchange. 1237 It is a protocol error if a packet with unsupported protocol bits is 1238 received. 1240 8. Requests From the Client to the Server 1242 Requests from the client to the server represent the various file 1243 system operations. 1245 8.1. Opening and Closing Files and Directories 1247 Many operations in the protocol operate on open files. The 1248 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 1249 an opaque, variable-length string) which may be used to access the 1250 file or directory later. The client MUST NOT send requests to the 1251 server with bogus or closed handles. However, the server MUST 1252 perform adequate checks on the handle in order to avoid security 1253 risks due to fabricated handles. 1255 This design allows either stateful and stateless server 1256 implementation, as well as an implementation which caches state 1257 between requests but may also flush it. The contents of the file 1258 handle string are entirely up to the server and its design. The 1259 client should not modify or attempt to interpret the file handle 1260 strings. 1262 The file handle strings MUST NOT be longer than 256 bytes. 1264 8.1.1. Opening a File 1266 Files are opened and created using the SSH_FXP_OPEN message. 1268 byte SSH_FXP_OPEN 1269 uint32 request-id 1270 string filename [UTF-8] 1271 uint32 desired-access 1272 uint32 flags 1273 ATTRS attrs 1275 The response to this message will be either SSH_FXP_HANDLE (if the 1276 operation is successful) or SSH_FXP_STATUS (if the operation fails.) 1278 8.1.1.1. filename 1280 The 'filename' field specifies the file name. See Section ''File 1281 Names'' for more information. If 'filename' is a directory file, the 1282 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 1284 8.1.1.2. desired-access 1286 The 'desired-access' field is a bitmask containing a combination of 1287 values from the ace-mask flags (Section 7.8). Note that again, the 1288 meaning of these flags is given in [RFC3010]. 1290 The server MUST be prepared to translate the SFTP access flags into 1291 its local equivalents. If the server cannot grant the access 1292 desired, it MUST return SSH_FX_PERMISSION_DENIED. 1294 The server MAY open the file with greater access than requested if 1295 the user has such access and the server implementation requires it. 1296 For example, a server that does not distinguish between 1297 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access 1298 to the file when the client only requested READ_ATTRIBUTE, resulting 1299 in greater access than the client originally requested. 1301 In such cases, it is possible, and permissible in the protocol, that 1302 the client could open a file requesting some limited access, and then 1303 access the file in a way not permitted by that limited access and the 1304 server would permit such action. However, the server MUST NOT ever 1305 grant access to the file that the client does not actually have the 1306 rights to. 1308 8.1.1.3. flags 1310 The 'flags' field controls various aspects of the operation, 1311 including whether or not the file is created and the kind of locking 1312 desired. 1314 The following 'flags' are defined: 1316 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 1317 SSH_FXF_CREATE_NEW = 0x00000000 1318 SSH_FXF_CREATE_TRUNCATE = 0x00000001 1319 SSH_FXF_OPEN_EXISTING = 0x00000002 1320 SSH_FXF_OPEN_OR_CREATE = 0x00000003 1321 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 1322 SSH_FXF_APPEND_DATA = 0x00000008 1323 SSH_FXF_APPEND_DATA_ATOMIC = 0x00000010 1324 SSH_FXF_TEXT_MODE = 0x00000020 1325 SSH_FXF_BLOCK_READ = 0x00000040 1326 SSH_FXF_BLOCK_WRITE = 0x00000080 1327 SSH_FXF_BLOCK_DELETE = 0x00000100 1328 SSH_FXF_BLOCK_ADVISORY = 0x00000200 1329 SSH_FXF_NOFOLLOW = 0x00000400 1330 SSH_FXF_DELETE_ON_CLOSE = 0x00000800 1331 SSH_FXF_ACCESS_AUDIT_ALARM_INFO = 0x00001000 1332 SSH_FXF_ACCESS_BACKUP = 0x00002000 1333 SSH_FXF_BACKUP_STREAM = 0x00004000 1334 SSH_FXF_OVERRIDE_OWNER = 0x00008000 1336 SSH_FXF_ACCESS_DISPOSITION 1337 Disposition is a 3 bit field that controls how the file is opened. 1338 The server MUST support these bits. Any one of the following 1339 enumeration is allowed: 1341 SSH_FXF_CREATE_NEW 1342 A new file is created; if the file already exists, the server 1343 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 1345 SSH_FXF_CREATE_TRUNCATE 1346 A new file is created; if the file already exists, it is opened 1347 and truncated. 1349 SSH_FXF_OPEN_EXISTING 1350 An existing file is opened. If the file does not exist, the 1351 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 1352 path does not exist, the server SHOULD return 1353 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 1354 returns SSH_FX_NO_SUCH_FILE in this case. 1356 SSH_FXF_OPEN_OR_CREATE 1357 If the file exists, it is opened. If the file does not exist, 1358 it is created. 1360 SSH_FXF_TRUNCATE_EXISTING 1361 An existing file is opened and truncated. If the file does not 1362 exist, the server MUST return the same error codes as defined 1363 for SSH_FXF_OPEN_EXISTING. 1365 SSH_FXF_APPEND_DATA 1366 Data is always written at the end of the file. The offset field 1367 of the SSH_FXP_WRITE requests are ignored. 1369 Data is not required to be appended atomically. This means that 1370 if multiple writers attempt to append data simultaneously, data 1371 from the first may be lost. However, data MAY be appended 1372 atomically. 1374 SSH_FXF_APPEND_DATA_ATOMIC 1375 Data is always written at the end of the file. The offset field 1376 of the SSH_FXP_WRITE requests are ignored. 1378 Data MUST be written atomically so that there is no chance that 1379 multiple appenders can collide and result in data being lost. 1381 If both append flags are specified, the server SHOULD use atomic 1382 append if it is available, but SHOULD use non-atomic appends 1383 otherwise. The server SHOULD NOT fail the request in this case. 1385 SSH_FXF_TEXT_MODE 1386 Indicates that the server should treat the file as text and 1387 convert it to the canonical newline convention in use. (See 1388 Determining Server Newline Convention. (Section 5.3) 1390 When a file is opened with this flag, the offset field in the read 1391 and write functions is ignored. 1393 Servers MUST process multiple, parallel reads and writes correctly 1394 in this mode. Naturally, it is permissible for them to do this by 1395 serializing the requests. 1397 Clients SHOULD use the SSH_FXF_APPEND_DATA flag to append data to 1398 a text file rather then using write with a calculated offset. 1400 To support seeks on text files the following SSH_FXP_EXTENDED 1401 packet is defined. 1403 string "text-seek" 1404 string file-handle 1405 uint64 line-number 1407 line-number is the index of the line number to seek to, where byte 1408 0 in the file is line number 0, and the byte directly following 1409 the first newline sequence in the file is line number 1 and so on. 1411 The response to a "text-seek" request is an SSH_FXP_STATUS 1412 message. 1414 An attempt to seek past the end-of-file should result in a 1415 SSH_FX_EOF status. 1417 Servers SHOULD support at least one "text-seek" in order to 1418 support resume. However, a client MUST be prepared to receive 1419 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 1420 The client can then try a fall-back strategy, if it has one. 1422 SSH_FXF_BLOCK_READ 1423 The server MUST guarantee that no other handle has been opened 1424 with ACE4_READ_DATA access, and that no other handle will be 1425 opened with ACE4_READ_DATA access until the client closes the 1426 handle. (This MUST apply both to other clients and to other 1427 processes on the server.) 1429 If there is a conflicting lock the server MUST return 1430 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1431 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1433 Other handles MAY be opened for ACE4_WRITE_DATA or any other 1434 combination of accesses, as long as ACE4_READ_DATA is not included 1435 in the mask. 1437 SSH_FXF_BLOCK_WRITE 1438 The server MUST guarantee that no other handle has been opened 1439 with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other 1440 handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA 1441 access until the client closes the handle. (This MUST apply both 1442 to other clients and to other processes on the server.) 1443 If there is a conflicting lock the server MUST return 1444 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1445 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1447 Other handles MAY be opened for ACE4_READ_DATA or any other 1448 combination of accesses, as long as neither ACE4_WRITE_DATA nor 1449 ACE4_APPEND_DATA are included in the mask. 1451 SSH_FXF_BLOCK_DELETE 1452 The server MUST guarantee that no other handle has been opened 1453 with ACE4_DELETE access, opened with the SSH_FXF_DELETE_ON_CLOSE 1454 flag set, and that no other handle will be opened with ACE4_DELETE 1455 access or with the SSH_FXF_DELETE_ON_CLOSE flag set, and that the 1456 file itself is not deleted in any other way until the client 1457 closes the handle. 1459 If there is a conflicting lock the server MUST return 1460 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1461 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1463 SSH_FXF_BLOCK_ADVISORY 1464 If this bit is set, the above BLOCK modes are advisory. In 1465 advisory mode, only other accesses that specify a BLOCK mode need 1466 be considered when determining whether the BLOCK can be granted, 1467 and the server need not prevent I/O operations that violate the 1468 block mode. 1470 The server MAY perform mandatory locking even if the 1471 BLOCK_ADVISORY bit is set. 1473 SSH_FXF_NOFOLLOW 1474 If the final component of the path is a symlink, then the open 1475 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 1477 SSH_FXF_DELETE_ON_CLOSE 1478 The file should be deleted when the last handle to it is closed. 1479 (The last handle may not be an sftp-handle.) This MAY be emulated 1480 by a server if the OS doesn't support it by deleting the file when 1481 this handle is closed. 1483 It is implementation specific whether the directory entry is 1484 removed immediately or when the handle is closed. 1486 SSH_FXF_ACCESS_AUDIT_ALARM_INFO 1487 The client wishes the server to enable any privileges or extra 1488 capabilities that the user may have in to allow the reading and 1489 writing of AUDIT or ALARM access control entries. 1491 SSH_FXF_ACCESS_BACKUP 1492 The client wishes the server to enable any privileges or extra 1493 capabilities that the user may have in order to bypass normal 1494 access checks for the purpose of backing up or restoring files. 1496 SSH_FXF_BACKUP_STREAM 1497 This bit indicates that the client wishes to read or write a 1498 backup stream. A backup stream is a system dependent structured 1499 data stream that encodes all the information that must be 1500 preserved in order to restore the file from backup medium. 1502 The only well defined use for backup stream data read in this 1503 fashion is to write it to the same server to a file also opened 1504 using the BACKUP_STREAM flag. However, if the server has a well 1505 defined backup stream format, their may be other uses for this 1506 data outside the scope of this protocol. 1508 ACCESS_OVERRIDE_OWNER 1509 This bit indicates that the client wishes the server to enable any 1510 privileges or extra capabilities that the user may have in order 1511 to gain access to the file with WRITE_OWNER permission. 1513 This bit MUST always be specified in combination with 1514 ACE4_WRITE_OWNER. 1516 The 'attrs' field specifies the initial attributes for the file. 1517 Default values MUST be supplied by the server for those attributes 1518 that are not specified. See Section ''File Attributes'' for more 1519 information. 1521 The 'attrs' field is ignored if an existing file is opened. 1523 The following table is provided to assist in mapping POSIX semantics 1524 to equivalent SFTP file open parameters: 1525 O_RDONLY 1526 desired-access = READ_DATA|READ_ATTRIBUTES 1528 O_WRONLY 1529 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1531 O_RDWR 1532 desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA| 1533 WRITE_ATTRIBUTES 1535 O_APPEND 1536 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1537 flags = SSH_FXF_APPEND_DATA and or SSH_FXF_APPEND_DATA_ATOMIC 1539 O_CREAT 1540 flags = SSH_FXF_OPEN_OR_CREATE 1542 O_TRUNC 1543 flags = SSH_FXF_TRUNCATE_EXISTING 1545 O_TRUNC|O_CREATE 1546 flags = SSH_FXF_CREATE_TRUNCATE 1548 8.1.2. Opening a Directory 1550 To enumerate a directory, the client first obtains a handle and then 1551 issues directory read requests. When enumeration is complete, the 1552 handle MUST be closed. 1554 byte SSH_FXP_OPENDIR 1555 uint32 request-id 1556 string path [UTF-8] 1558 path 1559 The 'path' field is the path name of the directory to be listed 1560 (without any trailing slash). See Section 'File Names' for more 1561 information on file names. 1563 If 'path' does not refer to a directory, the server MUST return 1564 SSH_FX_NOT_A_DIRECTORY. 1566 The response to this message will be either SSH_FXP_HANDLE (if the 1567 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1569 8.1.3. Closing Handles 1571 A handle is closed using the following request. 1573 byte SSH_FXP_CLOSE 1574 uint32 request-id 1575 string handle 1577 handle 1578 'handle' is a handle previously returned in the response to 1579 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid 1580 immediately after this request has been sent. 1582 The response to this request will be a SSH_FXP_STATUS message. Note 1583 that on some server platforms even a close can fail. For example, if 1584 the server operating system caches writes, and an error occurs while 1585 flushing cached writes, the close operation may fail. 1587 Note that the handle is invalid regardless of the SSH_FXP_STATUS 1588 result. There is no way for the client to recover a handle that 1589 fails to close. The client MUST release all resources associated 1590 with the handle regardless of the status. The server SHOULD take 1591 whatever steps it can to recover from a close failure and to ensure 1592 that all resources associated with the handle on the server are 1593 correctly released. 1595 8.2. Reading and Writing 1597 8.2.1. Reading Files 1599 The following request can be used to read file data: 1601 byte SSH_FXP_READ 1602 uint32 request-id 1603 string handle 1604 uint64 offset 1605 uint32 length 1607 handle 1608 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1609 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1610 return SSH_FX_INVALID_HANDLE. 1612 offset 1613 The offset (in bytes) relative to the beginning of the file that 1614 the read MUST start at. This field is ignored if 1615 SSH_FXF_TEXT_MODE was specified during the open. 1617 length 1618 'length' is the maximum number of bytes to read. 1620 The server MUST not respond with more data than is specified by 1621 the 'length' parameter. However, the server MAY respond with less 1622 data if EOF is reached, an error is encountered, or the servers 1623 internal buffers can not handle such a large request. 1625 If the server specified a non-zero 'max-read-size' in its 1626 'supported2' (Section 5.4) extension, then failure to return 1627 'length' bytes indicates that EOF or an error occurred. 1629 8.2.2. Reading Directories 1631 In order to retrieve a directory listing, the client issues one or 1632 more SSH_FXP_READDIR requests. In order to obtain a complete 1633 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1634 requests until the server responds with an SSH_FXP_STATUS message. 1636 byte SSH_FXP_READDIR 1637 uint32 request-id 1638 string handle 1640 handle 1641 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is 1642 an ordinary file handle returned by SSH_FXP_OPEN, the server MUST 1643 return SSH_FX_INVALID_HANDLE. 1645 The server responds to this request with either a SSH_FXP_NAME or a 1646 SSH_FXP_STATUS message. One or more names may be returned at a time. 1647 Full status information is returned for each name in order to speed 1648 up typical directory listings. 1650 If there are no more names available to be read, the server MUST 1651 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1653 8.2.3. Writing Files 1655 Writing to a file is achieved using the following message: 1657 byte SSH_FXP_WRITE 1658 uint32 request-id 1659 string handle 1660 uint64 offset 1661 string data 1663 handle 1664 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1665 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1666 return SSH_FX_INVALID_HANDLE. 1668 offset 1669 The offset (in bytes) relative to the beginning of the file that 1670 the write MUST start at. This field is ignored if 1671 SSH_FXF_TEXT_MODE was specified during the open. 1673 The write will extend the file if writing beyond the end of the 1674 file. It is legal to write to an offset that extends beyond the 1675 end of the file; the semantics are to write the byte value 0x00 1676 from the end of the file to the specified offset and then the 1677 data. On most operating systems, such writes do not allocate disk 1678 space but instead create a sparse file. 1680 data 1681 The data to write to the file. 1683 The server responds to a write request with a SSH_FXP_STATUS message. 1685 8.3. Removing and Renaming Files 1687 The following request can be used to remove a file: 1689 byte SSH_FXP_REMOVE 1690 uint32 request-id 1691 string filename [UTF-8] 1693 filename 1694 'filename' is the name of the file to be removed. See Section 1695 'File Names' for more information. 1697 If 'filename' is a symbolic link, the link is removed, not the 1698 file it points to. 1699 This request cannot be used to remove directories. The server 1700 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. 1702 The server will respond to this request with a SSH_FXP_STATUS 1703 message. 1705 Files (and directories) can be renamed using the SSH_FXP_RENAME 1706 message. 1708 byte SSH_FXP_RENAME 1709 uint32 request-id 1710 string oldpath [UTF-8] 1711 string newpath [UTF-8] 1712 uint32 flags 1714 where 'request-id' is the request identifier, 'oldpath' is the name 1715 of an existing file or directory, and 'newpath' is the new name for 1716 the file or directory. 1718 'flags' is 0 or a combination of: 1720 SSH_FXF_RENAME_OVERWRITE 0x00000001 1721 SSH_FXF_RENAME_ATOMIC 0x00000002 1722 SSH_FXF_RENAME_NATIVE 0x00000004 1724 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1725 exists a file with the name specified by newpath, the server MUST 1726 respond with SSH_FX_FILE_ALREADY_EXISTS. 1728 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1729 already exists, it is replaced in an atomic fashion. I.e., there is 1730 no observable instant in time where the name does not refer to either 1731 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1732 SSH_FXP_RENAME_OVERWRITE. 1734 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace 1735 the destination in an atomic fashion, then the server MUST respond 1736 with SSH_FX_OP_UNSUPPORTED. 1738 Because some servers cannot provide atomic rename, clients should 1739 only specify atomic rename if correct operation requires it. If 1740 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1741 atomic rename even if it is not requested. 1743 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1744 rename operation in whatever fashion it deems appropriate. Other 1745 flag values are considered hints as to desired behavior, but not 1746 requirements. 1748 The server will respond to this request with a SSH_FXP_STATUS 1749 message. 1751 8.4. Creating and Deleting Directories 1753 New directories can be created using the SSH_FXP_MKDIR request. It 1754 has the following format: 1756 byte SSH_FXP_MKDIR 1757 uint32 request-id 1758 string path [UTF-8] 1759 ATTRS attrs 1761 where 'request-id' is the request identifier. 1763 'path' specifies the directory to be created. See Section ''File 1764 Names'' for more information on file names. 1766 'attrs' specifies the attributes that should be applied to it upon 1767 creation. Attributes are discussed in more detail in Section ''File 1768 Attributes''. 1770 The server will respond to this request with a SSH_FXP_STATUS 1771 message. If a file or directory with the specified path already 1772 exists, an error will be returned. 1774 Directories can be removed using the SSH_FXP_RMDIR request, which has 1775 the following format: 1777 byte SSH_FXP_RMDIR 1778 uint32 request-id 1779 string path [UTF-8] 1781 where 'request-id' is the request identifier, and 'path' specifies 1782 the directory to be removed. See Section ''File Names'' for more 1783 information on file names. 1785 The server responds to this request with a SSH_FXP_STATUS message. 1787 8.5. Retrieving File Attributes 1789 Very often, file attributes are automatically returned by 1790 SSH_FXP_READDIR. However, sometimes there is need to specifically 1791 retrieve the attributes for a named file. This can be done using the 1792 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1794 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1795 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1796 follow symbolic links. Both have the same format: 1798 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1799 uint32 request-id 1800 string path [UTF-8] 1801 uint32 flags 1803 where 'request-id' is the request identifier, and 'path' specifies 1804 the file system object for which status is to be returned. The 1805 server responds to this request with either SSH_FXP_ATTRS or 1806 SSH_FXP_STATUS. 1808 The flags field specify the attribute flags in which the client has 1809 particular interest. This is a hint to the server. For example, 1810 because retrieving owner / group and acl information can be an 1811 expensive operation under some operating systems, the server may 1812 choose not to retrieve this information unless the client expresses a 1813 specific interest in it. 1815 The client has no guarantee the server will provide all the fields 1816 that it has expressed an interest in. 1818 SSH_FXP_FSTAT differs from the others in that it returns status 1819 information for an open file (identified by the file handle). 1821 byte SSH_FXP_FSTAT 1822 uint32 request-id 1823 string handle 1824 uint32 flags 1826 handle 1827 'handle' is an open file handle from either SSH_FXP_OPEN or 1828 SSH_FXP_OPENDIR. 1830 The server responds to this request with SSH_FXP_ATTRS or 1831 SSH_FXP_STATUS. 1833 8.6. Setting File Attributes 1835 File attributes may be modified using the SSH_FXP_SETSTAT and 1836 SSH_FXP_FSETSTAT requests. 1838 byte SSH_FXP_SETSTAT 1839 uint32 request-id 1840 string path [UTF-8] 1841 ATTRS attrs 1843 byte SSH_FXP_FSETSTAT 1844 uint32 request-id 1845 string handle 1846 ATTRS attrs 1848 path 1849 The file system object (e.g. file or directory) whose attributes 1850 are to be modified. If this object does not exist, or the user 1851 does not have sufficient access to write the attributes, the 1852 request MUST fail. 1854 handle 1855 'handle' is an open file handle from either SSH_FXP_OPEN or 1856 SSH_FXP_OPENDIR. If the handle was not opened with sufficient 1857 access to write the requested attributes, the request MUST fail. 1859 attrs 1860 Specifies the modified attributes to be applied. Attributes are 1861 discussed in more detail in Section ''File Attributes''. 1863 The server will respond with a SSH_FXP_STATUS message. 1865 Because some systems must use separate system calls to set various 1866 attributes, it is possible that a failure response will be returned, 1867 but yet some of the attributes may be have been successfully 1868 modified. If possible, servers SHOULD avoid this situation; however, 1869 clients MUST be aware that this is possible. 1871 8.7. Dealing with Links 1873 The SSH_FXP_READLINK request reads the target of a symbolic link. 1875 byte SSH_FXP_READLINK 1876 uint32 request-id 1877 string path [UTF-8] 1879 where 'request-id' is the request identifier and 'path' specifies the 1880 path name of the symlink to be read. 1882 The server will respond with a SSH_FXP_NAME packet containing only 1883 one name and a dummy attributes value. The name in the returned 1884 packet contains the target of the link. If an error occurs, the 1885 server MAY respond with SSH_FXP_STATUS. 1887 The SSH_FXP_LINK request creates a link (either hard or symbolic) on 1888 the server. 1890 byte SSH_FXP_LINK 1891 uint32 request-id 1892 string new-link-path [UTF-8] 1893 string existing-path [UTF-8] 1894 bool sym-link 1896 new-link-path 1897 Specifies the path name of the new link to create. 1899 existing-path 1900 Specifies the path of an existing file system object to which the 1901 new-link-path will refer. 1903 sym-link 1904 Specifies that the link should be a symbolic link, or a special 1905 file that redirects file system parsing to the resulting path. It 1906 is generally possible to create symbolic links across device 1907 boundaries; however, it is not required that a server support 1908 this. 1910 If 'sym-link' is false, the link should be a hard link, or a 1911 second directory entry referring to the same file or directory 1912 object. It is generally not possible to create hard links across 1913 devices. 1915 The server shall respond with a SSH_FXP_STATUS. Clients should be 1916 aware that some servers may return SSH_FX_OP_UNSUPPORTED for either 1917 the hard-link, sym-link, or both operations. 1919 8.8. Byte-range locks 1921 SSH_FXP_BLOCK creates a byte-range lock on the file specified by the 1922 handle. The lock can be either mandatory (meaning that the server 1923 enforces that no other process or client can perform operations in 1924 violation of the lock) or advisory (meaning that no other process can 1925 obtain a conflicting lock, but the server does not enforce that no 1926 operation violates the lock. 1928 A server MAY implement an advisory lock in a mandatory fashion; in 1929 other words, the server MAY enforce that no operation violates the 1930 lock even when operating in advisory mode. 1932 The result is a SSH_FXP_STATUS return. 1934 byte SSH_FXP_BLOCK 1935 uint32 request-id 1936 string handle 1937 uint64 offset 1938 uint64 length 1939 uint32 uLockMask 1941 handle 1942 'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. 1943 Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the 1944 handle is a directory handle. 1946 offset 1947 Beginning of the byte-range to lock. 1949 length 1950 Number of bytes in the range to lock. The special value 0 means 1951 lock from 'offset' to the end of the file. 1953 uLockMask 1954 A bit mask of SSH_FXF_BLOCK_* values; the meanings are described 1955 in Section 8.1.1.3. 1957 SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the 1958 specified handle. 1960 The result is a SSH_FXP_STATUS return. 1962 byte SSH_FXP_UNBLOCK 1963 uint32 request-id 1964 string handle 1965 uint64 offset 1966 uint64 length 1968 handle 1969 'handle' on which a SSH_FXP_BLOCK request has previously been 1970 issued. 1972 offset 1973 Beginning of the byte-range to lock. 1975 length 1976 Number of bytes in the range to lock. The special value 0 means 1977 lock from 'offset' to the end of the file. 1979 8.9. Canonicalizing the Server-Side Path Name 1981 The SSH_FXP_REALPATH request can be used to have the server 1982 canonicalize any given path name to an absolute path. This is useful 1983 for converting path names containing ".." components or relative 1984 pathnames without a leading slash into absolute paths. The format of 1985 the request is as follows: 1987 byte SSH_FXP_REALPATH 1988 uint32 request-id 1989 string original-path [UTF-8] 1990 byte control-byte [optional] 1991 string compose-path[0..n] [optional] 1993 original-path 1994 The first component of the path which the client wishes resolved 1995 into a absolute canonical path. This may be the entire path. 1997 control-byte 1999 SSH_FXP_REALPATH_NO_CHECK 0x00000001 2000 SSH_FXP_REALPATH_STAT_IF 0x00000002 2001 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 2003 This field is optional, and if it is not present in the packet, it 2004 is assumed to be SSH_FXP_REALPATH_NO_CHECK. 2006 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT 2007 fail the request if the path does not exist, is hidden, or the 2008 user does not have access to the path or some component thereof. 2009 In addition, the path MUST NOT resolve symbolic links. This 2010 allows paths to be composed for the SSH_FXP_REMOVE command to 2011 remove symbolic links. 2013 The server MAY fail the request if the path is not syntactically 2014 valid, or for other reasons. 2016 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the 2017 path if it exists and is accessible to the client. However, if 2018 the path does not exist, isn't visible, or isn't accessible, the 2019 server MUST NOT fail the request. If the stat failed, the file 2020 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to 2021 distinguish between files that are actually 2022 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will have 2023 to issue a separate stat command in this case. 2025 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat 2026 the path. If the stat operation fails, the server MUST fail the 2027 request. 2029 compose-path 2030 A path which the client wishes the server to compose with the 2031 original path to form the new path. This field is optional, and 2032 if it is not present in the packet, it is assumed to be a zero 2033 length string. 2035 The client may specify multiple 'compose-path' elements, in which 2036 case the server should build the resultant path up by applying 2037 each compose path to the accumulated result until all 'compose- 2038 path' elements have been applied. 2040 The server MUST take the 'original-path' and apply the 'compose-path' 2041 as a modification to it. 'compose-path' MAY be relative to 'original- 2042 path' or may be an absolute path, in which case 'original-path' will 2043 be discarded. The 'compose-path' MAY be zero length. 2045 The server will respond with a SSH_FXP_NAME packet containing the 2046 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK 2047 is specified, the attributes are dummy values. 2049 8.9.1. Best Practice for Dealing with Paths 2051 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 2053 Previous to this version, clients typically composed new paths 2054 themselves and then called both realpath and stat on the resulting 2055 path to get its canonical name and see if it really existed and was a 2056 directory. 2058 This required clients to assume certain things about how a relative 2059 vs. realpath looked. The new realpath allows clients to no longer 2060 make those assumptions and to remove one round trip from the process 2061 and get deterministic behavior from all servers. 2063 END: RFCEDITOR REMOVE BEFORE PUBLISHING 2065 The client SHOULD treat the results of SSH_FXP_REALPATH as a 2066 canonical absolute path, even if the path does not appear to be 2067 absolute. A client that uses REALPATH(".", "") and treats the result 2068 as absolute, even if there is no leading slash, will continue to 2069 function correctly, even when talking to a Windows NT or VMS style 2070 system, where absolute paths may not begin with a slash. 2072 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so 2073 that it does not need to know when a path is absolute or relative. 2075 For example, if the client wishes to change directory up, and the 2076 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 2077 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) 2079 As a second example, if the client wishes transfer local file "a" to 2080 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the 2081 canonical path of the current directory, the client SHOULD send 2082 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This 2083 call will determine the correct path to use for the open request and 2084 whether the /b/d/e represents a directory. 2086 9. Responses from the Server to the Client 2088 The server responds to the client using one of a few response 2089 packets. All requests can return a SSH_FXP_STATUS response upon 2090 failure. When the operation is successful, and no data needs to be 2091 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 2092 appropriate. 2094 Exactly one response will be returned for each request. Each 2095 response packet contains a request identifier which can be used to 2096 match each response with the corresponding request. Note that it is 2097 legal to have several requests outstanding simultaneously, and the 2098 server is allowed to send responses to them in a different order from 2099 the order in which the requests were sent (the result of their 2100 execution, however, is guaranteed to be as if they had been processed 2101 one at a time in the order in which the requests were sent). 2103 Response packets are of the same general format as request packets. 2104 Each response packet begins with the request identifier. 2106 9.1. Status Response 2108 The format of the data portion of the SSH_FXP_STATUS response is as 2109 follows: 2111 byte SSH_FXP_STATUS 2112 uint32 request-id 2113 uint32 error/status code 2114 string error message (ISO-10646 UTF-8 [RFC-2279]) 2115 string language tag (as defined in [RFC-1766]) 2116 error-specific data 2118 request-id 2119 The 'request-id' specified by the client in the request the server 2120 is responding to. 2122 error/status code 2123 Machine readable status code indicating the result of the request. 2124 Error code values are defined below. The value SSH_FX_OK 2125 indicates success, and all other values indicate failure. 2127 Implementations MUST be prepared to receive unexpected error codes 2128 and handle them sensibly (such as by treating them as equivalent 2129 to SSH_FX_FAILURE). Future protocol revisions will add additional 2130 error codes without changing the version number. 2132 error message 2133 Human readable description of the error. 2135 language tag 2136 'language tag' specifies the language the error is in. 2138 error-specific data 2139 The error-specific data may be empty, or may contain additional 2140 information about the error. For error codes that send error- 2141 specific data, the format of the data is defined below. 2143 Error codes: 2145 SSH_FX_OK 0 2146 SSH_FX_EOF 1 2147 SSH_FX_NO_SUCH_FILE 2 2148 SSH_FX_PERMISSION_DENIED 3 2149 SSH_FX_FAILURE 4 2150 SSH_FX_BAD_MESSAGE 5 2151 SSH_FX_NO_CONNECTION 6 2152 SSH_FX_CONNECTION_LOST 7 2153 SSH_FX_OP_UNSUPPORTED 8 2154 SSH_FX_INVALID_HANDLE 9 2155 SSH_FX_NO_SUCH_PATH 10 2156 SSH_FX_FILE_ALREADY_EXISTS 11 2157 SSH_FX_WRITE_PROTECT 12 2158 SSH_FX_NO_MEDIA 13 2159 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 2160 SSH_FX_QUOTA_EXCEEDED 15 2161 SSH_FX_UNKNOWN_PRINCIPAL 16 2162 SSH_FX_LOCK_CONFLICT 17 2163 SSH_FX_DIR_NOT_EMPTY 18 2164 SSH_FX_NOT_A_DIRECTORY 19 2165 SSH_FX_INVALID_FILENAME 20 2166 SSH_FX_LINK_LOOP 21 2167 SSH_FX_CANNOT_DELETE 22 2168 SSH_FX_INVALID_PARAMETER 23 2169 SSH_FX_FILE_IS_A_DIRECTORY 24 2170 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 2171 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 2172 SSH_FX_DELETE_PENDING 27 2173 SSH_FX_FILE_CORRUPT 28 2174 SSH_FX_OWNER_INVALID 29 2175 SSH_FX_GROUP_INVALID 30 2177 SSH_FX_OK 2178 Indicates successful completion of the operation. 2180 SSH_FX_EOF 2181 An attempt to read past the end-of-file was made; or, there are no 2182 more directory entries to return. 2184 SSH_FX_NO_SUCH_FILE 2185 A reference was made to a file which does not exist. 2187 SSH_FX_PERMISSION_DENIED 2188 The user does not have sufficient permissions to perform the 2189 operation. 2191 SSH_FX_FAILURE 2192 An error occurred, but no specific error code exists to describe 2193 the failure. 2195 This error message SHOULD always have meaningful text in the the 2196 'error message' field. 2198 SSH_FX_BAD_MESSAGE 2199 A badly formatted packet or other SFTP protocol incompatibility 2200 was detected. 2202 SSH_FX_NO_CONNECTION 2203 There is no connection to the server. This error MAY be used 2204 locally, but MUST NOT be return by a server. 2206 SSH_FX_CONNECTION_LOST 2207 The connection to the server was lost. This error MAY be used 2208 locally, but MUST NOT be return by a server. 2210 SSH_FX_OP_UNSUPPORTED 2211 An attempted operation could not be completed by the server 2212 because the server does not support the operation. 2214 This error MAY be generated locally by the client if e.g. the 2215 version number exchange indicates that a required feature is not 2216 supported by the server, or it may be returned by the server if 2217 the server does not implement an operation. 2219 SSH_FX_INVALID_HANDLE 2220 The handle value was invalid. 2222 SSH_FX_NO_SUCH_PATH 2223 The file path does not exist or is invalid. 2225 SSH_FX_FILE_ALREADY_EXISTS 2226 The file already exists. 2228 SSH_FX_WRITE_PROTECT 2229 The file is on read-only media, or the media is write protected. 2231 SSH_FX_NO_MEDIA 2232 The requested operation cannot be completed because there is no 2233 media available in the drive. 2235 SSH_FX_NO_SPACE_ON_FILESYSTEM 2236 The requested operation cannot be completed because there is no 2237 free space on the filesystem. 2239 SSH_FX_QUOTA_EXCEEDED 2240 The operation cannot be completed because it would exceed the 2241 user's storage quota. 2243 SSH_FX_UNKNOWN_PRINCIPAL 2244 A principal referenced by the request (either the 'owner', 2245 'group', or 'who' field of an ACL), was unknown. The error 2246 specific data contains the problematic names. The format is one 2247 or more: 2249 string unknown-name 2251 Each string contains the name of a principal that was unknown. 2253 SSH_FX_LOCK_CONFLICT 2254 The file could not be opened because it is locked by another 2255 process. 2257 SSH_FX_DIR_NOT_EMPTY 2258 The directory is not empty. 2260 SSH_FX_NOT_A_DIRECTORY 2261 The specified file is not a directory. 2263 SSH_FX_INVALID_FILENAME 2264 The filename is not valid. 2266 SSH_FX_LINK_LOOP 2267 Too many symbolic links encountered. 2269 SSH_FX_CANNOT_DELETE 2270 The file cannot be deleted. One possible reason is that the 2271 advisory READONLY attribute-bit is set. 2273 SSH_FX_INVALID_PARAMETER 2274 On of the parameters was out of range, or the parameters specified 2275 cannot be used together. 2277 SSH_FX_FILE_IS_A_DIRECTORY 2278 The specified file was a directory in a context where a directory 2279 cannot be used. 2281 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 2282 A read or write operation failed because another process's 2283 mandatory byte-range lock overlaps with the request. 2285 SSH_FX_BYTE_RANGE_LOCK_REFUSED 2286 A request for a byte range lock was refused. 2288 SSH_FX_DELETE_PENDING 2289 An operation was attempted on a file for which a delete operation 2290 is pending. 2292 SSH_FX_FILE_CORRUPT 2293 The file is corrupt; an filesystem integrity check should be run. 2295 SSH_FX_OWNER_INVALID 2296 The principal specified can not be assigned as an owner of a file. 2298 SSH_FX_GROUP_INVALID 2299 The principal specified can not be assigned as the primary group 2300 of a file. 2302 9.2. Handle Response 2304 The SSH_FXP_HANDLE response has the following format: 2306 byte SSH_FXP_HANDLE 2307 uint32 request-id 2308 string handle 2310 'handle' 2311 An arbitrary string that identifies an open file or directory on 2312 the server. The handle is opaque to the client; the client MUST 2313 NOT attempt to interpret or modify it in any way. The length of 2314 the handle string MUST NOT exceed 256 data bytes. 2316 9.3. Data Response 2318 The SSH_FXP_DATA response has the following format: 2320 byte SSH_FXP_DATA 2321 uint32 request-id 2322 string data 2323 bool end-of-file [optional] 2325 data 2326 'data' is an arbitrary byte string containing the requested data. 2327 The data string may be at most the number of bytes requested in a 2328 SSH_FXP_READ request, but may also be shorter. (See 2329 Section 8.2.1.) 2331 end-of-file 2332 This field is optional. If it is present in the packet, it MUST 2333 be true, and it indicates that EOF was reached during this read. 2334 This can help the client avoid a round trip to determine whether a 2335 short read was normal (due to EOF) or some other problem (limited 2336 server buffer for example.) 2338 9.4. Name Response 2340 The SSH_FXP_NAME response has the following format: 2342 byte SSH_FXP_NAME 2343 uint32 request-id 2344 uint32 count 2345 repeats count times: 2346 string filename [UTF-8] 2347 ATTRS attrs 2348 bool end-of-list [optional] 2350 count 2351 The number of names returned in this response, and the 'filename' 2352 and 'attrs' field repeat 'count' times. 2354 filename 2355 A file name being returned (for SSH_FXP_READDIR, it will be a 2356 relative name within the directory, without any path components; 2357 for SSH_FXP_REALPATH it will be an absolute path name.) 2359 attrs 2360 The attributes of the file as described in Section ''File 2361 Attributes''. 2363 end-of-list 2364 If this field is present and true, there are no more entries to be 2365 read. 2367 9.5. Attrs Response 2369 The SSH_FXP_ATTRS response has the following format: 2371 byte SSH_FXP_ATTRS 2372 uint32 request-id 2373 ATTRS attrs 2375 attrs 2376 The returned file attributes as described in Section ''File 2377 Attributes''. 2379 10. Extensions 2381 The SSH_FXP_EXTENDED request provides a generic extension mechanism 2382 for adding additional commands. 2384 byte SSH_FXP_EXTENDED 2385 uint32 request-id 2386 string extended-request 2387 ... any request-specific data ... 2389 request-id 2390 Identifier to be returned from the server with the response. 2392 extended-request 2393 A string naming the extension, following the the DNS extensibility 2394 naming convention outlined in [RFC4251], or defined by IETF 2395 consensus. 2397 request-specific data 2398 The rest of the request is defined by the extension; servers 2399 SHOULD NOT attempt to interpret it if they do not recognize the 2400 'extended-request' name. 2402 The server may respond to such requests using any of the response 2403 packets defined in Section ''Responses from the Server to the 2404 Client''. Additionally, the server may also respond with a 2405 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 2406 not recognize the 'extended-request' name, then the server MUST 2407 respond with SSH_FXP_STATUS with error/status set to 2408 SSH_FX_OP_UNSUPPORTED. 2410 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 2411 extension-specific data from the server to the client. It is of the 2412 following format: 2414 byte SSH_FXP_EXTENDED_REPLY 2415 uint32 request-id 2416 ... any request-specific data ... 2418 There is a range of packet types reserved for use by extensions. In 2419 order to avoid collision, extensions that that use additional packet 2420 types should determine those numbers dynamically. 2422 The suggested way of doing this is have an extension request from the 2423 client to the server that enables the extension; the extension 2424 response from the server to the client would specify the actual type 2425 values to use, in addition to any other data. 2427 Extension authors should be mindful of the limited range of packet 2428 types available (there are only 45 values available) and avoid 2429 requiring a new packet type where possible. 2431 11. Implementation Considerations 2433 In order for this protocol to perform well, especially over high 2434 latency networks, multiple read and write requests should be queued 2435 to the server. 2437 The data size of requests should match the maximum packet size for 2438 the next layer up in the protocol chain. 2440 When implemented over ssh, the best performance should be achieved 2441 when the data size matches the channel's max packet, and the channel 2442 window is a multiple of the channel packet size. 2444 Implementations MUST be aware that requests do not have to be 2445 satisfied in the order issued. (See Request Synchronization and 2446 Reordering (Section 4.1).) 2448 Implementations MUST also be aware that read requests may not return 2449 all the requested data, even if the data is available. 2451 12. IANA Considerations 2453 An IANA registry needs to be created containing: 2454 o The packet types define defined in Section 4.3 2455 o The extension specified in this draft, which are: 'text-seek', 2456 'supported2', 'acl-supported', 'newline', 'versions', 'version- 2457 select', 'filename-charset', 'filename-translation-control' 2459 13. Security Considerations 2461 It is assumed that both ends of the connection have been 2462 authenticated and that the connection has privacy and integrity 2463 features. Such security issues are left to the underlying transport 2464 protocol, except to note that if this is not the case, an attacker 2465 could manipulate files on the server at will and thus wholly 2466 compromise the server. 2468 This protocol provides file system access to arbitrary files on the 2469 server (constrained only by the server implementation). It is the 2470 responsibility of the server implementation to enforce any access 2471 controls that may be required to limit the access allowed for any 2472 particular user (the user being authenticated externally to this 2473 protocol, typically using [RFC4252]. 2475 Extreme care must be used when interpreting file handle strings. In 2476 particular, care must be taken that a file handle string is valid in 2477 the context of a given 'file-share' session. For example, the 'file- 2478 share' server daemon may have files which it has opened for its own 2479 purposes, and the client must not be able to access these files by 2480 specifying an arbitrary file handle string. 2482 The permission field of the attrib structure (Section 7.6) may 2483 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 2484 extreme caution when setting these bits on either remote or local 2485 files. (I.e., just because a file was SUID on the remote system does 2486 not necessarily imply that it should be SUID on the local system.) 2488 Filesystems often contain entries for objects that are not files at 2489 all, but are rather devices. For example, it may be possible to 2490 access serial ports, tape devices, or named pipes using this 2491 protocol. Servers should exercise caution when granting access to 2492 such resources. In addition to the dangers inherent in allowing 2493 access to such a device, some devices may be 'slow', and could cause 2494 denial of service by causing the server to block for a long period of 2495 time while I/O is performed to such a device. 2497 Servers should take care that file-system quotas are respected for 2498 users. In addition, implementations should be aware that attacks may 2499 be possible, or facilitated, by filling a filesystem. For example, 2500 filling the filesystem where event logging and auditing occurs may, 2501 at best, cause the system to crash, or at worst, allow the attacker 2502 to take untraceable actions in the future. 2504 Servers should take care that filenames are in their appropriate 2505 canonical form, and to ensure that filenames not in canonical form 2506 cannot be used to bypass access checks or controls. 2508 If the server implementation limits access to certain parts of the 2509 file system, extra care must be taken in parsing file names which 2510 contain the '..' path element, and when following symbolic links, 2511 shortcuts, or other filesystem objects which might transpose the path 2512 to refer to an object outside of the restricted area. There have 2513 been numerous reported security bugs where a ".." in a path name has 2514 allowed access outside the intended area. 2516 14. Changes from Previous Protocol Versions 2518 RFC EDITOR: PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2520 Please refer to the following web page for pervious versions of the 2521 protocol: 2523 http://tools.ietf.org/wg/secsh/draft-ietf-secsh-filexfer/ 2525 RFC EDITOR: END PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2527 15. References 2529 15.1. Normative References 2531 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2532 Beame, C., Eisler, M., and D. Noveck, "NFS version 4 2533 Protocol", RFC 3010, December 2000. 2535 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2536 Protocol Architecture", RFC 4251, January 2006. 2538 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2539 Transport Layer Protocol", RFC 4253, January 2006. 2541 [RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2542 Connection Protocol", RFC 4254, January 2006. 2544 [IEEE.1003-1.1996] 2545 Institute of Electrical and Electronics Engineers, 2546 "Information Technology - Portable Operating System 2547 Interface (POSIX) - Part 1: System Application Program 2548 Interface (API) [C Language]", IEEE Standard 1003.2, 1996. 2550 15.2. Informative References 2552 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet 2553 Mail Extensions) Part One: Mechanisms for Specifying and 2554 Describing the Format of Internet Message Bodies", 2555 RFC 1521, September 1993. 2557 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2558 RFC 2246, January 1999. 2560 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2561 Languages", BCP 18, RFC 2277, January 1998. 2563 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2564 Authentication Protocol", RFC 4252, January 2006. 2566 Trademark notice 2568 "ssh" is a registered trademark in the United States and/or other 2569 countries. 2571 Authors' Addresses 2573 Joseph Galbraith 2574 VanDyke Software 2575 4848 Tramway Ridge Blvd 2576 Suite 101 2577 Albuquerque, NM 87111 2578 US 2580 Phone: +1 505 332 5700 2581 Email: galb-list@vandyke.com 2583 Oskari Saarenmaa 2584 F-Secure 2585 Tammasaarenkatu 7 2586 Helsinki 00180 2587 FI 2589 Email: oskari.saarenmaa@f-secure.com 2591 Intellectual Property Statement 2593 The IETF takes no position regarding the validity or scope of any 2594 Intellectual Property Rights or other rights that might be claimed to 2595 pertain to the implementation or use of the technology described in 2596 this document or the extent to which any license under such rights 2597 might or might not be available; nor does it represent that it has 2598 made any independent effort to identify any such rights. Information 2599 on the procedures with respect to rights in RFC documents can be 2600 found in BCP 78 and BCP 79. 2602 Copies of IPR disclosures made to the IETF Secretariat and any 2603 assurances of licenses to be made available, or the result of an 2604 attempt made to obtain a general license or permission for the use of 2605 such proprietary rights by implementers or users of this 2606 specification can be obtained from the IETF on-line IPR repository at 2607 http://www.ietf.org/ipr. 2609 The IETF invites any interested party to bring to its attention any 2610 copyrights, patents or patent applications, or other proprietary 2611 rights that may cover technology that may be required to implement 2612 this standard. Please address the information to the IETF at 2613 ietf-ipr@ietf.org. 2615 Disclaimer of Validity 2617 This document and the information contained herein are provided on an 2618 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2619 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2620 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2621 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2622 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2623 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2625 Copyright Statement 2627 Copyright (C) The Internet Society (2006). This document is subject 2628 to the rights, licenses and restrictions contained in BCP 78, and 2629 except as set forth therein, the authors retain all their rights. 2631 Acknowledgment 2633 Funding for the RFC Editor function is currently provided by the 2634 Internet Society.