idnits 2.17.1 draft-ietf-secsh-filexfer-09.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 19. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2909. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2886. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2893. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2899. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 169: '...rr by the server SHOULD be considered ...' RFC 2119 keyword, line 170: '...information, and MAY be displayed to t...' RFC 2119 keyword, line 176: '...rors or warnings MAY be sent as stderr...' RFC 2119 keyword, line 196: '...the length field MUST be included in a...' RFC 2119 keyword, line 200: '...overhead). All servers SHOULD support...' (189 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 678 has weird spacing: '... bool do-...' == Line 707 has weird spacing: '... string owne...' == Line 708 has weird spacing: '... string grou...' == Line 718 has weird spacing: '... string acl ...' == Line 722 has weird spacing: '... string mime...' == (6 more instances...) -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == 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 4). 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: 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 expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT fail the request if the path does not exist, is hidden, or the user does not have access to the path or some component thereof. However, the path MAY NOT be completely resolved to it's component form. For example, symlinks may not be followed in this case. The server MAY fail the request if the path is not syntactically valid, or for other reasons. -- 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 (June 10, 2005) is 6887 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 2556, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 2011, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 2012, but not defined ** Obsolete undefined reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Downref: Normative reference to an Informational RFC: RFC 1321 ** Obsolete normative reference: RFC 1510 (Obsoleted by RFC 4120, RFC 6649) ** Obsolete normative reference: RFC 3010 (Obsoleted by RFC 3530) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE.1003-1.1996' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS-180-2' -- 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: 10 errors (**), 0 flaws (~~), 14 warnings (==), 12 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: December 12, 2005 O. Saarenmaa 5 F-Secure 6 T. Ylonen 7 S. Lehtinen 8 SSH Communications Security Corp 9 June 10, 2005 11 SSH File Transfer Protocol 12 draft-ietf-secsh-filexfer-09.txt 14 Status of this Memo 16 By submitting this Internet-Draft, each author represents that any 17 applicable patent or other IPR claims of which he or she is aware 18 have been or will be disclosed, and any of which he or she becomes 19 aware will be disclosed, in accordance with Section 6 of BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on December 12, 2005. 39 Copyright Notice 41 Copyright (C) The Internet Society (2005). 43 Abstract 45 The SSH File Transfer Protocol provides secure file transfer 46 functionality over any reliable data stream. It is the standard file 47 transfer protocol for use with the SSH2 protocol. This document 48 describes the file transfer protocol and its interface to the SSH2 49 protocol suite. 51 Table of Contents 53 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 54 2. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 55 2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 4 56 3. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 57 3.1 Request Synchronization and Reordering . . . . . . . . . . 6 58 3.2 New data types defined by this document . . . . . . . . . 6 59 3.3 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 60 4. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9 61 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 9 62 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 9 63 4.3 Determining Server Newline Convention . . . . . . . . . . 10 64 4.4 Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . 10 65 4.5 Supported Features . . . . . . . . . . . . . . . . . . . . 11 66 4.6 Version re-negotiation . . . . . . . . . . . . . . . . . . 13 67 5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14 68 6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16 69 6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 17 70 6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 71 6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 72 6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 19 73 6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 19 74 6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 20 75 6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20 76 6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 77 6.9 attrib-bits and attrib-bits-valid . . . . . . . . . . . . 23 78 6.10 text-hint . . . . . . . . . . . . . . . . . . . . . . . . 25 79 6.11 mime-type . . . . . . . . . . . . . . . . . . . . . . . . 26 80 6.12 link-count . . . . . . . . . . . . . . . . . . . . . . . . 26 81 6.13 untranslated-name . . . . . . . . . . . . . . . . . . . . 26 82 6.14 Extended Attributes . . . . . . . . . . . . . . . . . . . 26 83 7. Requests From the Client to the Server . . . . . . . . . . . . 26 84 7.1 Opening and Closing Files and Directories . . . . . . . . 27 85 7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 27 86 7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 32 87 7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 33 88 7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 33 89 7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 33 90 7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 34 91 7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 35 92 7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 35 93 7.4 Creating and Deleting Directories . . . . . . . . . . . . 37 94 7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 37 95 7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 38 96 7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 39 97 7.8 Byte-range locks . . . . . . . . . . . . . . . . . . . . . 40 98 7.9 Canonicalizing the Server-Side Path Name . . . . . . . . . 42 99 7.9.1 Best Practice for Dealing with Paths . . . . . . . . . 43 100 8. Responses from the Server to the Client . . . . . . . . . . . 44 101 8.1 Status Response . . . . . . . . . . . . . . . . . . . . . 44 102 8.2 Handle Response . . . . . . . . . . . . . . . . . . . . . 49 103 8.3 Data Response . . . . . . . . . . . . . . . . . . . . . . 49 104 8.4 Name Response . . . . . . . . . . . . . . . . . . . . . . 50 105 8.5 Attrs Response . . . . . . . . . . . . . . . . . . . . . . 50 106 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 51 107 9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 52 108 9.1.1 Checking File Contents: v5 extension . . . . . . . . . 53 109 9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 54 110 9.2 Querying Available Space . . . . . . . . . . . . . . . . . 56 111 9.3 Querying User Home Directory . . . . . . . . . . . . . . . 57 112 10. Implementation Considerations . . . . . . . . . . . . . . . 57 113 11. Security Considerations . . . . . . . . . . . . . . . . . . 58 114 12. Changes from Previous Protocol Versions . . . . . . . . . . 59 115 12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 59 116 12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 60 117 12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 61 118 12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 61 119 12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 61 120 12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 61 121 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 122 13.1 Normative References . . . . . . . . . . . . . . . . . . . 62 123 13.2 Informative References . . . . . . . . . . . . . . . . . . 63 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 63 125 Intellectual Property and Copyright Statements . . . . . . . . 65 127 1. Introduction 129 This protocol provides secure file transfer (and more generally file 130 system access.) It is designed so that it could be used to implement 131 a secure remote file system service, as well as a secure file 132 transfer service. 134 This protocol assumes that it runs over a secure channel, such as a 135 channel in [I-D.ietf-secsh-architecture], and that the server has 136 already authenticated the client, and that the identity of the client 137 user is available to the protocol. 139 In general, this protocol follows a simple request-response model. 140 Each request and response contains a sequence number and multiple 141 requests may be pending simultaneously. There are a relatively large 142 number of different request messages, but a small number of possible 143 response messages. Each request has one or more response messages 144 that may be returned in result (e.g., a read either returns data or 145 reports error status). 147 The packet format descriptions in this specification follow the 148 notation presented in [I-D.ietf-secsh-architecture]. 150 Even though this protocol is described in the context of the SSH2 151 protocol, this protocol is general and independent of the rest of the 152 SSH2 protocol suite. It could be used in a number of different 153 applications, such as secure file transfer over TLS [RFC2246] and 154 transfer of management information in VPN applications. 156 2. Use with the SSH Connection Protocol 158 When used with the SSH2 Protocol suite, this protocol is intended to 159 be used as a subsystem as described in [I-D.ietf-secsh-connect] in 160 the section "Starting a Shell or a Command". The subsystem name used 161 with this protocol is "sftp". 163 2.1 The Use of 'stderr' in the server 165 This protocol uses stdout and stdin to transmit binary protocol data. 166 The "session" channel ([I-D.ietf-secsh-connect]), which is used by 167 the subsystem, also supports the use of stderr. 169 Data sent on stderr by the server SHOULD be considered free format 170 debug or supplemental error information, and MAY be displayed to the 171 user. 173 For example, during initialization, there is no client request 174 active, so errors or warning information cannot be sent to the client 175 as part of the SFTP protocol at this early stage. However, the 176 errors or warnings MAY be sent as stderr text. 178 3. General Packet Format 180 All packets transmitted over the secure connection are of the 181 following format: 183 uint32 length 184 byte type 185 uint32 request-id 186 ... type specific fields ... 188 'length' 189 The length of the entire packet, excluding the length field 190 itself, such that, for example, for a packet type containing no 191 type specific fields, the length field would be 5, and 9 bytes of 192 data would be sent on the wire. (This is the packet format used 193 in [I-D.ietf-secsh-transport].) 195 All packet descriptions in this document omit the length field for 196 brevity; the length field MUST be included in any case. 198 The maximum size of a packet is in practice determined by the 199 client (the maximum size of read or write requests that it sends, 200 plus a few bytes of packet overhead). All servers SHOULD support 201 packets of at least 34000 bytes (where the packet size refers to 202 the full length, including the header above). This should allow 203 for reads and writes of at most 32768 bytes. 205 'type' 206 The type code for the packet. 208 'request-id' 209 Each request from the client contains a 'request-id' field. Each 210 response from the server includes that same 'request-id' from the 211 request that the server is responding to. One possible 212 implementation is for the client to us a monotonically increasing 213 request sequence number (modulo 2^32). There is, however, no 214 particular requirement the 'request-id' fields be unique. 216 There are two packets, INIT and VERSION, which do not use the 217 request-id. 218 Packet descriptions in this document will contain the 'request-id' 219 field, but will not redefine it. 221 Implementations MUST ignore excess data at the end of an otherwise 222 valid packet. Implementations MUST respond to unrecognized packet 223 types with an SSH_FX_OP_UNSUPPORTED error. This will allow the 224 protocol to be extended in a backwards compatible way as needed. 226 There is no limit on the number of outstanding (non-acknowledged) 227 requests that the client may send to the server. In practice this is 228 limited by the buffering available on the data stream and the queuing 229 performed by the server. If the server's queues are full, it should 230 not read any more data from the stream, and flow control will prevent 231 the client from sending more requests. Note, however, that while 232 there is no restriction on the protocol level, the client's API may 233 provide a limit in order to prevent infinite queuing of outgoing 234 requests at the client. 236 3.1 Request Synchronization and Reordering 238 The protocol and implementations MUST process requests relating to 239 the same file in the order in which they are received. In other 240 words, if an application submits multiple requests to the server, the 241 results in the responses will be the same as if it had sent the 242 requests one at a time and waited for the response in each case. For 243 example, the server may process non-overlapping read/write requests 244 to the same file in parallel, but overlapping reads and writes cannot 245 be reordered or parallelized. However, there are no ordering 246 restrictions on the server for processing requests from two different 247 file transfer connections. The server may interleave and parallelize 248 them at will. 250 There are no restrictions on the order in which responses to 251 outstanding requests are delivered to the client, except that the 252 server must ensure fairness in the sense that processing of no 253 request will be indefinitely delayed even if the client is sending 254 other requests so that there are multiple outstanding requests all 255 the time. 257 A client MUST be prepared to recieve responses to multiple overlapped 258 requests out of order. 260 3.2 New data types defined by this document 262 This document defines these data types in addition to those defined 263 in [I-D.ietf-secsh-architecture]. 265 uint16 266 Represents a 16-bit unsigned integer. Stored as 2 bytes in the 267 order of decreasing significance (network byte order). 269 int64 270 Represents a 64-bit signed integer. Stored using two's 271 complement, as eight bytes in the order of decreasing significance 272 (network byte order). 274 extension-pair 276 string extension-name 277 string extension-data 279 'extension-name' is the name of a protocol extension. Extensions 280 not defined by IETF CONSENSUS MUST follow the the DNS 281 extensibility naming convention outlined in [I-D.ietf-secsh- 282 architecture]. 284 'extension-data' is any data specific to the extension, and MAY be 285 zero length if the extension has no data. 287 3.3 Packet Types 289 The following values are defined for packet types. 291 SSH_FXP_INIT 1 292 SSH_FXP_VERSION 2 293 SSH_FXP_OPEN 3 294 SSH_FXP_CLOSE 4 295 SSH_FXP_READ 5 296 SSH_FXP_WRITE 6 297 SSH_FXP_LSTAT 7 298 SSH_FXP_FSTAT 8 299 SSH_FXP_SETSTAT 9 300 SSH_FXP_FSETSTAT 10 301 SSH_FXP_OPENDIR 11 302 SSH_FXP_READDIR 12 303 SSH_FXP_REMOVE 13 304 SSH_FXP_MKDIR 14 305 SSH_FXP_RMDIR 15 306 SSH_FXP_REALPATH 16 307 SSH_FXP_STAT 17 308 SSH_FXP_RENAME 18 309 SSH_FXP_READLINK 19 310 SSH_FXP_LINK 21 311 SSH_FXP_BLOCK 22 312 SSH_FXP_UNBLOCK 23 314 SSH_FXP_STATUS 101 315 SSH_FXP_HANDLE 102 316 SSH_FXP_DATA 103 317 SSH_FXP_NAME 104 318 SSH_FXP_ATTRS 105 320 SSH_FXP_EXTENDED 200 321 SSH_FXP_EXTENDED_REPLY 201 323 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 324 implement extensions, which can be vendor specific. See Section 325 ''Extensions'' for more details. 327 Values 210-255 are reserved for use in conjunction with these 328 extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the 329 meaning of these reserved types. It is suggested that the actual 330 value to be used also be negotiated, since this will prevent 331 collision among multiple uncoordinated extensions. 333 The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if 334 it receives a packet it does not recognize. 336 The use of additional packet types in the non-extension range MUST be 337 introduced through IETF consensus. New packet types to be sent from 338 the client to the server MAY be introduced without changing the 339 protocol version (Section 4). Because the client has no way to 340 respond to unrecognized packet types, new packet types to be sent 341 from the server to the client the client MUST not used unless the 342 protocol version is changed or the client has negotiated to received 343 them. This negotiation MAY be explicit, through the use of 344 extensions, or MAY be implicit, by the client itself using a packet 345 type not defined above. 347 4. Protocol Initialization 349 When the file transfer protocol starts, the client first sends a 350 SSH_FXP_INIT (including its version number) packet to the server. 351 The server responds with a SSH_FXP_VERSION packet, supplying the 352 lowest of its own and the client's version number. Both parties 353 should from then on adhere to that particular version of the 354 protocol. 356 The version number of the protocol specified in this document is 6. 357 The version number should be incremented for each incompatible 358 revision of this protocol. 360 Note that these two packets DO NOT contain a request id. These are 361 the only such packets in the protocol. 363 4.1 Client Initialization 365 The SSH_FXP_INIT packet (from client to server) has the following 366 data: 368 uint32 version 370 'version' is the version number of the client. If the client wishes 371 to interoperate with servers that support discontiguous version 372 numbers it SHOULD send '3', and then use the 'version-select' 373 extension (see below.) Otherwise, this value is '6' for this version 374 of the protocol. 376 4.2 Server Initialization 378 The SSH_FXP_VERSION packet (from server to client) has the following 379 data: 381 uint32 version 382 extension-pair extensions[0..n] 384 'version' is the lower of the protocol version supported by the 385 server and the version number received from the client. 387 'extensions' is 0 or more extension-pairs (Section 3.2). 388 Implementations MUST silently ignore any extensions whose names they 389 do not recognize. 391 4.3 Determining Server Newline Convention 393 In order to correctly process text files in a cross platform 394 compatible way, newline sequences must be converted between client 395 and server conventions. 397 The SSH_FXF_ACCESS_TEXT_MODE file open flag (Section 7.1.1) makes it 398 possible to request that the server translate a file to a 'canonical' 399 wire format. This format uses CRLF as the line separator. 401 Servers for systems using other conventions MUST translate to and 402 from the canonical form. 404 However, to ease the burden of implementation on servers that use a 405 single, simple, separator sequence the following extension allows the 406 canonical format to be changed. 408 string "newline" 409 string new-canonical-separator (usually CR or LF or CRLF) 411 All clients MUST support this extension. 413 When processing text files, clients SHOULD NOT translate any 414 character or sequence that is not an exact match of the server's 415 newline separator. 417 In particular, if the newline sequence being used is the canonical 418 CRLF sequence, a lone CR or a lone LF SHOULD be written through 419 without change. 421 4.4 Vendor Id 423 It is often necessary to detect the version of the server so that 424 bugs can be worked around. This extension allows the client to do 425 so. (It may also be sent by the client using an EXTENDED request.) 427 string "vendor-id" 428 string vendor-structure 429 string vendor-name 430 string product-name 431 string product-version 432 uint64 product-build-number 434 vendor-name 435 Arbitrary name identifying the maker of the product. 437 product-name 438 Arbitrary name identifying the product. 440 product-name 441 Arbitrary string identifying the version of the product. 443 product-build-number 444 A build-number for the product, such that if a bug is fixed in 445 build-number 'x', it can be assumed that (barring regression in 446 the product) it is fixed in all build-numbers > 'x'. 448 4.5 Supported Features 450 The sftp protocol has grown to be very rich, and now supports a 451 number of features that may not be available on all servers. 453 When a server receives a request for a feature it cannot support, it 454 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 455 specified. The following extension facilitates clients being able to 456 use the maximum available feature set, and yet not be overly burdened 457 by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST 458 include as part of their version packet. 460 string "supported2" 461 string supported-structure 462 uint32 supported-attribute-mask 463 uint32 supported-attribute-bits 464 uint32 supported-open-flags 465 uint32 supported-access-mask 466 uint32 max-read-size 467 uint16 supported-open-block-masks 468 uint16 supported-block-masks 469 uint32 attrib-extension-count 470 string attrib-extension-names[attrib_extension-count] 471 uint32 extension-count 472 string extension-names[extension-count] 474 Note that the name "supported2" is used here to avoid conflict with 475 the slightly different "supported" extension that was previously 476 used. 478 supported-attribute-mask 479 This mask MAY by applied to the 'File Attributes' valid-attribute- 480 flags field (Section 6.1) to ensure that no unsupported attributes 481 are present during a operation which writes attributes. 483 supported-attribute-bits 484 This mask MAY by applied to the 'File Attributes' attrib-bits 485 field (Section 6.9) to ensure that no unsupported attrib-bits are 486 present during a operation which writes attributes. 488 supported-open-flags 489 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN 490 (Section 7.1.1) flags field. 492 supported-access-mask 493 This mask may be applied to the ace-mask field of an ACL. 495 This mask SHOULD NOT be applied to the desired-access field of the 496 SSH_FXP_OPEN (Section 7.1.1) request. Doing so will simply result 497 in not requesting the access required by the client. In this 498 case, the server is responible for translating the clients 499 requested access to a mode it supports that is sufficient to grant 500 all access requested by the client. 502 max-read-size 503 This is the maximum read size that the server guarantees to 504 complete. For example, certain embedded server implementations 505 complete only the first 4K of a read, even if there is additional 506 data to be read from the file. 508 If the server specifies a non-zero value for max-read-size, it 509 MUST return the requested number of bytes for reads that are less 510 than or equal to the value, unless it encounters EOF or an ERROR. 512 The server MAY use this value to express that it is willing to 513 handle very large read requests, in excess of the standard 34000 514 bytes specfied in Section 3. 516 supported-open-block-masks 517 supported-block-masks 518 16-bit masks specifying which combinations of blocking flags are 519 supported. Each bit corresponds to one combination of the 520 SSH_FXF_ACCESS_BLOCK_READ, SSH_FXF_ACCESS_BLOCK_WRITE, 521 SSH_FXF_ACCESS_BLOCK_DELETE, and SSH_FXF_ACCESS_BLOCK_ADVISORY 522 bits from Section 7.1.1.3, with a set bit corresponding to a 523 supported combination and a clear bit an unsupported combination. 524 The index of a bit, bit zero being the least significant bit, 525 viewed as a four-bit number, corresponds to a combination of flag 526 bits, shifted right so that BLOCK_READ is the least significant 527 bit. The combination `no blocking flags' MUST be supported, so 528 the low bit will always be set. 530 For example, a server supporting only the classic advisory read 531 (shared) and write (exclusive) locks would set the bits 532 corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, 533 0b1010, plus the always-set bit 0b0000, giving a mask value of 534 0b0000110000000001, or 0x0c01; a server supporting no locking at 535 all would set only bit zero, giving 0x0001. 537 'supported-open-block-masks' applies to the SSH_FXP_OPEN 538 (Section 7.1.1) flags field. 'supported-block-masks' applies to 539 the SSH_FXF_BLOCK request. 541 attrib-extension-count 542 Count of extension names in the attrib-extension array. 544 attrib-extension-names 545 Names of extensions that can be used in an ATTRS (Section 6.14) 546 structure. 548 extension-count 549 Count of extension names in the attrib-extension array. 551 extension-names 552 Names of extensions that can be used with the SSH_FXP_EXTEND 553 (Section 9) packet. 555 Naturally, if a given attribute field, attribute mask bit, open flag, 556 or extension is required for correct operation, the client MUST 557 either not allow the bit to be masked off, or MUST fail the operation 558 gracefully without sending the request to the server. 560 The client MAY send requests that are not supported by the server; 561 however, it is not normally expected to be productive to do so. The 562 client SHOULD apply the mask even to attrib structures received from 563 the server. The server MAY include attributes or attrib-bits that 564 are not included in the mask. Such attributes or attrib-bits are 565 effectively read-only. 567 4.6 Version re-negotiation 569 If the server supports other versions than what was negotiated, it 570 may wish to send the 'versions' extension to inform the client of 571 this fact. The client may then optionally choose to use one of the 572 other versions supported. 574 string "versions" 575 string comma-separated-versions 577 'comma-separated-versions' is a string of comma separated version 578 numbers. Defined versions are: "2", "3", "4", "5", "6". Any other 579 version advertised by the server must follow the DNS extensibility 580 naming convention outlined in [I-D.ietf-secsh-architecture]. 582 For example: "2,3,6,private@example.com". 584 If the client and server have negotiated a a version greater than or 585 equal to version '3' (the version at which SSH_FXP_EXTENDED was 586 introduced) in the initial VERSION/INIT exchange, the client may 587 select a new version to use from the list the server provided using 588 the following SSH_FXP_EXTENDED request. 590 string "version-select" 591 string version-from-list 593 If the 'version-from-list' is one of the versions on the servers 594 list, the server MUST respond with SSH_FX_OK. If the server did not 595 send the "versions" extension, or the version-from-list was not 596 included, the server MAY send a status response describing the 597 failure, but MUST then close the channel without processing any 598 further requests. 600 The 'version-select' MUST be the first request from the client to the 601 server; if it is not, the server MUST fail the request and close the 602 channel. 604 Although this request does take a full round trip, no client need 605 wait for the response before continuing, because any valid request 606 MUST succeed, and any invalid request results in a channel close. 607 Since the request is the first request, it is not possible for the 608 server to have already sent responses conforming to the old version. 610 Typically, the client SHOULD NOT down-grade the protocol version 611 using this extension; however, it is not forbidden to do so. One 612 reason a client might do so is to work around a buggy implementation. 614 5. File Names 616 This protocol represents file names as strings. File names are 617 assumed to use the slash ('/') character as a directory separator. 619 File names starting with a slash are "absolute", and are relative to 620 the root of the file system. Names starting with any other character 621 are relative to the user's default directory (home directory). Note 622 that identifying the user is assumed to take place outside of this 623 protocol. 625 Servers SHOULD interpret a path name component ".." (Section 11) as 626 referring to the parent directory, and "." as referring to the 627 current directory. 629 An empty path name is valid, and it refers to the user's default 630 directory (usually the user's home directory). 632 Otherwise, no syntax is defined for file names by this specification. 633 Clients should not make any other assumptions; however, they can 634 splice path name components returned by SSH_FXP_READDIR together 635 using a slash ('/') as the separator, and that will work as expected. 637 It is understood that the lack of well-defined semantics for file 638 names may cause interoperability problems between clients and servers 639 using radically different operating systems. However, this approach 640 is known to work acceptably with most systems, and alternative 641 approaches that e.g. treat file names as sequences of structured 642 components are quite complicated. 644 The prefered encoding for filenames is UTF-8. This is consistant 645 with IETF Policy on Character Sets and Languages [RFC2277] and it is 646 further supposed that the server is more likely to support any local 647 character set and be able to convert it to UTF-8. 649 However, because the server does not always know the encoding of 650 filenames, it is not always possible for the server to preform a 651 valid translation to UTF-8. When an invalid translation to UTF-8 is 652 preformed, it becomes impossible to manipulate the file, because the 653 translation is not reversable. Therefore, the following extensions 654 are provided in order to make it possible for the server to 655 communicate it's abilities to the client, and to allow the client to 656 control whether the server attempts the conversion. 658 A server MAY include the following extension with it's version 659 packet. 661 string "filename-charset" 662 string charset-name 664 A server that can always provide a valid UTF-8 translation for 665 filenames SHOULD NOT send this extension. Otherwise, the server 666 SHOULD send this extension and include the encoding most likely to be 667 used for filenames. This value will most likely be derived from the 668 LC_CTYPE on most unix-like systems. 670 A server that does not send this extension MUST send all filenames 671 encoded in UTF-8. All clients MUST support UTF-8 filenames. 673 If the server included the 'filename-charset' extension with its 674 VERSION packet, a client MAY send the following extension to turn off 675 server translation to UTF-8. 677 string "filename-translation-control" 678 bool do-translate 680 If the client does not send this extension, the server MUST continue 681 to attempt translation to UTF-8. When a client sends this extension, 682 the server MUST enable filename translation if 'do-translate' is 683 true, or disable filename translation if it is false. 685 The server MUST respond with a STATUS response; if the server sent a 686 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, 687 the status MUST be SSH_FX_OP_UNSUPPORTED. 689 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE 690 data MUST be used. The server is responsible for converting the 691 UNICODE data to whatever canonical form it requires. For example, if 692 the server requires that precomposed characters always be used, the 693 server MUST NOT assume the filename as sent by the client has this 694 attribute, but must do this normalization itself. 696 6. File Attributes 698 A new compound data type, 'ATTRS', is defined for encoding file 699 attributes. The same encoding is used both when returning file 700 attributes from the server and when sending file attributes to the 701 server. 703 uint32 valid-attribute-flags 704 byte type always present 705 uint64 size if flag SIZE 706 uint64 allocation-size if flag ALLOCATION_SIZE 707 string owner if flag OWNERGROUP 708 string group if flag OWNERGROUP 709 uint32 permissions if flag PERMISSIONS 710 int64 atime if flag ACCESSTIME 711 uint32 atime-nseconds if flag SUBSECOND_TIMES 712 int64 createtime if flag CREATETIME 713 uint32 createtime-nseconds if flag SUBSECOND_TIMES 714 int64 mtime if flag MODIFYTIME 715 uint32 mtime-nseconds if flag SUBSECOND_TIMES 716 int64 ctime if flag CTIME 717 uint32 ctime-nseconds if flag SUBSECOND_TIMES 718 string acl if flag ACL 719 uint32 attrib-bits if flag BITS 720 uint32 attrib-bits-valid if flag BITS 721 byte text-hint if flag TEXT_HINT 722 string mime-type if flag MIME_TYPE 723 uint32 link-count if flag LINK_COUNT 724 string untranslated-name if flag UNTRANSLATED_NAME 725 uint32 extended-count if flag EXTENDED 726 extended-pair extensions 728 6.1 valid-attribute-flags 730 The 'valid-attribute-flags' specifies which of the fields are 731 present. Those fields for which the corresponding flag is not set 732 are not present (not included in the packet). 734 The server generally includes all attributes it knows about; however, 735 it may exclude attributes that are overly expensive to retrieve 736 unless the client explicitly requests them. 738 When writing attributes, the server SHOULD NOT modify attributes that 739 are not present in the structure. However, if necessary, the server 740 MAY use a default value for an absent attribute. 742 In general, unless otherwise specified, if a server cannot support 743 writing an attribute requested, it must fail the setstat operation. 744 In this case, none of the attributes SHOULD be changed. 746 New fields can only be added by incrementing the protocol version 747 number (or by using the extension mechanism described below). 749 The following values are defined: 751 SSH_FILEXFER_ATTR_SIZE 0x00000001 752 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 753 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 754 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 755 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 756 SSH_FILEXFER_ATTR_ACL 0x00000040 757 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 758 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 759 SSH_FILEXFER_ATTR_BITS 0x00000200 760 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 761 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 762 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 763 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 764 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 765 SSH_FILEXFER_ATTR_CTIME 0x00008000 766 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 768 0x00000002 was used in a previous version of this protocol. It is 769 now a reserved value and MUST NOT appear in the mask. Some future 770 version of this protocol may reuse this value. 772 6.2 Type 774 The type field is always present. The following types are defined: 776 SSH_FILEXFER_TYPE_REGULAR 1 777 SSH_FILEXFER_TYPE_DIRECTORY 2 778 SSH_FILEXFER_TYPE_SYMLINK 3 779 SSH_FILEXFER_TYPE_SPECIAL 4 780 SSH_FILEXFER_TYPE_UNKNOWN 5 781 SSH_FILEXFER_TYPE_SOCKET 6 782 SSH_FILEXFER_TYPE_CHAR_DEVICE 7 783 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 784 SSH_FILEXFER_TYPE_FIFO 9 786 On a POSIX system, these values would be derived from the mode field 787 of the stat structure. SPECIAL should be used for files that are of 788 a known type which cannot be expressed in the protocol. UNKNOWN 789 should be used if the type is not known. 791 6.3 Size 793 The 'size' field specifies the number of bytes that can be read from 794 the file, or in other words, the location of the end-of-file. This 795 attribute MUST NOT be present during file creation. 797 If this field is present during a setstat operation, the file MUST be 798 extended or truncated to the specified size. 800 Files opened with the SSH_FXF_ACCESS_TEXT flag may have a size that 801 is greater or less than the value of the size field. The server MAY 802 fail setstat operations specifying size for files opened with the 803 SSH_FXF_ACCESS_TEXT flag. 805 6.4 allocation-size 807 The 'allocation-size' field specifies the number of bytes that the 808 file consumes on disk. This field MAY be less than the 'size' field 809 if the file is 'sparse' (Section 6.9). 811 When present during file creation, the file SHOULD be created and the 812 specified number of bytes pre-allocated. If the pre-allocation 813 fails, the file should be removed (if it was created) and an error 814 returned. 816 If this field is present during a setstat operation, the file SHOULD 817 be extended or truncated to the specified size. The 'size' of the 818 file may be affected by this operation. If the operation succeeds, 819 the 'size' should be the minimum of the 'size' before the operation 820 and the new 'allocation-size'. 822 Querying the 'allocation-size' after setting it MUST return a value 823 that is greater-than or equal to the value set, but it MAY not return 824 the precise value set. 826 If both 'size' and 'allocation-size' are set during a setstat 827 operation, and 'allocation-size' is less than 'size', the server MUST 828 return SSH_FX_INVALID_PARAMETER. 830 6.5 Owner and Group 832 The 'owner' and 'group' fields are represented as UTF-8 strings; this 833 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. 834 The following text is selected quotations from section 5.6. 836 To avoid a representation that is tied to a particular underlying 837 implementation at the client or server, the use of UTF-8 strings has 838 been chosen. The string should be of the form "user@dns_domain". 839 This will allow for a client and server that do not use the same 840 local representation the ability to translate to a common syntax that 841 can be interpreted by both. In the case where there is no 842 translation available to the client or server, the attribute value 843 must be constructed without the "@". Therefore, the absence of the @ 844 from the owner or owner_group attribute signifies that no translation 845 was available and the receiver of the attribute should not place any 846 special meaning on the attribute value. Even though the attribute 847 value cannot be translated, it may still be useful. In the case of a 848 client, the attribute string may be used for local display of 849 ownership. 851 user@localhost represents a user in the context of the server. 853 If either the owner or group field is zero length, the field should 854 be considered absent, and no change should be made to that specific 855 field during a modification operation. 857 6.6 Permissions 859 The 'permissions' field contains a bit mask specifying file 860 permissions. These permissions correspond to the st_mode field of 861 the stat structure defined by POSIX [IEEE.1003-1.1996]. 863 This protocol uses the following values for the symbols declared in 864 the POSIX standard. 866 S_IRUSR 0000400 (octal) 867 S_IWUSR 0000200 868 S_IXUSR 0000100 869 S_IRGRP 0000040 870 S_IWGRP 0000020 871 S_IXGRP 0000010 872 S_IROTH 0000004 873 S_IWOTH 0000002 874 S_IXOTH 0000001 875 S_ISUID 0004000 876 S_ISGID 0002000 877 S_ISVTX 0001000 879 Implementations MUST NOT send bits that are not defined. 881 The server SHOULD NOT apply a 'umask' to the mode bits; but should 882 set the mode bits as specified by the client. The client MUST apply 883 an appropriate 'umask' to the mode bits before sending them. 885 6.7 Times 887 The 'atime' field contains the last access time of the file. Many 888 operating systems either don't have this field, only optionally 889 maintain it, or maintain it with less resolution than other fields. 891 The 'mtime' contains the last time the file was written. 893 'createtime' contains the creation time of the file. 895 'ctime' contains the last time the file attrbutes were changed. The 896 exact meaning of this field depends on the server. 898 All times are represented as seconds from Jan 1, 1970 in UTC. A 899 negative value indicates number of seconds before Jan 1, 1970. In 900 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 901 nseconds field is to be added to the seconds field for the final time 902 representation. For example, if the time to be represented is one- 903 half second before 0 hour January 1, 1970, the seconds field would 904 have a value of negative one (-1) and the nseconds fields would have 905 a value of one-half second (500000000). Values greater than 906 999,999,999 for nseconds are considered invalid. 908 6.8 ACL 910 The 'ACL' field contains an ACL similar to that defined in section 911 5.9 of NFS version 4 Protocol [RFC3010]. 913 bool acl-present 914 uint32 ace-count 916 repeated ace-count times: 917 uint32 ace-type 918 uint32 ace-flag 919 uint32 ace-mask 920 string who [UTF-8] 922 If the 'acl-present' flag is not set, it indicates that the file does 923 not have an ACL. In this case the 'ace-count' field is omitted and 924 implicitly zero. This condition indicates that the server both 925 supports ACLs and that it checked the file and found no ACL for this 926 file. This is distinct from the case of SSH_FILEXFER_ATTR_ACL not 927 being present in the attrib flags. If SSH_FILEXFER_ATTR_ACL is not 928 present, the client can not deduce whether the server does not 929 support ACLs, did not check the ACL (because doing so was expensive), 930 or had some other reason for omitting the data. 932 ace-type is one of the following four values (taken from NFS Version 933 4 Protocol [RFC3010]: 935 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 936 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 937 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 938 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 940 ace-flag is a combination of the following flag values. See NFS 941 Version 4 Protocol [RFC3010] section 5.9.2: 943 ACE4_FILE_INHERIT_ACE 0x00000001 944 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 945 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 946 ACE4_INHERIT_ONLY_ACE 0x00000008 947 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 948 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 949 ACE4_IDENTIFIER_GROUP 0x00000040 951 ace-mask is any combination of the following flags (taken from 952 [RFC3010], section 5.9.3. The semantic meaning of these flags is 953 also given in [RFC3010]. 955 ACE4_READ_DATA 0x00000001 956 ACE4_LIST_DIRECTORY 0x00000001 957 ACE4_WRITE_DATA 0x00000002 958 ACE4_ADD_FILE 0x00000002 959 ACE4_APPEND_DATA 0x00000004 960 ACE4_ADD_SUBDIRECTORY 0x00000004 961 ACE4_READ_NAMED_ATTRS 0x00000008 962 ACE4_WRITE_NAMED_ATTRS 0x00000010 963 ACE4_EXECUTE 0x00000020 964 ACE4_DELETE_CHILD 0x00000040 965 ACE4_READ_ATTRIBUTES 0x00000080 966 ACE4_WRITE_ATTRIBUTES 0x00000100 967 ACE4_DELETE 0x00010000 968 ACE4_READ_ACL 0x00020000 969 ACE4_WRITE_ACL 0x00040000 970 ACE4_WRITE_OWNER 0x00080000 971 ACE4_SYNCHRONIZE 0x00100000 973 who is a UTF-8 string of the form described in 'Owner and Group' 974 (Section 6.5) 976 Also, as per '5.9.4 ACE who' [RFC3010] there are several identifiers 977 that need to be understood universally. Some of these identifiers 978 cannot be understood when an client access the server, but have 979 meaning when a local process accesses the file. The ability to 980 display and modify these permissions is permitted over SFTP. 982 OWNER The owner of the file. 983 GROUP The group associated with the file. 984 EVERYONE The world. 985 INTERACTIVE Accessed from an interactive terminal. 986 NETWORK Accessed via the network. 987 DIALUP Accessed as a dialup user to the server. 988 BATCH Accessed from a batch job. 990 ANONYMOUS Accessed without any authentication. 991 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 992 SERVICE Access from a system service. 994 To avoid conflict, these special identifiers are distinguish by an 995 appended "@". For example: ANONYMOUS@. 997 6.9 attrib-bits and attrib-bits-valid 999 These fields, taken together, reflect various attributes of the file 1000 or directory, on the server. 1002 Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- 1003 bits' field. This allows both the server and the client to 1004 communicate only the bits it knows about without inadvertantly 1005 twiddling bits they don't understand. 1007 The following attrib-bits are defined: 1009 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 1010 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 1011 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 1012 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 1013 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 1014 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 1015 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 1016 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 1017 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 1018 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 1019 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 1020 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 1022 SSH_FILEXFER_ATTR_FLAGS_READONLY 1023 Advisory, read-only bit. This bit is not part of the access 1024 control information on the file, but is rather an advisory field 1025 indicating that the file should not be written. 1027 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 1028 The file is part of the operating system. 1030 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 1031 File SHOULD NOT be shown to user unless specifically requested. 1032 For example, most UNIX systems SHOULD set this bit if the filename 1033 begins with a 'period'. This bit may be read-only (Section 4.5). 1034 Most UNIX systems will not allow this to be changed. 1036 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 1037 This attribute applies only to directories. This attribute is 1038 always read-only, and cannot be modified. This attribute means 1039 that files and directory names in this directory should be 1040 compared without regard to case. 1042 It is recommended that where possible, the server's filesystem be 1043 allowed to do comparisons. For example, if a client wished to 1044 prompt a user before overwriting a file, it should not compare the 1045 new name with the previously retrieved list of names in the 1046 directory. Rather, it should first try to create the new file by 1047 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 1048 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 1049 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 1051 Unless otherwise specified, filenames are assumed to be case 1052 sensitive. 1054 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 1055 The file should be included in backup / archive operations. 1057 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 1058 The file is stored on disk using file-system level transparent 1059 encryption. This flag does not affect the file data on the wire 1060 (for either READ or WRITE requests.) 1062 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 1063 The file is stored on disk using file-system level transparent 1064 compression. This flag does not affect the file data on the wire. 1066 SSH_FILEXFER_ATTR_FLAGS_SPARSE 1067 The file is a sparse file; this means that file blocks that have 1068 not been explicitly written are not stored on disk. For example, 1069 if a client writes a buffer at 10 M from the beginning of the 1070 file, the blocks between the previous EOF marker and the 10 M 1071 offset would not consume physical disk space. 1073 Some servers may store all files as sparse files, in which case 1074 this bit will be unconditionally set. Other servers may not have 1075 a mechanism for determining if the file is sparse, and so the file 1076 MAY be stored sparse even if this flag is not set. 1078 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 1079 Opening the file without either the SSH_FXF_ACCESS_APPEND_DATA or 1080 the SSH_FXF_ACCESS_APPEND_DATA_ATOMIC flag (Section 7.1.1.3) MUST 1081 result in an SSH_FX_INVALID_PARAMETER error. 1083 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 1084 The file cannot be deleted or renamed, no hard link can be created 1085 to this file, and no data can be written to the file. 1087 This bit implies a stronger level of protection than 1088 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 1089 ACLs. Typically even the superuser cannot write to immutable 1090 files, and only the superuser can set or remove the bit. 1092 SSH_FILEXFER_ATTR_FLAGS_SYNC 1093 When the file is modified, the changes are written synchronously 1094 to the disk. 1096 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 1097 The server MAY include this bit in a directory listing or realpath 1098 response. It indicates there was a failure in the translation to 1099 UTF-8. If this flag is included, the server SHOULD also include 1100 the UNTRANSLATED_NAME attribute. 1102 6.10 text-hint 1104 The value is one of the following enumerations, and indicates what 1105 the server knows about the content of the file. 1107 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 1108 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 1109 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 1110 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 1112 SSH_FILEXFER_ATTR_KNOWN_TEXT 1113 The server knows the file is a text file, and should be opened 1114 using the SSH_FXF_ACCESS_TEXT_MODE flag. 1116 SSH_FILEXFER_ATTR_GUESSED_TEXT 1117 The server has applied a hueristic or other mechanism and believes 1118 that the file should be opened with the SSH_FXF_ACCESS_TEXT_MODE 1119 flag. 1121 SSH_FILEXFER_ATTR_KNOWN_BINARY 1122 The server knows the file has binary content. 1124 SSH_FILEXFER_ATTR_GUESSED_BINARY 1125 The server has applied a hueristic or other mechanism and believes 1126 has binary content, and should not be opened with the 1127 SSH_FXF_ACCESS_TEXT_MODE flag. 1129 This flag MUST NOT be present during either a setstat or a fsetstat 1130 operation. 1132 6.11 mime-type 1134 The 'mime-type' field contains the mime-type [RFC1521] string. Most 1135 servers will not know this information and should not set the bit in 1136 their supported-attribute-mask. 1138 6.12 link-count 1140 This field contains the hard link count of the file. This attribute 1141 MUST NOT be present during a setstat operation. 1143 6.13 untranslated-name 1145 This field contains the name before filename translation was attempt. 1146 It MUST NOT be included unless the server also set the 1147 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 6.9) bit in the 1148 attrib-bits field. 1150 6.14 Extended Attributes 1152 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 1153 mechanism for the attrib structure. If the flag is specified, then 1154 the 'extended_count' field is present. It specifies the number of 1155 'extension-pair' items that follow. Each of these items specifies an 1156 extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED 1157 if there are any unrecognized extensions. Clients can avoid sending 1158 unsupported extensions by examining the attrib-extension-names of the 1159 "supported2" extension attrib-extension-names (Section 4.5). 1161 Additional fields can be added to the attributes by either defining 1162 additional bits to the flags field to indicate their presence, or by 1163 defining extended attributes for them. The extended attributes 1164 mechanism is recommended for most purposes; additional flags bits 1165 should be defined only by an IETF standards action that also 1166 increments the protocol version number. The use of such new fields 1167 MUST be negotiated by the version number in the protocol exchange. 1168 It is a protocol error if a packet with unsupported protocol bits is 1169 received. 1171 7. Requests From the Client to the Server 1173 Requests from the client to the server represent the various file 1174 system operations. 1176 7.1 Opening and Closing Files and Directories 1178 Many operations in the protocol operate on open files. The 1179 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 1180 an opaque, variable-length string) which may be used to access the 1181 file or directory later. The client MUST NOT send requests to the 1182 server with bogus or closed handles. However, the server MUST 1183 perform adequate checks on the handle in order to avoid security 1184 risks due to fabricated handles. 1186 This design allows either stateful and stateless server 1187 implementation, as well as an implementation which caches state 1188 between requests but may also flush it. The contents of the file 1189 handle string are entirely up to the server and its design. The 1190 client should not modify or attempt to interpret the file handle 1191 strings. 1193 The file handle strings MUST NOT be longer than 256 bytes. 1195 7.1.1 Opening a File 1197 Files are opened and created using the SSH_FXP_OPEN message. 1199 byte SSH_FXP_OPEN 1200 uint32 request-id 1201 string filename [UTF-8] 1202 uint32 desired-access 1203 uint32 flags 1204 ATTRS attrs 1206 The response to this message will be either SSH_FXP_HANDLE (if the 1207 operation is successful) or SSH_FXP_STATUS (if the operation fails.) 1209 7.1.1.1 filename 1211 The 'filename' field specifies the file name. See Section ''File 1212 Names'' for more information. If 'filename' is a directory file, the 1213 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 1215 7.1.1.2 desired-access 1217 The 'desired-access' field is a bitmask containing a combination of 1218 values from the ace-mask flags (Section 6.8). Note that again, the 1219 meaning of these flags is given in [RFC3010]. 1221 The server MUST be prepared to translate the SFTP access flags into 1222 its local equivalents. If the server cannot grant the access 1223 desired, it MUST return SSH_FX_PERMISSION_DENIED. 1225 The server MAY open the file with greater access than requested if 1226 the user has such access and the server implementation requires it. 1227 For example, a server that does not distinguish between 1228 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access 1229 to the file when the client only requested READ_ATTRIBUTE, resulting 1230 in greater access than the client originaly requested. 1232 In such cases, it is possible, and permissable in the protocol, that 1233 the client could open a file requesting some limited access, and then 1234 access the file in a way not permitted by that limited access and the 1235 server would permit such action. However, the server MUST NOT ever 1236 grant access to the file that the client does not actually have the 1237 rights to. 1239 7.1.1.3 flags 1241 The 'flags' field controls various aspects of the operation, 1242 including whether or not the file is created and the kind of locking 1243 desired. 1245 The following 'flags' are defined: 1247 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 1248 SSH_FXF_CREATE_NEW = 0x00000000 1249 SSH_FXF_CREATE_TRUNCATE = 0x00000001 1250 SSH_FXF_OPEN_EXISTING = 0x00000002 1251 SSH_FXF_OPEN_OR_CREATE = 0x00000003 1252 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 1253 SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 1254 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 1255 SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 1256 SSH_FXF_ACCESS_BLOCK_READ = 0x00000040 1257 SSH_FXF_ACCESS_BLOCK_WRITE = 0x00000080 1258 SSH_FXF_ACCESS_BLOCK_DELETE = 0x00000100 1259 SSH_FXF_ACCESS_BLOCK_ADVISORY = 0x00000200 1260 SSH_FXF_ACCESS_NOFOLLOW = 0x00000400 1261 SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000800 1263 SSH_FXF_ACCESS_DISPOSITION 1264 Disposition is a 3 bit field that controls how the file is opened. 1265 The server MUST support these bits. Any one of the following 1266 enumeration is allowed: 1268 SSH_FXF_CREATE_NEW 1269 A new file is created; if the file already exists, the server 1270 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 1272 SSH_FXF_CREATE_TRUNCATE 1273 A new file is created; if the file already exists, it is opened 1274 and truncated. 1276 SSH_FXF_OPEN_EXISTING 1277 An existing file is opened. If the file does not exist, the 1278 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 1279 path does not exist, the server SHOULD return 1280 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 1281 returns SSH_FX_NO_SUCH_FILE in this case. 1283 SSH_FXF_OPEN_OR_CREATE 1284 If the file exists, it is opened. If the file does not exist, 1285 it is created. 1287 SSH_FXF_TRUNCATE_EXISTING 1288 An existing file is opened and truncated. If the file does not 1289 exist, the server MUST return the same error codes as defined 1290 for SSH_FXF_OPEN_EXISTING. 1292 SSH_FXF_ACCESS_APPEND_DATA 1293 Data is always written at the end of the file. The offset field 1294 of the SSH_FXP_WRITE requests are ignored. 1296 Data is not required to be appended atomically. This means that 1297 if multiple writers attempt to append data simultaneously, data 1298 from the first may be lost. However, data MAY be appended 1299 atomically. 1301 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1302 Data is always written at the end of the file. The offset field 1303 of the SSH_FXP_WRITE requests are ignored. 1305 Data MUST be written atomically so that there is no chance that 1306 multiple appenders can collide and result in data being lost. 1308 If both append flags are specified, the server SHOULD use atomic 1309 append if it is available, but SHOULD use non-atomic appends 1310 otherwise. The server SHOULD NOT fail the request in this case. 1312 SSH_FXF_ACCESS_TEXT_MODE 1313 Indicates that the server should treat the file as text and 1314 convert it to the canonical newline convention in use. (See 1315 Determining Server Newline Convention. (Section 4.3) 1316 When a file is opened with this flag, the offset field in the read 1317 and write functions is ignored. 1319 Servers MUST process multiple, parallel reads and writes correctly 1320 in this mode. Naturally, it is permissible for them to do this by 1321 serializing the requests. 1323 Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append 1324 data to a text file rather then using write with a calculated 1325 offset. 1327 To support seeks on text files the following SSH_FXP_EXTENDED 1328 packet is defined. 1330 string "text-seek" 1331 string file-handle 1332 uint64 line-number 1334 line-number is the index of the line number to seek to, where byte 1335 0 in the file is line number 0, and the byte directly following 1336 the first newline sequence in the file is line number 1 and so on. 1338 The response to a "text-seek" request is an SSH_FXP_STATUS 1339 message. 1341 An attempt to seek past the end-of-file should result in a 1342 SSH_FX_EOF status. 1344 Servers SHOULD support at least one "text-seek" in order to 1345 support resume. However, a client MUST be prepared to receive 1346 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 1347 The client can then try a fall-back strategy, if it has one. 1349 SSH_FXF_ACCESS_BLOCK_READ 1350 The server MUST guarantee that no other handle has been opened 1351 with ACE4_READ_DATA access, and that no other handle will be 1352 opened with ACE4_READ_DATA access until the client closes the 1353 handle. (This MUST apply both to other clients and to other 1354 processes on the server.) 1356 If there is a conflicting lock the server MUST return 1357 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1358 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1360 Other handles MAY be opened for ACE4_WRITE_DATA or any other 1361 combinatation of accesses, as long as ACE4_READ_DATA is not 1362 included in the mask. 1364 SSH_FXF_ACCESS_BLOCK_WRITE 1365 The server MUST guarantee that no other handle has been opened 1366 with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other 1367 handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA 1368 access until the client closes the handle. (This MUST apply both 1369 to other clients and to other processes on the server.) 1371 If there is a conflicting lock the server MUST return 1372 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1373 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1375 Other handles MAY be opened for ACE4_READ_DATA or any other 1376 combinatation of accesses, as long as neither ACE4_WRITE_DATA nor 1377 ACE4_APPEND_DATA are included in the mask. 1379 SSH_FXF_ACCESS_BLOCK_DELETE 1380 The server MUST guarantee that no other handle has been opened 1381 with ACE4_DELETE access, opened with the 1382 SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that no other handle 1383 will be opened with ACE4_DELETE access or with the 1384 SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that the file itself 1385 is not deleted in any other way until the client closes the 1386 handle. 1388 If there is a conflicting lock the server MUST return 1389 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1390 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1392 SSH_FXF_ACCESS_BLOCK_ADVISORY 1393 If this bit is set, the above BLOCK modes are advisory. In 1394 advisory mode, only other accesses that specify a BLOCK mode need 1395 be considered when determining whether the BLOCK can be granted, 1396 and the server need not prevent I/O operations that violate the 1397 block mode. 1399 The server MAY perform mandatory locking even if the 1400 BLOCK_ADVISORY bit is set. 1402 SSH_FXF_ACCESS_NOFOLLOW 1403 If the final component of the path is a symlink, then the open 1404 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 1406 SSH_FXF_ACCESS_DELETE_ON_CLOSE 1407 The file should be deleted when the last handle to it is closed. 1408 (The last handle may not be an sftp-handle.) This MAY be emulated 1409 by a server if the OS doesn't support it by deleting the file when 1410 this handle is closed. 1412 It is implementation specific whether the directory entry is 1413 removed immediately or when the handle is closed. 1415 The 'attrs' field specifies the initial attributes for the file. 1416 Default values MUST be supplied by the server for those attributes 1417 that are not specified. See Section ''File Attributes'' for more 1418 information. 1420 The 'attrs' field is ignored if an existing file is opened. 1422 The following table is provided to assist in mapping POSIX semantics 1423 to equivalent SFTP file open parameters: 1424 O_RDONLY 1425 desired-access = READ_DATA|READ_ATTRIBUTES 1427 O_WRONLY 1428 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1430 O_RDWR 1431 desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA| 1432 WRITE_ATTRIBUTES 1434 O_APPEND 1435 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1436 flags = SSH_FXF_ACCESS_APPEND_DATA and or 1437 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1439 O_CREAT 1440 flags = SSH_FXF_OPEN_OR_CREATE 1442 O_TRUNC 1443 flags = SSH_FXF_TRUNCATE_EXISTING 1445 O_TRUNC|O_CREATE 1446 flags = SSH_FXF_CREATE_TRUNCATE 1448 7.1.2 Opening a Directory 1450 To enumerate a directory, the client first obtains a handle and then 1451 issues directory read requests. When enumeration is complete, the 1452 handle MUST be closed. 1454 byte SSH_FXP_OPENDIR 1455 uint32 request-id 1456 string path [UTF-8] 1458 path 1459 The 'path' field is the path name of the directory to be listed 1460 (without any trailing slash). See Section 'File Names' for more 1461 information on file names. 1463 If 'path' does not refer to a directory, the server MUST return 1464 SSH_FX_NOT_A_DIRECTORY. 1466 The response to this message will be either SSH_FXP_HANDLE (if the 1467 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1469 7.1.3 Closing Handles 1471 A handle is closed using the following request. 1473 byte SSH_FXP_CLOSE 1474 uint32 request-id 1475 string handle 1477 handle 1478 'handle' is a handle previously returned in the response to 1479 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid 1480 immediately after this request has been sent. 1482 The response to this request will be a SSH_FXP_STATUS message. Note 1483 that on some server platforms even a close can fail. For example, if 1484 the server operating system caches writes, and an error occurs while 1485 flushing cached writes, the close operation may fail. 1487 Note that the handle is invalid regardless of the SSH_FXP_STATUS 1488 result. There is no way for the client to recover a handle that 1489 fails to close. The client MUST release all resources associated 1490 with the handle regardless of the status. The server SHOULD take 1491 whatever steps it can to recover from a close failure and to ensure 1492 that all resources associated with the handle on the server are 1493 correctly released. 1495 7.2 Reading and Writing 1497 7.2.1 Reading Files 1499 The following request can be used to read file data: 1501 byte SSH_FXP_READ 1502 uint32 request-id 1503 string handle 1504 uint64 offset 1505 uint32 length 1507 handle 1508 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1509 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1510 return SSH_FX_INVALID_HANDLE. 1512 offset 1513 The offset (in bytes) relative to the beginning of the file that 1514 the read MUST start at. This field is ignored if 1515 SSH_FXF_ACCESS_TEXT_MODE was specified during the open. 1517 length 1518 'length' is the maximum number of bytes to read. 1520 The server MUST not respond with more data than is specified by 1521 the 'length' parameter. However, the server MAY respond with less 1522 data if EOF is reached, an error is encountered, or the servers 1523 internal buffers can not handle such a large request. 1525 If the server specified a non-zero 'max-read-size' in its 1526 'supported2' (Section 4.5) extension, then failure to return 1527 'length' bytes indicates that EOF or an error occured. 1529 7.2.2 Reading Directories 1531 In order to retrieve a directory listing, the client issues one or 1532 more SSH_FXP_READDIR requests. In order to obtain a complete 1533 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1534 requests until the server responds with an SSH_FXP_STATUS message. 1536 byte SSH_FXP_READDIR 1537 uint32 request-id 1538 string handle 1540 handle 1541 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is 1542 an ordinary file handle returned by SSH_FXP_OPEN, the server MUST 1543 return SSH_FX_INVALID_HANDLE. 1545 The server responds to this request with either a SSH_FXP_NAME or a 1546 SSH_FXP_STATUS message. One or more names may be returned at a time. 1548 Full status information is returned for each name in order to speed 1549 up typical directory listings. 1551 If there are no more names available to be read, the server MUST 1552 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1554 7.2.3 Writing Files 1556 Writing to a file is achieved using the following message: 1558 byte SSH_FXP_WRITE 1559 uint32 request-id 1560 string handle 1561 uint64 offset 1562 string data 1564 handle 1565 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1566 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1567 return SSH_FX_INVALID_HANDLE. 1569 offset 1570 The offset (in bytes) relative to the beginning of the file that 1571 the write MUST start at. This field is ignored if 1572 SSH_FXF_ACCESS_TEXT_MODE was specified during the open. 1574 The write will extend the file if writing beyond the end of the 1575 file. It is legal to write to an offset that extends beyond the 1576 end of the file; the semantics are to write the byte value 0x00 1577 from the end of the file to the specified offset and then the 1578 data. On most operating systems, such writes do not allocate disk 1579 space but instead create a sparse file. 1581 data 1582 The data to write to the file. 1584 The server responds to a write request with a SSH_FXP_STATUS message. 1586 7.3 Removing and Renaming Files 1588 The following request can be used to remove a file: 1590 byte SSH_FXP_REMOVE 1591 uint32 request-id 1592 string filename [UTF-8] 1594 filename 1595 'filename' is the name of the file to be removed. See Section 1596 'File Names' for more information. 1598 This request cannot be used to remove directories. The server 1599 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. 1601 The server will respond to this request with a SSH_FXP_STATUS 1602 message. 1604 Files (and directories) can be renamed using the SSH_FXP_RENAME 1605 message. 1607 byte SSH_FXP_RENAME 1608 uint32 request-id 1609 string oldpath [UTF-8] 1610 string newpath [UTF-8] 1611 uint32 flags 1613 where 'request-id' is the request identifier, 'oldpath' is the name 1614 of an existing file or directory, and 'newpath' is the new name for 1615 the file or directory. 1617 'flags' is 0 or a combination of: 1619 SSH_FXP_RENAME_OVERWRITE 0x00000001 1620 SSH_FXP_RENAME_ATOMIC 0x00000002 1621 SSH_FXP_RENAME_NATIVE 0x00000004 1623 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1624 exists a file with the name specified by newpath, the server MUST 1625 respond with SSH_FX_FILE_ALREADY_EXISTS. 1627 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1628 already exists, it is replaced in an atomic fashion. I.e., there is 1629 no observable instant in time where the name does not refer to either 1630 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1631 SSH_FXP_RENAME_OVERWRITE. 1633 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace 1634 the destination in an atomic fashion, then the server MUST respond 1635 with SSH_FX_OP_UNSUPPORTED. 1637 Because some servers cannot provide atomic rename, clients should 1638 only specify atomic rename if correct operation requires it. If 1639 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1640 atomic rename even if it is not requested. 1642 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1643 rename operation in whatever fashion it deems appropriate. Other 1644 flag values are considered hints as to desired behavior, but not 1645 requirements. 1647 The server will respond to this request with a SSH_FXP_STATUS 1648 message. 1650 7.4 Creating and Deleting Directories 1652 New directories can be created using the SSH_FXP_MKDIR request. It 1653 has the following format: 1655 byte SSH_FXP_MKDIR 1656 uint32 request-id 1657 string path [UTF-8] 1658 ATTRS attrs 1660 where 'request-id' is the request identifier. 1662 'path' specifies the directory to be created. See Section ''File 1663 Names'' for more information on file names. 1665 'attrs' specifies the attributes that should be applied to it upon 1666 creation. Attributes are discussed in more detail in Section ''File 1667 Attributes''. 1669 The server will respond to this request with a SSH_FXP_STATUS 1670 message. If a file or directory with the specified path already 1671 exists, an error will be returned. 1673 Directories can be removed using the SSH_FXP_RMDIR request, which has 1674 the following format: 1676 byte SSH_FXP_RMDIR 1677 uint32 request-id 1678 string path [UTF-8] 1680 where 'request-id' is the request identifier, and 'path' specifies 1681 the directory to be removed. See Section ''File Names'' for more 1682 information on file names. 1684 The server responds to this request with a SSH_FXP_STATUS message. 1686 7.5 Retrieving File Attributes 1688 Very often, file attributes are automatically returned by 1689 SSH_FXP_READDIR. However, sometimes there is need to specifically 1690 retrieve the attributes for a named file. This can be done using the 1691 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1693 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1694 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1695 follow symbolic links. Both have the same format: 1697 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1698 uint32 request-id 1699 string path [UTF-8] 1700 uint32 flags 1702 where 'request-id' is the request identifier, and 'path' specifies 1703 the file system object for which status is to be returned. The 1704 server responds to this request with either SSH_FXP_ATTRS or 1705 SSH_FXP_STATUS. 1707 The flags field specify the attribute flags in which the client has 1708 particular interest. This is a hint to the server. For example, 1709 because retrieving owner / group and acl information can be an 1710 expensive operation under some operating systems, the server may 1711 choose not to retrieve this information unless the client expresses a 1712 specific interest in it. 1714 The client has no guarantee the server will provide all the fields 1715 that it has expressed an interest in. 1717 SSH_FXP_FSTAT differs from the others in that it returns status 1718 information for an open file (identified by the file handle). 1720 byte SSH_FXP_FSTAT 1721 uint32 request-id 1722 string handle 1723 uint32 flags 1725 handle 1726 'handle' is an open file handle from either SSH_FXP_OPEN or 1727 SSH_FXP_OPENDIR. 1729 The server responds to this request with SSH_FXP_ATTRS or 1730 SSH_FXP_STATUS. 1732 7.6 Setting File Attributes 1734 File attributes may be modified using the SSH_FXP_SETSTAT and 1735 SSH_FXP_FSETSTAT requests. 1737 byte SSH_FXP_SETSTAT 1738 uint32 request-id 1739 string path [UTF-8] 1740 ATTRS attrs 1742 byte SSH_FXP_FSETSTAT 1743 uint32 request-id 1744 string handle 1745 ATTRS attrs 1747 path 1748 The file system object (e.g. file or directory) whose attributes 1749 are to be modified. If this object does not exist, or the user 1750 does not have sufficient access to write the attributes, the 1751 request MUST fail. 1753 handle 1754 'handle' is an open file handle from either SSH_FXP_OPEN or 1755 SSH_FXP_OPENDIR. If the handle was not opened with sufficient 1756 access to write the requested attributes, the request MUST fail. 1758 attrs 1759 Specifies the modified attributes to be applied. Attributes are 1760 discussed in more detail in Section ''File Attributes''. 1762 The server will respond with a SSH_FXP_STATUS message. 1764 Because some systems must use separate system calls to set various 1765 attributes, it is possible that a failure response will be returned, 1766 but yet some of the attributes may be have been successfully 1767 modified. If possible, servers SHOULD avoid this situation; however, 1768 clients MUST be aware that this is possible. 1770 7.7 Dealing with Links 1772 The SSH_FXP_READLINK request reads the target of a symbolic link. 1774 byte SSH_FXP_READLINK 1775 uint32 request-id 1776 string path [UTF-8] 1778 where 'request-id' is the request identifier and 'path' specifies the 1779 path name of the symlink to be read. 1781 The server will respond with a SSH_FXP_NAME packet containing only 1782 one name and a dummy attributes value. The name in the returned 1783 packet contains the target of the link. If an error occurs, the 1784 server MAY respond with SSH_FXP_STATUS. 1786 The SSH_FXP_LINK request creates a link (either hard or symbolic) on 1787 the server. 1789 byte SSH_FXP_LINK 1790 uint32 request-id 1791 string new-link-path [UTF-8] 1792 string existing-path [UTF-8] 1793 bool sym-link 1795 new-link-path 1796 Specifies the path name of the new link to create. 1798 existing-path 1799 Specifies the path of an existing file system object to which the 1800 new-link-path will refer. 1802 sym-link 1803 Specifies that the link should be a symbolic link, or a special 1804 file that redirects file system parsing to the resulting path. It 1805 is generally possible to create symbolic links across device 1806 boundaries; however, it is not required that a server support 1807 this. 1809 If 'sym-link' is false, the link should be a hard link, or a 1810 second directory entry refering to the same file or directory 1811 object. It is generally not possible to create hard links across 1812 devices. 1814 The server shall respond with a SSH_FXP_STATUS. Clients should be 1815 aware that some servers may return SSH_FX_OP_UNSUPPORTED for either 1816 the hard-link, sym-link, or both operations. 1818 7.8 Byte-range locks 1820 SSH_FXP_BLOCK creates a byte-range lock on the file specified by the 1821 handle. The lock can be either mandatory (meaning that the server 1822 enforces that no other process or client can perform operations in 1823 violation of the lock) or advisory (meaning that no other process can 1824 obtain a conflicting lock, but the server does not enforce that no 1825 operation violates the lock. 1827 A server MAY implement an advisory lock in a mandatory fashion; in 1828 other words, the server MAY enforce that no operation violates the 1829 lock even when operating in advisory mode. 1831 The result is a SSH_FXP_STATUS return. 1833 byte SSH_FXP_BLOCK 1834 uint32 request-id 1835 string handle 1836 uint64 offset 1837 uint64 length 1838 uint32 uLockMask 1840 handle 1841 'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. 1842 Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the 1843 handle is a directory handle. 1845 offset 1846 Beginning of the byte-range to lock. 1848 length 1849 Number of bytes in the range to lock. The special value 0 means 1850 lock from 'offset' to the end of the file. 1852 uLockMask 1853 A bit mask of SSH_FXF_ACCESS_BLOCK_* values; the meanings are 1854 described in Section 7.1.1.3. 1856 SSH_FXP_UNBLOCK removes a previously aquired byte-range lock on the 1857 specified handle. 1859 The result is a SSH_FXP_STATUS return. 1861 byte SSH_FXP_UNBLOCK 1862 uint32 request-id 1863 string handle 1864 uint64 offset 1865 uint64 length 1867 handle 1868 'handle' on which a SSH_FXP_BLOCK request has previously been 1869 issued. 1871 offset 1872 Beginning of the byte-range to lock. 1874 length 1875 Number of bytes in the range to lock. The special value 0 means 1876 lock from 'offset' to the end of the file. 1878 7.9 Canonicalizing the Server-Side Path Name 1880 The SSH_FXP_REALPATH request can be used to have the server 1881 canonicalize any given path name to an absolute path. This is useful 1882 for converting path names containing ".." components or relative 1883 pathnames without a leading slash into absolute paths. The format of 1884 the request is as follows: 1886 byte SSH_FXP_REALPATH 1887 uint32 request-id 1888 string original-path [UTF-8] 1889 byte control-byte [optional] 1890 string compose-path[0..n] [optional] 1892 original-path 1893 The first component of the path which the client wishes resolved 1894 into a absolute canonical path. This may be the entire path. 1896 control-byte 1898 SSH_FXP_REALPATH_NO_CHECK 0x00000001 1899 SSH_FXP_REALPATH_STAT_IF 0x00000002 1900 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 1902 This field is optional, and if it is not present in the packet, it 1903 is assumed to be SSH_FXP_REALPATH_NO_CHECK. 1905 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT 1906 fail the request if the path does not exist, is hidden, or the 1907 user does not have access to the path or some component thereof. 1908 However, the path MAY NOT be completely resolved to it's component 1909 form. For example, symlinks may not be followed in this case. 1910 The server MAY fail the request if the path is not syntactically 1911 valid, or for other reasons. 1913 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the 1914 path if it exists and is accessible to the client. However, if 1915 the path does not exist, isn't visible, or isn't accessible, the 1916 server MUST NOT fail the request. If the stat failed, the file 1917 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to 1918 distinguish between files that are actually 1919 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will 1920 have to issue a seperate stat command in this case. 1922 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat 1923 the path. If the stat operation fails, the server MUST fail the 1924 request. 1926 compose-path 1927 A path which the client wishs the server to compose with the 1928 original path to form the new path. This field is optional, and 1929 if it is not present in the packet, it is assumed to be a zero 1930 length string. 1932 The client may specify multiple 'compose-path' elements, in which 1933 case the server should build the resultant path up by applying 1934 each compose path to the accumulated result until all 'compose- 1935 path' elements have been applied. 1937 The server MUST take the 'original-path' and apply the 'compose-path' 1938 as a modification to it. 'compose-path' MAY be relative to 'original- 1939 path' or may be an absolute path, in which case 'original-path' will 1940 be discarded. The 'compose-path' MAY be zero length. 1942 The server will respond with a SSH_FXP_NAME packet containing the 1943 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK 1944 is specified, the attributes are dummy values. 1946 7.9.1 Best Practice for Dealing with Paths 1948 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 1950 Previous to this version, clients typically composed new paths 1951 themselves and then called both realpath and stat on the resulting 1952 path to get its canonical name and see if it really existed and was a 1953 directory. 1955 This required clients to assume certain things about how a relative 1956 vs. realpath looked. The new realpath allows clients to no longer 1957 make those assumptions and to remove one round trip from the process 1958 and get deterministic behavior from all servers. 1960 END: RFCEDITOR REMOVE BEFORE PUBLISHING 1962 The client SHOULD treat the results of SSH_FXP_REALPATH as a 1963 canonical absolute path, even if the path does not appear to be 1964 absolute. A client that uses REALPATH(".", "") and treats the result 1965 as absolute, even if there is no leading slash, will continue to 1966 function correctly, even when talking to a Windows NT or VMS style 1967 system, where absolute paths may not begin with a slash. 1969 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so 1970 that it does not need to know when a path is absolute or relative. 1972 For example, if the client wishes to change directory up, and the 1973 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 1974 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) 1976 As a second example, if the client wishes transfer local file "a" to 1977 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the 1978 canonical path of the current directory, the client SHOULD send 1979 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This 1980 call will determine the correct path to use for the open request and 1981 whether the /b/d/e represents a directory. 1983 8. Responses from the Server to the Client 1985 The server responds to the client using one of a few response 1986 packets. All requests can return a SSH_FXP_STATUS response upon 1987 failure. When the operation is successful, and no data needs to be 1988 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 1989 appropriate. 1991 Exactly one response will be returned for each request. Each 1992 response packet contains a request identifier which can be used to 1993 match each response with the corresponding request. Note that it is 1994 legal to have several requests outstanding simultaneously, and the 1995 server is allowed to send responses to them in a different order from 1996 the order in which the requests were sent (the result of their 1997 execution, however, is guaranteed to be as if they had been processed 1998 one at a time in the order in which the requests were sent). 2000 Response packets are of the same general format as request packets. 2001 Each response packet begins with the request identifier. 2003 8.1 Status Response 2005 The format of the data portion of the SSH_FXP_STATUS response is as 2006 follows: 2008 byte SSH_FXP_STATUS 2009 uint32 request-id 2010 uint32 error/status code 2011 string error message (ISO-10646 UTF-8 [RFC-2279]) 2012 string language tag (as defined in [RFC-1766]) 2013 error-specific data 2015 request-id 2016 The 'request-id' specified by the client in the request the server 2017 is responding to. 2019 error/status code 2020 Machine readable status code indicating the result of the request. 2021 Error code values are defined below. The value SSH_FX_OK 2022 indicates success, and all other values indicate failure. 2024 error message 2025 Human readable description of the error. 2027 language tag 2028 'language tag' specifies the language the error is in. 2030 error-specific data 2031 The error-specific data may be empty, or may contain additional 2032 information about the error. For error codes that send error- 2033 specific data, the format of the data is defined below. 2035 Error codes: 2037 SSH_FX_OK 0 2038 SSH_FX_EOF 1 2039 SSH_FX_NO_SUCH_FILE 2 2040 SSH_FX_PERMISSION_DENIED 3 2041 SSH_FX_FAILURE 4 2042 SSH_FX_BAD_MESSAGE 5 2043 SSH_FX_NO_CONNECTION 6 2044 SSH_FX_CONNECTION_LOST 7 2045 SSH_FX_OP_UNSUPPORTED 8 2046 SSH_FX_INVALID_HANDLE 9 2047 SSH_FX_NO_SUCH_PATH 10 2048 SSH_FX_FILE_ALREADY_EXISTS 11 2049 SSH_FX_WRITE_PROTECT 12 2050 SSH_FX_NO_MEDIA 13 2051 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 2052 SSH_FX_QUOTA_EXCEEDED 15 2053 SSH_FX_UNKNOWN_PRINCIPAL 16 2054 SSH_FX_LOCK_CONFLICT 17 2055 SSH_FX_DIR_NOT_EMPTY 18 2056 SSH_FX_NOT_A_DIRECTORY 19 2057 SSH_FX_INVALID_FILENAME 20 2058 SSH_FX_LINK_LOOP 21 2059 SSH_FX_CANNOT_DELETE 22 2060 SSH_FX_INVALID_PARAMETER 23 2061 SSH_FX_FILE_IS_A_DIRECTORY 24 2062 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 2063 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 2064 SSH_FX_DELETE_PENDING 27 2065 SSH_FX_FILE_CORRUPT 28 2067 SSH_FX_OK 2068 Indicates successful completion of the operation. 2070 SSH_FX_EOF 2071 An attempt to read past the end-of-file was made; or, there are no 2072 more directory entries to return. 2074 SSH_FX_NO_SUCH_FILE 2075 A reference was made to a file which does not exist. 2077 SSH_FX_PERMISSION_DENIED 2078 The user does not have sufficient permissions to perform the 2079 operation. 2081 SSH_FX_FAILURE 2082 An error occured, but no specific error code exists to describe 2083 the failure. 2085 This error message SHOULD always have meaningful text in the the 2086 'error message' field. 2088 SSH_FX_BAD_MESSAGE 2089 A badly formatted packet or other SFTP protocol incompatibility 2090 was detected. 2092 SSH_FX_NO_CONNECTION 2093 There is no connection to the server. This error MAY be used 2094 locally, but MUST NOT be return by a server. 2096 SSH_FX_CONNECTION_LOST 2097 The connection to the server was lost. This error MAY be used 2098 locally, but MUST NOT be return by a server. 2100 SSH_FX_OP_UNSUPPORTED 2101 An attempted operation could not be completed by the server 2102 because the server does not support the operation. 2104 This error MAY be generated locally by the client if e.g. the 2105 version number exchange indicates that a required feature is not 2106 supported by the server, or it may be returned by the server if 2107 the server does not implement an operation. 2109 SSH_FX_INVALID_HANDLE 2110 The handle value was invalid. 2112 SSH_FX_NO_SUCH_PATH 2113 The file path does not exist or is invalid. 2115 SSH_FX_FILE_ALREADY_EXISTS 2116 The file already exists. 2118 SSH_FX_WRITE_PROTECT 2119 The file is on read-only media, or the media is write protected. 2121 SSH_FX_NO_MEDIA 2122 The requested operation cannot be completed because there is no 2123 media available in the drive. 2125 SSH_FX_NO_SPACE_ON_FILESYSTEM 2126 The requested operation cannot be completed because there is no 2127 free space on the filesystem. 2129 SSH_FX_QUOTA_EXCEEDED 2130 The operation cannot be completed because it would exceed the 2131 user's storage quota. 2133 SSH_FX_UNKNOWN_PRINCIPAL 2134 A principal referenced by the request (either the 'owner', 2135 'group', or 'who' field of an ACL), was unknown. The error 2136 specific data contains the problematic names. The format is one 2137 or more: 2139 string unknown-name 2141 Each string contains the name of a principal that was unknown. 2143 SSH_FX_LOCK_CONFLICT 2144 The file could not be opened because it is locked by another 2145 process. 2147 SSH_FX_DIR_NOT_EMPTY 2148 The directory is not empty. 2150 SSH_FX_NOT_A_DIRECTORY 2151 The specified file is not a directory. 2153 SSH_FX_INVALID_FILENAME 2154 The filename is not valid. 2156 SSH_FX_LINK_LOOP 2157 Too many symbolic links encountered. 2159 SSH_FX_CANNOT_DELETE 2160 The file cannot be deleted. One possible reason is that the 2161 advisory READONLY attribute-bit is set. 2163 SSH_FX_INVALID_PARAMETER 2164 On of the parameters was out of range, or the parameters specified 2165 cannot be used together. 2167 SSH_FX_FILE_IS_A_DIRECTORY 2168 The specifed file was a directory in a context where a directory 2169 cannot be used. 2171 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 2172 A read or write operation failed because another process's 2173 mandatory byte-range lock overlaps with the request. 2175 SSH_FX_BYTE_RANGE_LOCK_REFUSED 2176 A request for a byte range lock was refused. 2178 SSH_FX_DELETE_PENDING 2179 An operation was attempted on a file for which a delete operation 2180 is pending. 2182 SSH_FX_FILE_CORRUPT 2183 The file is corrupt; an filesystem integrity check should be run. 2185 8.2 Handle Response 2187 The SSH_FXP_HANDLE response has the following format: 2189 byte SSH_FXP_HANDLE 2190 uint32 request-id 2191 string handle 2193 'handle' 2194 An arbitrary string that identifies an open file or directory on 2195 the server. The handle is opaque to the client; the client MUST 2196 NOT attempt to interpret or modify it in any way. The length of 2197 the handle string MUST NOT exceed 256 data bytes. 2199 8.3 Data Response 2201 The SSH_FXP_DATA response has the following format: 2203 byte SSH_FXP_DATA 2204 uint32 request-id 2205 string data 2206 bool end-of-file [optional] 2208 data 2209 'data' is an arbitrary byte string containing the requested data. 2210 The data string may be at most the number of bytes requested in a 2211 SSH_FXP_READ request, but may also be shorter. (See 2212 Section 7.2.1.) 2214 end-of-file 2215 This field is optional. If it is present in the packet, it MUST 2216 be true, and it indicates that EOF was reached during this read. 2217 This can help the client avoid a round trip to determine whether a 2218 short read was normal (due to EOF) or some other problem (limited 2219 server buffer for example.) 2221 8.4 Name Response 2223 The SSH_FXP_NAME response has the following format: 2225 byte SSH_FXP_NAME 2226 uint32 request-id 2227 uint32 count 2228 repeats count times: 2229 string filename [UTF-8] 2230 ATTRS attrs 2231 bool end-of-list [optional] 2233 count 2234 The number of names returned in this response, and the 'filename' 2235 and 'attrs' field repeat 'count' times. 2237 filename 2238 A file name being returned (for SSH_FXP_READDIR, it will be a 2239 relative name within the directory, without any path components; 2240 for SSH_FXP_REALPATH it will be an absolute path name.) 2242 attrs 2243 The attributes of the file as described in Section ''File 2244 Attributes''. 2246 end-of-list 2247 This field is optional. If present in the packet, it MUST be 2248 true, and indicates that there are no more entries to be read. 2249 This can save the client a round trip to determine if there are 2250 more entries to be read. 2252 8.5 Attrs Response 2254 The SSH_FXP_ATTRS response has the following format: 2256 byte SSH_FXP_ATTRS 2257 uint32 request-id 2258 ATTRS attrs 2260 attrs 2261 The returned file attributes as described in Section ''File 2262 Attributes''. 2264 9. Extensions 2266 The SSH_FXP_EXTENDED request provides a generic extension mechanism 2267 for adding additional commands. 2269 byte SSH_FXP_EXTENDED 2270 uint32 request-id 2271 string extended-request 2272 ... any request-specific data ... 2274 request-id 2275 Identifier to be returned from the server with the response. 2277 extended-request 2278 A string naming the extension, following the the DNS extensibility 2279 naming convention outlined in [I-D.ietf-secsh-architecture], or 2280 defined by IETF consensus. 2282 request-specific data 2283 The rest of the request is defined by the extension; servers 2284 SHOULD NOT attempt to interpret it if they do not recognize the 2285 'extended-request' name. 2287 The server may respond to such requests using any of the response 2288 packets defined in Section ''Responses from the Server to the 2289 Client''. Additionally, the server may also respond with a 2290 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 2291 not recognize the 'extended-request' name, then the server MUST 2292 respond with SSH_FXP_STATUS with error/status set to 2293 SSH_FX_OP_UNSUPPORTED. 2295 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 2296 extension-specific data from the server to the client. It is of the 2297 following format: 2299 byte SSH_FXP_EXTENDED_REPLY 2300 uint32 request-id 2301 ... any request-specific data ... 2303 There is a range of packet types reserved for use by extensions. In 2304 order to avoid collision, extensions that that use additional packet 2305 types should determine those numbers dynamically. 2307 The suggested way of doing this is have an extension request from the 2308 client to the server that enables the extension; the extension 2309 response from the server to the client would specify the actual type 2310 values to use, in addition to any other data. 2312 Extension authors should be mindful of the limited range of packet 2313 types available (there are only 45 values available) and avoid 2314 requiring a new packet type where possible. 2316 9.1 File Hashing 2318 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 2320 After some discussion of this at connectathon, I know of two uses for 2321 this feature, neither one of which the feature is entirely suited 2322 for: 2323 o Checking that a file has been uploaded to the server correctly; 2324 some portion of the customers wanting this feature want it in a 2325 security sense, as part of proof the server has the file. 2326 o Optimizing upload or download of the file; multiple hashes are 2327 performed on small pieces of the file and the results are used to 2328 determine what chunks of the file, if any, need to be transfered. 2329 This is similar to the way rsync works. 2331 I've seen both of these implemented. 2333 For the first case, the extension has several drawbacks, including: 2334 o A FIPS implementation can't ship md5. 2335 o MD5's security is potential weaker than other options. 2336 o Being hard-coded to MD5 makes in impossible to adapt to future 2337 developments in the arena of MD5 compromises. 2339 For the second case, the extension has these drawbacks: 2340 o MD5 is expensive (relative to other options.) 2341 o The extension must be sent potentially thousands of times to 2342 retrieve the desired granularity of hashes. 2344 Therefore, for this draft, this section is marked experimental; I've 2345 included a second proposed extension. Please post your thoughts on 2346 the mailing list. (I did it this way just so I could get a draft out 2347 that I and my active co-author are happy with. 2349 In addition, implemenation experience has shown the quick check hash 2350 to not be useful. 2352 END: RFCEDITOR REMOVE BEFORE PUBLISHING 2354 9.1.1 Checking File Contents: v5 extension 2356 This extension allows a client to easily check if a file (or portion 2357 thereof) that it already has matches what is on the server. 2359 byte SSH_FXP_EXTENDED 2360 uint32 request-id 2361 string "md5-hash" / "md5-hash-handle" 2362 string filename [UTF-8] / file-handle 2363 uint64 start-offset 2364 uint64 length 2365 string quick-check-hash 2367 filename 2368 Used if "md5-hash" is specified; indicates the name of the file to 2369 use. The hash will be of the file contents as it would appear on 2370 the wire if the file were opened with no special flags. 2372 file-handle 2373 Used if "md5-hash-handle" is specified; specifies a file handle to 2374 read the data from. The handle MUST be a file handle, and 2375 ACE4_READ_DATA MUST have been included in the desired-access when 2376 the file was opened. 2378 If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode, 2379 the md5-hash must be made of the data as it would be sent on the 2380 wire. 2382 start-offset 2383 The starting offset of the data to hash. 2385 length 2386 The length of data to include in the hash. If both start-offset 2387 and length are zero, the entire file should be included. 2389 quick-check-hash 2390 The hash over the first 2048 bytes of the data range as the client 2391 knows it, or the entire range, if it is less than 2048 bytes. 2392 This allows the server to quickly check if it is worth the 2393 resources to hash a big file. 2395 If this is a zero length string, the client does not have the 2396 data, and is requesting the hash for reasons other than comparing 2397 with a local file. The server MAY return SSH_FX_OP_UNSUPPORTED in 2398 this case. 2400 The response is either a SSH_FXP_STATUS packet, indicating an error, 2401 or the following extended reply packet: 2403 byte SSH_FXP_EXTENDED_REPLY 2404 uint32 request-id 2405 string "md5-hash" 2406 string hash 2408 If 'hash' is zero length, then the 'quick-check-hash' did not match, 2409 and no hash operation was preformed. Otherwise, 'hash' contains the 2410 hash of the entire data range (including the first 2048 bytes that 2411 were included in the 'quick-check-hash'.) 2413 9.1.2 Checking File Contents 2415 This extension allows a client to easily check if a file (or portion 2416 thereof) that it already has matches what is on the server. 2418 byte SSH_FXP_EXTENDED 2419 uint32 request-id 2420 string "check-file-handle" / "check-file-name" 2421 string handle / name 2422 string hash-algorithm-list 2423 uint64 start-offset 2424 uint64 length 2425 uint32 block-size 2427 handle 2428 For "check-file-handle", 'handle' is an open file handle returned 2429 by SSH_FXP_OPEN. If 'handle' is not a handle returned by 2430 SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. If 2431 ACE4_READ_DATA was not included when the file was opened, the 2432 server MUST return STATUS_PERMISSION_DENIED. 2434 If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode, 2435 the check must be performed on the data as it would be sent on the 2436 wire. 2438 name 2439 For "check-file-name", 'name' is the path to the file to check. 2440 If 'check-file-name' is a directory, SSH_FX_FILE_IS_A_DIRECTORY 2441 SHOULD be returned. If 'check-file-name' refers to a 2442 SSH_FILEXFER_TYPE_SYMLINK, the target should be opened. The 2443 results are undefined file types other than 2444 SSH_FILEXFER_TYPE_REGULAR. 2446 The file MUST be opened without the SSH_FXF_ACCESS_TEXT_MODE 2447 access flag (in binary mode.) 2448 hash-algorithm-list 2449 A comma separated list of hash algorithms the client is willing to 2450 accept for this operation. The server MUST pick the first hash on 2451 the list that it supports. 2453 Currently defined algorithms are "md5", "sha1", "sha224", 2454 "sha256", "sha384", "sha512", and "crc32". Additional algorithms 2455 may be added by following the DNS extensibility naming convention 2456 outlined in [I-D.ietf-secsh-architecture]. 2458 MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384, 2459 and SHA-512 are decribed in [FIPS-180-2]. [ISO.3309.1991] 2460 describes crc32, and is the same algorithm used in [RFC1510] 2462 start-offset 2463 The starting offset of the data to include in the hash. 2465 length 2466 The length of data to include in the hash. If length is zero, all 2467 the data from start-offset to the end-of-file should be included. 2469 block-size 2470 An independant hash MUST be computed over every block in the file. 2471 The size of blocks is specified by block-size. The block-size 2472 MUST NOT be smaller than 256 bytes. If the block-size is 0, then 2473 only one hash, over the entire range, MUST be made. 2475 The response is either a SSH_FXP_STATUS packet, indicating an error, 2476 or the following extended reply packet: 2478 byte SSH_FXP_EXTENDED_REPLY 2479 uint32 request-id 2480 string "check-file" 2481 string hash-algo-used 2482 byte hash[n][block-count] 2484 hash-algo-used 2485 The hash algorithm that was actually used. 2487 hash 2488 The computed hashes. The hash algorithm used determines the size 2489 of n. The number of block-size chunks of data in the file 2490 determines block-count. The hashes are placed in the packet one 2491 after another, with no decoration. 2493 Note that if the length of the range is not an even multiple of 2494 block-size, the last hash will have been computed over only the 2495 remainder of the range instead of a full block. 2497 9.2 Querying Available Space 2499 The following extension provides a way to discover the available 2500 space for an arbitrary path. 2502 byte SSH_FXP_EXTENDED 2503 uint32 request-id 2504 string "space-available" 2505 string path [UTF-8] 2507 path 2508 'path' for which the available space should be reported. This 2509 'path' is not required to be the mount point path, but MAY be a 2510 directory or file contained within the mount. 2512 The reply to the request is as follows: 2514 byte SSH_FXP_EXTENDED_REPLY 2515 uint32 request-id 2516 uint64 bytes-on-device 2517 uint64 unused-bytes-on-device 2518 uint64 bytes-available-to-user 2519 uint64 unused-bytes-available-to-user 2520 uint32 bytes-per-allocation-unit 2522 bytes-on-device 2523 The total number of bytes on the device which stores 'path', both 2524 used and unused, or 0 if unknown. 2526 unused-bytes-on-device 2527 The total number of unused bytes available on the device which 2528 stores 'path', or 0 if unknown. 2530 bytes-available-to-user 2531 The total number of bytes, both used and unused, available to the 2532 authenticated user on the device which stores 'path', or 0 if 2533 unknown. 2535 unused-bytes-available-to-user 2536 The total number of unused bytes available to the authenticated 2537 user on the device which stores 'path', or 0 if unknown. 2539 bytes-per-allocation-unit 2540 The number of bytes in each allocation unit on the device, or in 2541 other words, the minimum number of bytes that a file allocation 2542 size can grow or shrink by. If the server does not know this 2543 information, or the file-system in use does not use allocation 2544 blocks, this value MUST be 0. 2546 9.3 Querying User Home Directory 2548 Many users are used to being able to type '~' as an alias for their 2549 home directory, or ~username as an alias for another user's home 2550 directory. To support this feature, a server MAY support following 2551 extension. 2553 byte SSH_FXP_EXTENDED 2554 uint32 request-id 2555 string "home-directory" 2556 string username [UTF-8] 2558 username 2559 Username whose home directory path is being requested. An empty 2560 string implies the current user. 2562 The reply to the request is either a SSH_FXP_STATUS packet or the 2563 following extended reply: 2565 byte SSH_FXP_EXTENDED_REPLY 2566 uint32 request-id 2567 string "home-directory" 2568 string absolute-pathname 2570 absolute-pathname 2571 Absolute pathname of the specified user's home directory, suitable 2572 for use in operations such as REALPATH or OPENDIR. 2574 10. Implementation Considerations 2576 In order for this protocol to perform well, especially over high 2577 latency networks, multiple read and write requests should be queued 2578 to the server. 2580 The data size of requests should match the maximum packet size for 2581 the next layer up in the protocol chain. 2583 When implemented over ssh, the best performance should be achieved 2584 when the data size matches the channel's max packet, and the channel 2585 window is a multiple of the channel packet size. 2587 Implementations MUST be aware that requests do not have to be 2588 satisfied in the order issued. (See Request Synchronization and 2589 Reordering (Section 3.1).) 2591 Implementations MUST also be aware that read requests may not return 2592 all the requested data, even if the data is available. 2594 11. Security Considerations 2596 It is assumed that both ends of the connection have been 2597 authenticated and that the connection has privacy and integrity 2598 features. Such security issues are left to the underlying transport 2599 protocol, except to note that if this is not the case, an attacker 2600 could manipulate files on the server at will and thus wholly 2601 compromise the server. 2603 This protocol provides file system access to arbitrary files on the 2604 server (constrained only by the server implementation). It is the 2605 responsibility of the server implementation to enforce any access 2606 controls that may be required to limit the access allowed for any 2607 particular user (the user being authenticated externally to this 2608 protocol, typically using [I-D.ietf-secsh-userauth]. 2610 Extreme care must be used when interpreting file handle strings. In 2611 particular, care must be taken that a file handle string is valid in 2612 the context of a given 'file-share' session. For example, the 'file- 2613 share' server daemon may have files which it has opened for its own 2614 purposes, and the client must not be able to access these files by 2615 specifying an arbitrary file handle string. 2617 The permission field of the attrib structure (Section 6.6) may 2618 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 2619 extreme caution when setting these bits on either remote or local 2620 files. (I.e., just because a file was SUID on the remote system does 2621 not necessarily imply that it should be SUID on the local system.) 2623 Filesystems often contain entries for objects that are not files at 2624 all, but are rather devices. For example, it may be possible to 2625 access serial ports, tape devices, or named pipes using this 2626 protocol. Servers should exercise caution when granting access to 2627 such resources. In addition to the dangers inherent in allowing 2628 access to such a device, some devices may be 'slow', and could cause 2629 denial of service by causing the server to block for a long period of 2630 time while I/O is performed to such a device. 2632 Servers should take care that file-system quotas are respected for 2633 users. In addition, implementations should be aware that attacks may 2634 be possible, or facilitated, by filling a filesystem. For example, 2635 filling the filesystem where event logging and auditing occurs may, 2636 at best, cause the system to crash, or at worst, allow the attacker 2637 to take untraceable actions in the future. 2639 Servers should take care that filenames are in their appropriate 2640 canonical form, and to ensure that filenames not in canonical form 2641 cannot be used to bypass access checks or controls. 2643 If the server implementation limits access to certain parts of the 2644 file system, extra care must be taken in parsing file names which 2645 contain the '..' path element, and when following symbolic links, 2646 shortcuts, or other filesystem objects which might transpose the path 2647 to refer to an object outside of the restricted area. There have 2648 been numerous reported security bugs where a ".." in a path name has 2649 allowed access outside the intended area. 2651 12. Changes from Previous Protocol Versions 2653 The SSH File Transfer Protocol has changed over time, before its 2654 standardization. The following is a description of the incompatible 2655 changes between different versions. 2657 12.1 Changes Between Versions 6 and 5 2658 o Add ability to negotiate version when client supports discontigous 2659 ranges of protocol version. 2660 o Add 'filename-charset' and the 'filename-translation-control' 2661 extensions to allow better support of servers that can't reliably 2662 translate to UTF-8. 2663 o Add DIR_NOT_EMPTY, NOT_A_DIRECTORY, INVALID_FILENAME LINK_LOOP, 2664 CANNOT_DELETE, INVALID_PARAMETER, FILE_IS_A_DIRECTORY, 2665 BYTE_RANGE_LOCK_CONFLICT, BYTE_RANGE_LOCK_REFUSED, DELETE_PENDING, 2666 and FILE_CORRUPT error codes. 2667 o Added space-available extension. 2668 o Added NOFOLLOW and DELETE_ON_CLOSE flag to open flags. 2669 o Added allocation-size, text-hint, link-count, mime-type, and 2670 untranslated-name fields to attrib structure. Add 2671 ATTR_FLAGS_TRANSLATION_ERR to the attrib-bits. 2672 o Add optional 'compose-path' and 'control-byte' to REALPATH; make 2673 realpath's behaviour truly deterministic (i.e., MUST instead of 2674 SHOULD.) Give clients the ability to compose path's without 2675 understanding what is relative and what is absolute. 2676 o Give SSH_FXP_DATA and SSH_FXP_NAME optional end-of-data-set flags, 2677 which can help the client avoid a round trip during normal 2678 operation. 2680 o Changed the SYMLINK packet to be LINK and give it the ability to 2681 create hard links. Also change it's packet number because many 2682 implementation implemented SYMLINK with the arguments reversed. 2683 Hopefully the new argument names make it clear which way is which. 2684 o Clarify who should apply umask to POSIX mode bits (the client, not 2685 the server.) 2686 o Specify behavior for otherwise valid packets with excess data and 2687 unrecognized packet types. 2688 o Add home directory extension. 2689 o Remove "#define" from symbol definitions to shorten line and help 2690 us pass idnits. 2691 o Change "supported" extension to "supported2", remove desired- 2692 access-bits, seperate attrib extension from SSH_FXP_EXTENDED 2693 extensions. 2694 o Add "vendor-id" extension. 2695 o Add ctime and attrib-bits-valid to attrib structure. 2696 o Unrecognized attrib extensions cause failure rather than ignored. 2697 o Optional 'end of data' flags on data and names responses. 2698 o Add valid-access-mask back into supported2 2699 o Add acl-present flag to acl. 2701 12.2 Changes Between Versions 5 and 4 2703 Many of the changes between version 5 and version 4 are to better 2704 support the changes in version 4, and to better specify error 2705 conditions. 2707 o Add "supported" extension to communicate features supported. 2708 o Clarify error handling when client requests unsupported feature. 2709 (For example, attempts to write an unsupported attribute.) 2710 o Add attrib-bits field to the attribute structure, which specifies 2711 a number of boolean attributes related to files and directories, 2712 including advisory read-only and case-sensitivity bits. 2713 o Clarify the actual bit values to be used for the permissions field 2714 (since POSIX doesn't define values) and correct the value of 2715 ATTR_PERMISSIONS flag. 2716 o Some reordering of sections to attempt to get a better grouping of 2717 related functionality. 2718 o Open request explicitly specifies the access desired for the file. 2719 o Add support for explicitly requesting file locking. 2720 o Add support for better control of the rename operation. 2721 o Add SSH_FX_NO_SPACE_ON_FILESYSTEM, SSH_FX_QUOTA_EXCEEDED, and 2722 SSH_FX_UNKNOWN_PRINCIPLE error codes. 2723 o Add support for error specific data. This is used by a new 2724 SSH_FX_UNKNOWN_PRINCIPLE error to communicate which principles are 2725 unknown. 2727 o Add support for retrieving md5-hash of file contents. 2728 o Update security section. 2730 12.3 Changes Between Versions 4 and 3 2732 Many of the changes between version 4 and version 3 are to the 2733 attribute structure to make it more flexible for non-unix platforms. 2735 o Clarify the use of stderr by the server. 2736 o Clarify handling of very large read requests by the server. 2737 o Make all filenames UTF-8. 2738 o Added 'newline' extension. 2739 o Made time fields 64 bit, and optionally have nanosecond 2740 resolution. 2741 o Made file attribute owner and group strings so they can actually 2742 be used on disparate systems. 2743 o Added createtime field, and added separate flags for atime, 2744 createtime, and mtime so they can be set separately. 2745 o Split the file type out of the permissions field and into its own 2746 field (which is always present.) 2747 o Added acl attribute. 2748 o Added SSH_FXF_TEXT file open flag. 2749 o Added flags field to the get stat commands so that the client can 2750 specifically request information the server might not normally 2751 included for performance reasons. 2752 o Removed the long filename from the names structure-- it can now be 2753 built from information available in the attrs structure. 2754 o Added reserved range of packet numbers for extensions. 2755 o Added several additional error codes. 2757 12.4 Changes Between Versions 3 and 2 2759 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. 2760 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were 2761 added. 2762 o The SSH_FXP_STATUS message was changed to include fields 'error 2763 message' and 'language tag'. 2765 12.5 Changes Between Versions 2 and 1 2767 o The SSH_FXP_RENAME message was added. 2769 12.6 Changes Between Versions 1 and 0 2771 o Implementation changes, no actual protocol changes. 2773 13. References 2774 13.1 Normative References 2776 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 2777 April 1992. 2779 [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network 2780 Authentication Service (V5)", RFC 1510, September 1993. 2782 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2783 Beame, C., Eisler, M., and D. Noveck, "NFS version 4 2784 Protocol", RFC 3010, December 2000. 2786 [I-D.ietf-secsh-architecture] 2787 Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", 2788 draft-ietf-secsh-architecture-22 (work in progress), 2789 March 2005. 2791 [I-D.ietf-secsh-transport] 2792 Lonvick, C., "SSH Transport Layer Protocol", 2793 draft-ietf-secsh-transport-24 (work in progress), 2794 March 2005. 2796 [I-D.ietf-secsh-connect] 2797 Lonvick, C. and T. Ylonen, "SSH Connection Protocol", 2798 draft-ietf-secsh-connect-25 (work in progress), 2799 March 2005. 2801 [IEEE.1003-1.1996] 2802 Institute of Electrical and Electronics Engineers, 2803 "Information Technology - Portable Operating System 2804 Interface (POSIX) - Part 1: System Application Program 2805 Interface (API) [C Language]", IEEE Standard 1003.2, 1996. 2807 [FIPS-180-2] 2808 National Institute of Standards and Technology, "Secure 2809 Hash Standard (SHS)", Federal Information Processing 2810 Standards Publication 180-2, August 2002. 2812 [ISO.3309.1991] 2813 International Organization for Standardization, 2814 "Information Technology - Telecommunications and 2815 information exchange between systems - High-level data 2816 link control (HDLC) procedures - Frame structure", 2817 ISO Standard 3309, June 1991. 2819 13.2 Informative References 2821 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet 2822 Mail Extensions) Part One: Mechanisms for Specifying and 2823 Describing the Format of Internet Message Bodies", 2824 RFC 1521, September 1993. 2826 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2827 RFC 2246, January 1999. 2829 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2830 Languages", BCP 18, RFC 2277, January 1998. 2832 [I-D.ietf-secsh-userauth] 2833 Lonvick, C. and T. Ylonen, "SSH Authentication Protocol", 2834 draft-ietf-secsh-userauth-27 (work in progress), 2835 March 2005. 2837 Authors' Addresses 2839 Joseph Galbraith 2840 VanDyke Software 2841 4848 Tramway Ridge Blvd 2842 Suite 101 2843 Albuquerque, NM 87111 2844 US 2846 Phone: +1 505 332 5700 2847 Email: galb-list@vandyke.com 2849 Oskari Saarenmaa 2850 F-Secure 2851 Tammasaarenkatu 7 2852 Helsinki 00180 2853 FI 2855 Email: oskari.saarenmaa@f-secure.com 2856 Tatu Ylonen 2857 SSH Communications Security Corp 2858 Fredrikinkatu 42 2859 HELSINKI FIN-00100 2860 Finland 2862 Email: ylo@ssh.com 2864 Sami Lehtinen 2865 SSH Communications Security Corp 2866 Fredrikinkatu 42 2867 HELSINKI FIN-00100 2868 Finland 2870 Email: sjl@ssh.com 2872 Trademark notice 2874 "ssh" is a registered trademark in the United States and/or other 2875 countries. 2877 Intellectual Property Statement 2879 The IETF takes no position regarding the validity or scope of any 2880 Intellectual Property Rights or other rights that might be claimed to 2881 pertain to the implementation or use of the technology described in 2882 this document or the extent to which any license under such rights 2883 might or might not be available; nor does it represent that it has 2884 made any independent effort to identify any such rights. Information 2885 on the procedures with respect to rights in RFC documents can be 2886 found in BCP 78 and BCP 79. 2888 Copies of IPR disclosures made to the IETF Secretariat and any 2889 assurances of licenses to be made available, or the result of an 2890 attempt made to obtain a general license or permission for the use of 2891 such proprietary rights by implementers or users of this 2892 specification can be obtained from the IETF on-line IPR repository at 2893 http://www.ietf.org/ipr. 2895 The IETF invites any interested party to bring to its attention any 2896 copyrights, patents or patent applications, or other proprietary 2897 rights that may cover technology that may be required to implement 2898 this standard. Please address the information to the IETF at 2899 ietf-ipr@ietf.org. 2901 Disclaimer of Validity 2903 This document and the information contained herein are provided on an 2904 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2905 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2906 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2907 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2908 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2909 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2911 Copyright Statement 2913 Copyright (C) The Internet Society (2005). This document is subject 2914 to the rights, licenses and restrictions contained in BCP 78, and 2915 except as set forth therein, the authors retain all their rights. 2917 Acknowledgment 2919 Funding for the RFC Editor function is currently provided by the 2920 Internet Society.