idnits 2.17.1 draft-ietf-secsh-filexfer-07.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 21. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2618. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2595. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2602. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2608. ** 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 164: '...rr by the server SHOULD be considered ...' RFC 2119 keyword, line 165: '...information, and MAY be displayed to t...' RFC 2119 keyword, line 171: '...rors or warnings MAY be sent as stderr...' RFC 2119 keyword, line 191: '...the length field MUST be included in a...' RFC 2119 keyword, line 195: '...overhead). All servers SHOULD support...' (157 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 559 has weird spacing: '... bool do-...' == Line 587 has weird spacing: '... string owne...' == Line 588 has weird spacing: '... string grou...' == Line 593 has weird spacing: '...seconds if ...' == Line 596 has weird spacing: '... string acl ...' == (7 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 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 (March 24, 2005) is 6972 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 2272, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 1747, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 1748, 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. -------------------------------------------------------------------------------- 2 Secure Shell Working Group J. Galbraith 3 Internet-Draft VanDyke Software 4 Expires: September 25, 2005 O. Saarenmaa 5 F-Secure 6 T. Ylonen 7 S. Lehtinen 8 SSH Communications Security Corp 9 March 24, 2005 11 SSH File Transfer Protocol 12 draft-ietf-secsh-filexfer-07.txt 14 Status of this Memo 16 This document is an Internet-Draft and is subject to all provisions 17 of Section 3 of RFC 3667. By submitting this Internet-Draft, each 18 author represents that any applicable patent or other IPR claims of 19 which he or she is aware have been or will be disclosed, and any of 20 which he or she become aware will be disclosed, in accordance with 21 RFC 3668. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as 26 Internet-Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six months 29 and may be updated, replaced, or obsoleted by other documents at any 30 time. It is inappropriate to use Internet-Drafts as reference 31 material or to cite them other than as "work in progress." 33 The list of current Internet-Drafts can be accessed at 34 http://www.ietf.org/ietf/1id-abstracts.txt. 36 The list of Internet-Draft Shadow Directories can be accessed at 37 http://www.ietf.org/shadow.html. 39 This Internet-Draft will expire on September 25, 2005. 41 Copyright Notice 43 Copyright (C) The Internet Society (2005). 45 Abstract 47 The SSH File Transfer Protocol provides secure file transfer 48 functionality over any reliable data stream. It is the standard file 49 transfer protocol for use with the SSH2 protocol. This document 50 describes the file transfer protocol and its interface to the SSH2 51 protocol suite. 53 Table of Contents 55 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 56 2. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 57 2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 4 58 3. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 59 3.1 Request Synchronization and Reordering . . . . . . . . . . 6 60 3.2 New data types defined by this document . . . . . . . . . 6 61 3.3 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 62 4. Protocol Initialization . . . . . . . . . . . . . . . . . . . 8 63 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 64 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8 65 4.3 Determining Server Newline Convention . . . . . . . . . . 9 66 4.4 Supported Features . . . . . . . . . . . . . . . . . . . . 9 67 4.5 Version re-negotiation . . . . . . . . . . . . . . . . . . 11 68 5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 11 69 6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 13 70 6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 14 71 6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 72 6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 73 6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 16 74 6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 16 75 6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 17 76 6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 17 77 6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 78 6.9 attrib-bits . . . . . . . . . . . . . . . . . . . . . . . 19 79 6.10 Text Hint . . . . . . . . . . . . . . . . . . . . . . . . 22 80 6.11 Mime type . . . . . . . . . . . . . . . . . . . . . . . . 22 81 6.12 Link Count . . . . . . . . . . . . . . . . . . . . . . . . 22 82 6.13 Extended Attributes . . . . . . . . . . . . . . . . . . . 22 83 7. Requests From the Client to the Server . . . . . . . . . . . . 23 84 7.1 Opening and Closing Files and Directories . . . . . . . . 23 85 7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 23 86 7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 28 87 7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 29 88 7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 29 89 7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 29 90 7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 30 91 7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 30 92 7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 31 93 7.4 Creating and Deleting Directories . . . . . . . . . . . . 32 94 7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 33 95 7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 34 96 7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 35 97 7.8 Canonicalizing the Server-Side Path Name . . . . . . . . . 36 98 7.8.1 Best Practice for Dealing with Paths . . . . . . . . . 37 99 8. Responses from the Server to the Client . . . . . . . . . . . 38 100 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 44 101 9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 45 102 9.1.1 Checking File Contents: v5 extension . . . . . . . . . 46 103 9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 47 104 9.2 Querying Available Space . . . . . . . . . . . . . . . . . 48 105 9.3 Querying User Home Directory . . . . . . . . . . . . . . . 49 106 10. Implementation Considerations . . . . . . . . . . . . . . . 50 107 11. Security Considerations . . . . . . . . . . . . . . . . . . 50 108 12. Changes from Previous Protocol Versions . . . . . . . . . . 52 109 12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 52 110 12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 52 111 12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 53 112 12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 54 113 12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 54 114 12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 54 115 13. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 54 116 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 117 14.1 Normative References . . . . . . . . . . . . . . . . . . . 54 118 14.2 Informative References . . . . . . . . . . . . . . . . . . 55 119 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 55 120 Intellectual Property and Copyright Statements . . . . . . . . 57 122 1. Introduction 124 This protocol provides secure file transfer (and more generally file 125 system access.) It is designed so that it could be used to implement 126 a secure remote file system service, as well as a secure file 127 transfer service. 129 This protocol assumes that it runs over a secure channel, such as a 130 channel in [I-D.ietf-secsh-architecture]. and that the server has 131 already authenticated the client, and that the identity of the client 132 user is available to the protocol. 134 In general, this protocol follows a simple request-response model. 135 Each request and response contains a sequence number and multiple 136 requests may be pending simultaneously. There are a relatively large 137 number of different request messages, but a small number of possible 138 response messages. Each request has one or more response messages 139 that may be returned in result (e.g., a read either returns data or 140 reports error status). 142 The packet format descriptions in this specification follow the 143 notation presented in [I-D.ietf-secsh-architecture]. 145 Even though this protocol is described in the context of the SSH2 146 protocol, this protocol is general and independent of the rest of the 147 SSH2 protocol suite. It could be used in a number of different 148 applications, such as secure file transfer over TLS [RFC2246] and 149 transfer of management information in VPN applications. 151 2. Use with the SSH Connection Protocol 153 When used with the SSH2 Protocol suite, this protocol is intended to 154 be used as a subsystem as described in [I-D.ietf-secsh-connect] in 155 the section "Starting a Shell or a Command". The subsystem name used 156 with this protocol is "sftp". 158 2.1 The Use of 'stderr' in the server 160 This protocol uses stdout and stdin to transmit binary protocol data. 161 The "session" channel ([I-D.ietf-secsh-connect]), which is used by 162 the subsystem, also supports the use of stderr. 164 Data sent on stderr by the server SHOULD be considered free format 165 debug or supplemental error information, and MAY be displayed to the 166 user. 168 For example, during initialization, there is no client request 169 active, so errors or warning information cannot be sent to the client 170 as part of the SFTP protocol at this early stage. However, the 171 errors or warnings MAY be sent as stderr text. 173 3. General Packet Format 175 All packets transmitted over the secure connection are of the 176 following format: 178 uint32 length 179 byte type 180 uint32 request-id 181 ... type specific fields ... 183 'length' 184 The length of the entire packet, excluding the length field 185 itself, such that, for example, for a packet type containing no 186 type specific fields, the length field would be 5, and 9 bytes of 187 data would be sent on the wire. (This is the packet format used 188 in [I-D.ietf-secsh-transport].) 190 All packet descriptions in this document omit the length field for 191 brevity; the length field MUST be included in any case. 193 The maximum size of a packet is in practice determined by the 194 client (the maximum size of read or write requests that it sends, 195 plus a few bytes of packet overhead). All servers SHOULD support 196 packets of at least 34000 bytes (where the packet size refers to 197 the full length, including the header above). This should allow 198 for reads and writes of at most 32768 bytes. 200 'type' 201 The type code for the packet. 203 'request-id' 204 Each request from the client contains a 'request-id' field. Each 205 response from the server includes that same 'request-id' from the 206 request that the server is responding to. One possible 207 implementation is for the client to us a monotonically increasing 208 request sequence number (modulo 2^32). There is, however, no 209 particular requirement the 'request-id' fields be unique. 211 There are two packets, INIT and VERSION, which do not use the 212 request-id. 213 Packet descriptions in this document will contain the 'request-id' 214 field, but will not redefine it. 216 Implementations MUST ignore excess data after an otherwise valid 217 packet. Implementation MUST respond to unrecognized packet types 218 with an SSH_FX_OP_UNSUPPORTED error. This will allow the protocol to 219 be extended in a backwards compatible way as needed. 221 There is no limit on the number of outstanding (non-acknowledged) 222 requests that the client may send to the server. In practice this is 223 limited by the buffering available on the data stream and the queuing 224 performed by the server. If the server's queues are full, it should 225 not read any more data from the stream, and flow control will prevent 226 the client from sending more requests. Note, however, that while 227 there is no restriction on the protocol level, the client's API may 228 provide a limit in order to prevent infinite queuing of outgoing 229 requests at the client. 231 3.1 Request Synchronization and Reordering 233 The protocol and implementations MUST process requests relating to 234 the same file in the order in which they are received. In other 235 words, if an application submits multiple requests to the server, the 236 results in the responses will be the same as if it had sent the 237 requests one at a time and waited for the response in each case. For 238 example, the server may process non-overlapping read/write requests 239 to the same file in parallel, but overlapping reads and writes cannot 240 be reordered or parallelized. However, there are no ordering 241 restrictions on the server for processing requests from two different 242 file transfer connections. The server may interleave and parallelize 243 them at will. 245 There are no restrictions on the order in which responses to 246 outstanding requests are delivered to the client, except that the 247 server must ensure fairness in the sense that processing of no 248 request will be indefinitely delayed even if the client is sending 249 other requests so that there are multiple outstanding requests all 250 the time. 252 A client MUST be prepared to recieve responses to multiple overlapped 253 requests out of order. 255 3.2 New data types defined by this document 257 This document defines several data types in addition to those defined 258 in [I-D.ietf-secsh-architecture]. 260 int64 261 Represents a 64-bit signed integer. Stored as eight bytes in the 262 order of decreasing significance (network byte order). 264 extension-pair 266 string extension-name 267 string extension-data 269 'extension-name' is the name of a protocol extension. Extensions 270 not defined by IETF consensus MUST follow the the DNS 271 extensibility naming convention outlined in 272 [I-D.ietf-secsh-architecture]. 274 'extension-data' is any data specific to the extension, and MAY be 275 zero length if the extension has no data. 277 3.3 Packet Types 279 The following values are defined for packet types. 281 SSH_FXP_INIT 1 282 SSH_FXP_VERSION 2 283 SSH_FXP_OPEN 3 284 SSH_FXP_CLOSE 4 285 SSH_FXP_READ 5 286 SSH_FXP_WRITE 6 287 SSH_FXP_LSTAT 7 288 SSH_FXP_FSTAT 8 289 SSH_FXP_SETSTAT 9 290 SSH_FXP_FSETSTAT 10 291 SSH_FXP_OPENDIR 11 292 SSH_FXP_READDIR 12 293 SSH_FXP_REMOVE 13 294 SSH_FXP_MKDIR 14 295 SSH_FXP_RMDIR 15 296 SSH_FXP_REALPATH 16 297 SSH_FXP_STAT 17 298 SSH_FXP_RENAME 18 299 SSH_FXP_READLINK 19 300 SSH_FXP_LINK 21 302 SSH_FXP_STATUS 101 303 SSH_FXP_HANDLE 102 304 SSH_FXP_DATA 103 305 SSH_FXP_NAME 104 306 SSH_FXP_ATTRS 105 308 SSH_FXP_EXTENDED 200 309 SSH_FXP_EXTENDED_REPLY 201 310 RESERVED_FOR_EXTENSIONS 210-255 312 Additional packet types should only be defined if the protocol 313 version number (see Section ''Protocol Initialization'') is 314 incremented, and their use MUST be negotiated using the version 315 number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY 316 packets can be used to implement extensions, which can be vendor 317 specific. See Section ''Extensions'' for more details. 319 4. Protocol Initialization 321 When the file transfer protocol starts, the client first sends a 322 SSH_FXP_INIT (including its version number) packet to the server. 323 The server responds with a SSH_FXP_VERSION packet, supplying the 324 lowest of its own and the client's version number. Both parties 325 should from then on adhere to particular version of the protocol. 327 The version number of the protocol specified in this document is 6. 328 The version number should be incremented for each incompatible 329 revision of this protocol. 331 Note that these two packets DO NOT contain a request id. These are 332 the only such packets in the protocol. 334 4.1 Client Initialization 336 The SSH_FXP_INIT packet (from client to server) has the following 337 data: 339 uint32 version 341 'version' is the version number of the client. If the client wishes 342 to interoperate with servers that support dis-contigous version 343 numbers it SHOULD send '3', and then use the 'version-select' 344 extension (see below.) Otherwise, this value is '6' for this version 345 of the protocol. 347 4.2 Server Initialization 349 The SSH_FXP_VERSION packet (from server to client) has the following 350 data: 352 uint32 version 353 extension-pair extensions[0..n] 355 'version' is the lower of the protocol version supported by the 356 server and the version number received from the client. 358 'extensions' is 0 or more extension-pairs (Section 3.2). 359 Implementations MUST silently ignore any extensions whose name they 360 do not recognize. 362 4.3 Determining Server Newline Convention 364 In order to correctly process text files in a cross platform 365 compatible way, newline sequences must be converted between client 366 and server conventions. 368 The SSH_FXF_TEXT file open flag (Section 7.1.1) makes it possible to 369 request that the server translate a file to a 'canonical' wire 370 format. This format uses \r\n as the line separator. 372 Servers for systems using multiple newline characters (for example, 373 Mac OS X or VMS) or systems using counted records, MUST translate to 374 the canonical form. 376 However, to ease the burden of implementation on servers that use a 377 single, simple, separator sequence the following extension allows the 378 canonical format to be changed. 380 string "newline" 381 string new-canonical-separator (usually "\r" or "\n" or "\r\n") 383 All clients MUST support this extension. 385 When processing text files, clients SHOULD NOT translate any 386 character or sequence that is not an exact match of the server's 387 newline separator. 389 In particular, if the newline sequence being used is the canonical 390 "\r\n" sequence, a lone "\r" or a lone "\n" SHOULD be written through 391 without change. 393 4.4 Supported Features 395 The sftp protocol has grown to be very rich, and now supports a 396 number of features that may not be available on all servers. 398 When a server receives a request for a feature it cannot support, it 399 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 400 specified. In order to facilitate clients being able to use the 401 maximum available feature set, and yet not be overly burdened by 402 dealing with SSH_FX_OP_UNSUPPORTED status codes, the following 403 extension which all servers MUST include as part of their version 404 packet, is introduced. 406 string "supported2" 407 string supported-structure 408 uint32 supported-attribute-mask 409 uint32 supported-attribute-bits 410 uint32 supported-open-flags 411 uint32 max-read-size 412 string extension-names[0..n] 414 supported-attribute-mask 415 This mask MAY by applied to the 'File Attributes' 416 valid-attribute-flags field (Section 6.1) to ensure that no 417 unsupported attributes are present during a operation which writes 418 attributes. 420 supported-attribute-bits 421 This mask MAY by applied to the 'File Attributes' attrib-bits 422 field (Section 6.9) to ensure that no unsupported attrib-bits are 423 present during a operation which writes attributes. 425 supported-open-flags 426 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN 427 (Section 7.1.1) flags field. 429 max-read-size 430 This is the maximum read size that the server gaurantees to 431 complete. For example, certain embedded server implementations 432 only complete the first 4K of a read, even if there is additional 433 data to be read from the file. 435 If the server specifies a non-zero value, it MUST return at least 436 the max-read-size number of bytes for any read requesting 437 max-read-size bytes. Failure to return max-read-size bytes in 438 such a case indicates either EOF or another error condition 439 occurred. 441 extension names 442 The extension names may be empty (contains zero strings), or it 443 may contain any named extensions that the server wishes to 444 advertise. 446 The client must be able to differentiate between attribute 447 extensions (Section 6.13) and extended requests (Section 9) by the 448 extension name. 450 Naturally, if a given attribute field, attribute mask bit, open flag, 451 or extension is required for correct operation, the client MUST 452 either not allow the bit to be masked off, or MUST fail the operation 453 gracefully without sending the request to the server. 455 The client MAY send requests that are not supported by the server; 456 however, it is not normally expected to be productive to do so. The 457 client SHOULD apply the mask even to attrib structures received from 458 the server. The server MAY include attributes or attrib-bits that 459 are not included in the mask. Such attributes or attrib-bits are 460 effectively read-only. 462 4.5 Version re-negotiation 464 If the server supports a higher version than was negotiated, it may 465 wish to send the 'versions' extension to inform the client of this 466 fact. The client may then optionally choose to use one of the higher 467 versions supported. 469 string "versions" 470 string comma-seperated-versions 472 'comma-seperated-versions' is a string of comma seperated version 473 numbers, for example, "3,6,7. Versions defined by are: "2", "3", 474 "4", "5", "6". Any other version advertised by the server must 475 follow the DNS extensibility naming convention outlined in 476 [I-D.ietf-secsh-architecture]. 478 The client may select a new version to use from the list the server 479 provided using the following SSH_FXP_EXTENDED request. 481 string "version-select" 482 uint32 version-from-list 484 If the 'version-from-list' is one of the versions on the servers 485 list, the server MUST respond with SSH_FX_OK. If the server did not 486 send the "versions" extension, or the version-from-list was not 487 included, the server MAY send a status response describing the 488 failure, but MUST then close the channel without processing any 489 further requests. 491 Although this request does take a full round trip, no client need 492 wait for the response before continuing, because any valid request 493 MUST succeed, and any invalid request results in a channel close. 495 5. File Names 497 This protocol represents file names as strings. File names are 498 assumed to use the slash ('/') character as a directory separator. 500 File names starting with a slash are "absolute", and are relative to 501 the root of the file system. Names starting with any other character 502 are relative to the user's default directory (home directory). Note 503 that identifying the user is assumed to take place outside of this 504 protocol. 506 Servers SHOULD interpret a path name component ".." (Section 11) as 507 referring to the parent directory, and "." as referring to the 508 current directory. 510 An empty path name is valid, and it refers to the user's default 511 directory (usually the user's home directory). 513 Otherwise, no syntax is defined for file names by this specification. 514 Clients should not make any other assumptions; however, they can 515 splice path name components returned by SSH_FXP_READDIR together 516 using a slash ('/') as the separator, and that will work as expected. 518 It is understood that the lack of well-defined semantics for file 519 names may cause interoperability problems between clients and servers 520 using radically different operating systems. However, this approach 521 is known to work acceptably with most systems, and alternative 522 approaches that e.g. treat file names as sequences of structured 523 components are quite complicated. 525 The prefered encoding for filenames is UTF-8. This is consistant 526 with IETF Policy on Character Sets and Languages [RFC2277] and it is 527 further supposed that the server is more likely to support any local 528 character set and be able to convert it to UTF-8. 530 However, because the server does not always know the encoding of 531 filenames, it is not always possible for the server to preform a 532 valid translation to UTF-8. When an invalid translation to UTF-8 is 533 preformed, it becomes impossible to manipulate the file, because the 534 translation is not reversable. Therefore, the following extensions 535 are provided in order to make it possible for the server to 536 communicate it's abilities to the client, and to allow the client to 537 control whether the server attempts the conversion. 539 A server MAY include the following extension with it's version 540 packet. 542 string "filename-charset" 543 string charset-name 545 A server that can always provide a valid UTF-8 translation for 546 filenames SHOULD NOT send this extension. Otherwise, the server 547 SHOULD send this extension and include the encoding most likely to be 548 used for filenames. This value will most likely be derived from the 549 LC_CTYPE on most unix-like systems. 551 A server that does not send this extension MUST send all filenames 552 encoded in UTF-8. All clients MUST support UTF-8 filenames. 554 If the server included the 'filename-charset' extension with its 555 VERSION packet, a client MAY send the following extension to turn off 556 server translation to UTF-8. 558 string "filename-translation-control" 559 bool do-translate 561 If the client does not send this extension, the server MUST continue 562 to attempt translation to UTF-8. When a client sends this extension, 563 the server MUST enable or disable filename translation according to 564 the value of 'do-translate' 566 The server MUST respond with a STATUS response; if the server sent a 567 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, 568 the status MUST be UNSUPPORTED. 570 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE 571 data MUST be used. The server is responsible for converting the 572 UNICODE data to whatever canonical form it requires. For example, if 573 the server requires that precomposed characters always be used, the 574 server MUST NOT assume the filename as sent by the client has this 575 attribute, but must do this normalization itself. 577 6. File Attributes 579 A new compound data type is defined for encoding file attributes. 580 The same encoding is used both when returning file attributes from 581 the server and when sending file attributes to the server. 583 uint32 valid-attribute-flags 584 byte type always present 585 uint64 size if flag SIZE 586 uint64 allocation-size if flag ALLOCATION_SIZE 587 string owner if flag OWNERGROUP 588 string group if flag OWNERGROUP 589 uint32 permissions if flag PERMISSIONS 590 int64 atime if flag ACCESSTIME 591 uint32 atime_nseconds if flag SUBSECOND_TIMES 592 int64 createtime if flag CREATETIME 593 uint32 createtime_nseconds if flag SUBSECOND_TIMES 594 int64 mtime if flag MODIFYTIME 595 uint32 mtime_nseconds if flag SUBSECOND_TIMES 596 string acl if flag ACL 597 uint32 attrib-bits if flag BITS 598 byte text-hint if flag TEXT_HINT 599 string mime-type if flag MIME_TYPE 600 uint32 link-count if flag LINK_COUNT 601 string untranslated-name if flag UNTRANSLATED_NAME 602 uint32 extended_count if flag EXTENDED 603 extended-pair extensions 605 6.1 valid-attribute-flags 607 The 'valid-attribute-flags' specifies which of the fields are 608 present. Those fields for which the corresponding flag is not set 609 are not present (not included in the packet). 611 The server generally includes all attributes it knows about; however, 612 it may exclude attributes that are overly expensive to retrieve 613 unless the client explicitly requests them. 615 When writing attributes, the server SHOULD NOT modify attributes that 616 are not present in the structure. However, if necessary, the server 617 MAY use a default value for an absent attribute. 619 In general, unless otherwise specified, if a server cannot support 620 writing an attribute requested, it must fail the setstat operation. 621 In this case, none of the attributes SHOULD be changed. 623 New fields can only be added by incrementing the protocol version 624 number (or by using the extension mechanism described below). 626 The following values are defined: 628 SSH_FILEXFER_ATTR_SIZE 0x00000001 629 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 630 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 631 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 632 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 633 SSH_FILEXFER_ATTR_ACL 0x00000040 634 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 635 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 636 SSH_FILEXFER_ATTR_BITS 0x00000200 637 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 638 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 639 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 640 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 641 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 642 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 644 0x00000002 was used in a previous version of this protocol. It is 645 now a reserved value and MUST NOT appear in the mask. Some future 646 version of this protocol may reuse this value. 648 6.2 Type 650 The type field is always present. The following types are defined: 652 SSH_FILEXFER_TYPE_REGULAR 1 653 SSH_FILEXFER_TYPE_DIRECTORY 2 654 SSH_FILEXFER_TYPE_SYMLINK 3 655 SSH_FILEXFER_TYPE_SPECIAL 4 656 SSH_FILEXFER_TYPE_UNKNOWN 5 657 SSH_FILEXFER_TYPE_SOCKET 6 658 SSH_FILEXFER_TYPE_CHAR_DEVICE 7 659 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 660 SSH_FILEXFER_TYPE_FIFO 9 662 On a POSIX system, these values would be derived from the mode field 663 of the stat structure. SPECIAL should be used for files that are of 664 a known type which cannot be expressed in the protocol. UNKNOWN 665 should be used if the type is not known. 667 6.3 Size 669 The 'size' field specifies the number of bytes that can be read from 670 the file, or in other words, the location of the end-of-file. This 671 attribute MUST NOT be present during file creation. 673 If this field is present during a setstat operation, the file MUST be 674 extended or truncated to the specified size. 676 Files opened with the SSH_FXF_ACCESS_TEXT flag may have a size that 677 is greater or less than the value of the size field. The server MAY 678 fail setstat operations specifying size for files opened with the 679 SSH_FXF_ACCESS_TEXT flag. 681 6.4 allocation-size 683 The 'allocation-size' field specifies the number of bytes that the 684 file consumes on disk. This is greater than or equal to the 'size' 685 field. 687 When present during file creation, the file SHOULD be created and the 688 specified number of bytes pre-allocated. If the pre-allocation 689 fails, the file should be removed and an error returned. 691 If this field is present during a setstat operation, the file SHOULD 692 be extended or truncated to the specified size. The 'size' of the 693 file may be affected by this operation. If the operation succeeds, 694 it should be the min of the 'size' before the operation and the new 695 'allocation-size'. 697 Querying the 'allocation-size' after setting it MUST return a value 698 that is greater-than or equal to the value set, but it MAY not return 699 the precise value set. 701 6.5 Owner and Group 703 The 'owner' and 'group' fields are represented as UTF-8 strings; this 704 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. 705 The following text is selected quotations from section 5.6. 707 To avoid a representation that is tied to a particular underlying 708 implementation at the client or server, the use of UTF-8 strings has 709 been chosen. The string should be of the form user@dns_domain". 710 This will allow for a client and server that do not use the same 711 local representation the ability to translate to a common syntax that 712 can be interpreted by both. In the case where there is no 713 translation available to the client or server, the attribute value 714 must be constructed without the "@". Therefore, the absence of the @ 715 from the owner or owner_group attribute signifies that no translation 716 was available and the receiver of the attribute should not place any 717 special meaning with the attribute value. Even though the attribute 718 value cannot be translated, it may still be useful. In the case of a 719 client, the attribute string may be used for local display of 720 ownership. 722 user@localhost represents a user in the context of the server. 724 If either the owner or group field is zero length, the field should 725 be considered absent, and no change should be made to that specific 726 field. 728 6.6 Permissions 730 The 'permissions' field contains a bit mask specifying file 731 permissions. These permissions correspond to the st_mode field of 732 the stat structure defined by POSIX [IEEE.1003-1.1996]. 734 This protocol uses the following values for the symbols declared in 735 the posix standard. 737 S_IRUSR 0000400 (octal) 738 S_IWUSR 0000200 739 S_IXUSR 0000100 740 S_IRGRP 0000040 741 S_IWGRP 0000020 742 S_IXGRP 0000010 743 S_IROTH 0000004 744 S_IWOTH 0000002 745 S_IXOTH 0000001 746 S_ISUID 0004000 747 S_ISGID 0002000 748 S_ISVTX 0001000 750 Implementations MUST NOT send bits that are not defined. 752 The server SHOULD NOT apply a 'umask' to the mode bits; but should 753 set the mode bits as specified by the client. The client MUST apply 754 an appropriate 'umask' to the mode bits before sending them. 756 6.7 Times 758 The 'atime', 'createtime', and 'mtime' contain the access, creation, 759 and modification times of the files, respectively. They are 760 represented as seconds from Jan 1, 1970 in UTC. 762 A negative value indicates number of seconds before Jan 1, 1970. In 763 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 764 nseconds field is to be added to the seconds field for the final time 765 representation. For example, if the time to be represented is 766 one-half second before 0 hour January 1, 1970, the seconds field 767 would have a value of negative one (-1) and the nseconds fields would 768 have a value of one-half second (500000000). Values greater than 769 999,999,999 for nseconds are considered invalid. 771 6.8 ACL 773 The 'ACL' field contains an ACL similar to that defined in section 774 5.9 of NFS version 4 Protocol [RFC3010]. 776 uint32 ace-count 778 repeated ace-count time: 779 uint32 ace-type 780 uint32 ace-flag 781 uint32 ace-mask 782 string who [UTF-8] 784 ace-type is one of the following four values (taken from NFS Version 785 4 Protocol [RFC3010]: 787 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 788 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 789 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 790 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 792 ace-flag is a combination of the following flag values. See NFS 793 Version 4 Protocol [RFC3010] section 5.9.2: 795 ACE4_FILE_INHERIT_ACE 0x00000001 796 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 797 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 798 ACE4_INHERIT_ONLY_ACE 0x00000008 799 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 800 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 801 ACE4_IDENTIFIER_GROUP 0x00000040 803 ace-mask is any combination of the following flags (taken from NFS 804 Version 4 Protocol [RFC3010] section 5.9.3: 806 ACE4_READ_DATA 0x00000001 807 ACE4_LIST_DIRECTORY 0x00000001 808 ACE4_WRITE_DATA 0x00000002 809 ACE4_ADD_FILE 0x00000002 810 ACE4_APPEND_DATA 0x00000004 811 ACE4_ADD_SUBDIRECTORY 0x00000004 812 ACE4_READ_NAMED_ATTRS 0x00000008 813 ACE4_WRITE_NAMED_ATTRS 0x00000010 814 ACE4_EXECUTE 0x00000020 815 ACE4_DELETE_CHILD 0x00000040 816 ACE4_READ_ATTRIBUTES 0x00000080 817 ACE4_WRITE_ATTRIBUTES 0x00000100 818 ACE4_DELETE 0x00010000 819 ACE4_READ_ACL 0x00020000 820 ACE4_WRITE_ACL 0x00040000 821 ACE4_WRITE_OWNER 0x00080000 822 ACE4_SYNCHRONIZE 0x00100000 824 who is a UTF-8 string of the form described in 'Owner and Group' 825 (Section 6.5) 827 Also, as per '5.9.4 ACE who' [RFC3010] there are several identifiers 828 that need to be understood universally. Some of these identifiers 829 cannot be understood when an client access the server, but have 830 meaning when a local process accesses the file. The ability to 831 display and modify these permissions is permitted over SFTP. 833 OWNER The owner of the file. 834 GROUP The group associated with the file. 835 EVERYONE The world. 836 INTERACTIVE Accessed from an interactive terminal. 837 NETWORK Accessed via the network. 838 DIALUP Accessed as a dialup user to the server. 839 BATCH Accessed from a batch job. 840 ANONYMOUS Accessed without any authentication. 841 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 842 SERVICE Access from a system service. 844 To avoid conflict, these special identifiers are distinguish by an 845 appended "@". For example: ANONYMOUS@. 847 6.9 attrib-bits 849 These bits reflect various attributes of the file or directory on the 850 server. 852 The following attrib-bits are defined: 854 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 855 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 856 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 857 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 858 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 859 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 860 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 861 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 862 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 863 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 864 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 865 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 867 SSH_FILEXFER_ATTR_FLAGS_READONLY 868 Advisory, read-only bit. This bit is not part of the access 869 control information on the file, but is rather an advisory field 870 indicating that the file should not be written. 872 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 873 The file is part of operating system. 875 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 876 File SHOULD NOT be shown to user unless specifically requested. 877 For example, most UNIX systems SHOULD set this bit if the filename 878 begins with a 'period'. This bit may be read-only (Section 4.4). 879 Most UNIX systems will not allow this to be changed. 881 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 882 This attribute can only apply to directories. This attribute is 883 always read-only, and cannot be modified. This attribute means 884 that files and directory names in this directory should be 885 compared without regard to case. 887 It is recommended that where possible, the server's filesystem be 888 allowed to do comparisons. For example, if a client wished to 889 prompt a user before overwriting a file, it should not compare the 890 new name with the previously retrieved list of names in the 891 directory. Rather, it should first try to create the new file by 892 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 893 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 894 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 896 Unless otherwise specified, filenames are assumed to be case 897 sensitive. 899 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 900 The file should be included in backup / archive operations. 902 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 903 The file is stored on disk using file-system level transparent 904 encryption. This flag does not affect the file data on the wire 905 (for either READ or WRITE requests.) 907 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 908 The file is stored on disk using file-system level transparent 909 compression. This flag does not affect the file data on the wire. 911 SSH_FILEXFER_ATTR_FLAGS_SPARSE 912 The file is a sparse file; this means that file blocks that have 913 not been explicitly written are not stored on disk. For example, 914 if a client writes a buffer at 10 M from the beginning of the 915 file, the blocks between the previous EOF marker and the 10 M 916 offset would not consume physical disk space. 918 Some server may store all files as sparse files, in which case 919 this bit will be unconditionally set. Other servers may not have 920 a mechanism for determining if the file is sparse, and so the file 921 MAY be stored sparse even if this flag is not set. 923 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 924 The file can only be opened for writing in append mode. 926 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 927 The file cannot be deleted or renamed, no hard link can be created 928 to this file and no data can be written to the file. 930 This bit implies a stronger level of protection than 931 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 932 ACLs. Typically even the superuser cannot write to immutable 933 files, and only the superuser can set or remove the bit. 935 SSH_FILEXFER_ATTR_FLAGS_SYNC 936 When the file is modified, the changes are written synchronously 937 to the disk. 939 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 940 The server MAY include this bit in a directory listing or realpath 941 response. It indicates there was a failure in the translation to 942 UTF-8. If this flag is included, the server SHOULD also include 943 the UNTRANSLATED_NAME attribute. 945 6.10 Text Hint 947 The value is one of the following enumerations, and indicates what 948 the server knows about the content of the file. 950 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 951 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 952 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 953 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 955 SSH_FILEXFER_ATTR_KNOWN_TEXT 956 The server knows the file is a text file, and should be opened 957 using the SSH_FXF_ACCESS_TEXT_MODE flag. 959 SSH_FILEXFER_ATTR_GUESSED_TEXT 960 The server has applied a hueristic or other mechanism and believes 961 that the file should be opened with the SSH_FXF_ACCESS_TEXT_MODE 962 flag. 964 SSH_FILEXFER_ATTR_KNOWN_BINARY 965 The server knows the file has binary content. 967 SSH_FILEXFER_ATTR_GUESSED_BINARY 968 The server has applied a hueristic or other mechanism and believes 969 has binary content, and should not be opened with the 970 SSH_FXF_ACCESS_TEXT_MODE flag. 972 This flag MUST NOT be present during a setstat operation. If this 973 flag is present during an fsetstat operation, the file handle is 974 converted to a text-mode handle, as if it had been opened with 975 SSH_FXF_ACCESS_TEXT_MODE. 977 6.11 Mime type 979 The 'mime-type' field contains the mime-type [RFC1521] string. Most 980 servers will not know this information and should not set the bit in 981 their supported-attribute-mask. 983 6.12 Link Count 985 The 'link-count' field contains the hard link count of the file. 986 This attribute MUST NOT be present during a setstat operation. 988 6.13 Extended Attributes 990 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 991 mechanism for the attrib structure. If the flag is specified, then 992 the 'extended_count' field is present. It specifies the number of 993 extended_type-extended_data pairs that follow. Each of these pairs 994 specifies an extended attribute. For each of the attributes, the 995 extended_type field should be a string of the format "name@domain", 996 where "domain" is a valid, registered domain name and "name" 997 identifies the method. The IETF may later standardize certain names 998 that deviate from this format (e.g., that do not contain the "@" 999 sign). The interpretation of 'extended_data' depends on the type. 1000 Implementations SHOULD ignore extended data fields that they do not 1001 understand. 1003 Additional fields can be added to the attributes by either defining 1004 additional bits to the flags field to indicate their presence, or by 1005 defining extended attributes for them. The extended attributes 1006 mechanism is recommended for most purposes; additional flags bits 1007 should only be defined by an IETF standards action that also 1008 increments the protocol version number. The use of such new fields 1009 MUST be negotiated by the version number in the protocol exchange. 1010 It is a protocol error if a packet with unsupported protocol bits is 1011 received. 1013 7. Requests From the Client to the Server 1015 Requests from the client to the server represent the various file 1016 system operations. 1018 7.1 Opening and Closing Files and Directories 1020 Many operations in the protocol operate on open files. The 1021 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 1022 an opaque, variable-length string) which may be used to access the 1023 file or directory later. The client MUST NOT send requests to the 1024 server with bogus or closed handles. However, the server MUST 1025 perform adequate checks on the handle in order to avoid security 1026 risks due to fabricated handles. 1028 This design allows either stateful and stateless server 1029 implementation, as well as an implementation which caches state 1030 between requests but may also flush it. The contents of the file 1031 handle string are entirely up to the server and its design. The 1032 client should not modify or attempt to interpret the file handle 1033 strings. 1035 The file handle strings MUST NOT be longer than 256 bytes. 1037 7.1.1 Opening a File 1039 Files are opened and created using the SSH_FXP_OPEN message. 1041 byte SSH_FXP_OPEN 1042 uint32 request-id 1043 string filename [UTF-8] 1044 uint32 desired-access 1045 uint32 flags 1046 ATTRS attrs 1048 The response to this message will be either SSH_FXP_HANDLE (if the 1049 operation is successful) or SSH_FXP_STATUS (if the operation fails.) 1051 7.1.1.1 filename 1053 The 'filename' field specifies the file name. See Section ''File 1054 Names'' for more information. If 'filename' is a directory file, the 1055 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 1057 7.1.1.2 desired-access 1059 The 'desired-access' field is a bitmask containing a combination of 1060 values from the ace-mask flags from section 5.7. 1062 The server MUST be prepared to translate the SFTP access flags into 1063 it's local equivilants. If the server can not grant the access 1064 desired, it MUST return SSH_FX_PERMISSION_DENIED. 1066 The server MAY open the file with greater access than requested if 1067 the user has such access and the server implementation requires it. 1068 For example, a server that does not distinguish between 1069 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access 1070 to the file when the client only requested READ_ATTRIBUTE, resulting 1071 in greater access than the client originaly requested. 1073 In such cases, it is possible, and permissable in the protocol, that 1074 the client could open a file requesting some limitted access, and 1075 then access the file in a way not permitted by that limitted access 1076 and the server would permit such action. However, the server MUST 1077 NOT ever grant access to the file that the client does not actually 1078 have the rights to. 1080 7.1.1.3 flags 1082 The 'flags' field controls various aspects of the operation, 1083 including whether or not the file is created and the kind of locking 1084 desired. 1086 The following 'flags' are defined: 1088 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 1089 SSH_FXF_CREATE_NEW = 0x00000000 1090 SSH_FXF_CREATE_TRUNCATE = 0x00000001 1091 SSH_FXF_OPEN_EXISTING = 0x00000002 1092 SSH_FXF_OPEN_OR_CREATE = 0x00000003 1093 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 1094 SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 1095 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 1096 SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 1097 SSH_FXF_ACCESS_READ_LOCK = 0x00000040 1098 SSH_FXF_ACCESS_WRITE_LOCK = 0x00000080 1099 SSH_FXF_ACCESS_DELETE_LOCK = 0x00000100 1100 SSH_FXF_ACCESS_NOFOLLOW = 0x00000200 1101 SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000400 1103 SSH_FXF_ACCESS_DISPOSITION 1104 Disposition is a 3 bit field that controls how the file is opened. 1105 The server MUST support these bits. Any one of the following 1106 enumeration is allowed: 1108 SSH_FXF_CREATE_NEW 1109 A new file is created; if the file already exists, the server 1110 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 1112 SSH_FXF_CREATE_TRUNCATE 1113 A new file is created; if the file already exists, it is opened 1114 and truncated. 1116 SSH_FXF_OPEN_EXISTING 1117 An existing file is opened. If the file does not exist, the 1118 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 1119 path does not exist, the server SHOULD return 1120 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 1121 returns SSH_FX_NO_SUCH_FILE in this case. 1123 SSH_FXF_OPEN_OR_CREATE 1124 If the file exists, it is opened. If the file does not exist, 1125 it is created. 1127 SSH_FXF_TRUNCATE_EXISTING 1128 An existing file is opened and truncated. If the file does not 1129 exist, the server MUST return the same error codes as defined 1130 for SSH_FXF_OPEN_EXISTING. 1132 SSH_FXF_ACCESS_APPEND_DATA 1133 Data is always written at the end of the file. The offset field 1134 of the SSH_FXP_WRITE requests are ignored. 1136 Data is not required to be appended atomically. This means that 1137 if multiple writers attempt to append data simultaneously, data 1138 from the first may be lost. However, data MAY be appended 1139 atomically. 1141 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1142 Data is always written at the end of the file. The offset field 1143 of the SSH_FXP_WRITE requests are ignored. 1145 Data MUST be written atomically so that there is no chance that 1146 multiple appenders can collide and result in data being lost. 1148 If both append flags are specified, the server SHOULD use atomic 1149 append if it is available, but SHOULD use non-atomic appends 1150 otherwise. The server SHOULD NOT fail the request in this case. 1152 SSH_FXF_TEXT 1153 Indicates that the server should treat the file as text and 1154 convert it to the canonical newline convention in use. (See 1155 Determining Server Newline Convention. (Section 4.3) 1157 When a file is opened with the FXF_TEXT flag, the offset field in 1158 both the read and write function are ignored. 1160 Servers MUST correctly process multiple, parallel reads and writes 1161 correctly in this mode. Naturally, it is permissible for them to 1162 do this by serializing the requests. 1164 Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append 1165 data to a text file rather then using write with a calculated 1166 offset. 1168 To support seeks on text files the following SSH_FXP_EXTENDED 1169 packet is defined. 1171 string "text-seek" 1172 string file-handle 1173 uint64 line-number 1175 line-number is the index of the line number to seek to, where byte 1176 0 in the file is line number 0, and the byte directly following 1177 the first newline sequence in the file is line number 1 and so on. 1179 The response to a "text-seek" request is an SSH_FXP_STATUS 1180 message. 1182 An attempt to seek past the end-of-file should result in a 1183 SSH_FX_EOF status. 1185 Servers SHOULD support at least one "text-seek" in order to 1186 support resume. However, a client MUST be prepared to receive 1187 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 1188 The client can then try a fall-back strategy, if it has one. 1190 Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned 1191 for read or write operations that are not sequential. 1193 SSH_FXF_ACCESS_READ_LOCK 1194 The file should be opened with a read lock. The server MUST 1195 gaurantee that the client will be the exclusive reader of the file 1196 until the client closes the handle. If there is a conflicting 1197 lock the server MUST return SSH_FX_LOCK_CONFlICT. If the server 1198 cannot make the locking gaurantee, it MUST return 1199 SSH_FX_OP_UNSUPPORTED. 1201 SSH_FXF_ACCESS_WRITE_LOCK 1202 The file should be opened with a write lock. The server MUST 1203 gaurantee that the client will be the exclusive writer of the file 1204 until the client closes the handle. 1206 SSH_FXF_ACCESS_DELETE_LOCK 1207 The file should be opened with a delete lock. The server MUST 1208 gaurantee that the file will not be deleted until the client 1209 closes the handle. 1211 SSH_FXF_ACCESS_NOFOLLOW 1212 If the final component of the path is a symlink, then the open 1213 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 1215 SSH_FXF_ACCESS_DELETE_ON_CLOSE 1216 The file should be deleted when the last handle to it is closed. 1217 (The last handle may not be an sftp-handle.) This MAY be emulated 1218 by a server if the OS doesn't support it by deleting the file when 1219 this handle is closed. 1221 The 'attrs' field specifies the initial attributes for the file. 1222 Default values MUST be supplied by the server for those attributes 1223 that are not specified. See Section ''File Attributes'' for more 1224 information. 1226 The 'attrs' field is ignored if an exiting file is opened. 1228 The following table is provided to assist in mapping posix semantics 1229 to equivalent SFTP file open parameters: 1230 O_RDONLY 1231 desired-access = READ_DATA|READ_ATTRIBUTES 1233 O_WRONLY 1234 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1236 O_RDWR 1237 desired-access = 1238 READ_DATA|READ_ATTRIBUTES|WRITE_DATA|WRITE_ATTRIBUTES 1240 O_APPEND 1241 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1242 flags = SSH_FXF_ACCESS_APPEND_DATA and or 1243 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1245 O_CREAT 1246 flags = SSH_FXF_OPEN_OR_CREATE 1248 O_TRUNC 1249 flags = SSH_FXF_TRUNCATE_EXISTING 1251 O_TRUNC|O_CREATE 1252 flags = SSH_FXF_CREATE_TRUNCATE 1254 7.1.2 Opening a Directory 1256 To enumerate a directory, the client first obtains a handle and then 1257 issues directory read requests. When enumeration is complete, the 1258 handle MUST be closed. 1260 byte SSH_FXP_OPENDIR 1261 uint32 request-id 1262 string path [UTF-8] 1264 path 1265 The 'path' field is the path name of the directory to be listed 1266 (without any trailing slash). See Section 'File Names' for more 1267 information on file names. 1269 If 'path' does not refer to a directory, the server MUST return 1270 SSH_FX_NOT_A_DIRECTORY. 1272 The response to this message will be either SSH_FXP_HANDLE (if the 1273 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1275 7.1.3 Closing Handles 1277 A handle is closed using the following request. 1279 byte SSH_FXP_CLOSE 1280 uint32 request-id 1281 string handle 1283 handle 1284 'handle' is a handle previously returned in the response to 1285 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid 1286 immediately after this request has been sent. 1288 The response to this request will be a SSH_FXP_STATUS message. Note 1289 that on some server platforms even a close can fail. For example, if 1290 the server operating system caches writes, and an error occurs while 1291 flushing cached writes, the close operation may fail. 1293 7.2 Reading and Writing 1295 7.2.1 Reading Files 1297 The following request can be used to read file data: 1299 byte SSH_FXP_READ 1300 uint32 request-id 1301 string handle 1302 uint64 offset 1303 uint32 length 1305 handle 1306 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1307 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1308 return SSH_FX_INVALID_HANDLE. 1310 offset 1311 'offset' is the offset (in bytes) relative to the beginning of the 1312 file that the read MUST start at. 'offset' is ignored if 1313 SSH_FXF_TEXT was specified during the open. 1315 length 1316 'length' is the maximum number of bytes to read. 1318 The server MUST not respond with more data than is specified by 1319 the 'length' parameter. However, the server MAY respond with less 1320 data if EOF is reached, an error is encountered, or the servers 1321 internal buffers can not handle such a large request. 1323 For normal disk files, it is normally guaranteed that this will 1324 read the specified number of bytes, or up to end of file. 1326 If the server specified 'max-read-size' then failure to return 1327 'length' bytes indicates that EOF or an error occured. 1329 7.2.2 Reading Directories 1331 In order to retrieve a directory listing, the client issues one or 1332 more SSH_FXP_READDIR requests. In order to obtain a complete 1333 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1334 requests until the server responds with an SSH_FXP_STATUS message. 1336 byte SSH_FXP_READDIR 1337 uint32 request-id 1338 string handle 1340 handle 1341 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is 1342 an oridinary file handle returned by SSH_FXP_OPEN, the server MUST 1343 return SSH_FX_INVALID_HANDLE. 1345 The server responds to this request with either a SSH_FXP_NAME or a 1346 SSH_FXP_STATUS message. One or more names may be returned at a time. 1347 Full status information is returned for each name in order to speed 1348 up typical directory listings. 1350 If there are no more names available to be read, the server MUST 1351 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1353 7.2.3 Writing Files 1355 Writing to a file is achieved using the following message: 1357 byte SSH_FXP_WRITE 1358 uint32 request-id 1359 string handle 1360 uint64 offset 1361 string data 1363 handle 1364 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1365 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1366 return SSH_FX_INVALID_HANDLE. 1368 offset 1369 'offset' is the offset (in bytes) relative to the beginning of the 1370 file that the write MUST start at. 'offset' is ignored if 1371 SSH_FXF_TEXT was specified during the open. 1373 The write will extend the file if writing beyond the end of the 1374 file. It is legal to write to an offset that extends beyond the 1375 end of the file; the semantics are to write zeroes from the end of 1376 the file to the specified offset and then the data. On most 1377 operating systems, such writes do not allocate disk space but 1378 instead create a sparse file. 1380 data 1381 The data to write to the file. 1383 The server responds to a write request with a SSH_FXP_STATUS message. 1385 7.3 Removing and Renaming Files 1387 The following request can be used to remove a file: 1389 byte SSH_FXP_REMOVE 1390 uint32 request-id 1391 string filename [UTF-8] 1393 filename 1394 'filename' is the name of the file to be removed. See Section 1395 'File Names' for more information. 1397 This request cannot be used to remove directories. The server 1398 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. 1400 The server will respond to this request with a SSH_FXP_STATUS 1401 message. 1403 Files (and directories) can be renamed using the SSH_FXP_RENAME 1404 message. 1406 byte SSH_FXP_RENAME 1407 uint32 request-id 1408 string oldpath [UTF-8] 1409 string newpath [UTF-8] 1410 uint32 flags 1412 where 'request-id' is the request identifier, 'oldpath' is the name 1413 of an existing file or directory, and 'newpath' is the new name for 1414 the file or directory. 1416 'flags' is 0 or a combination of: 1418 SSH_FXP_RENAME_OVERWRITE 0x00000001 1419 SSH_FXP_RENAME_ATOMIC 0x00000002 1420 SSH_FXP_RENAME_NATIVE 0x00000004 1422 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1423 exists a file with the name specified by newpath, the server MUST 1424 respond with SSH_FX_FILE_ALREADY_EXISTS. 1426 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1427 already exists, it is replaced in an atomic fashion. I.e., there is 1428 no observable instant in time where the name does not refer to either 1429 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1430 SSH_FXP_RENAME_OVERWRITE. 1432 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace 1433 the destination in an atomic fashion, then the server MUST respond 1434 with SSH_FX_OP_UNSUPPORTED. 1436 Because some servers cannot provide atomic rename, clients should 1437 only specify atomic rename if correct operation requires it. If 1438 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1439 atomic rename even if it is not requested. 1441 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1442 rename operation in whatever fashion it deems appropriate. Other 1443 flag values are considered hints as to desired behavior, but not 1444 requirements. 1446 The server will respond to this request with a SSH_FXP_STATUS 1447 message. 1449 7.4 Creating and Deleting Directories 1451 New directories can be created using the SSH_FXP_MKDIR request. It 1452 has the following format: 1454 byte SSH_FXP_MKDIR 1455 uint32 request-id 1456 string path [UTF-8] 1457 ATTRS attrs 1459 where 'request-id' is the request identifier. 1461 'path' specifies the directory to be created. See Section ''File 1462 Names'' for more information on file names. 1464 'attrs' specifies the attributes that should be applied to it upon 1465 creation. Attributes are discussed in more detail in Section ''File 1466 Attributes''. 1468 The server will respond to this request with a SSH_FXP_STATUS 1469 message. If a file or directory with the specified path already 1470 exists, an error will be returned. 1472 Directories can be removed using the SSH_FXP_RMDIR request, which has 1473 the following format: 1475 byte SSH_FXP_RMDIR 1476 uint32 request-id 1477 string path [UTF-8] 1479 where 'request-id' is the request identifier, and 'path' specifies 1480 the directory to be removed. See Section ''File Names'' for more 1481 information on file names. 1483 The server responds to this request with a SSH_FXP_STATUS message. 1485 7.5 Retrieving File Attributes 1487 Very often, file attributes are automatically returned by 1488 SSH_FXP_READDIR. However, sometimes there is need to specifically 1489 retrieve the attributes for a named file. This can be done using the 1490 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1492 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1493 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1494 follow symbolic links. Both have the same format: 1496 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1497 uint32 request-id 1498 string path [UTF-8] 1499 uint32 flags 1501 where 'request-id' is the request identifier, and 'path' specifies 1502 the file system object for which status is to be returned. The 1503 server responds to this request with either SSH_FXP_ATTRS or 1504 SSH_FXP_STATUS. 1506 The flags field specify the attribute flags in which the client has 1507 particular interest. This is a hint to the server. For example, 1508 because retrieving owner / group and acl information can be an 1509 expensive operation under some operating systems, the server may 1510 choose not to retrieve this information unless the client expresses a 1511 specific interest in it. 1513 The client has no guarantee the server will provide all the fields 1514 that it has expressed an interest in. 1516 SSH_FXP_FSTAT differs from the others in that it returns status 1517 information for an open file (identified by the file handle). 1519 byte SSH_FXP_FSTAT 1520 uint32 request-id 1521 string handle 1522 uint32 flags 1524 handle 1525 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1526 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1527 return SSH_FX_INVALID_HANDLE. 1529 The server responds to this request with SSH_FXP_ATTRS or 1530 SSH_FXP_STATUS. 1532 7.6 Setting File Attributes 1534 File attributes may be modified using the SSH_FXP_SETSTAT and 1535 SSH_FXP_FSETSTAT requests. 1537 byte SSH_FXP_SETSTAT 1538 uint32 request-id 1539 string path [UTF-8] 1540 ATTRS attrs 1542 byte SSH_FXP_FSETSTAT 1543 uint32 request-id 1544 string handle 1545 ATTRS attrs 1547 path 1548 The file system object (e.g. file or directory) whose attributes 1549 are to be modified. If this object does not exist, or the user 1550 does not have sufficient access to write the attributes, the 1551 request MUST fail. 1553 handle 1554 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1555 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1556 return SSH_FX_INVALID_HANDLE. If the handle was not opened with 1557 sufficient access to write the requested attributes, the request 1558 MUST fail. 1560 attrs 1561 Specifies the modified attributes to be applied. Attributes are 1562 discussed in more detail in Section ''File Attributes''. 1564 The server will respond with a SSH_FXP_STATUS message. 1566 Because some systems must use separate system calls to set various 1567 attributes, it is possible that a failure response will be returned, 1568 but yet some of the attributes may be have been successfully 1569 modified. If possible, servers SHOULD avoid this situation; however, 1570 client MUST be aware that this is possible. 1572 7.7 Dealing with Links 1574 The SSH_FXP_READLINK request reads the target of a symbolic link. 1576 byte SSH_FXP_READLINK 1577 uint32 request-id 1578 string path [UTF-8] 1580 where 'request-id' is the request identifier and 'path' specifies the 1581 path name of the symlink to be read. 1583 The server will respond with a SSH_FXP_NAME packet containing only 1584 one name and a dummy attributes value. The name in the returned 1585 packet contains the target of the link. If an error occurs, the 1586 server MAY respond with SSH_FXP_STATUS. 1588 The SSH_FXP_LINK request creates a symbolic link on the server. 1590 byte SSH_FXP_LINK 1591 uint32 request-id 1592 string new-link-path [UTF-8] 1593 string existing-path [UTF-8] 1594 bool sym-link 1596 new-link-path 1597 Specifies the path name of the new link to create. 1599 existing-path 1600 Specifies the path of an existing file system object to which the 1601 new-link-path will refer. 1603 sym-link 1604 Specifies that the link should be a symbolic link, or a special 1605 file that redirects file system parsing to the resulting path. It 1606 is generally possible to create symbolic links across device 1607 boundaries; however, it is not required that a server support 1608 this. 1610 If 'sym-link' is false, the link should be a hard link, or a 1611 second directory entry refering to the same file or directory 1612 object. It is generally not possible to create hard links across 1613 devices. 1615 The server shall respond with a SSH_FXP_STATUS. Clients should be 1616 aware that some server may return SSH_FX_OP_UNSUPPORTED for either 1617 the hard-link, sym-link, or both operations. 1619 7.8 Canonicalizing the Server-Side Path Name 1621 The SSH_FXP_REALPATH request can be used to have the server 1622 canonicalize any given path name to an absolute path. This is useful 1623 for converting path names containing ".." components or relative 1624 pathnames without a leading slash into absolute paths. The format of 1625 the request is as follows: 1627 byte SSH_FXP_REALPATH 1628 uint32 request-id 1629 string original-path [UTF-8] 1630 string compose-path [optional] 1631 byte control-byte [optional] 1633 original-path 1634 The first component of the path which the client wishes resolved 1635 into a absolute canonical path. This may be the entire path. 1637 compose-path 1638 A path which the client wishs the server to compose with the 1639 original path to form the new path. This field is optional, and 1640 if it is not present in the packet, it is assumed to be a zero 1641 length string. 1643 control-byte 1645 SSH_FXP_REALPATH_NO_CHECK 0x00000001 1646 SSH_FXP_REALPATH_STAT_IF 0x00000002 1647 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 1649 This field is optional, and if it is not present in the packet, it 1650 is assumed to be SSH_FXP_REALPATH_NO_CHECK. 1652 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT 1653 fail the request if the path does not exist, is hidden, or the 1654 user does not have access to the path or some component thereof. 1655 However, the path MAY NOT be completely resolved to it's component 1656 form. For example, symlinks may not be followed in this case. 1658 The server MAY fail the request if the path is not syntaticly 1659 valid, or for other reasons. 1661 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the 1662 path if it exists and is accessible to the client. However, if 1663 the path does not exist, isn't visible, or isn't accessible, the 1664 server MUST NOT fail the request. If the stat failed, the file 1665 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to 1666 distinguish between files that are actually 1667 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will 1668 have to issue a seperate stat command in this case. 1670 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat 1671 the path. If the stat operation fails, the server MUST fail the 1672 request. 1674 The server MUST take the 'original-path' and apply the 'compose-path' 1675 as a modification to it. 'compose-path' MAY be relative to 1676 'original-path' or may be an absolute path, in which case 1677 'original-path' will be discarded. The 'compose-path' may be zero 1678 length. 1680 The server will respond with a SSH_FXP_NAME packet containing the 1681 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK 1682 is specified, the attributes are dummy values. 1684 7.8.1 Best Practice for Dealing with Paths 1686 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 1688 Previous to this version, clients typically composed new paths 1689 themselves and then called both realpath and stat on the resulting 1690 path to get it's canonical name and see if it really existed and was 1691 a directory. 1693 This required clients to assume certain things about how a relative 1694 vs. realpath looked. The new realpath allows clients to no longer 1695 make those assumptions and to remove one round trip from the process 1696 and get deterministic behavior from all servers. 1698 END: RFCEDITOR REMOVE BEFORE PUBLISHING 1700 The client SHOULD treat the results of SSH_FXP_REALPATH as a 1701 canonical absolute path, even if the path does not appear to be 1702 absolute. A client that use REALPATH(".", "") and treats the result 1703 as absolute, even if there is no leading slash, will continue to 1704 function correctly, even when talking to a Windows NT or VMS style 1705 system, where absolute paths may not begin with a slash. 1707 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so 1708 that it does not need to know when a path is absolute or relative. 1710 For example, if the client wishes to change directory up, and the 1711 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 1712 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) 1714 As a second example, if the client wishes transfer local file "a" to 1715 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the 1716 canonical path of the current directory, the client SHOULD send 1717 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This 1718 call will determine the correct path to use for the open request and 1719 whether the /b/d/e represents a directory. 1721 8. Responses from the Server to the Client 1723 The server responds to the client using one of a few response 1724 packets. All requests can return a SSH_FXP_STATUS response upon 1725 failure. When the operation is successful, and no data needs to be 1726 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 1727 appropriate. 1729 Exactly one response will be returned for each request. Each 1730 response packet contains a request identifier which can be used to 1731 match each response with the corresponding request. Note that it is 1732 legal to have several requests outstanding simultaneously, and the 1733 server is allowed to send responses to them in a different order from 1734 the order in which the requests were sent (the result of their 1735 execution, however, is guaranteed to be as if they had been processed 1736 one at a time in the order in which the requests were sent). 1738 Response packets are of the same general format as request packets. 1739 Each response packet begins with the request identifier. 1741 The format of the data portion of the SSH_FXP_STATUS response is as 1742 follows: 1744 byte SSH_FXP_STATUS 1745 uint32 request-id 1746 uint32 error/status code 1747 string error message (ISO-10646 UTF-8 [RFC-2279]) 1748 string language tag (as defined in [RFC-1766]) 1749 1751 request-id 1752 The 'request-id' specified by the client in the request the server 1753 is responding to. 1755 error/status code 1756 Machine readable status code indicating the result of the request. 1757 Error code values are defined below. The value SSH_FX_OK 1758 indicates success, and all other values indicate failure. 1760 error message 1761 Human readable description of the error. 'language tag' specifies 1762 the language the error is in. 1764 1765 The error-specific data may be empty, or may contain additional 1766 information about the error. For error codes that send 1767 error-specific data, the format of the data is defined below. 1769 Error codes: 1771 SSH_FX_OK 0 1772 SSH_FX_EOF 1 1773 SSH_FX_NO_SUCH_FILE 2 1774 SSH_FX_PERMISSION_DENIED 3 1775 SSH_FX_FAILURE 4 1776 SSH_FX_BAD_MESSAGE 5 1777 SSH_FX_NO_CONNECTION 6 1778 SSH_FX_CONNECTION_LOST 7 1779 SSH_FX_OP_UNSUPPORTED 8 1780 SSH_FX_INVALID_HANDLE 9 1781 SSH_FX_NO_SUCH_PATH 10 1782 SSH_FX_FILE_ALREADY_EXISTS 11 1783 SSH_FX_WRITE_PROTECT 12 1784 SSH_FX_NO_MEDIA 13 1785 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 1786 SSH_FX_QUOTA_EXCEEDED 15 1787 SSH_FX_UNKNOWN_PRINCIPLE 16 1788 SSH_FX_LOCK_CONFLICT 17 1789 SSH_FX_DIR_NOT_EMPTY 18 1790 SSH_FX_NOT_A_DIRECTORY 19 1791 SSH_FX_INVALID_FILENAME 20 1792 SSH_FX_LINK_LOOP 21 1793 SSH_FX_CANNOT_DELETE 22 1794 SSH_FX_INVALID_PARAMETER 23 1795 SSH_FX_FILE_IS_A_DIRECTORY 24 1796 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 1797 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 1798 SSH_FX_DELETE_PENDING 27 1799 SSH_FX_FILE_CORRUPT 28 1801 SSH_FX_OK 1802 Indicates successful completion of the operation. 1804 SSH_FX_EOF 1805 An attempt to read past the end-of-file was made; or, there are no 1806 more directory entries to return. 1808 SSH_FX_NO_SUCH_FILE 1809 A reference was made to a file which does not exist. 1811 SSH_FX_PERMISSION_DENIED 1812 The user does not have sufficient permissions to perform the 1813 operation. 1815 SSH_FX_FAILURE 1816 An error occured, but no specific error code exists to describe 1817 the failure. 1819 This error message SHOULD always have meaningful text in the the 1820 'error message' field. 1822 SSH_FX_BAD_MESSAGE 1823 A badly formatted packet or other SFTP protocol incompatibility 1824 was detected. 1826 SSH_FX_NO_CONNECTION 1827 There is no connection to the server. This error can only be 1828 generated locally, and MUST NOT be return by a server. 1830 SSH_FX_CONNECTION_LOST 1831 The connection to the server was lost. This error can only be 1832 generated locally, and MUST NOT be return by a server. 1834 SSH_FX_OP_UNSUPPORTED 1835 An attempted operation could not be completed by the server 1836 because the server does not support the operation. 1838 This error MAY be generated locally by the client if e.g. the 1839 version number exchange indicates that a required feature is not 1840 supported by the server, or it may be returned by the server if 1841 the server does not implement an operation). 1843 SSH_FX_INVALID_HANDLE 1844 The handle value was invalid. 1846 SSH_FX_NO_SUCH_PATH 1847 The file path does not exist or is invalid. 1849 SSH_FX_FILE_ALREADY_EXISTS 1850 The file already exists. 1852 SSH_FX_WRITE_PROTECT 1853 The file is on read-only media, or the media is write protected. 1855 SSH_FX_NO_MEDIA 1856 The requested operation cannot be completed because there is no 1857 media available in the drive. 1859 SSH_FX_NO_SPACE_ON_FILESYSTEM 1860 The requested operation cannot be completed because there is no 1861 free space on the filesystem. 1863 SSH_FX_QUOTA_EXCEEDED 1864 The operation cannot be completed because the it would exceed the 1865 users storage quota. 1867 SSH_FX_UNKNOWN_PRINCIPLE 1868 A principle referenced by the request (either the 'owner', 1869 'group', or 'who' field of an ACL), was unknown. The error 1870 specific data contains the problematic names. The format is one 1871 or more: 1873 string unknown-name 1875 Each string contains the name of a principle that was unknown. 1877 SSH_FX_LOCK_CONFLICT 1878 The file could not be opened because it is locked by another 1879 process. 1881 SSH_FX_DIR_NOT_EMPTY 1882 The directory is not empty. 1884 SSH_FX_NOT_A_DIRECTORY 1885 The specified file is not a directory. 1887 SSH_FX_INVALID_FILENAME 1888 The filename is not valid. 1890 SSH_FX_LINK_LOOP 1891 Too many symbolic links encountered. 1893 SSH_FX_CANNOT_DELETE 1894 The file cannot be deleted. One possible reason is that the 1895 advisory READONLY attribute-bit is set. 1897 SSH_FX_INVALID_PARAMETER 1898 On of the parameters was out of range, or the parameters specified 1899 cannot be used together. 1901 SSH_FX_FILE_IS_A_DIRECTORY 1902 The specifed file was a directory in a context where a directory 1903 cannot be used. 1905 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 1906 A read or write operation failed because another process owns a 1907 byte range lock that conflicts. 1909 SSH_FX_BYTE_RANGE_LOCK_REFUSED 1910 A request for a byte range lock was refused. 1912 SSH_FX_DELETE_PENDING 1913 An operation was attempted on a file for which a delete operation 1914 is pending. 1916 SSH_FX_FILE_CORRUPT 1917 The file is corrupt; an filesystem integrity check should be run. 1919 The SSH_FXP_HANDLE response has the following format: 1921 byte SSH_FXP_HANDLE 1922 uint32 request-id 1923 string handle 1925 'handle' 1926 An arbitrary string that identifies an open file or directory on 1927 the server. The handle is opaque to the client; the client MUST 1928 NOT attempt to interpret or modify it in any way. The length of 1929 the handle string MUST NOT exceed 256 data bytes. 1931 The SSH_FXP_DATA response has the following format: 1933 byte SSH_FXP_DATA 1934 uint32 request-id 1935 string data 1936 bool end-of-file [optional] 1938 data 1939 'data' is an arbitrary byte string containing the requested data. 1940 The data string may be at most the number of bytes requested in a 1941 SSH_FXP_READ request, but may also be shorter. (See 1942 Section 7.2.1.) 1944 end-of-file 1945 This field is optional. If it is present in the packet, it MUST 1946 be true, and it indicates that EOF was reached during this read. 1947 This can help the client avoid a round trip to determine whether a 1948 short read was normal (due to EOF) or some other problem (limitted 1949 server buffer for example.) 1951 The SSH_FXP_NAME response has the following format: 1953 byte SSH_FXP_NAME 1954 uint32 request-id 1955 uint32 count 1956 repeats count times: 1957 string filename [UTF-8] 1958 ATTRS attrs 1959 bool end-of-list [optional] 1961 count 1962 The number of names returned in this response, and the remaining 1963 fields repeat 'count' times. 1965 filename 1966 A file name being returned (for SSH_FXP_READDIR, it will be a 1967 relative name within the directory, without any path components; 1968 for SSH_FXP_REALPATH it will be an absolute path name.) 1970 attrs 1971 The attributes of the file as described in Section ''File 1972 Attributes''. 1974 end-of-list 1975 This field is optional. If present in the packet, it MUST be 1976 true, and indicates that there are no more entries to be read. 1977 This can save the client a round trip to determine if there are 1978 more entries to be read. 1980 The SSH_FXP_ATTRS response has the following format: 1982 byte SSH_FXP_ATTRS 1983 uint32 request-id 1984 ATTRS attrs 1986 where 'request-id' is the request identifier, and 'attrs' is the 1987 returned file attributes as described in Section ''File Attributes''. 1989 9. Extensions 1991 The SSH_FXP_EXTENDED request provides a generic extension mechanism 1992 for adding additional commands. 1994 byte SSH_FXP_EXTENDED 1995 uint32 request-id 1996 string extended-request 1997 ... any request-specific data ... 1999 request-id 2000 Identifier to be returned from the server with the response. 2002 extended-request 2003 A string naming the extension. Vendor-specific extensions have 2004 use the "name@domain" syntax, where domain is an internet domain 2005 name of the vendor defining the request. 2007 The IETF may also define extensions to the protocol. These 2008 extension names will not have an '@' in them. 2010 request-specific data 2011 The rest of the request is defined by the extension, and servers 2012 should only attempt to interpret it if they recognize the 2013 'extended-request' name. 2015 The server may respond to such requests using any of the response 2016 packets defined in Section ''Responses from the Server to the 2017 Client''. Additionally, the server may also respond with a 2018 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 2019 not recognize the 'extended-request' name, then the server MUST 2020 respond with SSH_FXP_STATUS with error/status set to 2021 SSH_FX_OP_UNSUPPORTED. 2023 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 2024 extension-specific data from the server to the client. It is of the 2025 following format: 2027 byte SSH_FXP_EXTENDED_REPLY 2028 uint32 request-id 2029 ... any request-specific data ... 2031 There is a range of packet types reserved for use by extensions. In 2032 order to avoid collision, extensions that that use additional packet 2033 types should determine those numbers dynamically. 2035 The suggested way of doing this is have an extension request from the 2036 client to the server that enables the extension; the extension 2037 response from the server to the client would specify the actual type 2038 values to use, in additional to any other data. 2040 Extension authors should be mindful of the limited range of packet 2041 types available (there are only 45 values available) and avoid 2042 requiring a new packet type where possible. 2044 9.1 File Hashing 2046 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 2048 After some discussion of this at connectathon, I know of two uses for 2049 this feature, neither one of which the feature is entirely suited 2050 for: 2051 o Checking that a file has been uploaded to the server correctly; 2052 some portion of the customers wanting this feature want it in a 2053 security sense, as part of proof the server has the file. 2054 o Optimizing upload or download of the file; multiple hashes are 2055 performed on small pieces of the file and the results are used to 2056 determine what chunks of the file, if any, need to be transfered. 2057 This is similar to the way rsync works. 2059 I've seen both of these implemented. 2061 For the first case, the extension has several drawbacks, including: 2062 o A FIPS implementation can't ship md5. 2063 o MD5's security is potential weaker than other options. 2064 o Being hard-coded to MD5 makes in impossible to adapt to future 2065 developments in the arena of MD5 compromises. 2067 For the second case, the extension has these drawbacks: 2068 o MD5 is expensive (relative to other options.) 2069 o The extension must be sent potentially thousands of times to 2070 retrieve the desired granularity of hashes. 2072 Therefore, for this draft, this section is marked experimental; I've 2073 included a second proposed extension. Please post your thoughts on 2074 the mailing list. (I did it this way just so I could get a draft out 2075 that I and my active co-author are happy with. 2077 In addition, implemenation experience has shown the quick check hash 2078 to not be useful. 2080 END: RFCEDITOR REMOVE BEFORE PUBLISHING 2082 9.1.1 Checking File Contents: v5 extension 2084 This extension allows a client to easily check if a file (or portion 2085 thereof) that it already has matches what is on the server. 2087 byte SSH_FXP_EXTENDED 2088 uint32 request-id 2089 string "md5-hash" / "md5-hash-handle" 2090 string filename [UTF-8] / file-handle 2091 uint64 start-offset 2092 uint64 length 2093 string quick-check-hash 2095 filename 2096 Used if "md5-hash" is specified; indicates the name of the file to 2097 use. The hash will be of the file contents as it would appear on 2098 the wire if the file were opened with no special flags. 2100 file-handle 2101 Used if "md5-hash-handle" is specified; specifies a file handle to 2102 read the data from. The handle MUST be a file handle, and 2103 ACE4_READ_DATA MUST have been included in the desired-access when 2104 the file was opened. 2106 If this file handle was opened in TEXT mode, the md5-hash must be 2107 made of the data as it would be sent on the wire. 2109 start-offset 2110 The starting offset of the data to hash. 2112 length 2113 The length of data to include in the hash. If both start-offset 2114 and length are zero, the entire file should be included. 2116 quick-check-hash 2117 The hash over the first 2048 bytes of the data range as the client 2118 knows it, or the entire range, if it is less than 2048 bytes. 2119 This allows the server to quickly check if it is worth the 2120 resources to hash a big file. 2122 If this is a zero length string, the client does not have the 2123 data, and is requesting the hash for reasons other than comparing 2124 with a local file. The server MAY return SSH_FX_OP_UNSUPPORTED in 2125 this case. 2127 The response is either a SSH_FXP_STATUS packet, indicating an error, 2128 or the following extended reply packet: 2130 byte SSH_FXP_EXTENDED_REPLY 2131 uint32 request-id 2132 string "md5-hash" 2133 string hash 2135 If 'hash' is zero length, then the 'quick-check-hash' did not match, 2136 and no hash operation was preformed. Otherwise, 'hash' contains the 2137 hash of the entire data range (including the first 2048 bytes that 2138 were included in the 'quick-check-hash'.) 2140 9.1.2 Checking File Contents 2142 This extension allows a client to easily check if a file (or portion 2143 thereof) that it already has matches what is on the server. 2145 byte SSH_FXP_EXTENDED 2146 uint32 request-id 2147 string "check-file" 2148 string handle 2149 string hash-algorithm-list 2150 uint64 start-offset 2151 uint64 length 2152 uint32 block-size 2154 handle 2155 'handle' is an open file handle returned by SSH_FXP_OPEN. If 2156 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 2157 return SSH_FX_INVALID_HANDLE. If ACE4_READ_DATA MUST was not 2158 included when the file was opened, the server MUST return 2159 STATUS_PERMISSION_DENIED. 2161 If this file handle was opened in TEXT mode, the check must be 2162 performed on the data as it would be sent on the wire. 2164 hash-algorithm-list 2165 A comma seperated list of hash alogirthms the client is willing to 2166 accept for this operation. The server MUST pick the first hash on 2167 the list that it supports. 2169 Currently supported algorithms are "md5", "sha1", "sha224", 2170 "sha256", "sha384", "sha512", and "crc32". Additional algorithms 2171 may be added by following the DNS extensibility naming convention 2172 outlined in [I-D.ietf-secsh-architecture]. 2174 MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384, 2175 and SHA-512 are decribed in [FIPS-180-2]. crc32 is described in 2176 [ISO.3309.1991], and is the same algorithm used in [RFC1510] 2178 start-offset 2179 The starting offset of the data to include in the hash. 2181 length 2182 The length of data to include in the hash. If length is zero, all 2183 the data from start-offset to the end-of-file should be included. 2185 block-size 2186 An independant hash MUST be computed over ever block in the file. 2187 The size of blocks is specified by block-size. The block-size 2188 MUST NOT be smaller than 256 bytes. If the block-size is 0, then 2189 only one hash, over the entire range MUST be made. 2191 The response is either a SSH_FXP_STATUS packet, indicating an error, 2192 or the following extended reply packet: 2194 byte SSH_FXP_EXTENDED_REPLY 2195 uint32 request-id 2196 string "check-file" 2197 string hash-algo-used 2198 byte hash[n][block-count] 2200 hash-algo-used 2201 The hash algorithm that was actually used. 2203 hash 2204 The computed hashes. The hash algorithm used determines the size 2205 of n. The number of block-size chunks of data in the file 2206 determines block-count. The hashes are placed in the packet one 2207 after another, with no decoration. 2209 Note that if the length of the range is not an even multiple of 2210 block-size, the last hash will have been computer over only the 2211 remainder of the range instead of a full block. 2213 9.2 Querying Available Space 2215 The following extension provides a way to discover the available 2216 space for an arbitrary path. 2218 byte SSH_FXP_EXTENDED 2219 uint32 request-id 2220 string "space-available" 2221 string path [UTF-8] 2223 path 2224 'path' for which the available space should be reported. This 2225 'path' is not required to be the mount point path, but MAY be a 2226 directory or file contained within the mount. 2228 The reply to the request is as follows: 2230 byte SSH_FXP_EXTENDED_REPLY 2231 uint32 request-id 2232 uint64 bytes-on-device 2233 uint64 unused-bytes-on-device 2234 uint64 bytes-available-to-user 2235 uint64 unused-bytes-available-to-user 2236 uint32 bytes-per-allocation-unit 2238 bytes-on-device 2239 The total number of bytes on the device which stores 'path', both 2240 used and unused, or 0 if unknown. 2242 unused-bytes-on-device 2243 The total number of unused bytes availabe on the device which 2244 stores 'path', or 0 if unknown. 2246 bytes-available-to-user 2247 The total number of bytes, both used and unused, available to the 2248 authenticated user on the device which stores 'path', or 0 if 2249 unknown. 2251 unused-bytes-available-to-user 2252 The total number of unused bytes available to the authenticated 2253 user on the device which stores 'path', or 0 if unknown. 2255 bytes-per-allocation-unit 2256 The number of bytes in each allocation unit on the device, or in 2257 other words, the minimum number of bytes that a file allocation 2258 size can grow or shrink by. If the server does not know this 2259 information, or the file-system in use does not use allocation 2260 block, this value MUST be 0. 2262 9.3 Querying User Home Directory 2264 Many users are used to being able to type '~' as an alias for their 2265 home directory, or ~username as an alias for another user's home 2266 directory. To support this feature, a server MAY support following 2267 extension. 2269 byte SSH_FXP_EXTENDED 2270 uint32 request-id 2271 string "home-directory" 2272 string username [UTF-8] 2274 username 2275 Username whose home directory path is being requested. An empty 2276 string implies the current user. 2278 The reply to the request is either a SSH_FXP_STATUS packet or the 2279 following extended reply: 2281 byte SSH_FXP_EXTENDED_REPLY 2282 uint32 request-id 2283 string "home-directory" 2284 string absolute-pathname 2286 absolute-pathname 2287 Absolute pathname of the specified user's home directory. 2289 10. Implementation Considerations 2291 In order for this protocol to perform well, especially over high 2292 latency networks, multiple read and write requests should be queued 2293 to the server. 2295 The data size of requests should match the maximum packet size for 2296 the next layer up in the protocol chain. 2298 When implemented over ssh, the best performance should be achieved 2299 when the data size matches the channels max packet, and the channel 2300 window is a multiple of the channel packet size. 2302 Implementations MUST be aware that requests do not have to be 2303 satisfied in the order issued. (See Request Synchronization and 2304 Reordering (Section 3.1).) 2306 Implemenations MUST also be aware that read requests may not return 2307 all the requested data, even if the data is available. 2309 11. Security Considerations 2311 It is assumed that both ends of the connection have been 2312 authenticated and that the connection has privacy and integrity 2313 features. Such security issues are left to the underlying transport 2314 protocol, except to note that if this is not the case, an attacker 2315 could manipulate files on the server at will and thus wholly 2316 compromise the server. 2318 This protocol provides file system access to arbitrary files on the 2319 server (only constrained by the server implementation). It is the 2320 responsibility of the server implementation to enforce any access 2321 controls that may be required to limit the access allowed for any 2322 particular user (the user being authenticated externally to this 2323 protocol, typically using [I-D.ietf-secsh-userauth]. 2325 Extreme care must be used when interpreting file handle strings. In 2326 particular, care must be taken that a file handle string is valid in 2327 the context of a given 'file-share' session. For example, the 2328 'file-share' server daemon may have files which it has opened for its 2329 own purposes, and the client must not be able to access these files 2330 by specifying an arbitrary file handle string. 2332 The permission field of the attrib structure (Section 6.6) may 2333 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 2334 extreme caution when setting these bits on either remote or local 2335 files. (I.e., just because a file was SUID on the remote system does 2336 not necessarily imply that it should be SUID on the local system.) 2338 Filesystems often contain entries for objects that are not files at 2339 all, but are rather devices. For example, it may be possible to 2340 access serial ports, tape devices, or named pipes using this 2341 protocol. Servers should exercise caution when granting access to 2342 such resources. In addition to the dangers inherent in allowing 2343 access to such a device, some devices may be 'slow', and could cause 2344 denial of service by causing the server to block for a long period of 2345 time while I/O is performed to such a device. 2347 Servers should take care that file-system quotas are respected for 2348 users. In addition, implementations should be aware that attacks may 2349 be possible, or facilitated, by filling a filesystem. For example, 2350 filling the filesystem where event logging and auditing occurs may, 2351 at best, cause the system to crash, or at worst, allow the attacker 2352 to take untraceable actions in the future. 2354 Servers should take care that filenames are in their appropriate 2355 canonical form, and to insure that filenames not in canonical form 2356 cannot be used to bypass access checks or controls. 2358 If the server implementation limits access to certain parts of the 2359 file system, extra care must be taken in parsing file names which 2360 contain the '..' path element, and when following symbolic links, 2361 shortcuts, or other filesystem objects which might transpose the path 2362 to refer to an object outside of the restricted area. There have 2363 been numerous reported security bugs where a ".." in a path name has 2364 allowed access outside the intended area. 2366 12. Changes from Previous Protocol Versions 2368 The SSH File Transfer Protocol has changed over time, before its 2369 standardization. The following is a description of the incompatible 2370 changes between different versions. 2372 12.1 Changes Between Versions 6 and 5 2373 o Add ability to negotiate version when client supports discontigous 2374 ranges of protocol version. 2375 o Add 'filename-charset' and the 'filename-translation-control' 2376 extensions to allow better support of servers that can't reliably 2377 translate to UTF-8. 2378 o Add DIR_NOT_EMPTY, NOT_A_DIRECTORY, INVALID_FILENAME LINK_LOOP, 2379 CANNOT_DELETE, INVALID_PARAMETER, FILE_IS_A_DIRECTORY, 2380 BYTE_RANGE_LOCK_CONFLICT, BYTE_RANGE_LOCK_REFUSED, DELETE_PENDING, 2381 and FILE_CORRUPT error codes. 2382 o Added space-available extension. 2383 o Added NOFOLLOW and DELETE_ON_CLOSE flag to open flags. 2384 o Added allocation-size, text-hint, link-count, mime-type, and 2385 untranslated-name fields to attrib structure. Add 2386 ATTR_FLAGS_TRANSLATION_ERR to the attrib-bits. 2387 o Add optional 'compose-path' and 'control-byte' to REALPATH; make 2388 realpath's behaviour truly deterministic (i.e., MUST instead of 2389 SHOULD.) Give clients the ability to compose path's without 2390 understanding what is relative and what is absolute. 2391 o Give SSH_FXP_DATA and SSH_FXP_NAME optional end-of-data-set flags, 2392 which can help the client avoid a round trip during normal 2393 operation. 2394 o Changed the SYMLINK packet to be LINK and give it the ability to 2395 create hard links. Also change it's packet number because many 2396 implementation implemented SYMLINK with the arguments reversed. 2397 Hopefully the new argument names make it clear which way is which. 2398 o Clarify who should apply umask to posix mode bits (the client, not 2399 the server.) 2400 o Specify behavior for otherwise valid packets with excess data and 2401 unrecognized packet types. 2402 o Add home directory extension. 2403 o Remove "#define" from symbol definitions to shorten line and help 2404 us pass idnits. 2406 12.2 Changes Between Versions 5 and 4 2408 Many of the changes between version 5 and version 4 are to better 2409 support the changes in version 4, and to better specify error 2410 conditions. 2412 o Add "supported" extension to communicate features supported. 2413 o Clarify error handling when client requests unsupported feature. 2414 (For example, attempts to write an unsupported attribute.) 2415 o Add attrib-bits field to the attribute structure, which specifies 2416 a number of boolean attributes related to files and directories, 2417 including advisory read-only and case-sensitivity bits. 2418 o Clarify the actual bit values to be used for the permissions field 2419 (since posix doesn't define values) and correct the value of 2420 ATTR_PERMISSIONS flag. 2421 o Some reordering of sections to attempt to get a better grouping of 2422 related functionality. 2423 o Open request explicitly specifies the access desired for the file. 2424 o Add support for explicitly requesting file locking. 2425 o Add support for better control of the rename operation. 2426 o Add SSH_FX_NO_SPACE_ON_FILESYSTEM, SSH_FX_QUOTA_EXCEEDED, and 2427 SSH_FX_UNKNOWN_PRINCIPLE error codes. 2428 o Add support for error specific data. This is used by a new 2429 SSH_FX_UNKNOWN_PRINCIPLE error to communicate which principles are 2430 unknown. 2431 o Add support for retrieving md5-hash of file contents. 2432 o Update security section. 2434 12.3 Changes Between Versions 4 and 3 2436 Many of the changes between version 4 and version 3 are to the 2437 attribute structure to make it more flexible for non-unix platforms. 2439 o Clarify the use of stderr by the server. 2440 o Clarify handling of very large read requests by the server. 2441 o Make all filenames UTF-8. 2442 o Added 'newline' extension. 2443 o Made time fields 64 bit, and optionally have nanosecond 2444 resolution. 2445 o Made file attribute owner and group strings so they can actually 2446 be used on disparate systems. 2447 o Added createtime field, and added separate flags for atime, 2448 createtime, and mtime so they can be set separately. 2449 o Split the file type out of the permissions field and into its own 2450 field (which is always present.) 2451 o Added acl attribute. 2452 o Added SSH_FXF_TEXT file open flag. 2453 o Added flags field to the get stat commands so that the client can 2454 specifically request information the server might not normally 2455 included for performance reasons. 2456 o Removed the long filename from the names structure-- it can now be 2457 built from information available in the attrs structure. 2458 o Added reserved range of packet numbers for extensions. 2460 o Added several additional error codes. 2462 12.4 Changes Between Versions 3 and 2 2464 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. 2465 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were 2466 added. 2467 o The SSH_FXP_STATUS message was changed to include fields 'error 2468 message' and 'language tag'. 2470 12.5 Changes Between Versions 2 and 1 2472 o The SSH_FXP_RENAME message was added. 2474 12.6 Changes Between Versions 1 and 0 2476 o Implementation changes, no actual protocol changes. 2478 13. Trademark Issues 2480 "ssh" is a registered trademark of SSH Communications Security Corp 2481 in the United States and/or other countries. 2483 14. References 2485 14.1 Normative References 2487 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 2488 April 1992. 2490 [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network 2491 Authentication Service (V5)", RFC 1510, September 1993. 2493 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2494 Beame, C., Eisler, M. and D. Noveck, "NFS version 4 2495 Protocol", RFC 3010, December 2000. 2497 [I-D.ietf-secsh-architecture] 2498 Lonvick, C., "SSH Protocol Architecture", 2499 Internet-Draft draft-ietf-secsh-architecture-22, March 2500 2005. 2502 [I-D.ietf-secsh-transport] 2503 Lonvick, C., "SSH Transport Layer Protocol", 2504 Internet-Draft draft-ietf-secsh-transport-24, March 2005. 2506 [I-D.ietf-secsh-connect] 2507 Lonvick, C., "SSH Connection Protocol", 2508 Internet-Draft draft-ietf-secsh-connect-25, March 2005. 2510 [IEEE.1003-1.1996] 2511 Institute of Electrical and Electronics Engineers, 2512 "Information Technology - Portable Operating System 2513 Interface (POSIX) - Part 1: System Application Program 2514 Interface (API) [C Language]", IEEE Standard 1003.2, 1996. 2516 [FIPS-180-2] 2517 National Institute of Standards and Technology, "Secure 2518 Hash Standard (SHS)", Federal Information Processing 2519 Standards Publication 180-2, August 2002. 2521 [ISO.3309.1991] 2522 International Organization for Standardization, 2523 "Information Technology - Telecommunications and 2524 information exchange between systems - High-level data 2525 link control (HDLC) procedures - Frame structure", 2526 ISO Standard 3309, June 1991. 2528 14.2 Informative References 2530 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet 2531 Mail Extensions) Part One: Mechanisms for Specifying and 2532 Describing the Format of Internet Message Bodies", 2533 RFC 1521, September 1993. 2535 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2536 RFC 2246, January 1999. 2538 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2539 Languages", BCP 18, RFC 2277, January 1998. 2541 [I-D.ietf-secsh-userauth] 2542 Lonvick, C., "SSH Authentication Protocol", 2543 Internet-Draft draft-ietf-secsh-userauth-27, March 2005. 2545 Authors' Addresses 2547 Joseph Galbraith 2548 VanDyke Software 2549 4848 Tramway Ridge Blvd 2550 Suite 101 2551 Albuquerque, NM 87111 2552 US 2554 Phone: +1 505 332 5700 2555 Email: galb-list@vandyke.com 2557 Oskari Saarenmaa 2558 F-Secure 2559 Tammasaarenkatu 7 2560 Helsinki 00180 2561 FI 2563 Email: oskari.saarenmaa@f-secure.com 2565 Tatu Ylonen 2566 SSH Communications Security Corp 2567 Fredrikinkatu 42 2568 HELSINKI FIN-00100 2569 Finland 2571 Email: ylo@ssh.com 2573 Sami Lehtinen 2574 SSH Communications Security Corp 2575 Fredrikinkatu 42 2576 HELSINKI FIN-00100 2577 Finland 2579 Email: sjl@ssh.com 2581 Trademark notice 2583 "ssh" is a registered trademark in the United States and/or other 2584 countries. 2586 Intellectual Property Statement 2588 The IETF takes no position regarding the validity or scope of any 2589 Intellectual Property Rights or other rights that might be claimed to 2590 pertain to the implementation or use of the technology described in 2591 this document or the extent to which any license under such rights 2592 might or might not be available; nor does it represent that it has 2593 made any independent effort to identify any such rights. Information 2594 on the procedures with respect to rights in RFC documents can be 2595 found in BCP 78 and BCP 79. 2597 Copies of IPR disclosures made to the IETF Secretariat and any 2598 assurances of licenses to be made available, or the result of an 2599 attempt made to obtain a general license or permission for the use of 2600 such proprietary rights by implementers or users of this 2601 specification can be obtained from the IETF on-line IPR repository at 2602 http://www.ietf.org/ipr. 2604 The IETF invites any interested party to bring to its attention any 2605 copyrights, patents or patent applications, or other proprietary 2606 rights that may cover technology that may be required to implement 2607 this standard. Please address the information to the IETF at 2608 ietf-ipr@ietf.org. 2610 Disclaimer of Validity 2612 This document and the information contained herein are provided on an 2613 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2614 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2615 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2616 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2617 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2618 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2620 Copyright Statement 2622 Copyright (C) The Internet Society (2005). This document is subject 2623 to the rights, licenses and restrictions contained in BCP 78, and 2624 except as set forth therein, the authors retain all their rights. 2626 Acknowledgment 2628 Funding for the RFC Editor function is currently provided by the 2629 Internet Society.