idnits 2.17.1 draft-ietf-secsh-filexfer-08.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.a on line 20. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2847. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2824. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2831. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2837. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement. ** 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. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. 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...' (183 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 646 has weird spacing: '... bool do-...' == Line 675 has weird spacing: '... string owne...' == Line 676 has weird spacing: '... string grou...' == Line 686 has weird spacing: '... string acl ...' == Line 690 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 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 (April 5, 2005) is 6960 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 2497, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 1956, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 1957, 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: 12 errors (**), 0 flaws (~~), 13 warnings (==), 12 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Secure Shell Working Group J. Galbraith 2 Internet-Draft VanDyke Software 3 Expires: October 7, 2005 O. Saarenmaa 4 F-Secure 5 T. Ylonen 6 S. Lehtinen 7 SSH Communications Security Corp 8 April 5, 2005 10 SSH File Transfer Protocol 11 draft-ietf-secsh-filexfer-08.txt 13 Status of this Memo 15 This document is an Internet-Draft and is subject to all provisions 16 of Section 3 of RFC 3667. By submitting this Internet-Draft, each 17 author represents that any applicable patent or other IPR claims of 18 which he or she is aware have been or will be disclosed, and any of 19 which he or she become aware will be disclosed, in accordance with 20 RFC 3668. 22 Internet-Drafts are working documents of the Internet Engineering 23 Task Force (IETF), its areas, and its working groups. Note that 24 other groups may also distribute working documents as Internet- 25 Drafts. 27 Internet-Drafts are draft documents valid for a maximum of six months 28 and may be updated, replaced, or obsoleted by other documents at any 29 time. It is inappropriate to use Internet-Drafts as reference 30 material or to cite them other than as "work in progress." 32 The list of current Internet-Drafts can be accessed at 33 http://www.ietf.org/ietf/1id-abstracts.txt. 35 The list of Internet-Draft Shadow Directories can be accessed at 36 http://www.ietf.org/shadow.html. 38 This Internet-Draft will expire on October 7, 2005. 40 Copyright Notice 42 Copyright (C) The Internet Society (2005). 44 Abstract 46 The SSH File Transfer Protocol provides secure file transfer 47 functionality over any reliable data stream. It is the standard file 48 transfer protocol for use with the SSH2 protocol. This document 49 describes the file transfer protocol and its interface to the SSH2 50 protocol suite. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 56 2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 4 57 3. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 58 3.1 Request Synchronization and Reordering . . . . . . . . . . 6 59 3.2 New data types defined by this document . . . . . . . . . 6 60 3.3 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 61 4. Protocol Initialization . . . . . . . . . . . . . . . . . . . 8 62 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 63 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 9 64 4.3 Determining Server Newline Convention . . . . . . . . . . 9 65 4.4 Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . 9 66 4.5 Supported Features . . . . . . . . . . . . . . . . . . . . 10 67 4.6 Version re-negotiation . . . . . . . . . . . . . . . . . . 12 68 5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 13 69 6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 15 70 6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 16 71 6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 72 6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 73 6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 18 74 6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 18 75 6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 19 76 6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 19 77 6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 78 6.9 attrib-bits and attrib-bits-valid . . . . . . . . . . . . 21 79 6.10 text-hint . . . . . . . . . . . . . . . . . . . . . . . . 24 80 6.11 mime-type . . . . . . . . . . . . . . . . . . . . . . . . 24 81 6.12 link-count . . . . . . . . . . . . . . . . . . . . . . . . 24 82 6.13 untranslated-name . . . . . . . . . . . . . . . . . . . . 25 83 6.14 Extended Attributes . . . . . . . . . . . . . . . . . . . 25 84 7. Requests From the Client to the Server . . . . . . . . . . . . 25 85 7.1 Opening and Closing Files and Directories . . . . . . . . 25 86 7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 26 87 7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 31 88 7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 32 89 7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 32 90 7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 32 91 7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 33 92 7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 33 93 7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 34 94 7.4 Creating and Deleting Directories . . . . . . . . . . . . 35 95 7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 36 96 7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 37 97 7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 38 98 7.8 Canonicalizing the Server-Side Path Name . . . . . . . . . 40 99 7.8.1 Best Practice for Dealing with Paths . . . . . . . . . 42 100 8. Responses from the Server to the Client . . . . . . . . . . . 42 101 8.1 Status Response . . . . . . . . . . . . . . . . . . . . . 43 102 8.2 Handle Response . . . . . . . . . . . . . . . . . . . . . 47 103 8.3 Data Response . . . . . . . . . . . . . . . . . . . . . . 47 104 8.4 Name Response . . . . . . . . . . . . . . . . . . . . . . 48 105 8.5 Attrs Response . . . . . . . . . . . . . . . . . . . . . . 49 106 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 49 107 9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 50 108 9.1.1 Checking File Contents: v5 extension . . . . . . . . . 51 109 9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 52 110 9.2 Querying Available Space . . . . . . . . . . . . . . . . . 54 111 9.3 Querying User Home Directory . . . . . . . . . . . . . . . 55 112 10. Implementation Considerations . . . . . . . . . . . . . . . 55 113 11. Security Considerations . . . . . . . . . . . . . . . . . . 56 114 12. Changes from Previous Protocol Versions . . . . . . . . . . 57 115 12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 57 116 12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 58 117 12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 59 118 12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 59 119 12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 59 120 12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 59 121 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 122 13.1 Normative References . . . . . . . . . . . . . . . . . . . 60 123 13.2 Informative References . . . . . . . . . . . . . . . . . . 61 124 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 61 125 Intellectual Property and Copyright Statements . . . . . . . . 63 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 int64 266 Represents a 64-bit signed integer. Stored as eight bytes in the 267 order of decreasing significance (network byte order). 269 extension-pair 271 string extension-name 272 string extension-data 274 'extension-name' is the name of a protocol extension. Extensions 275 not defined by IETF CONSENSUS MUST follow the the DNS 276 extensibility naming convention outlined in [I-D.ietf-secsh- 277 architecture]. 279 'extension-data' is any data specific to the extension, and MAY be 280 zero length if the extension has no data. 282 3.3 Packet Types 284 The following values are defined for packet types. 286 SSH_FXP_INIT 1 287 SSH_FXP_VERSION 2 288 SSH_FXP_OPEN 3 289 SSH_FXP_CLOSE 4 290 SSH_FXP_READ 5 291 SSH_FXP_WRITE 6 292 SSH_FXP_LSTAT 7 293 SSH_FXP_FSTAT 8 294 SSH_FXP_SETSTAT 9 295 SSH_FXP_FSETSTAT 10 296 SSH_FXP_OPENDIR 11 297 SSH_FXP_READDIR 12 298 SSH_FXP_REMOVE 13 299 SSH_FXP_MKDIR 14 300 SSH_FXP_RMDIR 15 301 SSH_FXP_REALPATH 16 302 SSH_FXP_STAT 17 303 SSH_FXP_RENAME 18 304 SSH_FXP_READLINK 19 305 SSH_FXP_LINK 21 306 SSH_FXP_BLOCK 22 307 SSH_FXP_UNBLOCK 23 309 SSH_FXP_STATUS 101 310 SSH_FXP_HANDLE 102 311 SSH_FXP_DATA 103 312 SSH_FXP_NAME 104 313 SSH_FXP_ATTRS 105 315 SSH_FXP_EXTENDED 200 316 SSH_FXP_EXTENDED_REPLY 201 318 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 319 implement extensions, which can be vendor specific. See Section 320 ''Extensions'' for more details. 322 Values 210-255 are reserved for use in conjunction with these 323 extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the 324 meaning of these reserved types. It is suggested that the actual 325 value to be used also be negotiated, since this will prevent 326 collision among multiple uncoordinated extensions. 328 The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if 329 it receives a packet it does not recognize. The protocol version 330 (Section 4) MUST be incremented if the server is to send new packets 331 to the client (because the client has no way to respond indicating 332 that the packet isn't recognized.) 334 4. Protocol Initialization 336 When the file transfer protocol starts, the client first sends a 337 SSH_FXP_INIT (including its version number) packet to the server. 338 The server responds with a SSH_FXP_VERSION packet, supplying the 339 lowest of its own and the client's version number. Both parties 340 should from then on adhere to that particular version of the 341 protocol. 343 The version number of the protocol specified in this document is 6. 344 The version number should be incremented for each incompatible 345 revision of this protocol. 347 Note that these two packets DO NOT contain a request id. These are 348 the only such packets in the protocol. 350 4.1 Client Initialization 352 The SSH_FXP_INIT packet (from client to server) has the following 353 data: 355 uint32 version 357 'version' is the version number of the client. If the client wishes 358 to interoperate with servers that support discontiguous version 359 numbers it SHOULD send '3', and then use the 'version-select' 360 extension (see below.) Otherwise, this value is '6' for this version 361 of the protocol. 363 4.2 Server Initialization 365 The SSH_FXP_VERSION packet (from server to client) has the following 366 data: 368 uint32 version 369 extension-pair extensions[0..n] 371 'version' is the lower of the protocol version supported by the 372 server and the version number received from the client. 374 'extensions' is 0 or more extension-pairs (Section 3.2). 375 Implementations MUST silently ignore any extensions whose names they 376 do not recognize. 378 4.3 Determining Server Newline Convention 380 In order to correctly process text files in a cross platform 381 compatible way, newline sequences must be converted between client 382 and server conventions. 384 The SSH_FXF_TEXT file open flag (Section 7.1.1) makes it possible to 385 request that the server translate a file to a 'canonical' wire 386 format. This format uses CRLF as the line separator. 388 Servers for systems using other conventions MUST translate to and 389 from the canonical form. 391 However, to ease the burden of implementation on servers that use a 392 single, simple, separator sequence the following extension allows the 393 canonical format to be changed. 395 string "newline" 396 string new-canonical-separator (usually CR or LF or CRLF) 398 All clients MUST support this extension. 400 When processing text files, clients SHOULD NOT translate any 401 character or sequence that is not an exact match of the server's 402 newline separator. 404 In particular, if the newline sequence being used is the canonical 405 CRLF sequence, a lone CR or a lone LF SHOULD be written through 406 without change. 408 4.4 Vendor Id 410 It is often necessary to detect the version of a the server so that 411 bugs can be worked around. This extension allows the client to do 412 so. (It may also be sent by the client using an EXTENDED request. 414 string "vendor-id" 415 string vendor-structure 416 string vendor-name 417 string product-name 418 string product-version 419 uint64 product-build-number 421 vendor-name 422 Arbitrary name identifying the maker of the product. 424 product-name 425 Arbitrary name identifying the product. 427 product-name 428 Arbitrary string identifying the version of the product. 430 product-build-number 431 A build-number for the product, such that if a bug is fixed in 432 build-number 'x', it can be assumed that (barring regression in 433 the product) it is fixed in all build-numbers > 'x'. 435 4.5 Supported Features 437 The sftp protocol has grown to be very rich, and now supports a 438 number of features that may not be available on all servers. 440 When a server receives a request for a feature it cannot support, it 441 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 442 specified. The following extension facilitates clients being able to 443 use the maximum available feature set, and yet not be overly burdened 444 by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST 445 include as part of their version packet. 447 string "supported2" 448 string supported-structure 449 uint32 supported-attribute-mask 450 uint32 supported-attribute-bits 451 uint32 supported-open-flags 452 uint32 max-read-size 453 uint64 supported-open-block-masks 454 uint64 supported-block-masks 455 uint32 attrib-extension-count 456 string attrib-extension-names[attrib_extension-count] 457 uint32 extension-count 458 string extension-names[extension-count] 460 Note that the name "supported2" is used here to avoid conflict with 461 the slightly different "supported" extension that was previously 462 used. 463 supported-attribute-mask 464 This mask MAY by applied to the 'File Attributes' valid-attribute- 465 flags field (Section 6.1) to ensure that no unsupported attributes 466 are present during a operation which writes attributes. 468 supported-attribute-bits 469 This mask MAY by applied to the 'File Attributes' attrib-bits 470 field (Section 6.9) to ensure that no unsupported attrib-bits are 471 present during a operation which writes attributes. 473 supported-open-flags 474 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN 475 (Section 7.1.1) flags field. 477 max-read-size 478 This is the maximum read size that the server guarantees to 479 complete. For example, certain embedded server implementations 480 complete only the first 4K of a read, even if there is additional 481 data to be read from the file. 483 If the server specifies a non-zero value for max-read-size, it 484 MUST return the requested number of bytes for reads that are less 485 than or equal to the value, unless it encounters EOF or an ERROR. 487 The server MAY use this value to express that it is willing to 488 handle very large read requests, in excess of the standard 34000 489 bytes specfied in Section 3. 491 supported-open-block-masks 492 Series of four-bit fields representing the support combinations of 493 SSH_FXF_ACCESS_BLOCK_READ, SSH_FXF_ACCESS_BLOCK_WRITE, 494 SSH_FXF_ACCESS_BLOCK_DELETE, and SSH_FXF_ACCESS_BLOCK_ADVISORY 495 (Section 7.1.1.3.) 497 The bits are interpreted in four-bit groups, beginning with the 498 least significant bit. The bit values are the values used in the 499 file open flags, shifted right so that BLOCK_READ is the least 500 significant bit. 502 For example, a server that supported only the classic advisory 503 read lock (shared lock) and write lock (exclusive lock) would send 504 0b1011 1010, or 0xba. 506 supported-block-masks 507 Series of four-bit fields representing the supported combinations 508 of BLOCK_* flags for use with the SSH_FXF_BLOCK request, as 509 described above. 510 attrib-extension-count 511 Count of extension names in the attrib-extension array. 513 attrib-extension-names 514 Names of extensions that can be used in an ATTRS (Section 6.14) 515 structure. 517 extension-count 518 Count of extension names in the attrib-extension array. 520 extension-names 521 Names of extensions that can be used with the SSH_FXP_EXTEND 522 (Section 9) packet. 524 Naturally, if a given attribute field, attribute mask bit, open flag, 525 or extension is required for correct operation, the client MUST 526 either not allow the bit to be masked off, or MUST fail the operation 527 gracefully without sending the request to the server. 529 The client MAY send requests that are not supported by the server; 530 however, it is not normally expected to be productive to do so. The 531 client SHOULD apply the mask even to attrib structures received from 532 the server. The server MAY include attributes or attrib-bits that 533 are not included in the mask. Such attributes or attrib-bits are 534 effectively read-only. 536 4.6 Version re-negotiation 538 If the server supports other versions than what was negotiated, it 539 may wish to send the 'versions' extension to inform the client of 540 this fact. The client may then optionally choose to use one of the 541 other versions supported. 543 string "versions" 544 string comma-separated-versions 546 'comma-separated-versions' is a string of comma separated version 547 numbers, for example, "3,6,7". Defined versions are: "2", "3", "4", 548 "5", "6". Any other version advertised by the server must follow the 549 DNS extensibility naming convention outlined in [I-D.ietf-secsh- 550 architecture]. 552 If the client and server have negotiated any version higher than 553 version '3' (the version at which SSH_FXP_EXTENDED was introduced) in 554 the initial VERSION/INIT exchange, the client may select a new 555 version to use from the list the server provided using the following 556 SSH_FXP_EXTENDED request. 558 string "version-select" 559 uint32 version-from-list 561 If the 'version-from-list' is one of the versions on the servers 562 list, the server MUST respond with SSH_FX_OK. If the server did not 563 send the "versions" extension, or the version-from-list was not 564 included, the server MAY send a status response describing the 565 failure, but MUST then close the channel without processing any 566 further requests. 568 The 'version-select' MUST be the first request from the client to the 569 server; if it is not, the server MUST fail the request and close the 570 channel. 572 Although this request does take a full round trip, no client need 573 wait for the response before continuing, because any valid request 574 MUST succeed, and any invalid request results in a channel close. 575 Since the request is the first request, it is not possible for the 576 server to have already sent responses conforming to the old version. 578 The client SHOULD NOT select a version lower than was initially 579 negotiated; however, it is not forbidden to do so. One reason a 580 client might do so is to work around a buggy implementation. 582 5. File Names 584 This protocol represents file names as strings. File names are 585 assumed to use the slash ('/') character as a directory separator. 587 File names starting with a slash are "absolute", and are relative to 588 the root of the file system. Names starting with any other character 589 are relative to the user's default directory (home directory). Note 590 that identifying the user is assumed to take place outside of this 591 protocol. 593 Servers SHOULD interpret a path name component ".." (Section 11) as 594 referring to the parent directory, and "." as referring to the 595 current directory. 597 An empty path name is valid, and it refers to the user's default 598 directory (usually the user's home directory). 600 Otherwise, no syntax is defined for file names by this specification. 601 Clients should not make any other assumptions; however, they can 602 splice path name components returned by SSH_FXP_READDIR together 603 using a slash ('/') as the separator, and that will work as expected. 605 It is understood that the lack of well-defined semantics for file 606 names may cause interoperability problems between clients and servers 607 using radically different operating systems. However, this approach 608 is known to work acceptably with most systems, and alternative 609 approaches that e.g. treat file names as sequences of structured 610 components are quite complicated. 612 The prefered encoding for filenames is UTF-8. This is consistant 613 with IETF Policy on Character Sets and Languages [RFC2277] and it is 614 further supposed that the server is more likely to support any local 615 character set and be able to convert it to UTF-8. 617 However, because the server does not always know the encoding of 618 filenames, it is not always possible for the server to preform a 619 valid translation to UTF-8. When an invalid translation to UTF-8 is 620 preformed, it becomes impossible to manipulate the file, because the 621 translation is not reversable. Therefore, the following extensions 622 are provided in order to make it possible for the server to 623 communicate it's abilities to the client, and to allow the client to 624 control whether the server attempts the conversion. 626 A server MAY include the following extension with it's version 627 packet. 629 string "filename-charset" 630 string charset-name 632 A server that can always provide a valid UTF-8 translation for 633 filenames SHOULD NOT send this extension. Otherwise, the server 634 SHOULD send this extension and include the encoding most likely to be 635 used for filenames. This value will most likely be derived from the 636 LC_CTYPE on most unix-like systems. 638 A server that does not send this extension MUST send all filenames 639 encoded in UTF-8. All clients MUST support UTF-8 filenames. 641 If the server included the 'filename-charset' extension with its 642 VERSION packet, a client MAY send the following extension to turn off 643 server translation to UTF-8. 645 string "filename-translation-control" 646 bool do-translate 648 If the client does not send this extension, the server MUST continue 649 to attempt translation to UTF-8. When a client sends this extension, 650 the server MUST enable filename translation if 'do-translate' is 651 true, or disable filename translation if it is false. 653 The server MUST respond with a STATUS response; if the server sent a 654 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, 655 the status MUST be UNSUPPORTED. 657 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE 658 data MUST be used. The server is responsible for converting the 659 UNICODE data to whatever canonical form it requires. For example, if 660 the server requires that precomposed characters always be used, the 661 server MUST NOT assume the filename as sent by the client has this 662 attribute, but must do this normalization itself. 664 6. File Attributes 666 A new compound data type, 'ATTRS', is defined for encoding file 667 attributes. The same encoding is used both when returning file 668 attributes from the server and when sending file attributes to the 669 server. 671 uint32 valid-attribute-flags 672 byte type always present 673 uint64 size if flag SIZE 674 uint64 allocation-size if flag ALLOCATION_SIZE 675 string owner if flag OWNERGROUP 676 string group if flag OWNERGROUP 677 uint32 permissions if flag PERMISSIONS 678 int64 atime if flag ACCESSTIME 679 uint32 atime-nseconds if flag SUBSECOND_TIMES 680 int64 createtime if flag CREATETIME 681 uint32 createtime-nseconds if flag SUBSECOND_TIMES 682 int64 mtime if flag MODIFYTIME 683 uint32 mtime-nseconds if flag SUBSECOND_TIMES 684 int64 ctime if flag CTIME 685 uint32 ctime-nseconds if flag SUBSECOND_TIMES 686 string acl if flag ACL 687 uint32 attrib-bits if flag BITS 688 uint32 attrib-bits-valid if flag BITS 689 byte text-hint if flag TEXT_HINT 690 string mime-type if flag MIME_TYPE 691 uint32 link-count if flag LINK_COUNT 692 string untranslated-name if flag UNTRANSLATED_NAME 693 uint32 extended-count if flag EXTENDED 694 extended-pair extensions 696 6.1 valid-attribute-flags 698 The 'valid-attribute-flags' specifies which of the fields are 699 present. Those fields for which the corresponding flag is not set 700 are not present (not included in the packet). 702 The server generally includes all attributes it knows about; however, 703 it may exclude attributes that are overly expensive to retrieve 704 unless the client explicitly requests them. 706 When writing attributes, the server SHOULD NOT modify attributes that 707 are not present in the structure. However, if necessary, the server 708 MAY use a default value for an absent attribute. 710 In general, unless otherwise specified, if a server cannot support 711 writing an attribute requested, it must fail the setstat operation. 712 In this case, none of the attributes SHOULD be changed. 714 New fields can only be added by incrementing the protocol version 715 number (or by using the extension mechanism described below). 717 The following values are defined: 719 SSH_FILEXFER_ATTR_SIZE 0x00000001 720 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 721 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 722 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 723 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 724 SSH_FILEXFER_ATTR_ACL 0x00000040 725 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 726 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 727 SSH_FILEXFER_ATTR_BITS 0x00000200 728 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 729 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 730 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 731 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 732 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 733 SSH_FILEXFER_ATTR_CTIME 0x00008000 734 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 736 0x00000002 was used in a previous version of this protocol. It is 737 now a reserved value and MUST NOT appear in the mask. Some future 738 version of this protocol may reuse this value. 740 6.2 Type 742 The type field is always present. The following types are defined: 744 SSH_FILEXFER_TYPE_REGULAR 1 745 SSH_FILEXFER_TYPE_DIRECTORY 2 746 SSH_FILEXFER_TYPE_SYMLINK 3 747 SSH_FILEXFER_TYPE_SPECIAL 4 748 SSH_FILEXFER_TYPE_UNKNOWN 5 749 SSH_FILEXFER_TYPE_SOCKET 6 750 SSH_FILEXFER_TYPE_CHAR_DEVICE 7 751 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 752 SSH_FILEXFER_TYPE_FIFO 9 754 On a POSIX system, these values would be derived from the mode field 755 of the stat structure. SPECIAL should be used for files that are of 756 a known type which cannot be expressed in the protocol. UNKNOWN 757 should be used if the type is not known. 759 6.3 Size 761 The 'size' field specifies the number of bytes that can be read from 762 the file, or in other words, the location of the end-of-file. This 763 attribute MUST NOT be present during file creation. 765 If this field is present during a setstat operation, the file MUST be 766 extended or truncated to the specified size. 768 Files opened with the SSH_FXF_ACCESS_TEXT flag may have a size that 769 is greater or less than the value of the size field. The server MAY 770 fail setstat operations specifying size for files opened with the 771 SSH_FXF_ACCESS_TEXT flag. 773 6.4 allocation-size 775 The 'allocation-size' field specifies the number of bytes that the 776 file consumes on disk. This field MAY be less than the 'size' field 777 if the file is 'sparse' (Section 6.9). 779 When present during file creation, the file SHOULD be created and the 780 specified number of bytes pre-allocated. If the pre-allocation 781 fails, the file should be removed (if it was created) and an error 782 returned. 784 If this field is present during a setstat operation, the file SHOULD 785 be extended or truncated to the specified size. The 'size' of the 786 file may be affected by this operation. If the operation succeeds, 787 the 'size' should be the minimum of the 'size' before the operation 788 and the new 'allocation-size'. 790 Querying the 'allocation-size' after setting it MUST return a value 791 that is greater-than or equal to the value set, but it MAY not return 792 the precise value set. 794 If both 'size' and 'allocation-size' are set during a setstat 795 operation, and 'allocation-size' is less than 'size', the server MUST 796 return SSH_FX_INVALID_PARAMETER. 798 6.5 Owner and Group 800 The 'owner' and 'group' fields are represented as UTF-8 strings; this 801 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. 802 The following text is selected quotations from section 5.6. 804 To avoid a representation that is tied to a particular underlying 805 implementation at the client or server, the use of UTF-8 strings has 806 been chosen. The string should be of the form "user@dns_domain". 807 This will allow for a client and server that do not use the same 808 local representation the ability to translate to a common syntax that 809 can be interpreted by both. In the case where there is no 810 translation available to the client or server, the attribute value 811 must be constructed without the "@". Therefore, the absence of the @ 812 from the owner or owner_group attribute signifies that no translation 813 was available and the receiver of the attribute should not place any 814 special meaning on the attribute value. Even though the attribute 815 value cannot be translated, it may still be useful. In the case of a 816 client, the attribute string may be used for local display of 817 ownership. 819 user@localhost represents a user in the context of the server. 821 If either the owner or group field is zero length, the field should 822 be considered absent, and no change should be made to that specific 823 field during a modification operation. 825 6.6 Permissions 827 The 'permissions' field contains a bit mask specifying file 828 permissions. These permissions correspond to the st_mode field of 829 the stat structure defined by POSIX [IEEE.1003-1.1996]. 831 This protocol uses the following values for the symbols declared in 832 the POSIX standard. 834 S_IRUSR 0000400 (octal) 835 S_IWUSR 0000200 836 S_IXUSR 0000100 837 S_IRGRP 0000040 838 S_IWGRP 0000020 839 S_IXGRP 0000010 840 S_IROTH 0000004 841 S_IWOTH 0000002 842 S_IXOTH 0000001 843 S_ISUID 0004000 844 S_ISGID 0002000 845 S_ISVTX 0001000 847 Implementations MUST NOT send bits that are not defined. 849 The server SHOULD NOT apply a 'umask' to the mode bits; but should 850 set the mode bits as specified by the client. The client MUST apply 851 an appropriate 'umask' to the mode bits before sending them. 853 6.7 Times 855 The 'atime' field contains the last access time of the file. Many 856 operating systems either don't have this field, only optionally 857 maintain it, or maintain it with less resolution than other fields. 859 The 'mtime' contains the last time the file was written. 861 'createtime' contains the creation time of the file. 863 'ctime' contains the last time the file attrbutes were changed. The 864 exact meaning of this field depends on the server. 866 All times are represented as seconds from Jan 1, 1970 in UTC. A 867 negative value indicates number of seconds before Jan 1, 1970. In 868 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 869 nseconds field is to be added to the seconds field for the final time 870 representation. For example, if the time to be represented is one- 871 half second before 0 hour January 1, 1970, the seconds field would 872 have a value of negative one (-1) and the nseconds fields would have 873 a value of one-half second (500000000). Values greater than 874 999,999,999 for nseconds are considered invalid. 876 6.8 ACL 878 The 'ACL' field contains an ACL similar to that defined in section 879 5.9 of NFS version 4 Protocol [RFC3010]. 881 uint32 ace-count 883 repeated ace-count time: 884 uint32 ace-type 885 uint32 ace-flag 886 uint32 ace-mask 887 string who [UTF-8] 889 ace-type is one of the following four values (taken from NFS Version 890 4 Protocol [RFC3010]: 892 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 893 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 894 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 895 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 897 ace-flag is a combination of the following flag values. See NFS 898 Version 4 Protocol [RFC3010] section 5.9.2: 900 ACE4_FILE_INHERIT_ACE 0x00000001 901 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 902 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 903 ACE4_INHERIT_ONLY_ACE 0x00000008 904 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 905 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 906 ACE4_IDENTIFIER_GROUP 0x00000040 908 ace-mask is any combination of the following flags (taken from 909 [RFC3010], section 5.9.3. The semantic meaning of these flags is 910 also given in [RFC3010]. 912 ACE4_READ_DATA 0x00000001 913 ACE4_LIST_DIRECTORY 0x00000001 914 ACE4_WRITE_DATA 0x00000002 915 ACE4_ADD_FILE 0x00000002 916 ACE4_APPEND_DATA 0x00000004 917 ACE4_ADD_SUBDIRECTORY 0x00000004 918 ACE4_READ_NAMED_ATTRS 0x00000008 919 ACE4_WRITE_NAMED_ATTRS 0x00000010 920 ACE4_EXECUTE 0x00000020 921 ACE4_DELETE_CHILD 0x00000040 922 ACE4_READ_ATTRIBUTES 0x00000080 923 ACE4_WRITE_ATTRIBUTES 0x00000100 924 ACE4_DELETE 0x00010000 925 ACE4_READ_ACL 0x00020000 926 ACE4_WRITE_ACL 0x00040000 927 ACE4_WRITE_OWNER 0x00080000 928 ACE4_SYNCHRONIZE 0x00100000 930 who is a UTF-8 string of the form described in 'Owner and Group' 931 (Section 6.5) 933 Also, as per '5.9.4 ACE who' [RFC3010] there are several identifiers 934 that need to be understood universally. Some of these identifiers 935 cannot be understood when an client access the server, but have 936 meaning when a local process accesses the file. The ability to 937 display and modify these permissions is permitted over SFTP. 939 OWNER The owner of the file. 940 GROUP The group associated with the file. 941 EVERYONE The world. 942 INTERACTIVE Accessed from an interactive terminal. 943 NETWORK Accessed via the network. 944 DIALUP Accessed as a dialup user to the server. 945 BATCH Accessed from a batch job. 946 ANONYMOUS Accessed without any authentication. 947 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 948 SERVICE Access from a system service. 950 To avoid conflict, these special identifiers are distinguish by an 951 appended "@". For example: ANONYMOUS@. 953 6.9 attrib-bits and attrib-bits-valid 955 These fields, taken together, reflect various attributes of the file 956 or directory, on the server. 958 Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- 959 bits' field. This allows both the server and the client to 960 comminicute only the bits it knows about without inadvertantly 961 twiddling bits they don't understand. 963 The following attrib-bits are defined: 965 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 966 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 967 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 968 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 969 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 970 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 971 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 972 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 973 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 974 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 975 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 976 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 978 SSH_FILEXFER_ATTR_FLAGS_READONLY 979 Advisory, read-only bit. This bit is not part of the access 980 control information on the file, but is rather an advisory field 981 indicating that the file should not be written. 983 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 984 The file is part of the operating system. 986 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 987 File SHOULD NOT be shown to user unless specifically requested. 988 For example, most UNIX systems SHOULD set this bit if the filename 989 begins with a 'period'. This bit may be read-only (Section 4.5). 990 Most UNIX systems will not allow this to be changed. 992 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 993 This attribute applies only to directories. This attribute is 994 always read-only, and cannot be modified. This attribute means 995 that files and directory names in this directory should be 996 compared without regard to case. 998 It is recommended that where possible, the server's filesystem be 999 allowed to do comparisons. For example, if a client wished to 1000 prompt a user before overwriting a file, it should not compare the 1001 new name with the previously retrieved list of names in the 1002 directory. Rather, it should first try to create the new file by 1003 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 1004 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 1005 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 1007 Unless otherwise specified, filenames are assumed to be case 1008 sensitive. 1010 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 1011 The file should be included in backup / archive operations. 1013 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 1014 The file is stored on disk using file-system level transparent 1015 encryption. This flag does not affect the file data on the wire 1016 (for either READ or WRITE requests.) 1018 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 1019 The file is stored on disk using file-system level transparent 1020 compression. This flag does not affect the file data on the wire. 1022 SSH_FILEXFER_ATTR_FLAGS_SPARSE 1023 The file is a sparse file; this means that file blocks that have 1024 not been explicitly written are not stored on disk. For example, 1025 if a client writes a buffer at 10 M from the beginning of the 1026 file, the blocks between the previous EOF marker and the 10 M 1027 offset would not consume physical disk space. 1029 Some servers may store all files as sparse files, in which case 1030 this bit will be unconditionally set. Other servers may not have 1031 a mechanism for determining if the file is sparse, and so the file 1032 MAY be stored sparse even if this flag is not set. 1034 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 1035 Opening the file without either the SSH_FXF_ACCESS_APPEND_DATA or 1036 the SSH_FXF_ACCESS_APPEND_DATA_ATOMIC flag (Section 7.1.1.3) MUST 1037 result in an SSH_FX_INVALID_PARAMETER error. 1039 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 1040 The file cannot be deleted or renamed, no hard link can be created 1041 to this file, and no data can be written to the file. 1043 This bit implies a stronger level of protection than 1044 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 1045 ACLs. Typically even the superuser cannot write to immutable 1046 files, and only the superuser can set or remove the bit. 1048 SSH_FILEXFER_ATTR_FLAGS_SYNC 1049 When the file is modified, the changes are written synchronously 1050 to the disk. 1052 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 1053 The server MAY include this bit in a directory listing or realpath 1054 response. It indicates there was a failure in the translation to 1055 UTF-8. If this flag is included, the server SHOULD also include 1056 the UNTRANSLATED_NAME attribute. 1058 6.10 text-hint 1060 The value is one of the following enumerations, and indicates what 1061 the server knows about the content of the file. 1063 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 1064 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 1065 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 1066 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 1068 SSH_FILEXFER_ATTR_KNOWN_TEXT 1069 The server knows the file is a text file, and should be opened 1070 using the SSH_FXF_ACCESS_TEXT_MODE flag. 1072 SSH_FILEXFER_ATTR_GUESSED_TEXT 1073 The server has applied a hueristic or other mechanism and believes 1074 that the file should be opened with the SSH_FXF_ACCESS_TEXT_MODE 1075 flag. 1077 SSH_FILEXFER_ATTR_KNOWN_BINARY 1078 The server knows the file has binary content. 1080 SSH_FILEXFER_ATTR_GUESSED_BINARY 1081 The server has applied a hueristic or other mechanism and believes 1082 has binary content, and should not be opened with the 1083 SSH_FXF_ACCESS_TEXT_MODE flag. 1085 This flag MUST NOT be present during either a setstat or a fsetstat 1086 operation. 1088 6.11 mime-type 1090 The 'mime-type' field contains the mime-type [RFC1521] string. Most 1091 servers will not know this information and should not set the bit in 1092 their supported-attribute-mask. 1094 6.12 link-count 1096 This field contains the hard link count of the file. This attribute 1097 MUST NOT be present during a setstat operation. 1099 6.13 untranslated-name 1101 This field contains the name before filename translation was attempt. 1102 It MUST NOT be included unless the server also set the 1103 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 6.9) bit in the 1104 attrib-bits field. 1106 6.14 Extended Attributes 1108 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 1109 mechanism for the attrib structure. If the flag is specified, then 1110 the 'extended_count' field is present. It specifies the number of 1111 'extension-pair' items that follow. Each of these items specifies an 1112 extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED 1113 if there are any unrecognized extensions. Clients can avoid sending 1114 unsupported extensions by examining the attrib-extension-names of the 1115 "supported2" extension attrib-extension-names (Section 4.5). 1117 Additional fields can be added to the attributes by either defining 1118 additional bits to the flags field to indicate their presence, or by 1119 defining extended attributes for them. The extended attributes 1120 mechanism is recommended for most purposes; additional flags bits 1121 should only be defined by an IETF standards action that also 1122 increments the protocol version number. The use of such new fields 1123 MUST be negotiated by the version number in the protocol exchange. 1124 It is a protocol error if a packet with unsupported protocol bits is 1125 received. 1127 7. Requests From the Client to the Server 1129 Requests from the client to the server represent the various file 1130 system operations. 1132 7.1 Opening and Closing Files and Directories 1134 Many operations in the protocol operate on open files. The 1135 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 1136 an opaque, variable-length string) which may be used to access the 1137 file or directory later. The client MUST NOT send requests to the 1138 server with bogus or closed handles. However, the server MUST 1139 perform adequate checks on the handle in order to avoid security 1140 risks due to fabricated handles. 1142 This design allows either stateful and stateless server 1143 implementation, as well as an implementation which caches state 1144 between requests but may also flush it. The contents of the file 1145 handle string are entirely up to the server and its design. The 1146 client should not modify or attempt to interpret the file handle 1147 strings. 1149 The file handle strings MUST NOT be longer than 256 bytes. 1151 7.1.1 Opening a File 1153 Files are opened and created using the SSH_FXP_OPEN message. 1155 byte SSH_FXP_OPEN 1156 uint32 request-id 1157 string filename [UTF-8] 1158 uint32 desired-access 1159 uint32 flags 1160 ATTRS attrs 1162 The response to this message will be either SSH_FXP_HANDLE (if the 1163 operation is successful) or SSH_FXP_STATUS (if the operation fails.) 1165 7.1.1.1 filename 1167 The 'filename' field specifies the file name. See Section ''File 1168 Names'' for more information. If 'filename' is a directory file, the 1169 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 1171 7.1.1.2 desired-access 1173 The 'desired-access' field is a bitmask containing a combination of 1174 values from the ace-mask flags (Section 6.8). Note that again, the 1175 meaning of these flags is given in [RFC3010]. 1177 The server MUST be prepared to translate the SFTP access flags into 1178 its local equivalents. If the server cannot grant the access 1179 desired, it MUST return SSH_FX_PERMISSION_DENIED. 1181 The server MAY open the file with greater access than requested if 1182 the user has such access and the server implementation requires it. 1183 For example, a server that does not distinguish between 1184 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access 1185 to the file when the client only requested READ_ATTRIBUTE, resulting 1186 in greater access than the client originaly requested. 1188 In such cases, it is possible, and permissable in the protocol, that 1189 the client could open a file requesting some limited access, and then 1190 access the file in a way not permitted by that limited access and the 1191 server would permit such action. However, the server MUST NOT ever 1192 grant access to the file that the client does not actually have the 1193 rights to. 1195 7.1.1.3 flags 1197 The 'flags' field controls various aspects of the operation, 1198 including whether or not the file is created and the kind of locking 1199 desired. 1201 The following 'flags' are defined: 1203 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 1204 SSH_FXF_CREATE_NEW = 0x00000000 1205 SSH_FXF_CREATE_TRUNCATE = 0x00000001 1206 SSH_FXF_OPEN_EXISTING = 0x00000002 1207 SSH_FXF_OPEN_OR_CREATE = 0x00000003 1208 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 1209 SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 1210 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 1211 SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 1212 SSH_FXF_ACCESS_BLOCK_READ = 0x00000040 1213 SSH_FXF_ACCESS_BLOCK_WRITE = 0x00000080 1214 SSH_FXF_ACCESS_BLOCK_DELETE = 0x00000100 1215 SSH_FXF_ACCESS_BLOCK_ADVISORY = 0x00000200 1216 SSH_FXF_ACCESS_NOFOLLOW = 0x00000400 1217 SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000800 1219 SSH_FXF_ACCESS_DISPOSITION 1220 Disposition is a 3 bit field that controls how the file is opened. 1221 The server MUST support these bits. Any one of the following 1222 enumeration is allowed: 1224 SSH_FXF_CREATE_NEW 1225 A new file is created; if the file already exists, the server 1226 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 1228 SSH_FXF_CREATE_TRUNCATE 1229 A new file is created; if the file already exists, it is opened 1230 and truncated. 1232 SSH_FXF_OPEN_EXISTING 1233 An existing file is opened. If the file does not exist, the 1234 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 1235 path does not exist, the server SHOULD return 1236 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 1237 returns SSH_FX_NO_SUCH_FILE in this case. 1239 SSH_FXF_OPEN_OR_CREATE 1240 If the file exists, it is opened. If the file does not exist, 1241 it is created. 1243 SSH_FXF_TRUNCATE_EXISTING 1244 An existing file is opened and truncated. If the file does not 1245 exist, the server MUST return the same error codes as defined 1246 for SSH_FXF_OPEN_EXISTING. 1248 SSH_FXF_ACCESS_APPEND_DATA 1249 Data is always written at the end of the file. The offset field 1250 of the SSH_FXP_WRITE requests are ignored. 1252 Data is not required to be appended atomically. This means that 1253 if multiple writers attempt to append data simultaneously, data 1254 from the first may be lost. However, data MAY be appended 1255 atomically. 1257 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1258 Data is always written at the end of the file. The offset field 1259 of the SSH_FXP_WRITE requests are ignored. 1261 Data MUST be written atomically so that there is no chance that 1262 multiple appenders can collide and result in data being lost. 1264 If both append flags are specified, the server SHOULD use atomic 1265 append if it is available, but SHOULD use non-atomic appends 1266 otherwise. The server SHOULD NOT fail the request in this case. 1268 SSH_FXF_TEXT 1269 Indicates that the server should treat the file as text and 1270 convert it to the canonical newline convention in use. (See 1271 Determining Server Newline Convention. (Section 4.3) 1273 When a file is opened with the FXF_TEXT flag, the offset field in 1274 the read and write functions is ignored. 1276 Servers MUST process multiple, parallel reads and writes correctly 1277 in this mode. Naturally, it is permissible for them to do this by 1278 serializing the requests. 1280 Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append 1281 data to a text file rather then using write with a calculated 1282 offset. 1284 To support seeks on text files the following SSH_FXP_EXTENDED 1285 packet is defined. 1287 string "text-seek" 1288 string file-handle 1289 uint64 line-number 1291 line-number is the index of the line number to seek to, where byte 1292 0 in the file is line number 0, and the byte directly following 1293 the first newline sequence in the file is line number 1 and so on. 1295 The response to a "text-seek" request is an SSH_FXP_STATUS 1296 message. 1298 An attempt to seek past the end-of-file should result in a 1299 SSH_FX_EOF status. 1301 Servers SHOULD support at least one "text-seek" in order to 1302 support resume. However, a client MUST be prepared to receive 1303 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 1304 The client can then try a fall-back strategy, if it has one. 1306 Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned 1307 for read or write operations that are not sequential. 1309 SSH_FXF_ACCESS_BLOCK_READ 1310 The server MUST guarantee that no other open has taken place which 1311 blocked handle has been opened with ACE4_READ_DATA access, and 1312 that no other handle will be opened with ACE4_READ_DATA access 1313 until the client closes the handle. (This MUST apply both to 1314 other clients and to other processes on the server.) 1316 If there is a conflicting lock the server MUST return 1317 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1318 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1320 Other handles MAY be opened for ACE4_WRITE_DATA or any other 1321 combinatation of accesses, as long as ACE4_READ_DATA is not 1322 included in the mask. 1324 SSH_FXF_ACCESS_BLOCK_WRITE 1325 The server MUST guarantee that no other lock has been opened with 1326 ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other 1327 handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA 1328 access until the client closes the handle. (This MUST apply both 1329 to other clients and to other processes on the server.) 1330 If there is a conflicting lock the server MUST return 1331 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1332 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1334 Other handles MAY be opened for ACE4_READ_DATA or any other 1335 combinatation of accesses, as long as neither ACE4_WRITE_DATA nor 1336 ACE4_APPEND_DATA are included in the mask. 1338 SSH_FXF_ACCESS_BLOCK_DELETE 1339 The server MUST guarantee that no other handle has been opened 1340 with ACE4_DELETE access, opened with the 1341 SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that no other handle 1342 will be opened with ACE4_DELETE access or with the 1343 SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that the file itself 1344 is not deleted in any other way until the client closes the 1345 handle. 1347 If there is a conflicting lock the server MUST return 1348 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1349 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1351 SSH_FXF_ACCESS_BLOCK_ADVISORY 1352 If this bit is set, the above BLOCK modes are advisory. In 1353 advisory mode, only other accesses that specify a BLOCK mode need 1354 be considered when determining whether the BLOCK can be granted, 1355 and the server need not prevent I/O operations that violate the 1356 block mode. 1358 The server MAY perform mandatory locking even if the 1359 BLOCK_ADVISORY bit is set. 1361 SSH_FXF_ACCESS_NOFOLLOW 1362 If the final component of the path is a symlink, then the open 1363 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 1365 SSH_FXF_ACCESS_DELETE_ON_CLOSE 1366 The file should be deleted when the last handle to it is closed. 1367 (The last handle may not be an sftp-handle.) This MAY be emulated 1368 by a server if the OS doesn't support it by deleting the file when 1369 this handle is closed. 1371 The 'attrs' field specifies the initial attributes for the file. 1372 Default values MUST be supplied by the server for those attributes 1373 that are not specified. See Section ''File Attributes'' for more 1374 information. 1376 The 'attrs' field is ignored if an existing file is opened. 1378 The following table is provided to assist in mapping POSIX semantics 1379 to equivalent SFTP file open parameters: 1380 O_RDONLY 1381 desired-access = READ_DATA|READ_ATTRIBUTES 1383 O_WRONLY 1384 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1386 O_RDWR 1387 desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA| 1388 WRITE_ATTRIBUTES 1390 O_APPEND 1391 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1392 flags = SSH_FXF_ACCESS_APPEND_DATA and or 1393 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1395 O_CREAT 1396 flags = SSH_FXF_OPEN_OR_CREATE 1398 O_TRUNC 1399 flags = SSH_FXF_TRUNCATE_EXISTING 1401 O_TRUNC|O_CREATE 1402 flags = SSH_FXF_CREATE_TRUNCATE 1404 7.1.2 Opening a Directory 1406 To enumerate a directory, the client first obtains a handle and then 1407 issues directory read requests. When enumeration is complete, the 1408 handle MUST be closed. 1410 byte SSH_FXP_OPENDIR 1411 uint32 request-id 1412 string path [UTF-8] 1414 path 1415 The 'path' field is the path name of the directory to be listed 1416 (without any trailing slash). See Section 'File Names' for more 1417 information on file names. 1419 If 'path' does not refer to a directory, the server MUST return 1420 SSH_FX_NOT_A_DIRECTORY. 1422 The response to this message will be either SSH_FXP_HANDLE (if the 1423 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1425 7.1.3 Closing Handles 1427 A handle is closed using the following request. 1429 byte SSH_FXP_CLOSE 1430 uint32 request-id 1431 string handle 1433 handle 1434 'handle' is a handle previously returned in the response to 1435 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid 1436 immediately after this request has been sent. 1438 The response to this request will be a SSH_FXP_STATUS message. Note 1439 that on some server platforms even a close can fail. For example, if 1440 the server operating system caches writes, and an error occurs while 1441 flushing cached writes, the close operation may fail. 1443 Note that the handle is invalid regardless of the SSH_FXP_STATUS 1444 result. There is no way for the client to recover a handle that 1445 fails to close. The client MUST release all resources associated 1446 with the handle regardless of the status. The server SHOULD take 1447 whatever steps it can to recover from a close failure and to ensure 1448 that all resources associated with the handle on the server are 1449 correctly released. 1451 7.2 Reading and Writing 1453 7.2.1 Reading Files 1455 The following request can be used to read file data: 1457 byte SSH_FXP_READ 1458 uint32 request-id 1459 string handle 1460 uint64 offset 1461 uint32 length 1463 handle 1464 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1465 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1466 return SSH_FX_INVALID_HANDLE. 1468 offset 1469 'offset' is the offset (in bytes) relative to the beginning of the 1470 file that the read MUST start at. 'offset' is ignored if 1471 SSH_FXF_TEXT was specified during the open. 1473 length 1474 'length' is the maximum number of bytes to read. 1476 The server MUST not respond with more data than is specified by 1477 the 'length' parameter. However, the server MAY respond with less 1478 data if EOF is reached, an error is encountered, or the servers 1479 internal buffers can not handle such a large request. 1481 If the server specified a non-zero 'max-read-size' in it's 1482 'supported2' (Section 4.5) extension, then failure to return 1483 'length' bytes indicates that EOF or an error occured. 1485 7.2.2 Reading Directories 1487 In order to retrieve a directory listing, the client issues one or 1488 more SSH_FXP_READDIR requests. In order to obtain a complete 1489 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1490 requests until the server responds with an SSH_FXP_STATUS message. 1492 byte SSH_FXP_READDIR 1493 uint32 request-id 1494 string handle 1496 handle 1497 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is 1498 an ordinary file handle returned by SSH_FXP_OPEN, the server MUST 1499 return SSH_FX_INVALID_HANDLE. 1501 The server responds to this request with either a SSH_FXP_NAME or a 1502 SSH_FXP_STATUS message. One or more names may be returned at a time. 1503 Full status information is returned for each name in order to speed 1504 up typical directory listings. 1506 If there are no more names available to be read, the server MUST 1507 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1509 7.2.3 Writing Files 1511 Writing to a file is achieved using the following message: 1513 byte SSH_FXP_WRITE 1514 uint32 request-id 1515 string handle 1516 uint64 offset 1517 string data 1519 handle 1520 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1521 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1522 return SSH_FX_INVALID_HANDLE. 1524 offset 1525 'offset' is the offset (in bytes) relative to the beginning of the 1526 file that the write MUST start at. 'offset' is ignored if 1527 SSH_FXF_TEXT was specified during the open. 1529 The write will extend the file if writing beyond the end of the 1530 file. It is legal to write to an offset that extends beyond the 1531 end of the file; the semantics are to write the byte value 0x00 1532 from the end of the file to the specified offset and then the 1533 data. On most operating systems, such writes do not allocate disk 1534 space but instead create a sparse file. 1536 data 1537 The data to write to the file. 1539 The server responds to a write request with a SSH_FXP_STATUS message. 1541 7.3 Removing and Renaming Files 1543 The following request can be used to remove a file: 1545 byte SSH_FXP_REMOVE 1546 uint32 request-id 1547 string filename [UTF-8] 1549 filename 1550 'filename' is the name of the file to be removed. See Section 1551 'File Names' for more information. 1553 This request cannot be used to remove directories. The server 1554 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. 1556 The server will respond to this request with a SSH_FXP_STATUS 1557 message. 1559 Files (and directories) can be renamed using the SSH_FXP_RENAME 1560 message. 1562 byte SSH_FXP_RENAME 1563 uint32 request-id 1564 string oldpath [UTF-8] 1565 string newpath [UTF-8] 1566 uint32 flags 1568 where 'request-id' is the request identifier, 'oldpath' is the name 1569 of an existing file or directory, and 'newpath' is the new name for 1570 the file or directory. 1572 'flags' is 0 or a combination of: 1574 SSH_FXP_RENAME_OVERWRITE 0x00000001 1575 SSH_FXP_RENAME_ATOMIC 0x00000002 1576 SSH_FXP_RENAME_NATIVE 0x00000004 1578 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1579 exists a file with the name specified by newpath, the server MUST 1580 respond with SSH_FX_FILE_ALREADY_EXISTS. 1582 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1583 already exists, it is replaced in an atomic fashion. I.e., there is 1584 no observable instant in time where the name does not refer to either 1585 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1586 SSH_FXP_RENAME_OVERWRITE. 1588 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace 1589 the destination in an atomic fashion, then the server MUST respond 1590 with SSH_FX_OP_UNSUPPORTED. 1592 Because some servers cannot provide atomic rename, clients should 1593 only specify atomic rename if correct operation requires it. If 1594 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1595 atomic rename even if it is not requested. 1597 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1598 rename operation in whatever fashion it deems appropriate. Other 1599 flag values are considered hints as to desired behavior, but not 1600 requirements. 1602 The server will respond to this request with a SSH_FXP_STATUS 1603 message. 1605 7.4 Creating and Deleting Directories 1607 New directories can be created using the SSH_FXP_MKDIR request. It 1608 has the following format: 1610 byte SSH_FXP_MKDIR 1611 uint32 request-id 1612 string path [UTF-8] 1613 ATTRS attrs 1615 where 'request-id' is the request identifier. 1617 'path' specifies the directory to be created. See Section ''File 1618 Names'' for more information on file names. 1620 'attrs' specifies the attributes that should be applied to it upon 1621 creation. Attributes are discussed in more detail in Section ''File 1622 Attributes''. 1624 The server will respond to this request with a SSH_FXP_STATUS 1625 message. If a file or directory with the specified path already 1626 exists, an error will be returned. 1628 Directories can be removed using the SSH_FXP_RMDIR request, which has 1629 the following format: 1631 byte SSH_FXP_RMDIR 1632 uint32 request-id 1633 string path [UTF-8] 1635 where 'request-id' is the request identifier, and 'path' specifies 1636 the directory to be removed. See Section ''File Names'' for more 1637 information on file names. 1639 The server responds to this request with a SSH_FXP_STATUS message. 1641 7.5 Retrieving File Attributes 1643 Very often, file attributes are automatically returned by 1644 SSH_FXP_READDIR. However, sometimes there is need to specifically 1645 retrieve the attributes for a named file. This can be done using the 1646 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1648 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1649 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1650 follow symbolic links. Both have the same format: 1652 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1653 uint32 request-id 1654 string path [UTF-8] 1655 uint32 flags 1657 where 'request-id' is the request identifier, and 'path' specifies 1658 the file system object for which status is to be returned. The 1659 server responds to this request with either SSH_FXP_ATTRS or 1660 SSH_FXP_STATUS. 1662 The flags field specify the attribute flags in which the client has 1663 particular interest. This is a hint to the server. For example, 1664 because retrieving owner / group and acl information can be an 1665 expensive operation under some operating systems, the server may 1666 choose not to retrieve this information unless the client expresses a 1667 specific interest in it. 1669 The client has no guarantee the server will provide all the fields 1670 that it has expressed an interest in. 1672 SSH_FXP_FSTAT differs from the others in that it returns status 1673 information for an open file (identified by the file handle). 1675 byte SSH_FXP_FSTAT 1676 uint32 request-id 1677 string handle 1678 uint32 flags 1680 handle 1681 'handle' is an open file handle from either SSH_FXP_OPEN or 1682 SSH_FXP_OPENDIR. 1684 The server responds to this request with SSH_FXP_ATTRS or 1685 SSH_FXP_STATUS. 1687 7.6 Setting File Attributes 1689 File attributes may be modified using the SSH_FXP_SETSTAT and 1690 SSH_FXP_FSETSTAT requests. 1692 byte SSH_FXP_SETSTAT 1693 uint32 request-id 1694 string path [UTF-8] 1695 ATTRS attrs 1696 byte SSH_FXP_FSETSTAT 1697 uint32 request-id 1698 string handle 1699 ATTRS attrs 1701 path 1702 The file system object (e.g. file or directory) whose attributes 1703 are to be modified. If this object does not exist, or the user 1704 does not have sufficient access to write the attributes, the 1705 request MUST fail. 1707 handle 1708 'handle' is an open file handle from either SSH_FXP_OPEN or 1709 SSH_FXP_OPENDIR. If the handle was not opened with sufficient 1710 access to write the requested attributes, the request MUST fail. 1712 attrs 1713 Specifies the modified attributes to be applied. Attributes are 1714 discussed in more detail in Section ''File Attributes''. 1716 The server will respond with a SSH_FXP_STATUS message. 1718 Because some systems must use separate system calls to set various 1719 attributes, it is possible that a failure response will be returned, 1720 but yet some of the attributes may be have been successfully 1721 modified. If possible, servers SHOULD avoid this situation; however, 1722 clients MUST be aware that this is possible. 1724 7.7 Dealing with Links 1726 The SSH_FXP_READLINK request reads the target of a symbolic link. 1728 byte SSH_FXP_READLINK 1729 uint32 request-id 1730 string path [UTF-8] 1732 where 'request-id' is the request identifier and 'path' specifies the 1733 path name of the symlink to be read. 1735 The server will respond with a SSH_FXP_NAME packet containing only 1736 one name and a dummy attributes value. The name in the returned 1737 packet contains the target of the link. If an error occurs, the 1738 server MAY respond with SSH_FXP_STATUS. 1740 The SSH_FXP_LINK request creates a link (either hare or symbolic) on 1741 the server. 1743 byte SSH_FXP_LINK 1744 uint32 request-id 1745 string new-link-path [UTF-8] 1746 string existing-path [UTF-8] 1747 bool sym-link 1749 new-link-path 1750 Specifies the path name of the new link to create. 1752 existing-path 1753 Specifies the path of an existing file system object to which the 1754 new-link-path will refer. 1756 sym-link 1757 Specifies that the link should be a symbolic link, or a special 1758 file that redirects file system parsing to the resulting path. It 1759 is generally possible to create symbolic links across device 1760 boundaries; however, it is not required that a server support 1761 this. 1763 If 'sym-link' is false, the link should be a hard link, or a 1764 second directory entry refering to the same file or directory 1765 object. It is generally not possible to create hard links across 1766 devices. 1768 The server shall respond with a SSH_FXP_STATUS. Clients should be 1769 aware that some servers may return SSH_FX_OP_UNSUPPORTED for either 1770 the hard-link, sym-link, or both operations. 1772 The SSH_FXP_LOCK creates a byte-range lock on the file specified by 1773 the handle. The lock can be either mandatory (meaning that the 1774 server enforces that no other process or client can perform 1775 operations in violation of the lock) or advisory (meaning that no 1776 other process can obtain a conflicting lock, but the server does not 1777 enforce that no operation violates the lock. 1779 A server MAY implement an advisory lock in a mandatory fashion; in 1780 other words, the server MAY enforce that no operation violates the 1781 lock even when operating in advisory mode. 1783 The result is a SSH_FXP_STATUS return. 1785 byte SSH_FXP_BLOCK 1786 uint32 request-id 1787 string handle 1788 uint64 offset 1789 uint64 length 1790 uint32 uLockMask 1792 handle 1793 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1794 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1795 return SSH_FX_INVALID_HANDLE. 1797 offset 1798 Beginning of the byte-range to lock. 1799 length 1800 Number of bytes in the range to lock. The special value 0 means 1801 lock from 'offset' to the end of the file. 1802 uLockMask 1803 A bit mask of SSH_FXF_ACCESS_BLOCK_* values; the meanings are 1804 described in Section 7.1.1.3. 1806 The SSH_FXP_UNLOCK removes a previously aquired byte-range lock on 1807 the specified handle. 1809 The result is a SSH_FXP_STATUS return. 1811 byte SSH_FXP_UNBLOCK 1812 uint32 request-id 1813 string handle 1814 uint64 offset 1815 uint64 length 1817 handle 1818 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1819 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1820 return SSH_FX_INVALID_HANDLE. 1822 offset 1823 Beginning of the byte-range to lock. 1824 length 1825 Number of bytes in the range to lock. The special value 0 means 1826 lock from 'offset' to the end of the file. 1828 7.8 Canonicalizing the Server-Side Path Name 1830 The SSH_FXP_REALPATH request can be used to have the server 1831 canonicalize any given path name to an absolute path. This is useful 1832 for converting path names containing ".." components or relative 1833 pathnames without a leading slash into absolute paths. The format of 1834 the request is as follows: 1836 byte SSH_FXP_REALPATH 1837 uint32 request-id 1838 string original-path [UTF-8] 1839 string compose-path [optional] 1840 byte control-byte [optional] 1842 original-path 1843 The first component of the path which the client wishes resolved 1844 into a absolute canonical path. This may be the entire path. 1846 compose-path 1847 A path which the client wishs the server to compose with the 1848 original path to form the new path. This field is optional, and 1849 if it is not present in the packet, it is assumed to be a zero 1850 length string. 1852 control-byte 1854 SSH_FXP_REALPATH_NO_CHECK 0x00000001 1855 SSH_FXP_REALPATH_STAT_IF 0x00000002 1856 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 1858 This field is optional, and if it is not present in the packet, it 1859 is assumed to be SSH_FXP_REALPATH_NO_CHECK. 1861 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT 1862 fail the request if the path does not exist, is hidden, or the 1863 user does not have access to the path or some component thereof. 1864 However, the path MAY NOT be completely resolved to it's component 1865 form. For example, symlinks may not be followed in this case. 1866 The server MAY fail the request if the path is not syntactically 1867 valid, or for other reasons. 1869 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the 1870 path if it exists and is accessible to the client. However, if 1871 the path does not exist, isn't visible, or isn't accessible, the 1872 server MUST NOT fail the request. If the stat failed, the file 1873 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to 1874 distinguish between files that are actually 1875 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will 1876 have to issue a seperate stat command in this case. 1878 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat 1879 the path. If the stat operation fails, the server MUST fail the 1880 request. 1882 The server MUST take the 'original-path' and apply the 'compose-path' 1883 as a modification to it. 'compose-path' MAY be relative to 'original- 1884 path' or may be an absolute path, in which case 'original-path' will 1885 be discarded. The 'compose-path' may be zero length. 1887 The server will respond with a SSH_FXP_NAME packet containing the 1888 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK 1889 is specified, the attributes are dummy values. 1891 7.8.1 Best Practice for Dealing with Paths 1893 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 1895 Previous to this version, clients typically composed new paths 1896 themselves and then called both realpath and stat on the resulting 1897 path to get its canonical name and see if it really existed and was a 1898 directory. 1900 This required clients to assume certain things about how a relative 1901 vs. realpath looked. The new realpath allows clients to no longer 1902 make those assumptions and to remove one round trip from the process 1903 and get deterministic behavior from all servers. 1905 END: RFCEDITOR REMOVE BEFORE PUBLISHING 1907 The client SHOULD treat the results of SSH_FXP_REALPATH as a 1908 canonical absolute path, even if the path does not appear to be 1909 absolute. A client that uses REALPATH(".", "") and treats the result 1910 as absolute, even if there is no leading slash, will continue to 1911 function correctly, even when talking to a Windows NT or VMS style 1912 system, where absolute paths may not begin with a slash. 1914 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so 1915 that it does not need to know when a path is absolute or relative. 1917 For example, if the client wishes to change directory up, and the 1918 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 1919 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) 1921 As a second example, if the client wishes transfer local file "a" to 1922 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the 1923 canonical path of the current directory, the client SHOULD send 1924 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This 1925 call will determine the correct path to use for the open request and 1926 whether the /b/d/e represents a directory. 1928 8. Responses from the Server to the Client 1930 The server responds to the client using one of a few response 1931 packets. All requests can return a SSH_FXP_STATUS response upon 1932 failure. When the operation is successful, and no data needs to be 1933 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 1934 appropriate. 1936 Exactly one response will be returned for each request. Each 1937 response packet contains a request identifier which can be used to 1938 match each response with the corresponding request. Note that it is 1939 legal to have several requests outstanding simultaneously, and the 1940 server is allowed to send responses to them in a different order from 1941 the order in which the requests were sent (the result of their 1942 execution, however, is guaranteed to be as if they had been processed 1943 one at a time in the order in which the requests were sent). 1945 Response packets are of the same general format as request packets. 1946 Each response packet begins with the request identifier. 1948 8.1 Status Response 1950 The format of the data portion of the SSH_FXP_STATUS response is as 1951 follows: 1953 byte SSH_FXP_STATUS 1954 uint32 request-id 1955 uint32 error/status code 1956 string error message (ISO-10646 UTF-8 [RFC-2279]) 1957 string language tag (as defined in [RFC-1766]) 1958 error-specific data 1960 request-id 1961 The 'request-id' specified by the client in the request the server 1962 is responding to. 1964 error/status code 1965 Machine readable status code indicating the result of the request. 1966 Error code values are defined below. The value SSH_FX_OK 1967 indicates success, and all other values indicate failure. 1969 error message 1970 Human readable description of the error. 1972 language tag 1973 'language tag' specifies the language the error is in. 1974 1975 The error-specific data may be empty, or may contain additional 1976 information about the error. For error codes that send error- 1977 specific data, the format of the data is defined below. 1979 Error codes: 1981 SSH_FX_OK 0 1982 SSH_FX_EOF 1 1983 SSH_FX_NO_SUCH_FILE 2 1984 SSH_FX_PERMISSION_DENIED 3 1985 SSH_FX_FAILURE 4 1986 SSH_FX_BAD_MESSAGE 5 1987 SSH_FX_NO_CONNECTION 6 1988 SSH_FX_CONNECTION_LOST 7 1989 SSH_FX_OP_UNSUPPORTED 8 1990 SSH_FX_INVALID_HANDLE 9 1991 SSH_FX_NO_SUCH_PATH 10 1992 SSH_FX_FILE_ALREADY_EXISTS 11 1993 SSH_FX_WRITE_PROTECT 12 1994 SSH_FX_NO_MEDIA 13 1995 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 1996 SSH_FX_QUOTA_EXCEEDED 15 1997 SSH_FX_UNKNOWN_PRINCIPAL 16 1998 SSH_FX_LOCK_CONFLICT 17 1999 SSH_FX_DIR_NOT_EMPTY 18 2000 SSH_FX_NOT_A_DIRECTORY 19 2001 SSH_FX_INVALID_FILENAME 20 2002 SSH_FX_LINK_LOOP 21 2003 SSH_FX_CANNOT_DELETE 22 2004 SSH_FX_INVALID_PARAMETER 23 2005 SSH_FX_FILE_IS_A_DIRECTORY 24 2006 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 2007 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 2008 SSH_FX_DELETE_PENDING 27 2009 SSH_FX_FILE_CORRUPT 28 2011 SSH_FX_OK 2012 Indicates successful completion of the operation. 2014 SSH_FX_EOF 2015 An attempt to read past the end-of-file was made; or, there are no 2016 more directory entries to return. 2018 SSH_FX_NO_SUCH_FILE 2019 A reference was made to a file which does not exist. 2021 SSH_FX_PERMISSION_DENIED 2022 The user does not have sufficient permissions to perform the 2023 operation. 2025 SSH_FX_FAILURE 2026 An error occured, but no specific error code exists to describe 2027 the failure. 2029 This error message SHOULD always have meaningful text in the the 2030 'error message' field. 2032 SSH_FX_BAD_MESSAGE 2033 A badly formatted packet or other SFTP protocol incompatibility 2034 was detected. 2036 SSH_FX_NO_CONNECTION 2037 There is no connection to the server. This error MAY be used 2038 locally, but MUST NOT be return by a server. 2040 SSH_FX_CONNECTION_LOST 2041 The connection to the server was lost. This error MAY be used 2042 locally, but MUST NOT be return by a server. 2044 SSH_FX_OP_UNSUPPORTED 2045 An attempted operation could not be completed by the server 2046 because the server does not support the operation. 2048 This error MAY be generated locally by the client if e.g. the 2049 version number exchange indicates that a required feature is not 2050 supported by the server, or it may be returned by the server if 2051 the server does not implement an operation). 2053 SSH_FX_INVALID_HANDLE 2054 The handle value was invalid. 2056 SSH_FX_NO_SUCH_PATH 2057 The file path does not exist or is invalid. 2059 SSH_FX_FILE_ALREADY_EXISTS 2060 The file already exists. 2062 SSH_FX_WRITE_PROTECT 2063 The file is on read-only media, or the media is write protected. 2065 SSH_FX_NO_MEDIA 2066 The requested operation cannot be completed because there is no 2067 media available in the drive. 2069 SSH_FX_NO_SPACE_ON_FILESYSTEM 2070 The requested operation cannot be completed because there is no 2071 free space on the filesystem. 2073 SSH_FX_QUOTA_EXCEEDED 2074 The operation cannot be completed because it would exceed the 2075 user's storage quota. 2077 SSH_FX_UNKNOWN_PRINCIPAL 2078 A principal referenced by the request (either the 'owner', 2079 'group', or 'who' field of an ACL), was unknown. The error 2080 specific data contains the problematic names. The format is one 2081 or more: 2083 string unknown-name 2085 Each string contains the name of a principle that was unknown. 2087 SSH_FX_LOCK_CONFLICT 2088 The file could not be opened because it is locked by another 2089 process. 2091 SSH_FX_DIR_NOT_EMPTY 2092 The directory is not empty. 2094 SSH_FX_NOT_A_DIRECTORY 2095 The specified file is not a directory. 2097 SSH_FX_INVALID_FILENAME 2098 The filename is not valid. 2100 SSH_FX_LINK_LOOP 2101 Too many symbolic links encountered. 2103 SSH_FX_CANNOT_DELETE 2104 The file cannot be deleted. One possible reason is that the 2105 advisory READONLY attribute-bit is set. 2107 SSH_FX_INVALID_PARAMETER 2108 On of the parameters was out of range, or the parameters specified 2109 cannot be used together. 2111 SSH_FX_FILE_IS_A_DIRECTORY 2112 The specifed file was a directory in a context where a directory 2113 cannot be used. 2115 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 2116 Some operating systems support locking a range of bytes within a 2117 file. On such operating systems, it is possible for a SFTP 2118 request to fail due to some other process owning a byte-range 2119 lock, even though the SFTP protocol does not support byte-range 2120 locks natively. 2122 A read or write operation failed because another process's byte- 2123 range lock overlaps with the request. 2125 SSH_FX_BYTE_RANGE_LOCK_REFUSED 2126 A request for a byte range lock was refused. 2128 SSH_FX_DELETE_PENDING 2129 An operation was attempted on a file for which a delete operation 2130 is pending. 2132 SSH_FX_FILE_CORRUPT 2133 The file is corrupt; an filesystem integrity check should be run. 2135 8.2 Handle Response 2137 The SSH_FXP_HANDLE response has the following format: 2139 byte SSH_FXP_HANDLE 2140 uint32 request-id 2141 string handle 2143 'handle' 2144 An arbitrary string that identifies an open file or directory on 2145 the server. The handle is opaque to the client; the client MUST 2146 NOT attempt to interpret or modify it in any way. The length of 2147 the handle string MUST NOT exceed 256 data bytes. 2149 8.3 Data Response 2151 The SSH_FXP_DATA response has the following format: 2153 byte SSH_FXP_DATA 2154 uint32 request-id 2155 string data 2156 bool end-of-file [optional] 2158 data 2159 'data' is an arbitrary byte string containing the requested data. 2160 The data string may be at most the number of bytes requested in a 2161 SSH_FXP_READ request, but may also be shorter. (See 2162 Section 7.2.1.) 2164 end-of-file 2165 This field is optional. If it is present in the packet, it MUST 2166 be true, and it indicates that EOF was reached during this read. 2167 This can help the client avoid a round trip to determine whether a 2168 short read was normal (due to EOF) or some other problem (limited 2169 server buffer for example.) 2171 8.4 Name Response 2173 The SSH_FXP_NAME response has the following format: 2175 byte SSH_FXP_NAME 2176 uint32 request-id 2177 uint32 count 2178 repeats count times: 2179 string filename [UTF-8] 2180 ATTRS attrs 2181 bool end-of-list [optional] 2183 count 2184 The number of names returned in this response, and the 'filename' 2185 and 'attrs' field repeat 'count' times. 2187 filename 2188 A file name being returned (for SSH_FXP_READDIR, it will be a 2189 relative name within the directory, without any path components; 2190 for SSH_FXP_REALPATH it will be an absolute path name.) 2192 attrs 2193 The attributes of the file as described in Section ''File 2194 Attributes''. 2196 end-of-list 2197 This field is optional. If present in the packet, it MUST be 2198 true, and indicates that there are no more entries to be read. 2199 This can save the client a round trip to determine if there are 2200 more entries to be read. 2202 8.5 Attrs Response 2204 The SSH_FXP_ATTRS response has the following format: 2206 byte SSH_FXP_ATTRS 2207 uint32 request-id 2208 ATTRS attrs 2210 attrs 2211 The returned file attributes as described in Section ''File 2212 Attributes''. 2214 9. Extensions 2216 The SSH_FXP_EXTENDED request provides a generic extension mechanism 2217 for adding additional commands. 2219 byte SSH_FXP_EXTENDED 2220 uint32 request-id 2221 string extended-request 2222 ... any request-specific data ... 2224 request-id 2225 Identifier to be returned from the server with the response. 2227 extended-request 2228 A string naming the extension. Vendor-specific extensions have 2229 use the "name@domain" syntax, where domain is an internet domain 2230 name of the vendor defining the request. 2232 The IETF may also define extensions to the protocol. These 2233 extension names will not have an '@' in them. 2235 request-specific data 2236 The rest of the request is defined by the extension; servers 2237 SHOULD NOT attempt to interpret it if they do not recognize the 2238 'extended-request' name. 2240 The server may respond to such requests using any of the response 2241 packets defined in Section ''Responses from the Server to the 2242 Client''. Additionally, the server may also respond with a 2243 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 2244 not recognize the 'extended-request' name, then the server MUST 2245 respond with SSH_FXP_STATUS with error/status set to 2246 SSH_FX_OP_UNSUPPORTED. 2248 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 2249 extension-specific data from the server to the client. It is of the 2250 following format: 2252 byte SSH_FXP_EXTENDED_REPLY 2253 uint32 request-id 2254 ... any request-specific data ... 2256 There is a range of packet types reserved for use by extensions. In 2257 order to avoid collision, extensions that that use additional packet 2258 types should determine those numbers dynamically. 2260 The suggested way of doing this is have an extension request from the 2261 client to the server that enables the extension; the extension 2262 response from the server to the client would specify the actual type 2263 values to use, in addition to any other data. 2265 Extension authors should be mindful of the limited range of packet 2266 types available (there are only 45 values available) and avoid 2267 requiring a new packet type where possible. 2269 9.1 File Hashing 2271 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 2273 After some discussion of this at connectathon, I know of two uses for 2274 this feature, neither one of which the feature is entirely suited 2275 for: 2276 o Checking that a file has been uploaded to the server correctly; 2277 some portion of the customers wanting this feature want it in a 2278 security sense, as part of proof the server has the file. 2279 o Optimizing upload or download of the file; multiple hashes are 2280 performed on small pieces of the file and the results are used to 2281 determine what chunks of the file, if any, need to be transfered. 2282 This is similar to the way rsync works. 2284 I've seen both of these implemented. 2286 For the first case, the extension has several drawbacks, including: 2287 o A FIPS implementation can't ship md5. 2288 o MD5's security is potential weaker than other options. 2289 o Being hard-coded to MD5 makes in impossible to adapt to future 2290 developments in the arena of MD5 compromises. 2292 For the second case, the extension has these drawbacks: 2293 o MD5 is expensive (relative to other options.) 2294 o The extension must be sent potentially thousands of times to 2295 retrieve the desired granularity of hashes. 2297 Therefore, for this draft, this section is marked experimental; I've 2298 included a second proposed extension. Please post your thoughts on 2299 the mailing list. (I did it this way just so I could get a draft out 2300 that I and my active co-author are happy with. 2302 In addition, implemenation experience has shown the quick check hash 2303 to not be useful. 2305 END: RFCEDITOR REMOVE BEFORE PUBLISHING 2307 9.1.1 Checking File Contents: v5 extension 2309 This extension allows a client to easily check if a file (or portion 2310 thereof) that it already has matches what is on the server. 2312 byte SSH_FXP_EXTENDED 2313 uint32 request-id 2314 string "md5-hash" / "md5-hash-handle" 2315 string filename [UTF-8] / file-handle 2316 uint64 start-offset 2317 uint64 length 2318 string quick-check-hash 2320 filename 2321 Used if "md5-hash" is specified; indicates the name of the file to 2322 use. The hash will be of the file contents as it would appear on 2323 the wire if the file were opened with no special flags. 2325 file-handle 2326 Used if "md5-hash-handle" is specified; specifies a file handle to 2327 read the data from. The handle MUST be a file handle, and 2328 ACE4_READ_DATA MUST have been included in the desired-access when 2329 the file was opened. 2331 If this file handle was opened in TEXT mode, the md5-hash must be 2332 made of the data as it would be sent on the wire. 2334 start-offset 2335 The starting offset of the data to hash. 2337 length 2338 The length of data to include in the hash. If both start-offset 2339 and length are zero, the entire file should be included. 2341 quick-check-hash 2342 The hash over the first 2048 bytes of the data range as the client 2343 knows it, or the entire range, if it is less than 2048 bytes. 2344 This allows the server to quickly check if it is worth the 2345 resources to hash a big file. 2347 If this is a zero length string, the client does not have the 2348 data, and is requesting the hash for reasons other than comparing 2349 with a local file. The server MAY return SSH_FX_OP_UNSUPPORTED in 2350 this case. 2352 The response is either a SSH_FXP_STATUS packet, indicating an error, 2353 or the following extended reply packet: 2355 byte SSH_FXP_EXTENDED_REPLY 2356 uint32 request-id 2357 string "md5-hash" 2358 string hash 2360 If 'hash' is zero length, then the 'quick-check-hash' did not match, 2361 and no hash operation was preformed. Otherwise, 'hash' contains the 2362 hash of the entire data range (including the first 2048 bytes that 2363 were included in the 'quick-check-hash'.) 2365 9.1.2 Checking File Contents 2367 This extension allows a client to easily check if a file (or portion 2368 thereof) that it already has matches what is on the server. 2370 byte SSH_FXP_EXTENDED 2371 uint32 request-id 2372 string "check-file" 2373 string handle 2374 string hash-algorithm-list 2375 uint64 start-offset 2376 uint64 length 2377 uint32 block-size 2379 handle 2380 'handle' is an open file handle returned by SSH_FXP_OPEN. If 2381 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 2382 return SSH_FX_INVALID_HANDLE. If ACE4_READ_DATA MUST was not 2383 included when the file was opened, the server MUST return 2384 STATUS_PERMISSION_DENIED. 2386 If this file handle was opened in TEXT mode, the check must be 2387 performed on the data as it would be sent on the wire. 2389 hash-algorithm-list 2390 A comma separated list of hash alogirthms the client is willing to 2391 accept for this operation. The server MUST pick the first hash on 2392 the list that it supports. 2394 Currently supported algorithms are "md5", "sha1", "sha224", 2395 "sha256", "sha384", "sha512", and "crc32". Additional algorithms 2396 may be added by following the DNS extensibility naming convention 2397 outlined in [I-D.ietf-secsh-architecture]. 2399 MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384, 2400 and SHA-512 are decribed in [FIPS-180-2]. crc32 is described in 2401 [ISO.3309.1991], and is the same algorithm used in [RFC1510] 2403 start-offset 2404 The starting offset of the data to include in the hash. 2406 length 2407 The length of data to include in the hash. If length is zero, all 2408 the data from start-offset to the end-of-file should be included. 2410 block-size 2411 An independant hash MUST be computed over every block in the file. 2412 The size of blocks is specified by block-size. The block-size 2413 MUST NOT be smaller than 256 bytes. If the block-size is 0, then 2414 only one hash, over the entire range, MUST be made. 2416 The response is either a SSH_FXP_STATUS packet, indicating an error, 2417 or the following extended reply packet: 2419 byte SSH_FXP_EXTENDED_REPLY 2420 uint32 request-id 2421 string "check-file" 2422 string hash-algo-used 2423 byte hash[n][block-count] 2425 hash-algo-used 2426 The hash algorithm that was actually used. 2428 hash 2429 The computed hashes. The hash algorithm used determines the size 2430 of n. The number of block-size chunks of data in the file 2431 determines block-count. The hashes are placed in the packet one 2432 after another, with no decoration. 2434 Note that if the length of the range is not an even multiple of 2435 block-size, the last hash will have been computed over only the 2436 remainder of the range instead of a full block. 2438 9.2 Querying Available Space 2440 The following extension provides a way to discover the available 2441 space for an arbitrary path. 2443 byte SSH_FXP_EXTENDED 2444 uint32 request-id 2445 string "space-available" 2446 string path [UTF-8] 2448 path 2449 'path' for which the available space should be reported. This 2450 'path' is not required to be the mount point path, but MAY be a 2451 directory or file contained within the mount. 2453 The reply to the request is as follows: 2455 byte SSH_FXP_EXTENDED_REPLY 2456 uint32 request-id 2457 uint64 bytes-on-device 2458 uint64 unused-bytes-on-device 2459 uint64 bytes-available-to-user 2460 uint64 unused-bytes-available-to-user 2461 uint32 bytes-per-allocation-unit 2463 bytes-on-device 2464 The total number of bytes on the device which stores 'path', both 2465 used and unused, or 0 if unknown. 2467 unused-bytes-on-device 2468 The total number of unused bytes available on the device which 2469 stores 'path', or 0 if unknown. 2471 bytes-available-to-user 2472 The total number of bytes, both used and unused, available to the 2473 authenticated user on the device which stores 'path', or 0 if 2474 unknown. 2476 unused-bytes-available-to-user 2477 The total number of unused bytes available to the authenticated 2478 user on the device which stores 'path', or 0 if unknown. 2480 bytes-per-allocation-unit 2481 The number of bytes in each allocation unit on the device, or in 2482 other words, the minimum number of bytes that a file allocation 2483 size can grow or shrink by. If the server does not know this 2484 information, or the file-system in use does not use allocation 2485 blocks, this value MUST be 0. 2487 9.3 Querying User Home Directory 2489 Many users are used to being able to type '~' as an alias for their 2490 home directory, or ~username as an alias for another user's home 2491 directory. To support this feature, a server MAY support following 2492 extension. 2494 byte SSH_FXP_EXTENDED 2495 uint32 request-id 2496 string "home-directory" 2497 string username [UTF-8] 2499 username 2500 Username whose home directory path is being requested. An empty 2501 string implies the current user. 2503 The reply to the request is either a SSH_FXP_STATUS packet or the 2504 following extended reply: 2506 byte SSH_FXP_EXTENDED_REPLY 2507 uint32 request-id 2508 string "home-directory" 2509 string absolute-pathname 2511 absolute-pathname 2512 Absolute pathname of the specified user's home directory, suitable 2513 for use in operations such as REALPATH or OPEN. 2515 10. Implementation Considerations 2517 In order for this protocol to perform well, especially over high 2518 latency networks, multiple read and write requests should be queued 2519 to the server. 2521 The data size of requests should match the maximum packet size for 2522 the next layer up in the protocol chain. 2524 When implemented over ssh, the best performance should be achieved 2525 when the data size matches the channel's max packet, and the channel 2526 window is a multiple of the channel packet size. 2528 Implementations MUST be aware that requests do not have to be 2529 satisfied in the order issued. (See Request Synchronization and 2530 Reordering (Section 3.1).) 2532 Implementations MUST also be aware that read requests may not return 2533 all the requested data, even if the data is available. 2535 11. Security Considerations 2537 It is assumed that both ends of the connection have been 2538 authenticated and that the connection has privacy and integrity 2539 features. Such security issues are left to the underlying transport 2540 protocol, except to note that if this is not the case, an attacker 2541 could manipulate files on the server at will and thus wholly 2542 compromise the server. 2544 This protocol provides file system access to arbitrary files on the 2545 server (constrained only by the server implementation). It is the 2546 responsibility of the server implementation to enforce any access 2547 controls that may be required to limit the access allowed for any 2548 particular user (the user being authenticated externally to this 2549 protocol, typically using [I-D.ietf-secsh-userauth]. 2551 Extreme care must be used when interpreting file handle strings. In 2552 particular, care must be taken that a file handle string is valid in 2553 the context of a given 'file-share' session. For example, the 'file- 2554 share' server daemon may have files which it has opened for its own 2555 purposes, and the client must not be able to access these files by 2556 specifying an arbitrary file handle string. 2558 The permission field of the attrib structure (Section 6.6) may 2559 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 2560 extreme caution when setting these bits on either remote or local 2561 files. (I.e., just because a file was SUID on the remote system does 2562 not necessarily imply that it should be SUID on the local system.) 2564 Filesystems often contain entries for objects that are not files at 2565 all, but are rather devices. For example, it may be possible to 2566 access serial ports, tape devices, or named pipes using this 2567 protocol. Servers should exercise caution when granting access to 2568 such resources. In addition to the dangers inherent in allowing 2569 access to such a device, some devices may be 'slow', and could cause 2570 denial of service by causing the server to block for a long period of 2571 time while I/O is performed to such a device. 2573 Servers should take care that file-system quotas are respected for 2574 users. In addition, implementations should be aware that attacks may 2575 be possible, or facilitated, by filling a filesystem. For example, 2576 filling the filesystem where event logging and auditing occurs may, 2577 at best, cause the system to crash, or at worst, allow the attacker 2578 to take untraceable actions in the future. 2580 Servers should take care that filenames are in their appropriate 2581 canonical form, and to ensure that filenames not in canonical form 2582 cannot be used to bypass access checks or controls. 2584 If the server implementation limits access to certain parts of the 2585 file system, extra care must be taken in parsing file names which 2586 contain the '..' path element, and when following symbolic links, 2587 shortcuts, or other filesystem objects which might transpose the path 2588 to refer to an object outside of the restricted area. There have 2589 been numerous reported security bugs where a ".." in a path name has 2590 allowed access outside the intended area. 2592 12. Changes from Previous Protocol Versions 2594 The SSH File Transfer Protocol has changed over time, before its 2595 standardization. The following is a description of the incompatible 2596 changes between different versions. 2598 12.1 Changes Between Versions 6 and 5 2599 o Add ability to negotiate version when client supports discontigous 2600 ranges of protocol version. 2601 o Add 'filename-charset' and the 'filename-translation-control' 2602 extensions to allow better support of servers that can't reliably 2603 translate to UTF-8. 2604 o Add DIR_NOT_EMPTY, NOT_A_DIRECTORY, INVALID_FILENAME LINK_LOOP, 2605 CANNOT_DELETE, INVALID_PARAMETER, FILE_IS_A_DIRECTORY, 2606 BYTE_RANGE_LOCK_CONFLICT, BYTE_RANGE_LOCK_REFUSED, DELETE_PENDING, 2607 and FILE_CORRUPT error codes. 2608 o Added space-available extension. 2609 o Added NOFOLLOW and DELETE_ON_CLOSE flag to open flags. 2610 o Added allocation-size, text-hint, link-count, mime-type, and 2611 untranslated-name fields to attrib structure. Add 2612 ATTR_FLAGS_TRANSLATION_ERR to the attrib-bits. 2613 o Add optional 'compose-path' and 'control-byte' to REALPATH; make 2614 realpath's behaviour truly deterministic (i.e., MUST instead of 2615 SHOULD.) Give clients the ability to compose path's without 2616 understanding what is relative and what is absolute. 2617 o Give SSH_FXP_DATA and SSH_FXP_NAME optional end-of-data-set flags, 2618 which can help the client avoid a round trip during normal 2619 operation. 2621 o Changed the SYMLINK packet to be LINK and give it the ability to 2622 create hard links. Also change it's packet number because many 2623 implementation implemented SYMLINK with the arguments reversed. 2624 Hopefully the new argument names make it clear which way is which. 2625 o Clarify who should apply umask to POSIX mode bits (the client, not 2626 the server.) 2627 o Specify behavior for otherwise valid packets with excess data and 2628 unrecognized packet types. 2629 o Add home directory extension. 2630 o Remove "#define" from symbol definitions to shorten line and help 2631 us pass idnits. 2632 o Change "supported" extension to "supported2", remove desired- 2633 access-bits, seperate attrib extension from SSH_FXP_EXTENDED 2634 extensions. 2635 o Add "vendor-id" extension. 2636 o Add ctime and attrib-bits-valid to attrib structure. 2637 o Unrecognized attrib extensions cause failure rather than ignored. 2638 o Option 'end of data' flags on data ane names responses. 2640 12.2 Changes Between Versions 5 and 4 2642 Many of the changes between version 5 and version 4 are to better 2643 support the changes in version 4, and to better specify error 2644 conditions. 2646 o Add "supported" extension to communicate features supported. 2647 o Clarify error handling when client requests unsupported feature. 2648 (For example, attempts to write an unsupported attribute.) 2649 o Add attrib-bits field to the attribute structure, which specifies 2650 a number of boolean attributes related to files and directories, 2651 including advisory read-only and case-sensitivity bits. 2652 o Clarify the actual bit values to be used for the permissions field 2653 (since POSIX doesn't define values) and correct the value of 2654 ATTR_PERMISSIONS flag. 2655 o Some reordering of sections to attempt to get a better grouping of 2656 related functionality. 2657 o Open request explicitly specifies the access desired for the file. 2658 o Add support for explicitly requesting file locking. 2659 o Add support for better control of the rename operation. 2660 o Add SSH_FX_NO_SPACE_ON_FILESYSTEM, SSH_FX_QUOTA_EXCEEDED, and 2661 SSH_FX_UNKNOWN_PRINCIPLE error codes. 2662 o Add support for error specific data. This is used by a new 2663 SSH_FX_UNKNOWN_PRINCIPLE error to communicate which principles are 2664 unknown. 2665 o Add support for retrieving md5-hash of file contents. 2666 o Update security section. 2668 12.3 Changes Between Versions 4 and 3 2670 Many of the changes between version 4 and version 3 are to the 2671 attribute structure to make it more flexible for non-unix platforms. 2673 o Clarify the use of stderr by the server. 2674 o Clarify handling of very large read requests by the server. 2675 o Make all filenames UTF-8. 2676 o Added 'newline' extension. 2677 o Made time fields 64 bit, and optionally have nanosecond 2678 resolution. 2679 o Made file attribute owner and group strings so they can actually 2680 be used on disparate systems. 2681 o Added createtime field, and added separate flags for atime, 2682 createtime, and mtime so they can be set separately. 2683 o Split the file type out of the permissions field and into its own 2684 field (which is always present.) 2685 o Added acl attribute. 2686 o Added SSH_FXF_TEXT file open flag. 2687 o Added flags field to the get stat commands so that the client can 2688 specifically request information the server might not normally 2689 included for performance reasons. 2690 o Removed the long filename from the names structure-- it can now be 2691 built from information available in the attrs structure. 2692 o Added reserved range of packet numbers for extensions. 2693 o Added several additional error codes. 2695 12.4 Changes Between Versions 3 and 2 2697 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. 2698 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were 2699 added. 2700 o The SSH_FXP_STATUS message was changed to include fields 'error 2701 message' and 'language tag'. 2703 12.5 Changes Between Versions 2 and 1 2705 o The SSH_FXP_RENAME message was added. 2707 12.6 Changes Between Versions 1 and 0 2709 o Implementation changes, no actual protocol changes. 2711 13. References 2712 13.1 Normative References 2714 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 2715 April 1992. 2717 [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network 2718 Authentication Service (V5)", RFC 1510, September 1993. 2720 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2721 Beame, C., Eisler, M., and D. Noveck, "NFS version 4 2722 Protocol", RFC 3010, December 2000. 2724 [I-D.ietf-secsh-architecture] 2725 Lonvick, C., "SSH Protocol Architecture", 2726 draft-ietf-secsh-architecture-22 (work in progress), 2727 March 2005. 2729 [I-D.ietf-secsh-transport] 2730 Lonvick, C., "SSH Transport Layer Protocol", 2731 draft-ietf-secsh-transport-24 (work in progress), 2732 March 2005. 2734 [I-D.ietf-secsh-connect] 2735 Lonvick, C., "SSH Connection Protocol", 2736 draft-ietf-secsh-connect-25 (work in progress), 2737 March 2005. 2739 [IEEE.1003-1.1996] 2740 Institute of Electrical and Electronics Engineers, 2741 "Information Technology - Portable Operating System 2742 Interface (POSIX) - Part 1: System Application Program 2743 Interface (API) [C Language]", IEEE Standard 1003.2, 1996. 2745 [FIPS-180-2] 2746 National Institute of Standards and Technology, "Secure 2747 Hash Standard (SHS)", Federal Information Processing 2748 Standards Publication 180-2, August 2002. 2750 [ISO.3309.1991] 2751 International Organization for Standardization, 2752 "Information Technology - Telecommunications and 2753 information exchange between systems - High-level data 2754 link control (HDLC) procedures - Frame structure", 2755 ISO Standard 3309, June 1991. 2757 13.2 Informative References 2759 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet 2760 Mail Extensions) Part One: Mechanisms for Specifying and 2761 Describing the Format of Internet Message Bodies", 2762 RFC 1521, September 1993. 2764 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2765 RFC 2246, January 1999. 2767 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2768 Languages", BCP 18, RFC 2277, January 1998. 2770 [I-D.ietf-secsh-userauth] 2771 Lonvick, C., "SSH Authentication Protocol", 2772 draft-ietf-secsh-userauth-27 (work in progress), 2773 March 2005. 2775 Authors' Addresses 2777 Joseph Galbraith 2778 VanDyke Software 2779 4848 Tramway Ridge Blvd 2780 Suite 101 2781 Albuquerque, NM 87111 2782 US 2784 Phone: +1 505 332 5700 2785 Email: galb-list@vandyke.com 2787 Oskari Saarenmaa 2788 F-Secure 2789 Tammasaarenkatu 7 2790 Helsinki 00180 2791 FI 2793 Email: oskari.saarenmaa@f-secure.com 2794 Tatu Ylonen 2795 SSH Communications Security Corp 2796 Fredrikinkatu 42 2797 HELSINKI FIN-00100 2798 Finland 2800 Email: ylo@ssh.com 2802 Sami Lehtinen 2803 SSH Communications Security Corp 2804 Fredrikinkatu 42 2805 HELSINKI FIN-00100 2806 Finland 2808 Email: sjl@ssh.com 2810 Trademark notice 2812 "ssh" is a registered trademark in the United States and/or other 2813 countries. 2815 Intellectual Property Statement 2817 The IETF takes no position regarding the validity or scope of any 2818 Intellectual Property Rights or other rights that might be claimed to 2819 pertain to the implementation or use of the technology described in 2820 this document or the extent to which any license under such rights 2821 might or might not be available; nor does it represent that it has 2822 made any independent effort to identify any such rights. Information 2823 on the procedures with respect to rights in RFC documents can be 2824 found in BCP 78 and BCP 79. 2826 Copies of IPR disclosures made to the IETF Secretariat and any 2827 assurances of licenses to be made available, or the result of an 2828 attempt made to obtain a general license or permission for the use of 2829 such proprietary rights by implementers or users of this 2830 specification can be obtained from the IETF on-line IPR repository at 2831 http://www.ietf.org/ipr. 2833 The IETF invites any interested party to bring to its attention any 2834 copyrights, patents or patent applications, or other proprietary 2835 rights that may cover technology that may be required to implement 2836 this standard. Please address the information to the IETF at 2837 ietf-ipr@ietf.org. 2839 Disclaimer of Validity 2841 This document and the information contained herein are provided on an 2842 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2843 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2844 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2845 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2846 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2847 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2849 Copyright Statement 2851 Copyright (C) The Internet Society (2005). This document is subject 2852 to the rights, licenses and restrictions contained in BCP 78, and 2853 except as set forth therein, the authors retain all their rights. 2855 Acknowledgment 2857 Funding for the RFC Editor function is currently provided by the 2858 Internet Society.