idnits 2.17.1 draft-ietf-secsh-filexfer-13.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 2673. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2650. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2657. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2663. ** 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 166: '...rr by the server SHOULD be considered ...' RFC 2119 keyword, line 167: '...information, and MAY be displayed to t...' RFC 2119 keyword, line 173: '...rors or warnings MAY be sent as stderr...' RFC 2119 keyword, line 193: '...the length field MUST be included in a...' RFC 2119 keyword, line 197: '...overhead). All servers SHOULD support...' (190 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 684 has weird spacing: '... bool do-...' == Line 713 has weird spacing: '... string owne...' == Line 714 has weird spacing: '... string grou...' == Line 724 has weird spacing: '... string acl ...' == Line 728 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 (July 10, 2006) is 6498 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 2395, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 2158, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 2159, 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: January 11, 2007 O. Saarenmaa 5 F-Secure 6 July 10, 2006 8 SSH File Transfer Protocol 9 draft-ietf-secsh-filexfer-13.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 January 11, 2007. 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, bidirectional octect stream. It is 44 the standard file transfer protocol for use with the SSH2 protocol. 45 This document describes the file transfer protocol and its interface 46 to the SSH2 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 . . . . . . . . . . . . . . . . . . 14 64 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 15 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 . . . . . . . . . . . . . . . . . . . . . . . . . . 21 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.8.1. Obtaining a byte range lock . . . . . . . . . . . . . 43 96 8.8.2. Releasing a byte range lock . . . . . . . . . . . . . 44 97 8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 45 98 8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 46 99 9. Responses from the Server to the Client . . . . . . . . . . . 47 100 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 48 101 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 52 102 9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52 103 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 53 104 9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53 105 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 54 106 11. Implementation Considerations . . . . . . . . . . . . . . . . 55 107 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 108 13. Security Considerations . . . . . . . . . . . . . . . . . . . 55 109 14. Changes from Previous Protocol Versions . . . . . . . . . . . 57 110 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 111 15.1. Normative References . . . . . . . . . . . . . . . . . . . 57 112 15.2. Informative References . . . . . . . . . . . . . . . . . . 57 113 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59 114 Intellectual Property and Copyright Statements . . . . . . . . . . 60 116 1. Introduction 118 This protocol provides secure file transfer (and more generally file 119 system access). It is designed so that it could be used to implement 120 a secure remote file system service as well as a secure file transfer 121 service. 123 This protocol assumes that it runs over a secure channel, such as a 124 channel in [RFC4251], that the server has already authenticated the 125 client, and that the identity of the client user is available to the 126 protocol. 128 In general, this protocol follows a simple request-response model. 129 Each request and response contains a sequence number and multiple 130 requests may be pending simultaneously. There are a relatively large 131 number of different request messages, but a small number of possible 132 response messages. Each request has one or more response messages 133 that may be returned in result (e.g., a read either returns data or 134 reports error status). 136 The packet format descriptions in this specification follow the 137 notation presented in [RFC4251]. 139 Even though this protocol is described in the context of the SSH2 140 protocol, this protocol is general and independent of the rest of the 141 SSH2 protocol suite. It could be used in a number of different 142 applications, such as secure file transfer over TLS [RFC2246] and 143 transfer of management information in VPN applications. 145 2. Acknowledgements 147 This document owes its initial creation and protocol design to Tatu 148 Ylonen and Sami Lehtinen of SSH Communications Security Corp. 150 We express our gratitude to them for their initial work on this 151 protocol. 153 3. Use with the SSH Connection Protocol 155 When used with the SSH2 Protocol suite, this protocol is intended to 156 be used as a subsystem as described in [RFC4254] in the section 157 "Starting a Shell or a Command". The subsystem name used with this 158 protocol is "sftp". 160 3.1. The Use of 'stderr' in the server 162 This protocol uses stdout and stdin to transmit binary protocol data. 163 The "session" channel ([RFC4254]), which is used by the subsystem, 164 also supports the use of stderr. 166 Data sent on stderr by the server SHOULD be considered free format 167 debug or supplemental error information, and MAY be displayed to the 168 user. 170 For example, during initialization, there is no client request 171 active, so errors or warning information cannot be sent to the client 172 as part of the SFTP protocol at this early stage. However, the 173 errors or warnings MAY be sent as stderr text. 175 4. General Packet Format 177 All packets transmitted over the secure connection are of the 178 following format: 180 uint32 length 181 byte type 182 uint32 request-id 183 ... type specific fields ... 185 'length' 186 The length of the entire packet, excluding the length field 187 itself, such that, for example, for a packet type containing no 188 type specific fields, the length field would be 5, and 9 bytes of 189 data would be sent on the wire. (This is the packet format used 190 in [RFC4253].) 192 All packet descriptions in this document omit the length field for 193 brevity; the length field MUST be included in any case. 195 The maximum size of a packet is in practice determined by the 196 client (the maximum size of read or write requests that it sends, 197 plus a few bytes of packet overhead). All servers SHOULD support 198 packets of at least 34000 bytes (where the packet size refers to 199 the full length, including the header above). This should allow 200 for reads and writes of at most 32768 bytes. 202 'type' 203 The type code for the packet. 205 'request-id' 206 Each request from the client contains a 'request-id' field. Each 207 response from the server includes that same 'request-id' from the 208 request that the server is responding to. One possible 209 implementation is for the client to us a monotonically increasing 210 request sequence number (modulo 2^32). There is, however, no 211 particular requirement the 'request-id' fields be unique. 213 There are two packets, INIT and VERSION, which do not use the 214 request-id. 216 Packet descriptions in this document will contain the 'request-id' 217 field, but will not redefine it. 219 Implementations MUST ignore excess data at the end of an otherwise 220 valid packet. Implementations MUST respond to unrecognized packet 221 types with an SSH_FX_OP_UNSUPPORTED error. This will allow the 222 protocol to be extended in a backwards compatible way as needed. 224 Additionally, when a packet has two or more optional fields, and an 225 implementation wishes to use the i-th optional field, all fields from 226 1 to i MUST be present. In other words, only fields after the last 227 field the implementation wishes to send are actually optional. 229 There is no limit on the number of outstanding (non-acknowledged) 230 requests that the client may send to the server. In practice this is 231 limited by the buffering available on the data stream and the queuing 232 performed by the server. If the server's queues are full, it should 233 not read any more data from the stream, and flow control will prevent 234 the client from sending more requests. Note, however, that while 235 there is no restriction on the protocol level, the client's API may 236 provide a limit in order to prevent infinite queuing of outgoing 237 requests at the client. 239 4.1. Request Synchronization and Reordering 241 The protocol and implementations MUST process requests relating to 242 the same file in the order in which they are received. In other 243 words, if an application submits multiple requests to the server, the 244 results in the responses will be the same as if it had sent the 245 requests one at a time and waited for the response in each case. For 246 example, the server may process non-overlapping read/write requests 247 to the same file in parallel, but overlapping reads and writes cannot 248 be reordered or parallelized. However, there are no ordering 249 restrictions on the server for processing requests from two different 250 file transfer connections. The server may interleave and parallelize 251 them at will. 253 There are no restrictions on the order in which responses to 254 outstanding requests are delivered to the client, except that the 255 server must ensure fairness in the sense that processing of no 256 request will be indefinitely delayed even if the client is sending 257 other requests so that there are multiple outstanding requests all 258 the time. 260 A client MUST be prepared to receive responses to multiple overlapped 261 requests out of order. 263 4.2. New data types defined by this document 265 This document defines these data types in addition to those defined 266 in [RFC4251]. 268 uint16 269 Represents a 16-bit unsigned integer. Stored as 2 bytes in the 270 order of decreasing significance (network byte order). 272 int64 273 Represents a 64-bit signed integer. Stored using two's 274 complement, as eight bytes in the order of decreasing significance 275 (network byte order). 277 extension-pair 279 string extension-name 280 string extension-data 282 'extension-name' is the name of a protocol extension. Extensions 283 not defined by IETF CONSENSUS MUST follow the the DNS 284 extensibility naming convention outlined in [RFC4251]. 286 'extension-data' is any data specific to the extension, and MAY be 287 zero length if the extension has no data. 289 4.3. Packet Types 291 The following values are defined for packet types. 293 SSH_FXP_INIT 1 294 SSH_FXP_VERSION 2 295 SSH_FXP_OPEN 3 296 SSH_FXP_CLOSE 4 297 SSH_FXP_READ 5 298 SSH_FXP_WRITE 6 299 SSH_FXP_LSTAT 7 300 SSH_FXP_FSTAT 8 301 SSH_FXP_SETSTAT 9 302 SSH_FXP_FSETSTAT 10 303 SSH_FXP_OPENDIR 11 304 SSH_FXP_READDIR 12 305 SSH_FXP_REMOVE 13 306 SSH_FXP_MKDIR 14 307 SSH_FXP_RMDIR 15 308 SSH_FXP_REALPATH 16 309 SSH_FXP_STAT 17 310 SSH_FXP_RENAME 18 311 SSH_FXP_READLINK 19 312 SSH_FXP_LINK 21 313 SSH_FXP_BLOCK 22 314 SSH_FXP_UNBLOCK 23 316 SSH_FXP_STATUS 101 317 SSH_FXP_HANDLE 102 318 SSH_FXP_DATA 103 319 SSH_FXP_NAME 104 320 SSH_FXP_ATTRS 105 322 SSH_FXP_EXTENDED 200 323 SSH_FXP_EXTENDED_REPLY 201 325 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 326 implement extensions, which can be vendor specific. See Section 327 ''Extensions'' for more details. 329 Values 210-255 are reserved for use in conjunction with these 330 extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the 331 meaning of these reserved types. It is suggested that the actual 332 value to be used also be negotiated, since this will prevent 333 collision among multiple uncoordinated extensions. 335 The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if 336 it receives a packet it does not recognize. 338 The use of additional packet types in the non-extension range MUST be 339 introduced through IETF consensus. New packet types to be sent from 340 the client to the server MAY be introduced without changing the 341 protocol version (Section 5). Because the client has no way to 342 respond to unrecognized packet types, new packet types to be sent 343 from the server to the client the client MUST not used unless the 344 protocol version is changed or the client has negotiated to received 345 them. This negotiation MAY be explicit, through the use of 346 extensions, or MAY be implicit, by the client itself using a packet 347 type not defined above. 349 5. Protocol Initialization 351 When the file transfer protocol starts, the client first sends a 352 SSH_FXP_INIT (including its version number) packet to the server. 353 The server responds with a SSH_FXP_VERSION packet, supplying the 354 lowest of its own and the client's version number. Both parties 355 should from then on adhere to that particular version of the 356 protocol. 358 The version number of the protocol specified in this document is 6. 359 The version number should be incremented for each incompatible 360 revision of this protocol. 362 Note that these two packets DO NOT contain a request id. These are 363 the only such packets in the protocol. 365 5.1. Client Initialization 367 The SSH_FXP_INIT packet (from client to server) has the following 368 data: 370 uint32 version 372 'version' is the version number of the client. If the client wishes 373 to interoperate with servers that support noncontiguous version 374 numbers it SHOULD send '3', and then use the 'version-select' 375 extension (see below.) Otherwise, this value is '6' for this version 376 of the protocol. 378 5.2. Server Initialization 380 The SSH_FXP_VERSION packet (from server to client) has the following 381 data: 383 uint32 version 384 extension-pair extensions[0..n] 386 'version' is the lower of the protocol version supported by the 387 server and the version number received from the client. 389 'extensions' is 0 or more extension-pairs (Section 4.2). 390 Implementations MUST silently ignore any extensions whose names they 391 do not recognize. 393 5.3. Determining Server Newline Convention 395 In order to correctly process text files in a cross platform 396 compatible way, newline sequences must be converted between client 397 and server conventions. 399 The SSH_FXF_TEXT_MODE file open flag (Section 8.1.1) makes it 400 possible to request that the server translate a file to a 'canonical' 401 wire format. This format uses CRLF as the line separator. 403 Servers for systems using other conventions MUST translate to and 404 from the canonical form. 406 However, to ease the burden of implementation on servers that use a 407 single, simple, separator sequence the following extension allows the 408 canonical format to be changed. 410 string "newline" 411 string new-canonical-separator (usually CR or LF or CRLF) 413 All clients MUST support this extension. 415 When processing text files, clients SHOULD NOT translate any 416 character or sequence that is not an exact match of the server's 417 newline separator. 419 In particular, if the newline sequence being used is the canonical 420 CRLF sequence, a lone CR or a lone LF SHOULD be written through 421 without change. 423 5.4. Supported Features 425 The sftp protocol has grown to be very rich, and now supports a 426 number of features that may not be available on all servers. 428 When a server receives a request for a feature it cannot support, it 429 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 430 specified. The following extension facilitates clients being able to 431 use the maximum available feature set, and yet not be overly burdened 432 by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST 433 include it as part of their version packet. 435 string "supported2" 436 string supported-structure 437 uint32 supported-attribute-mask 438 uint32 supported-attribute-bits 439 uint32 supported-open-flags 440 uint32 supported-access-mask 441 uint32 max-read-size 442 uint16 supported-open-block-vector 443 uint16 supported-block-vector 444 uint32 attrib-extension-count 445 string attrib-extension-names[attrib_extension-count] 446 uint32 extension-count 447 string extension-names[extension-count] 449 Note that the name "supported2" is used here to avoid conflict with 450 the slightly different "supported" extension that was previously 451 used. 452 supported-attribute-mask 453 This mask MAY be applied by the client to the 'File Attributes' 454 valid-attribute-flags field (Section 7.1) in order to ensure that 455 no unsupported attributes are present during a operation which 456 writes attributes. 458 supported-attribute-bits 459 This mask MAY be applied by the client to the 'File Attributes' 460 attrib-bits field (Section 7.9) in order to ensure that no 461 unsupported attrib-bits are present during a operation which 462 writes attribute bits. 464 supported-open-flags 465 The supported-open-flags mask MAY be applied by the client to the 466 SSH_FXP_OPEN (Section 8.1.1) flags field. 468 supported-access-mask 469 This mask may be applied by the client to the ace-mask field of an 470 ACL during a operation that writes the ACL. 472 This mask SHOULD NOT be applied to the desired-access field of the 473 SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result 474 in not requesting the access required by the client. In the case 475 of open operations, the server is responsible for translating the 476 client's requested access to a mode it supports that is sufficient 477 to grant all access requested by the client. 479 max-read-size 480 This is the maximum read size that the server guarantees to 481 complete. For example, certain embedded server implementations 482 complete only the first 4K of a read, even if there is additional 483 data to be read from the file. 485 If the server specifies a non-zero value for max-read-size, it 486 MUST return the requested number of bytes for reads that are less 487 than or equal to the value, unless it encounters EOF or an ERROR. 489 The server MAY use this value to express that it is willing to 490 handle very large read requests, in excess of the standard 34000 491 bytes specified in Section 4. 493 supported-open-block-vector 494 supported-block-vector 495 16-bit masks specifying which combinations of blocking flags are 496 supported. Each bit corresponds to one combination of the 497 SSH_FXF_BLOCK_READ, SSH_FXF_BLOCK_WRITE, SSH_FXF_BLOCK_DELETE, and 498 SSH_FXF_BLOCK_ADVISORY bits from Section 8.1.1.3, with a set bit 499 corresponding to a supported combination and a clear bit an 500 unsupported combination. The index of a bit, bit zero being the 501 least significant bit, viewed as a four-bit number, corresponds to 502 a combination of flag bits, shifted right so that BLOCK_READ is 503 the least significant bit. The combination `no blocking flags' 504 MUST be supported, so the low bit will always be set. 506 For example, a server supporting only the classic advisory read 507 (shared) and write (exclusive) locks would set the bits 508 corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, 509 0b1010, plus the always-set bit 0b0000, giving a mask value of 510 0b0000110000000001, or 0x0c01; a server supporting no locking at 511 all would set only bit zero, giving 0x0001. 513 'supported-open-block-masks' applies to the SSH_FXP_OPEN 514 (Section 8.1.1) flags field. 'supported-block-masks' applies to 515 the SSH_FXF_BLOCK request. 517 attrib-extension-count 518 Count of extension names in the attrib-extension-names array. 520 attrib-extension-names 521 Names of extensions that can be used in an ATTRS (Section 7.14) 522 structure. 524 extension-count 525 Count of extension names in the extension-names array. 527 extension-names 528 Names of extensions that can be used with the SSH_FXP_EXTEND 529 (Section 10) packet. 531 Naturally, if a given attribute field, attribute mask bit, open flag, 532 or extension is required for correct operation, the client MUST 533 either not mask the bit off, or MUST fail the operation gracefully 534 without sending the request to the server. 536 The client MAY send requests that are not supported by the server; 537 however, it is not normally expected to be productive to do so. The 538 client SHOULD apply the mask even to attrib structures received from 539 the server. The server MAY include attributes or attrib-bits that 540 are not included in the mask. Such attributes or attrib-bits are 541 effectively read-only. 543 The supported capabilities of the acl attribute are sent using the 544 following extension. 546 string "acl-supported" 547 string supported-structure 548 uint32 capabilities 550 'capabilities' is a combination of the following bits: 552 SSH_ACL_CAP_ALLOW 0x00000001 553 SSH_ACL_CAP_DENY 0x00000002 554 SSH_ACL_CAP_AUDIT 0x00000004 555 SSH_ACL_CAP_ALARM 0x00000008 556 SSH_ACL_CAP_INHERIT_ACCESS 0x00000010 557 SSH_ACL_CAP_INHERIT_AUDIT_ALARM 0x00000020 559 SSH_ACL_CAP_ALLOW 560 SSH_ACL_CAP_DENY 561 SSH_ACL_CAP_AUDIT 562 SSH_ACL_CAP_ALARM 563 The server supports the associated ACL ACE type. 565 SSH_ACL_CAP_INHERIT_ACCESS 566 The server can control whether a ACL will inherit DENY and ALLOW 567 ACEs that are marked inheritable from it's parent object. 569 SSH_ACL_CAP_INHERIT_AUDIT_ALARM 570 The server can control whether a ACL will inherit AUDIT or ALARM 571 ACEs that are marked inheritable from it's parent object. 573 5.5. Version re-negotiation 575 If the server supports other versions than what was negotiated, it 576 may wish to send the 'versions' extension to inform the client of 577 this fact. The client may then optionally choose to use one of the 578 other versions supported. 580 string "versions" 581 string comma-separated-versions 583 'comma-separated-versions' is a string of comma separated version 584 numbers. Defined versions are: "2", "3", "4", "5", "6". Any other 585 version advertised by the server must follow the DNS extensibility 586 naming convention outlined in [RFC4251]. 588 For example: "2,3,6,private@example.com". 590 If the client and server have negotiated a a version greater than or 591 equal to version '3' (the version at which SSH_FXP_EXTENDED was 592 introduced) in the initial VERSION/INIT exchange, the client may 593 select a new version to use from the list the server provided using 594 the following SSH_FXP_EXTENDED request. 596 string "version-select" 597 string version-from-list 599 If the 'version-from-list' is one of the versions on the servers 600 list, the server MUST respond with SSH_FX_OK. If the server did not 601 send the "versions" extension, or the version-from-list was not 602 included, the server MAY send a status response describing the 603 failure, but MUST then close the channel without processing any 604 further requests. 606 The 'version-select' MUST be the first request from the client to the 607 server; if it is not, the server MUST fail the request and close the 608 channel. 610 Although this request does take a full round trip, no client need 611 wait for the response before continuing, because any valid request 612 MUST succeed, and any invalid request results in a channel close. 613 Since the request is the first request, it is not possible for the 614 server to have already sent responses conforming to the old version. 616 Typically, the client SHOULD NOT down-grade the protocol version 617 using this extension; however, it is not forbidden to do so. One 618 reason a client might do so is to work around a buggy implementation. 620 6. File Names 622 This protocol represents file names as strings. File names are 623 assumed to use the slash ('/') character as a directory separator. 625 File names starting with a slash are "absolute", and are relative to 626 the root of the file system. Names starting with any other character 627 are relative to the user's default directory (home directory). Note 628 that identifying the user is assumed to take place outside of this 629 protocol. 631 Servers SHOULD interpret a path name component ".." (Section 13) as 632 referring to the parent directory, and "." as referring to the 633 current directory. 635 An empty path name is valid, and it refers to the user's default 636 directory (usually the user's home directory). 638 Otherwise, no syntax is defined for file names by this specification. 639 Clients should not make any other assumptions; however, they can 640 splice path name components returned by SSH_FXP_READDIR together 641 using a slash ('/') as the separator, and that will work as expected. 643 It is understood that the lack of well-defined semantics for file 644 names may cause interoperability problems between clients and servers 645 using radically different operating systems. However, this approach 646 is known to work acceptably with most systems, and alternative 647 approaches that e.g. treat file names as sequences of structured 648 components are quite complicated. 650 The preferred encoding for filenames is UTF-8. This is consistent 651 with IETF Policy on Character Sets and Languages [RFC2277] and it is 652 further supposed that the server is more likely to support any local 653 character set and be able to convert it to UTF-8. 655 However, because the server does not always know the encoding of 656 filenames, it is not always possible for the server to preform a 657 valid translation to UTF-8. When an invalid translation to UTF-8 is 658 preformed, it becomes impossible to manipulate the file, because the 659 translation is not reversible. Therefore, the following extensions 660 are provided in order to make it possible for the server to 661 communicate it's abilities to the client, and to allow the client to 662 control whether the server attempts the conversion. 664 A server MAY include the following extension with it's version 665 packet. 667 string "filename-charset" 668 string charset-name 670 A server that can always provide a valid UTF-8 translation for 671 filenames SHOULD NOT send this extension. Otherwise, the server 672 SHOULD send this extension and include the encoding most likely to be 673 used for filenames. This value will most likely be derived from the 674 LC_CTYPE on most unix-like systems. 676 A server that does not send this extension MUST send all filenames 677 encoded in UTF-8. All clients MUST support UTF-8 filenames. 679 If the server included the 'filename-charset' extension with its 680 VERSION packet, a client MAY send the following extension to turn off 681 server translation to UTF-8. 683 string "filename-translation-control" 684 bool do-translate 686 If the client does not send this extension, the server MUST continue 687 to attempt translation to UTF-8. When a client sends this extension, 688 the server MUST enable filename translation if 'do-translate' is 689 true, or disable filename translation if it is false. 691 The server MUST respond with a STATUS response; if the server sent a 692 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, 693 the status MUST be SSH_FX_OP_UNSUPPORTED. 695 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE 696 data MUST be used. The server is responsible for converting the 697 UNICODE data to whatever canonical form it requires. For example, if 698 the server requires that precomposed characters always be used, the 699 server MUST NOT assume the filename as sent by the client has this 700 attribute, but must do this normalization itself. 702 7. File Attributes 704 A new compound data type, 'ATTRS', is defined for encoding file 705 attributes. The same encoding is used both when returning file 706 attributes from the server and when sending file attributes to the 707 server. 709 uint32 valid-attribute-flags 710 byte type always present 711 uint64 size if flag SIZE 712 uint64 allocation-size if flag ALLOCATION_SIZE 713 string owner if flag OWNERGROUP 714 string group if flag OWNERGROUP 715 uint32 permissions if flag PERMISSIONS 716 int64 atime if flag ACCESSTIME 717 uint32 atime-nseconds if flag SUBSECOND_TIMES 718 int64 createtime if flag CREATETIME 719 uint32 createtime-nseconds if flag SUBSECOND_TIMES 720 int64 mtime if flag MODIFYTIME 721 uint32 mtime-nseconds if flag SUBSECOND_TIMES 722 int64 ctime if flag CTIME 723 uint32 ctime-nseconds if flag SUBSECOND_TIMES 724 string acl if flag ACL 725 uint32 attrib-bits if flag BITS 726 uint32 attrib-bits-valid if flag BITS 727 byte text-hint if flag TEXT_HINT 728 string mime-type if flag MIME_TYPE 729 uint32 link-count if flag LINK_COUNT 730 string untranslated-name if flag UNTRANSLATED_NAME 731 uint32 extended-count if flag EXTENDED 732 extension-pair extensions 734 7.1. valid-attribute-flags 736 The 'valid-attribute-flags' specifies which of the fields are 737 present. Those fields for which the corresponding flag is not set 738 are not present (not included in the packet). 740 The server generally includes all attributes it knows about; however, 741 it may exclude attributes that are overly expensive to retrieve 742 unless the client explicitly requests them. 744 When writing attributes, the server SHOULD NOT modify attributes that 745 are not present in the structure. However, if necessary, the server 746 MAY use a default value for an absent attribute. 748 In general, unless otherwise specified, if a server cannot support 749 writing an attribute requested, it must fail the setstat operation. 750 In this case, none of the attributes SHOULD be changed. 752 New fields can be added only by incrementing the protocol version 753 number (or by using the extension mechanism described below). 755 The following values are defined: 757 SSH_FILEXFER_ATTR_SIZE 0x00000001 758 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 759 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 760 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 761 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 762 SSH_FILEXFER_ATTR_ACL 0x00000040 763 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 764 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 765 SSH_FILEXFER_ATTR_BITS 0x00000200 766 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 767 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 768 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 769 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 770 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 771 SSH_FILEXFER_ATTR_CTIME 0x00008000 772 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 774 0x00000002 was used in a previous version of this protocol. It is 775 now a reserved value and MUST NOT appear in the mask. Some future 776 version of this protocol may reuse this value. 778 7.2. Type 780 The type field is always present. The following types are defined: 782 SSH_FILEXFER_TYPE_REGULAR 1 783 SSH_FILEXFER_TYPE_DIRECTORY 2 784 SSH_FILEXFER_TYPE_SYMLINK 3 785 SSH_FILEXFER_TYPE_SPECIAL 4 786 SSH_FILEXFER_TYPE_UNKNOWN 5 787 SSH_FILEXFER_TYPE_SOCKET 6 788 SSH_FILEXFER_TYPE_CHAR_DEVICE 7 789 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 790 SSH_FILEXFER_TYPE_FIFO 9 792 On a POSIX system, these values would be derived from the mode field 793 of the stat structure. SPECIAL should be used for files that are of 794 a known type which cannot be expressed in the protocol. UNKNOWN 795 should be used if the type is not known. 797 7.3. Size 799 The 'size' field specifies the number of bytes that can be read from 800 the file, or in other words, the location of the end-of-file. 802 If this field is present during file creation, it indicates the 803 number of bytes the client intends to transfer, but SHOULD NOT affect 804 the creation of the file. If the file is a text-file, then the bytes 805 are 'as encoded on the wire.' The server can use this information to 806 determine if the client sent all the intended data and the file was 807 transfered in its entirity. 809 If this field is present during a setstat operation, the file MUST be 810 extended or truncated to the specified size. If the file is 811 extended, the semantics are to write the byte value 0x00 from the 812 previous end of file to the new offset. 814 Files opened with the SSH_FXF_TEXT flag may have a size that is 815 greater or less than the value of the size field. The server MAY 816 fail setstat operations specifying size for files opened with the 817 SSH_FXF_TEXT flag. 819 7.4. allocation-size 821 The 'allocation-size' field specifies the number of bytes that the 822 file consumes on disk. This field MAY be less than the 'size' field 823 if the file is 'sparse' (Section 7.9). It will usually be larger 824 than the 'size' field, however, as most file-systems allocate space 825 to files in units that are larger than a single byte. 827 When present during file creation, the file SHOULD be created and the 828 specified number of bytes preallocated. If the preallocation fails, 829 the file should be removed (if it was created) and an error returned. 831 If this field is present during a setstat operation, the file 832 allocation SHOULD be changed to the specified size. If the 833 allocation size is increased, additional space is allocated to the 834 file, but the 'size' is not changed (the end-of-file marker is not 835 move.) If the new allocation size is smaller, than the operation is 836 effectively a truncation. 838 Querying the 'allocation-size' after setting it MUST return a value 839 that is greater-than or equal to the value set, but it MAY not return 840 the precise value set. 842 If both 'size' and 'allocation-size' are set during a setstat 843 operation, and 'allocation-size' is less than 'size', the server MUST 844 return SSH_FX_INVALID_PARAMETER. 846 7.5. Owner and Group 848 The 'owner' and 'group' fields are represented as UTF-8 strings; this 849 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. 850 The following text is selected quotations from section 5.6. 852 To avoid a representation that is tied to a particular underlying 853 implementation at the client or server, the use of UTF-8 strings has 854 been chosen. The string should be of the form "user@dns_domain". 855 This will allow for a client and server that do not use the same 856 local representation the ability to translate to a common syntax that 857 can be interpreted by both. In the case where there is no 858 translation available to the client or server, the attribute value 859 must be constructed without the "@". Therefore, the absence of the @ 860 from the owner or owner_group attribute signifies that no translation 861 was available and the receiver of the attribute should not place any 862 special meaning on the attribute value. Even though the attribute 863 value cannot be translated, it may still be useful. In the case of a 864 client, the attribute string may be used for local display of 865 ownership. 867 user@localhost represents a user in the context of the server. 869 If either the owner or group field is zero length, the field should 870 be considered absent, and no change should be made to that specific 871 field during a modification operation. 873 7.6. Permissions 875 The 'permissions' field contains a bit mask specifying file 876 permissions. These permissions correspond to the st_mode field of 877 the stat structure defined by POSIX [IEEE.1003-1.1996]. 879 This protocol uses the following values for the symbols declared in 880 the POSIX standard. 882 S_IRUSR 0000400 (octal) 883 S_IWUSR 0000200 884 S_IXUSR 0000100 885 S_IRGRP 0000040 886 S_IWGRP 0000020 887 S_IXGRP 0000010 888 S_IROTH 0000004 889 S_IWOTH 0000002 890 S_IXOTH 0000001 891 S_ISUID 0004000 892 S_ISGID 0002000 893 S_ISVTX 0001000 895 Implementations MUST NOT send bits that are not defined. 897 The server SHOULD NOT apply a 'umask' to the mode bits; but should 898 set the mode bits as specified by the client. The client MUST apply 899 an appropriate 'umask' to the mode bits before sending them. 901 7.7. Times 903 The 'atime' field contains the last access time of the file. Many 904 operating systems either don't have this field, only optionally 905 maintain it, or maintain it with less resolution than other fields. 907 The 'mtime' contains the last time the file was written. 909 'createtime' contains the creation time of the file. 911 'ctime' contains the last time the file attributes were changed. The 912 exact meaning of this field depends on the server. 914 All times are represented as seconds from Jan 1, 1970 in UTC. A 915 negative value indicates number of seconds before Jan 1, 1970. In 916 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 917 nseconds field is to be added to the seconds field for the final time 918 representation. For example, if the time to be represented is one- 919 half second before 0 hour January 1, 1970, the seconds field would 920 have a value of negative one (-1) and the nseconds fields would have 921 a value of one-half second (500000000). Values greater than 922 999,999,999 for nseconds are considered invalid. 924 7.8. ACL 926 The 'ACL' field contains an ACL similar to that defined in section 927 5.9 of NFS version 4 Protocol [RFC3010]. 929 The structure of the ACL is: 931 uint32 acl-flags 932 uint32 ace-count 933 ACE ace[ace-count] 935 The ACE data structure is composes as follows: 937 uint32 ace-type 938 uint32 ace-flag 939 uint32 ace-mask 940 string who [UTF-8] 942 acl-flags 944 SFX_ACL_CONTROL_INCLUDED 0x00000001 945 SFX_ACL_CONTROL_PRESENT 0x00000002 946 SFX_ACL_CONTROL_INHERITED 0x00000004 947 SFX_ACL_AUDIT_ALARM_INCLUDED 0x00000010 948 SFX_ACL_AUDIT_ALARM_INHERITED 0x00000020 950 SFX_ACL_CONTROL_INCLUDED 951 SFX_ACL_CONTROL_PRESENT 952 SFX_ACL_CONTROL_INHERITED 953 If INCLUDED is set during a setstat operation, then the client 954 intends to modify the ALLOWED/DENIED entries of the ACL. 955 Otherwise, the client intends for these entries to be 956 preserved. 958 If the PRESENT bit is not set, then the client wishes to remove 959 control entries. If the server doesn't support separate 960 control and audit information, the client MUST not clear this 961 bit without also clearing the AUDIT_ALARM_PRESENT bit. 963 If the PRESENT bit is clear, then control of the file MAY be 964 through the permissions mask. The server MAY also grant full 965 access to the file. 967 If the both the INCLUDE and the PRESENT bit are set, but their 968 are no ALLOW/DENY entries in the list, the client wishes to 969 deny all access to the file or directory. The server may have 970 to transform this into a ACL with a deny entry to implement it. 972 If INHERITED is set, then ALLOW/DENY ACEs MAY be inherited from 973 the parent directory. If it is off, then they MUST not be 974 INHERITED. If the server does not support controlling 975 inheritance, then the client MUST clear this bit; in this case 976 the inheritance properties of the server are undefined. 978 SFX_ACL_AUDIT_ALARM_INCLUDED 979 SFX_ACL_AUDIT_ALARM_INHERITED 980 If INCLUDE is set during a setstat operation, then the client 981 intends to modify the AUDIT/ALARM entries of the ACL. 982 Otherwise, the client intends for these entries to be 983 preserved. 985 If INHERITED is set, then AUDIT/ALARM ACEs MAY be inherited 986 from the parent directory. If it is off, then they MUST not be 987 INHERITED. If the server does not support controlling 988 inheritance, then the client MUST clear this bit; in this case 989 the inheritance properties of the server are undefined. 991 Because some server require special permissions / privileges in 992 order to modify the AUDIT/ALARM entries in the ACL, it is 993 important to communicate to the server the clients intent to 994 modify these entries. The client MUST both use the 995 ACCESS_AUDIT_ALARM_ATTRIBUTES bit in the desired attribute of the 996 open request and must set the SFX_ACL_AUDIT_ALARM_INCLUDED during 997 the setstat operation. 999 Clients that do not intend specifically to modify the AUDIT or 1000 ALARM entries SHOULD NOT set SSH_FXF_ACCESS_AUDIT_ALARM_INFO in 1001 the open-flags and SHOULD NOT set the SFX_ACL_AUDIT_ALARM_INCLUDED 1002 bit because these operations are often privileged and will fail. 1004 If the SFX_ACL_AUDIT_ALARM_INCLUDED is set, and the requested 1005 change can not be made, the server MUST fail the request. 1007 Servers that do not seperate control and audit/alarm information 1008 may have to read the existing ACL and merge in enteries not 1009 included by the client. The server must take this into account 1010 when opening files with the ACE4_WRITE_ACL permission requested. 1012 ace-type 1013 one of the following four values (taken from NFS Version 4 1014 Protocol [RFC3010]: 1016 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 1017 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 1018 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 1019 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 1021 ace-flag 1022 A combination of the following flag values. See NFS Version 4 1023 Protocol [RFC3010] section 5.9.2: 1025 ACE4_FILE_INHERIT_ACE 0x00000001 1026 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 1027 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 1028 ACE4_INHERIT_ONLY_ACE 0x00000008 1029 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 1030 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 1031 ACE4_IDENTIFIER_GROUP 0x00000040 1033 ace-mask 1034 Combination of the following flags (taken from [RFC3010], section 1035 5.9.3. The semantic meaning of these flags is also given in 1036 [RFC3010]. 1038 ACE4_READ_DATA 0x00000001 1039 ACE4_LIST_DIRECTORY 0x00000001 1040 ACE4_WRITE_DATA 0x00000002 1041 ACE4_ADD_FILE 0x00000002 1042 ACE4_APPEND_DATA 0x00000004 1043 ACE4_ADD_SUBDIRECTORY 0x00000004 1044 ACE4_READ_NAMED_ATTRS 0x00000008 1045 ACE4_WRITE_NAMED_ATTRS 0x00000010 1046 ACE4_EXECUTE 0x00000020 1047 ACE4_DELETE_CHILD 0x00000040 1048 ACE4_READ_ATTRIBUTES 0x00000080 1049 ACE4_WRITE_ATTRIBUTES 0x00000100 1050 ACE4_DELETE 0x00010000 1051 ACE4_READ_ACL 0x00020000 1052 ACE4_WRITE_ACL 0x00040000 1053 ACE4_WRITE_OWNER 0x00080000 1054 ACE4_SYNCHRONIZE 0x00100000 1056 who 1057 UTF-8 string of the form described in 'Owner and Group' 1058 (Section 7.5) 1059 Also, as per '5.9.4 ACE who' [RFC3010] there are several 1060 identifiers that need to be understood universally. Some of these 1061 identifiers cannot be understood when an client access the server, 1062 but have meaning when a local process accesses the file. The 1063 ability to display and modify these permissions is permitted over 1064 SFTP. 1066 OWNER The owner of the file. 1067 GROUP The group associated with the file. 1068 EVERYONE The world. 1069 INTERACTIVE Accessed from an interactive terminal. 1070 NETWORK Accessed via the network. 1071 DIALUP Accessed as a dialup user to the server. 1072 BATCH Accessed from a batch job. 1073 ANONYMOUS Accessed without any authentication. 1074 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 1075 SERVICE Access from a system service. 1076 To avoid conflict, these special identifiers are distinguish by an 1077 appended "@". For example: ANONYMOUS@. 1079 7.9. attrib-bits and attrib-bits-valid 1081 These fields, taken together, reflect various attributes of the file 1082 or directory, on the server. 1084 Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- 1085 bits' field. This allows both the server and the client to 1086 communicate only the bits they knows about without inadvertently 1087 twiddling bits they don't understand. 1089 The following attrib-bits are defined: 1091 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 1092 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 1093 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 1094 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 1095 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 1096 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 1097 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 1098 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 1099 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 1100 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 1101 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 1102 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 1104 SSH_FILEXFER_ATTR_FLAGS_READONLY 1105 Advisory, read-only bit. This bit is not part of the access 1106 control information on the file, but is rather an advisory field 1107 indicating that the file should not be written. 1109 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 1110 The file is part of the operating system. 1112 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 1113 File SHOULD NOT be shown to user unless specifically requested. 1114 For example, most UNIX systems SHOULD set this bit if the filename 1115 begins with a 'period'. This bit may be read-only (Section 5.4). 1116 Most UNIX systems will not allow this to be changed. 1118 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 1119 This attribute applies only to directories. This attribute is 1120 always read-only, and cannot be modified. This attribute means 1121 that files and directory names in this directory should be 1122 compared without regard to case. 1124 It is recommended that where possible, the server's filesystem be 1125 allowed to do comparisons. For example, if a client wished to 1126 prompt a user before overwriting a file, it should not compare the 1127 new name with the previously retrieved list of names in the 1128 directory. Rather, it should first try to create the new file by 1129 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 1130 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 1131 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 1133 Unless otherwise specified, filenames are assumed to be case 1134 sensitive. 1136 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 1137 The file should be included in backup / archive operations. 1139 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 1140 The file is stored on disk using file-system level transparent 1141 encryption. This flag does not affect the file data on the wire 1142 (for either READ or WRITE requests.) 1144 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 1145 The file is stored on disk using file-system level transparent 1146 compression. This flag does not affect the file data on the wire. 1148 SSH_FILEXFER_ATTR_FLAGS_SPARSE 1149 The file is a sparse file; this means that file blocks that have 1150 not been explicitly written are not stored on disk. For example, 1151 if a client writes a buffer at 10 M from the beginning of the 1152 file, the blocks between the previous EOF marker and the 10 M 1153 offset would not consume physical disk space. 1155 Some servers may store all files as sparse files, in which case 1156 this bit will be unconditionally set. Other servers may not have 1157 a mechanism for determining if the file is sparse, and so the file 1158 MAY be stored sparse even if this flag is not set. 1160 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 1161 Opening the file without either the SSH_FXF_APPEND_DATA or the 1162 SSH_FXF_APPEND_DATA_ATOMIC flag (Section 8.1.1.3) MUST result in 1163 an SSH_FX_INVALID_PARAMETER error. 1165 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 1166 The file cannot be deleted or renamed, no hard link can be created 1167 to this file, and no data can be written to the file. 1169 This bit implies a stronger level of protection than 1170 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 1171 ACLs. Typically even the superuser cannot write to immutable 1172 files, and only the superuser can set or remove the bit. 1174 SSH_FILEXFER_ATTR_FLAGS_SYNC 1175 When the file is modified, the changes are written synchronously 1176 to the disk. 1178 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 1179 The server MAY include this bit in a directory listing or realpath 1180 response. It indicates there was a failure in the translation to 1181 UTF-8. If this flag is included, the server SHOULD also include 1182 the UNTRANSLATED_NAME attribute. 1184 7.10. text-hint 1186 The value is one of the following enumerations, and indicates what 1187 the server knows about the content of the file. 1189 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 1190 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 1191 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 1192 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 1194 SSH_FILEXFER_ATTR_KNOWN_TEXT 1195 The server knows the file is a text file, and should be opened 1196 using the SSH_FXF_TEXT_MODE flag. 1198 SSH_FILEXFER_ATTR_GUESSED_TEXT 1199 The server has applied a heuristic or other mechanism and believes 1200 that the file should be opened with the SSH_FXF_TEXT_MODE flag. 1202 SSH_FILEXFER_ATTR_KNOWN_BINARY 1203 The server knows the file has binary content. 1205 SSH_FILEXFER_ATTR_GUESSED_BINARY 1206 The server has applied a heuristic or other mechanism and believes 1207 has binary content, and should not be opened with the 1208 SSH_FXF_TEXT_MODE flag. 1210 This flag MUST NOT be present during either a setstat or a fsetstat 1211 operation. 1213 7.11. mime-type 1215 The 'mime-type' field contains the mime-type [RFC1521] string. Most 1216 servers will not know this information and should not set the bit in 1217 their supported-attribute-mask. 1219 7.12. link-count 1221 This field contains the hard link count of the file. This attribute 1222 MUST NOT be present during a setstat operation. 1224 7.13. untranslated-name 1226 This field contains the name before filename translation was attempt. 1227 It MUST NOT be included unless the server also set the 1228 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 7.9) bit in the 1229 attrib-bits field. 1231 7.14. Extended Attributes 1233 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 1234 mechanism for the attrib structure. If the flag is specified, then 1235 the 'extended_count' field is present. It specifies the number of 1236 'extension-pair' items that follow. Each of these items specifies an 1237 extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED 1238 if there are any unrecognized extensions. Clients can avoid sending 1239 unsupported extensions by examining the attrib-extension-names of the 1240 "supported2" extension attrib-extension-names (Section 5.4). 1242 Additional fields can be added to the attributes by either defining 1243 additional bits to the flags field to indicate their presence, or by 1244 defining extended attributes for them. The extended attributes 1245 mechanism is recommended for most purposes; additional flags bits 1246 should be defined only by an IETF standards action that also 1247 increments the protocol version number. The use of such new fields 1248 MUST be negotiated by the version number in the protocol exchange. 1249 It is a protocol error if a packet with unsupported protocol bits is 1250 received. 1252 8. Requests From the Client to the Server 1254 Requests from the client to the server represent the various file 1255 system operations. 1257 8.1. Opening and Closing Files and Directories 1259 Many operations in the protocol operate on open files. The 1260 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 1261 an opaque variable-length string) which may be used to access the 1262 file or directory later. The client MUST NOT send requests to the 1263 server with bogus or closed handles. However, the server MUST 1264 perform adequate checks on the handle in order to avoid security 1265 risks due to fabricated handles. 1267 This design allows either stateful and stateless server 1268 implementation, as well as an implementation which caches state 1269 between requests but may also flush it. The contents of the file 1270 handle string are entirely up to the server and its design. The 1271 client should not modify or attempt to interpret the file handle 1272 strings. 1274 The file handle strings MUST NOT be longer than 256 bytes. 1276 8.1.1. Opening a File 1278 Files are opened and created using the SSH_FXP_OPEN message. 1280 byte SSH_FXP_OPEN 1281 uint32 request-id 1282 string filename [UTF-8] 1283 uint32 desired-access 1284 uint32 flags 1285 ATTRS attrs 1287 The response to this message will be either SSH_FXP_HANDLE (if the 1288 operation is successful) or SSH_FXP_STATUS (if the operation fails.) 1290 8.1.1.1. filename 1292 The 'filename' field specifies the file name. See Section ''File 1293 Names'' for more information. If 'filename' is a directory file, the 1294 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 1296 8.1.1.2. desired-access 1298 The 'desired-access' field is a bitmask containing a combination of 1299 values from the ace-mask flags (Section 7.8). Note that again, the 1300 meaning of these flags is given in [RFC3010]. 1302 The server MUST be prepared to translate the SFTP access flags into 1303 its local equivalents. If the server cannot grant the access 1304 desired, it MUST return SSH_FX_PERMISSION_DENIED. 1306 The server MAY open the file with greater access than requested if 1307 the user has such access and the server implementation requires it. 1308 For example, a server that does not distinguish between 1309 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access 1310 to the file when the client only requested READ_ATTRIBUTE, resulting 1311 in greater access than the client originally requested. 1313 In such cases, it is possible, and permissible in the protocol, that 1314 the client could open a file requesting some limited access, and then 1315 access the file in a way not permitted by that limited access and the 1316 server would permit such action. However, the server MUST NOT ever 1317 grant access to the file that the client does not actually have the 1318 rights to. 1320 8.1.1.3. flags 1322 The 'flags' field controls various aspects of the operation, 1323 including whether or not the file is created and the kind of locking 1324 desired. 1326 The following 'flags' are defined: 1328 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 1329 SSH_FXF_CREATE_NEW = 0x00000000 1330 SSH_FXF_CREATE_TRUNCATE = 0x00000001 1331 SSH_FXF_OPEN_EXISTING = 0x00000002 1332 SSH_FXF_OPEN_OR_CREATE = 0x00000003 1333 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 1334 SSH_FXF_APPEND_DATA = 0x00000008 1335 SSH_FXF_APPEND_DATA_ATOMIC = 0x00000010 1336 SSH_FXF_TEXT_MODE = 0x00000020 1337 SSH_FXF_BLOCK_READ = 0x00000040 1338 SSH_FXF_BLOCK_WRITE = 0x00000080 1339 SSH_FXF_BLOCK_DELETE = 0x00000100 1340 SSH_FXF_BLOCK_ADVISORY = 0x00000200 1341 SSH_FXF_NOFOLLOW = 0x00000400 1342 SSH_FXF_DELETE_ON_CLOSE = 0x00000800 1343 SSH_FXF_ACCESS_AUDIT_ALARM_INFO = 0x00001000 1344 SSH_FXF_ACCESS_BACKUP = 0x00002000 1345 SSH_FXF_BACKUP_STREAM = 0x00004000 1346 SSH_FXF_OVERRIDE_OWNER = 0x00008000 1348 SSH_FXF_ACCESS_DISPOSITION 1349 Disposition is a 3 bit field that controls how the file is opened. 1350 The server MUST support these bits. Any one of the following 1351 enumeration is allowed: 1353 SSH_FXF_CREATE_NEW 1354 A new file is created; if the file already exists, the server 1355 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 1357 SSH_FXF_CREATE_TRUNCATE 1358 A new file is created; if the file already exists, it is opened 1359 and truncated. 1361 SSH_FXF_OPEN_EXISTING 1362 An existing file is opened. If the file does not exist, the 1363 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 1364 path does not exist, the server SHOULD return 1365 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 1366 returns SSH_FX_NO_SUCH_FILE in this case. 1368 SSH_FXF_OPEN_OR_CREATE 1369 If the file exists, it is opened. If the file does not exist, 1370 it is created. 1372 SSH_FXF_TRUNCATE_EXISTING 1373 An existing file is opened and truncated. If the file does not 1374 exist, the server MUST return the same error codes as defined 1375 for SSH_FXF_OPEN_EXISTING. 1377 SSH_FXF_APPEND_DATA 1378 Data is always written at the end of the file. The offset field 1379 of SSH_FXP_WRITE requests is ignored. 1381 Data is not required to be appended atomically. This means that 1382 if multiple writers attempt to append data simultaneously, data 1383 from the first may be lost. However, data MAY be appended 1384 atomically. 1386 SSH_FXF_APPEND_DATA_ATOMIC 1387 Data is always written at the end of the file. The offset field 1388 of the SSH_FXP_WRITE requests are ignored. 1390 Data MUST be written atomically so that there is no chance that 1391 multiple appenders can collide and result in data being lost. 1393 If both append flags are specified, the server SHOULD use atomic 1394 append if it is available, but SHOULD use non-atomic appends 1395 otherwise. The server SHOULD NOT fail the request in this case. 1397 SSH_FXF_TEXT_MODE 1398 Indicates that the server should treat the file as text and 1399 convert it to the canonical newline convention in use. (See 1400 Determining Server Newline Convention. (Section 5.3) 1402 When a file is opened with this flag, the offset field in the read 1403 and write functions is ignored. 1405 Servers MUST process multiple, parallel reads and writes correctly 1406 in this mode. Naturally, it is permissible for them to do this by 1407 serializing the requests. 1409 Clients SHOULD use the SSH_FXF_APPEND_DATA flag to append data to 1410 a text file rather then using write with a calculated offset. 1412 To support seeks on text files the following SSH_FXP_EXTENDED 1413 packet is defined. 1415 string "text-seek" 1416 string file-handle 1417 uint64 line-number 1419 line-number is the index of the line number to seek to, where byte 1420 0 in the file is line number 0, and the byte directly following 1421 the first newline sequence in the file is line number 1 and so on. 1423 The response to a "text-seek" request is an SSH_FXP_STATUS 1424 message. 1426 An attempt to seek past the end-of-file should result in a 1427 SSH_FX_EOF status. 1429 Servers SHOULD support at least one "text-seek" in order to 1430 support resume. However, a client MUST be prepared to receive 1431 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 1432 The client can then try a fall-back strategy, if it has one. 1434 SSH_FXF_BLOCK_READ 1435 The server MUST guarantee that no other handle has been opened 1436 with ACE4_READ_DATA access, and that no other handle will be 1437 opened with ACE4_READ_DATA access until the client closes the 1438 handle. (This MUST apply both to other clients and to other 1439 processes on the server.) 1441 If there is a conflicting lock the server MUST return 1442 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1443 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1445 Other handles MAY be opened for ACE4_WRITE_DATA or any other 1446 combination of accesses, as long as ACE4_READ_DATA is not included 1447 in the mask. 1449 SSH_FXF_BLOCK_WRITE 1450 The server MUST guarantee that no other handle has been opened 1451 with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other 1452 handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA 1453 access until the client closes the handle. (This MUST apply both 1454 to other clients and to other processes on the server.) 1455 If there is a conflicting lock the server MUST return 1456 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1457 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1459 Other handles MAY be opened for ACE4_READ_DATA or any other 1460 combination of accesses, as long as neither ACE4_WRITE_DATA nor 1461 ACE4_APPEND_DATA are included in the mask. 1463 SSH_FXF_BLOCK_DELETE 1464 The server MUST guarantee that no other handle has been opened 1465 with ACE4_DELETE access, opened with the SSH_FXF_DELETE_ON_CLOSE 1466 flag set, and that no other handle will be opened with ACE4_DELETE 1467 access or with the SSH_FXF_DELETE_ON_CLOSE flag set, and that the 1468 file itself is not deleted in any other way until the client 1469 closes the handle. 1471 If there is a conflicting lock the server MUST return 1472 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1473 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1475 SSH_FXF_BLOCK_ADVISORY 1476 If this bit is set, the above BLOCK modes are advisory. In 1477 advisory mode, only other accesses that specify a BLOCK mode need 1478 be considered when determining whether the BLOCK can be granted, 1479 and the server need not prevent I/O operations that violate the 1480 block mode. 1482 The server MAY perform mandatory locking even if the 1483 BLOCK_ADVISORY bit is set. 1485 SSH_FXF_NOFOLLOW 1486 If the final component of the path is a symlink, then the open 1487 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 1489 SSH_FXF_DELETE_ON_CLOSE 1490 The file should be deleted when the last handle to it is closed. 1491 (The last handle may not be an sftp-handle.) This MAY be emulated 1492 by a server if the OS doesn't support it by deleting the file when 1493 this handle is closed. 1495 It is implementation specific whether the directory entry is 1496 removed immediately or when the handle is closed. 1498 SSH_FXF_ACCESS_AUDIT_ALARM_INFO 1499 The client wishes the server to enable any privileges or extra 1500 capabilities that the user may have in to allow the reading and 1501 writing of AUDIT or ALARM access control entries. 1503 SSH_FXF_ACCESS_BACKUP 1504 The client wishes the server to enable any privileges or extra 1505 capabilities that the user may have in order to bypass normal 1506 access checks for the purpose of backing up or restoring files. 1508 SSH_FXF_BACKUP_STREAM 1509 This bit indicates that the client wishes to read or write a 1510 backup stream. A backup stream is a system dependent structured 1511 data stream that encodes all the information that must be 1512 preserved in order to restore the file from backup medium. 1514 The only well defined use for backup stream data read in this 1515 fashion is to write it to the same server to a file also opened 1516 using the BACKUP_STREAM flag. However, if the server has a well 1517 defined backup stream format, there may be other uses for this 1518 data outside the scope of this protocol. 1520 ACCESS_OVERRIDE_OWNER 1521 This bit indicates that the client wishes the server to enable any 1522 privileges or extra capabilities that the user may have in order 1523 to gain access to the file with WRITE_OWNER permission. 1525 This bit MUST always be specified in combination with 1526 ACE4_WRITE_OWNER. 1528 The 'attrs' field specifies the initial attributes for the file. 1529 Default values MUST be supplied by the server for those attributes 1530 that are not specified. See Section ''File Attributes'' for more 1531 information. 1533 The 'attrs' field is ignored if an existing file is opened. 1535 The following table is provided to assist in mapping POSIX semantics 1536 to equivalent SFTP file open parameters: 1538 O_RDONLY 1539 desired-access = READ_DATA|READ_ATTRIBUTES 1541 O_WRONLY 1542 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1544 O_RDWR 1545 desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA| 1546 WRITE_ATTRIBUTES 1548 O_APPEND 1549 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1550 flags = SSH_FXF_APPEND_DATA and or SSH_FXF_APPEND_DATA_ATOMIC 1552 O_CREAT 1553 flags = SSH_FXF_OPEN_OR_CREATE 1555 O_TRUNC 1556 flags = SSH_FXF_TRUNCATE_EXISTING 1558 O_TRUNC|O_CREATE 1559 flags = SSH_FXF_CREATE_TRUNCATE 1561 8.1.2. Opening a Directory 1563 To enumerate a directory, the client first obtains a handle and then 1564 issues directory read requests. When enumeration is complete, the 1565 handle MUST be closed. 1567 byte SSH_FXP_OPENDIR 1568 uint32 request-id 1569 string path [UTF-8] 1571 path 1572 The 'path' field is the path name of the directory to be listed 1573 (without any trailing slash). See Section 'File Names' for more 1574 information on file names. 1576 If 'path' does not refer to a directory, the server MUST return 1577 SSH_FX_NOT_A_DIRECTORY. 1579 The response to this message will be either SSH_FXP_HANDLE (if the 1580 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1582 8.1.3. Closing Handles 1584 A handle is closed using the following request. 1586 byte SSH_FXP_CLOSE 1587 uint32 request-id 1588 string handle 1590 handle 1591 'handle' is a handle previously returned in the response to 1592 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid 1593 immediately after this request has been sent. 1595 The response to this request will be a SSH_FXP_STATUS message. Note 1596 that on some server platforms even a close can fail. For example, if 1597 the server operating system caches writes, and an error occurs while 1598 flushing cached writes, the close operation may fail. 1600 Note that the handle is invalid regardless of the SSH_FXP_STATUS 1601 result. There is no way for the client to recover a handle that 1602 fails to close. The client MUST release all resources associated 1603 with the handle regardless of the status. The server SHOULD take 1604 whatever steps it can to recover from a close failure and to ensure 1605 that all resources associated with the handle on the server are 1606 correctly released. 1608 8.2. Reading and Writing 1610 8.2.1. Reading Files 1612 The following request can be used to read file data: 1614 byte SSH_FXP_READ 1615 uint32 request-id 1616 string handle 1617 uint64 offset 1618 uint32 length 1620 handle 1621 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1622 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1623 return SSH_FX_INVALID_HANDLE. 1625 offset 1626 The offset (in bytes) relative to the beginning of the file that 1627 the read MUST start at. This field is ignored if 1628 SSH_FXF_TEXT_MODE was specified during the open. 1630 length 1631 'length' is the maximum number of bytes to read. 1633 The server MUST not respond with more data than is specified by 1634 the 'length' parameter. However, the server MAY respond with less 1635 data if EOF is reached, an error is encountered, or the servers 1636 internal buffers can not handle such a large request. 1638 If the server specified a non-zero 'max-read-size' in its 1639 'supported2' (Section 5.4) extension and 'length' is <= 'max-read- 1640 size', then failure to return 'length' bytes indicates that EOF or 1641 an error occurred. 1643 8.2.2. Reading Directories 1645 In order to retrieve a directory listing, the client issues one or 1646 more SSH_FXP_READDIR requests. In order to obtain a complete 1647 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1648 requests until the server responds with an SSH_FXP_STATUS message. 1650 byte SSH_FXP_READDIR 1651 uint32 request-id 1652 string handle 1654 handle 1655 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is 1656 an ordinary file handle returned by SSH_FXP_OPEN, the server MUST 1657 return SSH_FX_INVALID_HANDLE. 1659 The server responds to this request with either a SSH_FXP_NAME or a 1660 SSH_FXP_STATUS message. One or more names may be returned at a time. 1661 Full status information is returned for each name in order to speed 1662 up typical directory listings. 1664 If there are no more names available to be read, the server MUST 1665 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1667 8.2.3. Writing Files 1669 Writing to a file is achieved using the following message: 1671 byte SSH_FXP_WRITE 1672 uint32 request-id 1673 string handle 1674 uint64 offset 1675 string data 1677 handle 1678 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1679 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1680 return SSH_FX_INVALID_HANDLE. 1682 offset 1683 The offset (in bytes) relative to the beginning of the file that 1684 the write MUST start at. This field is ignored if 1685 SSH_FXF_TEXT_MODE was specified during the open. 1687 The write will extend the file if writing beyond the end of the 1688 file. It is legal to write to an offset that extends beyond the 1689 end of the file; the semantics are to write the byte value 0x00 1690 from the end of the file to the specified offset and then the 1691 data. On most operating systems, such writes do not allocate disk 1692 space but instead create a sparse file. 1694 data 1695 The data to write to the file. 1697 The server responds to a write request with a SSH_FXP_STATUS message. 1699 8.3. Removing and Renaming Files 1701 The following request can be used to remove a file: 1703 byte SSH_FXP_REMOVE 1704 uint32 request-id 1705 string filename [UTF-8] 1707 filename 1708 'filename' is the name of the file to be removed. See Section 1709 'File Names' for more information. 1711 If 'filename' is a symbolic link, the link is removed, not the 1712 file it points to. 1713 This request cannot be used to remove directories. The server 1714 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. 1716 The server will respond to this request with a SSH_FXP_STATUS 1717 message. 1719 Files (and directories) can be renamed using the SSH_FXP_RENAME 1720 message. 1722 byte SSH_FXP_RENAME 1723 uint32 request-id 1724 string oldpath [UTF-8] 1725 string newpath [UTF-8] 1726 uint32 flags 1728 where 'request-id' is the request identifier, 'oldpath' is the name 1729 of an existing file or directory, and 'newpath' is the new name for 1730 the file or directory. 1732 'flags' is 0 or a combination of: 1734 SSH_FXF_RENAME_OVERWRITE 0x00000001 1735 SSH_FXF_RENAME_ATOMIC 0x00000002 1736 SSH_FXF_RENAME_NATIVE 0x00000004 1738 If the server cannot support the requested mode of operation, it must 1739 return SSH_FX_OP_UNSUPPORTED. 1741 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1742 exists a file with the name specified by newpath, the server MUST 1743 respond with SSH_FX_FILE_ALREADY_EXISTS. 1745 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1746 already exists, it is replaced in an atomic fashion. I.e., there is 1747 no observable instant in time where the name does not refer to either 1748 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1749 SSH_FXP_RENAME_OVERWRITE. 1751 If 'SSH_FXP_RENAME_OVERWRITE' is not present, and the server does not 1752 support this mode natively, it MAY emulate it by checking for the 1753 existance of a file before executing the rename operation. 1755 If the 'SSH_FXF_RENAME_ATOMIC' is specified without the the 1756 'SSH_FXP_RENAME_OVERWRITE', then the server MUST be able to perform 1757 the check and rename operation atomically. 1759 Because some servers cannot provide atomic rename, clients should 1760 only specify atomic rename if correct operation requires it. If 1761 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1762 atomic rename even if it is not requested. 1764 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1765 rename operation in whatever fashion it deems appropriate. Other 1766 flag values are considered hints as to desired behavior, but not 1767 requirements. 1769 The server will respond to this request with a SSH_FXP_STATUS 1770 message. 1772 8.4. Creating and Deleting Directories 1774 New directories can be created using the SSH_FXP_MKDIR request. It 1775 has the following format: 1777 byte SSH_FXP_MKDIR 1778 uint32 request-id 1779 string path [UTF-8] 1780 ATTRS attrs 1782 where 'request-id' is the request identifier. 1784 'path' specifies the directory to be created. See Section ''File 1785 Names'' for more information on file names. 1787 'attrs' specifies the attributes that should be applied to it upon 1788 creation. Attributes are discussed in more detail in Section ''File 1789 Attributes''. 1791 The server will respond to this request with a SSH_FXP_STATUS 1792 message. If a file or directory with the specified path already 1793 exists, an error will be returned. 1795 Directories can be removed using the SSH_FXP_RMDIR request, which has 1796 the following format: 1798 byte SSH_FXP_RMDIR 1799 uint32 request-id 1800 string path [UTF-8] 1802 where 'request-id' is the request identifier, and 'path' specifies 1803 the directory to be removed. See Section ''File Names'' for more 1804 information on file names. 1806 The server responds to this request with a SSH_FXP_STATUS message. 1808 8.5. Retrieving File Attributes 1810 Very often, file attributes are automatically returned by 1811 SSH_FXP_READDIR. However, sometimes there is need to specifically 1812 retrieve the attributes for a named file. This can be done using the 1813 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1815 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1816 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1817 follow symbolic links. Both have the same format: 1819 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1820 uint32 request-id 1821 string path [UTF-8] 1822 uint32 flags 1824 where 'request-id' is the request identifier, and 'path' specifies 1825 the file system object for which status is to be returned. The 1826 server responds to this request with either SSH_FXP_ATTRS or 1827 SSH_FXP_STATUS. 1829 The flags field specify the attribute flags in which the client has 1830 particular interest. This is a hint to the server. For example, 1831 because retrieving owner / group and acl information can be an 1832 expensive operation under some operating systems, the server may 1833 choose not to retrieve this information unless the client expresses a 1834 specific interest in it. 1836 The client has no guarantee the server will provide all the fields 1837 that it has expressed an interest in. 1839 SSH_FXP_FSTAT differs from the others in that it returns status 1840 information for an open file (identified by the file handle). 1842 byte SSH_FXP_FSTAT 1843 uint32 request-id 1844 string handle 1845 uint32 flags 1847 handle 1848 'handle' is an open file handle from either SSH_FXP_OPEN or 1849 SSH_FXP_OPENDIR. 1851 The server responds to this request with SSH_FXP_ATTRS or 1852 SSH_FXP_STATUS. 1854 8.6. Setting File Attributes 1856 File attributes may be modified using the SSH_FXP_SETSTAT and 1857 SSH_FXP_FSETSTAT requests. 1859 byte SSH_FXP_SETSTAT 1860 uint32 request-id 1861 string path [UTF-8] 1862 ATTRS attrs 1864 byte SSH_FXP_FSETSTAT 1865 uint32 request-id 1866 string handle 1867 ATTRS attrs 1869 path 1870 The file system object (e.g. file or directory) whose attributes 1871 are to be modified. If this object does not exist, or the user 1872 does not have sufficient access to write the attributes, the 1873 request MUST fail. 1875 handle 1876 'handle' is an open file handle from either SSH_FXP_OPEN or 1877 SSH_FXP_OPENDIR. If the handle was not opened with sufficient 1878 access to write the requested attributes, the request MUST fail. 1880 attrs 1881 Specifies the modified attributes to be applied. Attributes are 1882 discussed in more detail in Section ''File Attributes''. 1884 The server will respond with a SSH_FXP_STATUS message. 1886 Because some systems must use separate system calls to set various 1887 attributes, it is possible that a failure response will be returned, 1888 but yet some of the attributes may be have been successfully 1889 modified. If possible, servers SHOULD avoid this situation; however, 1890 clients MUST be aware that this is possible. 1892 8.7. Dealing with Links 1894 The SSH_FXP_READLINK request reads the target of a symbolic link. 1896 byte SSH_FXP_READLINK 1897 uint32 request-id 1898 string path [UTF-8] 1900 where 'request-id' is the request identifier and 'path' specifies the 1901 path name of the symlink to be read. 1903 The server will respond with a SSH_FXP_NAME packet containing only 1904 one name and a dummy attributes value. The name in the returned 1905 packet contains the target of the link. If an error occurs, the 1906 server MAY respond with SSH_FXP_STATUS. 1908 The SSH_FXP_LINK request creates a link (either hard or symbolic) on 1909 the server. 1911 byte SSH_FXP_LINK 1912 uint32 request-id 1913 string new-link-path [UTF-8] 1914 string existing-path [UTF-8] 1915 bool sym-link 1917 new-link-path 1918 Specifies the path name of the new link to create. 1920 target-path 1921 Specifies the path of a target object to which the newly created 1922 link will refer. In the case of a symbolic link, this path may 1923 not exist. 1925 sym-link 1926 Specifies that the link should be a symbolic link, or a special 1927 file that redirects file system parsing to the resulting path. It 1928 is generally possible to create symbolic links across device 1929 boundaries; however, it is not required that a server support 1930 this. 1932 If 'sym-link' is false, the link should be a hard link, or a 1933 second directory entry referring to the same file or directory 1934 object. It is generally not possible to create hard links across 1935 devices. 1937 The server shall respond with a SSH_FXP_STATUS. Clients should be 1938 aware that some servers may return SSH_FX_OP_UNSUPPORTED for either 1939 the hard-link, sym-link, or both operations. 1941 8.8. Byte-range locks 1943 8.8.1. Obtaining a byte range lock 1945 SSH_FXP_BLOCK creates a byte-range lock on the file specified by the 1946 handle. The lock can be either mandatory (meaning that the server 1947 enforces that no other process or client can perform operations in 1948 violation of the lock) or advisory (meaning that no other process can 1949 obtain a conflicting lock, but the server does not enforce that no 1950 operation violates the lock.) 1952 A server MAY implement an advisory lock in a mandatory fashion; in 1953 other words, the server MAY enforce that no operation violates the 1954 lock even when operating in advisory mode. 1956 byte SSH_FXP_BLOCK 1957 uint32 request-id 1958 string handle 1959 uint64 offset 1960 uint64 length 1961 uint32 uLockMask 1963 handle 1964 'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. 1965 Note that some servers MAY return SSH_FX_OP_UNSUPPORTED if the 1966 handle is a directory handle. 1968 offset 1969 Beginning of the byte-range to lock. 1971 length 1972 Number of bytes in the range to lock. The special value 0 means 1973 lock from 'offset' to the current end-of-file. (This operation is 1974 equivalent to doing a SSH_FXP_STAT to retrive the 'size' and then 1975 using that to calculate the length.) 1977 uLockMask 1978 A bit mask of SSH_FXF_BLOCK_* values; the meanings are described 1979 in Section 8.1.1.3. 1981 The result is a SSH_FXP_STATUS packet. If the requested range 1982 overlaps in any fashion with an already granted SSH_FXP_BLOCK request 1983 (even if the request is from the same client in the same connection), 1984 the result is SSH_FX_BYTE_RANGE_LOCK_REFUSED. 1986 It is permissible for 'offset' to be >= 'size', or for 'length' to 1987 extend past 'size'. However, in no case does this operation effect 1988 'size'. Naturally, all of the same restrictions regarding 1989 conflicting locks / access apply to such a lock. 1991 Take together the 'offset' and the 'length' can be considered to form 1992 a unique key, which is then used to release the lock using the 1993 SSH_FXP_UNBLOCK (below) request. 1995 8.8.2. Releasing a byte range lock 1997 SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the 1998 specified handle. The 'offset' and 'length' MUST match exactly the 1999 offset and length specified to the SSH_FXP_LOCK request. 2001 byte SSH_FXP_UNBLOCK 2002 uint32 request-id 2003 string handle 2004 uint64 offset 2005 uint64 length 2007 handle 2008 'handle' on which a SSH_FXP_BLOCK request has previously been 2009 issued. 2011 offset 2012 Beginning of the byte-range to unlock-- must match exactly the 2013 'offset' given to the SSH_FXP_BLOCK request. 2015 length 2016 Number of bytes in the range to unlock. The special value 0 means 2017 unlock from 'offset' to the end of the file. This must match 2018 exactly the 'length' give to the SSH_FXP_BLOCK request. 2020 The result is a SSH_FXP_STATUS packet. If the 'offset' and 'length' 2021 do not exactly match a previously granted range, the server MUST 2022 return SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK. 2024 8.9. Canonicalizing the Server-Side Path Name 2026 The SSH_FXP_REALPATH request can be used to have the server 2027 canonicalize any given path name to an absolute path. This is useful 2028 for converting path names containing ".." components or relative 2029 pathnames without a leading slash into absolute paths. The format of 2030 the request is as follows: 2032 byte SSH_FXP_REALPATH 2033 uint32 request-id 2034 string original-path [UTF-8] 2035 byte control-byte [optional] 2036 string compose-path[0..n] [optional] 2038 original-path 2039 The first component of the path which the client wishes resolved 2040 into a absolute canonical path. This may be the entire path. 2042 control-byte 2044 SSH_FXP_REALPATH_NO_CHECK 0x00000001 2045 SSH_FXP_REALPATH_STAT_IF 0x00000002 2046 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 2048 This field is optional, and if it is not present in the packet, it 2049 is assumed to be SSH_FXP_REALPATH_NO_CHECK. 2051 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT 2052 fail the request if the path does not exist, is hidden, or the 2053 user does not have access to the path or some component thereof. 2054 In addition, the path MUST NOT resolve symbolic links. This 2055 allows paths to be composed for the SSH_FXP_REMOVE command to 2056 remove symbolic links. 2058 The server MAY fail the request if the path is not syntactically 2059 valid, or for other reasons. 2061 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the 2062 path if it exists and is accessible to the client. However, if 2063 the path does not exist, isn't visible, or isn't accessible, the 2064 server MUST NOT fail the request. If the stat failed, the file 2065 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to 2066 distinguish between files that are actually 2067 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will have 2068 to issue a separate stat command in this case. 2070 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat 2071 the path. If the stat operation fails, the server MUST fail the 2072 request. 2074 compose-path 2075 A path which the client wishes the server to compose with the 2076 original path to form the new path. This field is optional, and 2077 if it is not present in the packet, it is assumed to be a zero 2078 length string. 2080 The client may specify multiple 'compose-path' elements, in which 2081 case the server should build the resultant path up by applying 2082 each compose path to the accumulated result until all 'compose- 2083 path' elements have been applied. 2085 The server MUST take the 'original-path' and apply the 'compose-path' 2086 as a modification to it. 'compose-path' MAY be relative to 'original- 2087 path' or may be an absolute path, in which case 'original-path' will 2088 be discarded. The 'compose-path' MAY be zero length. 2090 The server will respond with a SSH_FXP_NAME packet containing the 2091 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK 2092 is specified, the attributes are dummy values. 2094 8.9.1. Best Practice for Dealing with Paths 2096 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 2097 Previous to this version, clients typically composed new paths 2098 themselves and then called both realpath and stat on the resulting 2099 path to get its canonical name and see if it really existed and was a 2100 directory. 2102 This required clients to assume certain things about how a relative 2103 vs. realpath looked. The new realpath allows clients to no longer 2104 make those assumptions and to remove one round trip from the process 2105 and get deterministic behavior from all servers. 2107 END: RFCEDITOR REMOVE BEFORE PUBLISHING 2109 The client SHOULD treat the results of SSH_FXP_REALPATH as a 2110 canonical absolute path, even if the path does not appear to be 2111 absolute. A client that uses REALPATH(".", "") and treats the result 2112 as absolute, even if there is no leading slash, will continue to 2113 function correctly, even when talking to a Windows NT or VMS style 2114 system, where absolute paths may not begin with a slash. 2116 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so 2117 that it does not need to know when a path is absolute or relative. 2119 For example, if the client wishes to change directory up, and the 2120 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 2121 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) 2123 As a second example, if the client wishes transfer local file "a" to 2124 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the 2125 canonical path of the current directory, the client SHOULD send 2126 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This 2127 call will determine the correct path to use for the open request and 2128 whether the /b/d/e represents a directory. 2130 9. Responses from the Server to the Client 2132 The server responds to the client using one of a few response 2133 packets. All requests can return a SSH_FXP_STATUS response upon 2134 failure. When the operation is successful, and no data needs to be 2135 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 2136 appropriate. 2138 Exactly one response will be returned for each request. Each 2139 response packet contains a request identifier which can be used to 2140 match each response with the corresponding request. Note that it is 2141 legal to have several requests outstanding simultaneously, and the 2142 server is allowed to send responses to them in a different order from 2143 the order in which the requests were sent (the result of their 2144 execution, however, is guaranteed to be as if they had been processed 2145 one at a time in the order in which the requests were sent). 2147 Response packets are of the same general format as request packets. 2148 Each response packet begins with the request identifier. 2150 9.1. Status Response 2152 The format of the data portion of the SSH_FXP_STATUS response is as 2153 follows: 2155 byte SSH_FXP_STATUS 2156 uint32 request-id 2157 uint32 error/status code 2158 string error message (ISO-10646 UTF-8 [RFC-2279]) 2159 string language tag (as defined in [RFC-1766]) 2160 error-specific data 2162 request-id 2163 The 'request-id' specified by the client in the request the server 2164 is responding to. 2166 error/status code 2167 Machine readable status code indicating the result of the request. 2168 Error code values are defined below. The value SSH_FX_OK 2169 indicates success, and all other values indicate failure. 2171 Implementations MUST be prepared to receive unexpected error codes 2172 and handle them sensibly (such as by treating them as equivalent 2173 to SSH_FX_FAILURE). Future protocol revisions may add additional 2174 error codes without changing the version number. 2176 error message 2177 Human readable description of the error. 2179 language tag 2180 'language tag' specifies the language the error is in. 2182 error-specific data 2183 The error-specific data may be empty, or may contain additional 2184 information about the error. For error codes that send error- 2185 specific data, the format of the data is defined below. 2187 Error codes: 2189 SSH_FX_OK 0 2190 SSH_FX_EOF 1 2191 SSH_FX_NO_SUCH_FILE 2 2192 SSH_FX_PERMISSION_DENIED 3 2193 SSH_FX_FAILURE 4 2194 SSH_FX_BAD_MESSAGE 5 2195 SSH_FX_NO_CONNECTION 6 2196 SSH_FX_CONNECTION_LOST 7 2197 SSH_FX_OP_UNSUPPORTED 8 2198 SSH_FX_INVALID_HANDLE 9 2199 SSH_FX_NO_SUCH_PATH 10 2200 SSH_FX_FILE_ALREADY_EXISTS 11 2201 SSH_FX_WRITE_PROTECT 12 2202 SSH_FX_NO_MEDIA 13 2203 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 2204 SSH_FX_QUOTA_EXCEEDED 15 2205 SSH_FX_UNKNOWN_PRINCIPAL 16 2206 SSH_FX_LOCK_CONFLICT 17 2207 SSH_FX_DIR_NOT_EMPTY 18 2208 SSH_FX_NOT_A_DIRECTORY 19 2209 SSH_FX_INVALID_FILENAME 20 2210 SSH_FX_LINK_LOOP 21 2211 SSH_FX_CANNOT_DELETE 22 2212 SSH_FX_INVALID_PARAMETER 23 2213 SSH_FX_FILE_IS_A_DIRECTORY 24 2214 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 2215 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 2216 SSH_FX_DELETE_PENDING 27 2217 SSH_FX_FILE_CORRUPT 28 2218 SSH_FX_OWNER_INVALID 29 2219 SSH_FX_GROUP_INVALID 30 2220 SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK 31 2222 SSH_FX_OK 2223 Indicates successful completion of the operation. 2225 SSH_FX_EOF 2226 An attempt to read past the end-of-file was made; or, there are no 2227 more directory entries to return. 2229 SSH_FX_NO_SUCH_FILE 2230 A reference was made to a file which does not exist. 2232 SSH_FX_PERMISSION_DENIED 2233 The user does not have sufficient permissions to perform the 2234 operation. 2236 SSH_FX_FAILURE 2237 An error occurred, but no specific error code exists to describe 2238 the failure. 2240 This error message SHOULD always have meaningful text in the the 2241 'error message' field. 2243 SSH_FX_BAD_MESSAGE 2244 A badly formatted packet or other SFTP protocol incompatibility 2245 was detected. 2247 SSH_FX_NO_CONNECTION 2248 There is no connection to the server. This error MAY be used 2249 locally, but MUST NOT be return by a server. 2251 SSH_FX_CONNECTION_LOST 2252 The connection to the server was lost. This error MAY be used 2253 locally, but MUST NOT be return by a server. 2255 SSH_FX_OP_UNSUPPORTED 2256 An attempted operation could not be completed by the server 2257 because the server does not support the operation. 2259 This error MAY be generated locally by the client if e.g. the 2260 version number exchange indicates that a required feature is not 2261 supported by the server, or it may be returned by the server if 2262 the server does not implement an operation. 2264 SSH_FX_INVALID_HANDLE 2265 The handle value was invalid. 2267 SSH_FX_NO_SUCH_PATH 2268 The file path does not exist or is invalid. 2270 SSH_FX_FILE_ALREADY_EXISTS 2271 The file already exists. 2273 SSH_FX_WRITE_PROTECT 2274 The file is on read-only media, or the media is write protected. 2276 SSH_FX_NO_MEDIA 2277 The requested operation cannot be completed because there is no 2278 media available in the drive. 2280 SSH_FX_NO_SPACE_ON_FILESYSTEM 2281 The requested operation cannot be completed because there is 2282 insufficient free space on the filesystem. 2284 SSH_FX_QUOTA_EXCEEDED 2285 The operation cannot be completed because it would exceed the 2286 user's storage quota. 2288 SSH_FX_UNKNOWN_PRINCIPAL 2289 A principal referenced by the request (either the 'owner', 2290 'group', or 'who' field of an ACL), was unknown. The error 2291 specific data contains the problematic names. The format is one 2292 or more: 2294 string unknown-name 2296 Each string contains the name of a principal that was unknown. 2298 SSH_FX_LOCK_CONFLICT 2299 The file could not be opened because it is locked by another 2300 process. 2302 SSH_FX_DIR_NOT_EMPTY 2303 The directory is not empty. 2305 SSH_FX_NOT_A_DIRECTORY 2306 The specified file is not a directory. 2308 SSH_FX_INVALID_FILENAME 2309 The filename is not valid. 2311 SSH_FX_LINK_LOOP 2312 Too many symbolic links encountered or, an SSH_FXF_NOFOLLOW open 2313 encountered a symbolic link as the final component 2315 SSH_FX_CANNOT_DELETE 2316 The file cannot be deleted. One possible reason is that the 2317 advisory READONLY attribute-bit is set. 2319 SSH_FX_INVALID_PARAMETER 2320 One of the parameters was out of range, or the parameters 2321 specified cannot be used together. 2323 SSH_FX_FILE_IS_A_DIRECTORY 2324 The specified file was a directory in a context where a directory 2325 cannot be used. 2327 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 2328 An read or write operation failed because another process's 2329 mandatory byte-range lock overlaps with the request. 2331 SSH_FX_BYTE_RANGE_LOCK_REFUSED 2332 A request for a byte range lock was refused. 2334 SSH_FX_DELETE_PENDING 2335 An operation was attempted on a file for which a delete operation 2336 is pending. 2338 SSH_FX_FILE_CORRUPT 2339 The file is corrupt; an filesystem integrity check should be run. 2341 SSH_FX_OWNER_INVALID 2342 The principal specified can not be assigned as an owner of a file. 2344 SSH_FX_GROUP_INVALID 2345 The principal specified can not be assigned as the primary group 2346 of a file. 2348 SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK 2349 The requested operation could not be completed because the 2350 specifed byte range lock has not been granted. 2352 9.2. Handle Response 2354 The SSH_FXP_HANDLE response has the following format: 2356 byte SSH_FXP_HANDLE 2357 uint32 request-id 2358 string handle 2360 'handle' 2361 An arbitrary string that identifies an open file or directory on 2362 the server. The handle is opaque to the client; the client MUST 2363 NOT attempt to interpret or modify it in any way. The length of 2364 the handle string MUST NOT exceed 256 data bytes. 2366 9.3. Data Response 2368 The SSH_FXP_DATA response has the following format: 2370 byte SSH_FXP_DATA 2371 uint32 request-id 2372 string data 2373 bool end-of-file [optional] 2375 data 2376 'data' is an arbitrary byte string containing the requested data. 2377 The data string may be at most the number of bytes requested in a 2378 SSH_FXP_READ request, but may also be shorter. (See 2379 Section 8.2.1.) 2381 end-of-file 2382 This field is optional, and if present and true it indicates that 2383 EOF was reached during this read. This can help the client avoid 2384 a round trip to determine whether a short read was normal (due to 2385 EOF) or some other problem (limited server buffer for example.) 2387 9.4. Name Response 2389 The SSH_FXP_NAME response has the following format: 2391 byte SSH_FXP_NAME 2392 uint32 request-id 2393 uint32 count 2394 repeats count times: 2395 string filename [UTF-8] 2396 ATTRS attrs 2397 bool end-of-list [optional] 2399 count 2400 The number of names returned in this response, and the 'filename' 2401 and 'attrs' field repeat 'count' times. 2403 filename 2404 A file name being returned (for SSH_FXP_READDIR, it will be a 2405 relative name within the directory, without any path components; 2406 for SSH_FXP_REALPATH it will be an absolute path name.) 2408 attrs 2409 The attributes of the file as described in Section ''File 2410 Attributes''. 2412 end-of-list 2413 If this field is present and true, there are no more entries to be 2414 read. This field should either be omitted or be true unless the 2415 request is SSH_FXP_READDIR. 2417 9.5. Attrs Response 2419 The SSH_FXP_ATTRS response has the following format: 2421 byte SSH_FXP_ATTRS 2422 uint32 request-id 2423 ATTRS attrs 2425 attrs 2426 The returned file attributes as described in Section ''File 2427 Attributes''. 2429 10. Extensions 2431 The SSH_FXP_EXTENDED request provides a generic extension mechanism 2432 for adding additional commands. 2434 byte SSH_FXP_EXTENDED 2435 uint32 request-id 2436 string extended-request 2437 ... any request-specific data ... 2439 request-id 2440 Identifier to be returned from the server with the response. 2442 extended-request 2443 A string naming the extension, following the the DNS extensibility 2444 naming convention outlined in [RFC4251], or defined by IETF 2445 consensus. 2447 request-specific data 2448 The rest of the request is defined by the extension; servers 2449 SHOULD NOT attempt to interpret it if they do not recognize the 2450 'extended-request' name. 2452 The server may respond to such requests using any of the response 2453 packets defined in Section ''Responses from the Server to the 2454 Client''. Additionally, the server may also respond with a 2455 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 2456 not recognize the 'extended-request' name, then the server MUST 2457 respond with SSH_FXP_STATUS with error/status set to 2458 SSH_FX_OP_UNSUPPORTED. 2460 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 2461 extension-specific data from the server to the client. It is of the 2462 following format: 2464 byte SSH_FXP_EXTENDED_REPLY 2465 uint32 request-id 2466 ... any request-specific data ... 2468 There is a range of packet types reserved for use by extensions. In 2469 order to avoid collision, extensions that that use additional packet 2470 types should determine those numbers dynamically. 2472 The suggested way of doing this is have an extension request from the 2473 client to the server that enables the extension; the extension 2474 response from the server to the client would specify the actual type 2475 values to use, in addition to any other data. 2477 Extension authors should be mindful of the limited range of packet 2478 types available (there are only 45 values available) and avoid 2479 requiring a new packet type where possible. 2481 11. Implementation Considerations 2483 In order for this protocol to perform well, especially over high 2484 latency networks, multiple read and write requests should be queued 2485 to the server. 2487 The data size of requests should match the maximum packet size for 2488 the next layer up in the protocol chain. 2490 When implemented over ssh, the best performance should be achieved 2491 when the data size matches the channel's max packet, and the channel 2492 window is a multiple of the channel packet size. 2494 Implementations MUST be aware that requests do not have to be 2495 satisfied in the order issued. (See Request Synchronization and 2496 Reordering (Section 4.1).) 2498 Implementations MUST also be aware that read requests may not return 2499 all the requested data, even if the data is available. 2501 12. IANA Considerations 2503 IANA registrie needs to be created for each of the following: 2504 o The packet types define defined in Section 4.3 2505 o The extension specified in this draft, which are: 'text-seek', 2506 'supported2', 'acl-supported', 'newline', 'versions', 'version- 2507 select', 'filename-charset', 'filename-translation-control' 2509 13. Security Considerations 2511 It is assumed that both ends of the connection have been 2512 authenticated and that the connection has privacy and integrity 2513 features. Such security issues are left to the underlying transport 2514 protocol, except to note that if this is not the case, an attacker 2515 may be able to manipulate files on the server and thus wholly 2516 compromise the server. 2518 This protocol provides file system access to arbitrary files on the 2519 server (constrained only by the server implementation). It is the 2520 responsibility of the server implementation to enforce any access 2521 controls that may be required to limit the access allowed for any 2522 particular user (the user being authenticated externally to this 2523 protocol, typically using [RFC4252]). 2525 Extreme care must be used when interpreting file handle strings. In 2526 particular, care must be taken that a file handle string is valid in 2527 the context of a given 'file-share' session. For example, the 'file- 2528 share' server daemon may have files which it has opened for its own 2529 purposes, and the client must not be able to access these files by 2530 specifying an arbitrary file handle string. 2532 The permission field of the attrib structure (Section 7.6) may 2533 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 2534 extreme caution when setting these bits on either remote or local 2535 files. (I.e., just because a file was SUID on the remote system does 2536 not necessarily imply that it should be SUID on the local system.) 2538 Filesystems often contain entries for objects that are not files at 2539 all, but are rather devices. For example, it may be possible to 2540 access serial ports, tape devices, or named pipes using this 2541 protocol. Servers should exercise caution when granting access to 2542 such resources. In addition to the dangers inherent in allowing 2543 access to such a device, some devices may be 'slow', and could cause 2544 denial of service by causing the server to block for a long period of 2545 time while I/O is performed to such a device. 2547 Servers should take care that file-system quotas are respected for 2548 users. In addition, implementations should be aware that attacks may 2549 be possible, or facilitated, by filling a filesystem. For example, 2550 filling the filesystem where event logging and auditing occurs may, 2551 at best, cause the system to crash, or at worst, allow the attacker 2552 to take untraceable actions in the future. 2554 Servers should take care that filenames are in their appropriate 2555 canonical form, and to ensure that filenames not in canonical form 2556 cannot be used to bypass access checks or controls. 2558 If the server implementation limits access to certain parts of the 2559 file system, extra care must be taken in parsing file names which 2560 contain the '..' path element, and when following symbolic links, 2561 shortcuts, or other filesystem objects which might transpose the path 2562 to refer to an object outside of the restricted area. There have 2563 been numerous reported security bugs where a ".." in a path name has 2564 allowed access outside the intended area. 2566 14. Changes from Previous Protocol Versions 2568 RFC EDITOR: PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2570 Please refer to the following web page for pervious versions of the 2571 protocol: 2573 http://tools.ietf.org/wg/secsh/draft-ietf-secsh-filexfer/ 2575 RFC EDITOR: END PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2577 15. References 2579 15.1. Normative References 2581 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2582 Beame, C., Eisler, M., and D. Noveck, "NFS version 4 2583 Protocol", RFC 3010, December 2000. 2585 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2586 Protocol Architecture", RFC 4251, January 2006. 2588 [RFC4253] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2589 Transport Layer Protocol", RFC 4253, January 2006. 2591 [RFC4254] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2592 Connection Protocol", RFC 4254, January 2006. 2594 [IEEE.1003-1.1996] 2595 Institute of Electrical and Electronics Engineers, 2596 "Information Technology - Portable Operating System 2597 Interface (POSIX) - Part 1: System Application Program 2598 Interface (API) [C Language]", IEEE Standard 1003.2, 1996. 2600 15.2. Informative References 2602 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet 2603 Mail Extensions) Part One: Mechanisms for Specifying and 2604 Describing the Format of Internet Message Bodies", 2605 RFC 1521, September 1993. 2607 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2608 RFC 2246, January 1999. 2610 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2611 Languages", BCP 18, RFC 2277, January 1998. 2613 [RFC4252] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 2614 Authentication Protocol", RFC 4252, January 2006. 2616 Trademark notice 2618 "ssh" is a registered trademark in the United States and/or other 2619 countries. 2621 Authors' Addresses 2623 Joseph Galbraith 2624 VanDyke Software 2625 4848 Tramway Ridge Blvd 2626 Suite 101 2627 Albuquerque, NM 87111 2628 US 2630 Phone: +1 505 332 5700 2631 Email: galb-list@vandyke.com 2633 Oskari Saarenmaa 2634 F-Secure 2635 Tammasaarenkatu 7 2636 Helsinki 00180 2637 FI 2639 Email: oskari.saarenmaa@f-secure.com 2641 Intellectual Property Statement 2643 The IETF takes no position regarding the validity or scope of any 2644 Intellectual Property Rights or other rights that might be claimed to 2645 pertain to the implementation or use of the technology described in 2646 this document or the extent to which any license under such rights 2647 might or might not be available; nor does it represent that it has 2648 made any independent effort to identify any such rights. Information 2649 on the procedures with respect to rights in RFC documents can be 2650 found in BCP 78 and BCP 79. 2652 Copies of IPR disclosures made to the IETF Secretariat and any 2653 assurances of licenses to be made available, or the result of an 2654 attempt made to obtain a general license or permission for the use of 2655 such proprietary rights by implementers or users of this 2656 specification can be obtained from the IETF on-line IPR repository at 2657 http://www.ietf.org/ipr. 2659 The IETF invites any interested party to bring to its attention any 2660 copyrights, patents or patent applications, or other proprietary 2661 rights that may cover technology that may be required to implement 2662 this standard. Please address the information to the IETF at 2663 ietf-ipr@ietf.org. 2665 Disclaimer of Validity 2667 This document and the information contained herein are provided on an 2668 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2669 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2670 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2671 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2672 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2673 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2675 Copyright Statement 2677 Copyright (C) The Internet Society (2006). This document is subject 2678 to the rights, licenses and restrictions contained in BCP 78, and 2679 except as set forth therein, the authors retain all their rights. 2681 Acknowledgment 2683 Funding for the RFC Editor function is currently provided by the 2684 Internet Society.