idnits 2.17.1 draft-ietf-secsh-filexfer-10.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 2473. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 2450. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 2457. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 2463. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 163: '...rr by the server SHOULD be considered ...' RFC 2119 keyword, line 164: '...information, and MAY be displayed to t...' RFC 2119 keyword, line 170: '...rors or warnings MAY be sent as stderr...' RFC 2119 keyword, line 190: '...the length field MUST be included in a...' RFC 2119 keyword, line 194: '...overhead). All servers SHOULD support...' (174 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 644 has weird spacing: '... bool do-...' == Line 672 has weird spacing: '... string owne...' == Line 673 has weird spacing: '... string grou...' == Line 683 has weird spacing: '... string acl ...' == Line 687 has weird spacing: '... string mime...' == (5 more instances...) -- The exact meaning of the all-uppercase expression 'MAY NOT' is not defined in RFC 2119. If it is intended as a requirements expression, it should be rewritten using one of the combinations defined in RFC 2119; otherwise it should not be all-uppercase. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The use of additional packet types in the non-extension range MUST be introduced through IETF consensus. New packet types to be sent from the client to the server MAY be introduced without changing the protocol version (Section 5). Because the client has no way to respond to unrecognized packet types, new packet types to be sent from the server to the client the client MUST not used unless the protocol version is changed or the client has negotiated to received them. This negotiation MAY be explicit, through the use of extensions, or MAY be implicit, by the client itself using a packet type not defined above. == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: The server MUST not respond with more data than is specified by the 'length' parameter. However, the server MAY respond with less data if EOF is reached, an error is encountered, or the servers internal buffers can not handle such a large request. == The expression 'MAY NOT', while looking like RFC 2119 requirements text, is not defined in RFC 2119, and should not be used. Consider using 'MUST NOT' instead (if that is what you mean). Found 'MAY NOT' in this paragraph: If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT fail the request if the path does not exist, is hidden, or the user does not have access to the path or some component thereof. However, the path MAY NOT be completely resolved to it's component form. For example, symlinks may not be followed in this case. The server MAY fail the request if the path is not syntactically valid, or for other reasons. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 2005) is 6883 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 2194, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 1962, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 1963, but not defined ** Obsolete undefined reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) ** Obsolete normative reference: RFC 3010 (Obsoleted by RFC 3530) -- Possible downref: Non-RFC (?) normative reference: ref. 'IEEE.1003-1.1996' -- Obsolete informational reference (is this intentional?): RFC 1521 (Obsoleted by RFC 2045, RFC 2046, RFC 2047, RFC 2048, RFC 2049) -- Obsolete informational reference (is this intentional?): RFC 2246 (Obsoleted by RFC 4346) Summary: 8 errors (**), 0 flaws (~~), 14 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Secure Shell Working Group J. Galbraith 3 Internet-Draft VanDyke Software 4 Expires: December 3, 2005 O. Saarenmaa 5 F-Secure 6 June 2005 8 SSH File Transfer Protocol 9 draft-ietf-secsh-filexfer-10.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on December 3, 2005. 36 Copyright Notice 38 Copyright (C) The Internet Society (2005). 40 Abstract 42 The SSH File Transfer Protocol provides secure file transfer 43 functionality over any reliable data stream. It is the standard file 44 transfer protocol for use with the SSH2 protocol. This document 45 describes the file transfer protocol and its interface to the SSH2 46 protocol suite. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 51 2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4 52 3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 53 3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5 54 4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 55 4.1. Request Synchronization and Reordering . . . . . . . . . . 6 56 4.2. New data types defined by this document . . . . . . . . . 7 57 4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 58 5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9 59 5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9 60 5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9 61 5.3. Determining Server Newline Convention . . . . . . . . . . 10 62 5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10 63 5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 13 64 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14 65 7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 15 66 7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 16 67 7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 68 7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 69 7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 18 70 7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 18 71 7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 19 72 7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 19 73 7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 74 7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 21 75 7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 24 76 7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 24 77 7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 25 78 7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 25 79 7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 25 80 8. Requests From the Client to the Server . . . . . . . . . . . . 25 81 8.1. Opening and Closing Files and Directories . . . . . . . . 25 82 8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 26 83 8.1.2. Opening a Directory . . . . . . . . . . . . . . . . . 31 84 8.1.3. Closing Handles . . . . . . . . . . . . . . . . . . . 32 85 8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 32 86 8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 32 87 8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 33 88 8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 34 89 8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 34 90 8.4. Creating and Deleting Directories . . . . . . . . . . . . 36 91 8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 36 92 8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 37 93 8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 38 94 8.8. Byte-range locks . . . . . . . . . . . . . . . . . . . . . 39 95 8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 40 96 8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 42 97 9. Responses from the Server to the Client . . . . . . . . . . . 43 98 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 43 99 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 48 100 9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 48 101 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 49 102 9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 50 103 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 50 104 11. Implementation Considerations . . . . . . . . . . . . . . . . 51 105 12. Security Considerations . . . . . . . . . . . . . . . . . . . 51 106 13. Changes from Previous Protocol Versions . . . . . . . . . . . 53 107 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 53 108 14.1. Normative References . . . . . . . . . . . . . . . . . . . 53 109 14.2. Informative References . . . . . . . . . . . . . . . . . . 53 110 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 55 111 Intellectual Property and Copyright Statements . . . . . . . . . . 56 113 1. Introduction 115 This protocol provides secure file transfer (and more generally file 116 system access.) It is designed so that it could be used to implement 117 a secure remote file system service, as well as a secure file 118 transfer service. 120 This protocol assumes that it runs over a secure channel, such as a 121 channel in [I-D.ietf-secsh-architecture], and that the server has 122 already authenticated the client, and that the identity of the client 123 user is available to the protocol. 125 In general, this protocol follows a simple request-response model. 126 Each request and response contains a sequence number and multiple 127 requests may be pending simultaneously. There are a relatively large 128 number of different request messages, but a small number of possible 129 response messages. Each request has one or more response messages 130 that may be returned in result (e.g., a read either returns data or 131 reports error status). 133 The packet format descriptions in this specification follow the 134 notation presented in [I-D.ietf-secsh-architecture]. 136 Even though this protocol is described in the context of the SSH2 137 protocol, this protocol is general and independent of the rest of the 138 SSH2 protocol suite. It could be used in a number of different 139 applications, such as secure file transfer over TLS [RFC2246] and 140 transfer of management information in VPN applications. 142 2. Acknowledgements 144 This document owes it's initial creation and protocol design to Tatu 145 Ylonen and Sami Lehtinen of SSH Communications Security Corp. 147 We express our gratitude to them for their initial work on this 148 protocol. 150 3. Use with the SSH Connection Protocol 152 When used with the SSH2 Protocol suite, this protocol is intended to 153 be used as a subsystem as described in [I-D.ietf-secsh-connect] in 154 the section "Starting a Shell or a Command". The subsystem name used 155 with this protocol is "sftp". 157 3.1. The Use of 'stderr' in the server 159 This protocol uses stdout and stdin to transmit binary protocol data. 160 The "session" channel ([I-D.ietf-secsh-connect]), which is used by 161 the subsystem, also supports the use of stderr. 163 Data sent on stderr by the server SHOULD be considered free format 164 debug or supplemental error information, and MAY be displayed to the 165 user. 167 For example, during initialization, there is no client request 168 active, so errors or warning information cannot be sent to the client 169 as part of the SFTP protocol at this early stage. However, the 170 errors or warnings MAY be sent as stderr text. 172 4. General Packet Format 174 All packets transmitted over the secure connection are of the 175 following format: 177 uint32 length 178 byte type 179 uint32 request-id 180 ... type specific fields ... 182 'length' 183 The length of the entire packet, excluding the length field 184 itself, such that, for example, for a packet type containing no 185 type specific fields, the length field would be 5, and 9 bytes of 186 data would be sent on the wire. (This is the packet format used 187 in [I-D.ietf-secsh-transport].) 189 All packet descriptions in this document omit the length field for 190 brevity; the length field MUST be included in any case. 192 The maximum size of a packet is in practice determined by the 193 client (the maximum size of read or write requests that it sends, 194 plus a few bytes of packet overhead). All servers SHOULD support 195 packets of at least 34000 bytes (where the packet size refers to 196 the full length, including the header above). This should allow 197 for reads and writes of at most 32768 bytes. 199 'type' 200 The type code for the packet. 202 'request-id' 203 Each request from the client contains a 'request-id' field. Each 204 response from the server includes that same 'request-id' from the 205 request that the server is responding to. One possible 206 implementation is for the client to us a monotonically increasing 207 request sequence number (modulo 2^32). There is, however, no 208 particular requirement the 'request-id' fields be unique. 210 There are two packets, INIT and VERSION, which do not use the 211 request-id. 212 Packet descriptions in this document will contain the 'request-id' 213 field, but will not redefine it. 215 Implementations MUST ignore excess data at the end of an otherwise 216 valid packet. Implementations MUST respond to unrecognized packet 217 types with an SSH_FX_OP_UNSUPPORTED error. This will allow the 218 protocol to be extended in a backwards compatible way as needed. 220 There is no limit on the number of outstanding (non-acknowledged) 221 requests that the client may send to the server. In practice this is 222 limited by the buffering available on the data stream and the queuing 223 performed by the server. If the server's queues are full, it should 224 not read any more data from the stream, and flow control will prevent 225 the client from sending more requests. Note, however, that while 226 there is no restriction on the protocol level, the client's API may 227 provide a limit in order to prevent infinite queuing of outgoing 228 requests at the client. 230 4.1. Request Synchronization and Reordering 232 The protocol and implementations MUST process requests relating to 233 the same file in the order in which they are received. In other 234 words, if an application submits multiple requests to the server, the 235 results in the responses will be the same as if it had sent the 236 requests one at a time and waited for the response in each case. For 237 example, the server may process non-overlapping read/write requests 238 to the same file in parallel, but overlapping reads and writes cannot 239 be reordered or parallelized. However, there are no ordering 240 restrictions on the server for processing requests from two different 241 file transfer connections. The server may interleave and parallelize 242 them at will. 244 There are no restrictions on the order in which responses to 245 outstanding requests are delivered to the client, except that the 246 server must ensure fairness in the sense that processing of no 247 request will be indefinitely delayed even if the client is sending 248 other requests so that there are multiple outstanding requests all 249 the time. 251 A client MUST be prepared to receive responses to multiple overlapped 252 requests out of order. 254 4.2. New data types defined by this document 256 This document defines these data types in addition to those defined 257 in [I-D.ietf-secsh-architecture]. 259 uint16 260 Represents a 16-bit unsigned integer. Stored as 2 bytes in the 261 order of decreasing significance (network byte order). 263 int64 264 Represents a 64-bit signed integer. Stored using two's 265 complement, as eight bytes in the order of decreasing significance 266 (network byte order). 268 extension-pair 270 string extension-name 271 string extension-data 273 'extension-name' is the name of a protocol extension. Extensions 274 not defined by IETF CONSENSUS MUST follow the the DNS 275 extensibility naming convention outlined in [I-D.ietf-secsh- 276 architecture]. 278 'extension-data' is any data specific to the extension, and MAY be 279 zero length if the extension has no data. 281 4.3. Packet Types 283 The following values are defined for packet types. 285 SSH_FXP_INIT 1 286 SSH_FXP_VERSION 2 287 SSH_FXP_OPEN 3 288 SSH_FXP_CLOSE 4 289 SSH_FXP_READ 5 290 SSH_FXP_WRITE 6 291 SSH_FXP_LSTAT 7 292 SSH_FXP_FSTAT 8 293 SSH_FXP_SETSTAT 9 294 SSH_FXP_FSETSTAT 10 295 SSH_FXP_OPENDIR 11 296 SSH_FXP_READDIR 12 297 SSH_FXP_REMOVE 13 298 SSH_FXP_MKDIR 14 299 SSH_FXP_RMDIR 15 300 SSH_FXP_REALPATH 16 301 SSH_FXP_STAT 17 302 SSH_FXP_RENAME 18 303 SSH_FXP_READLINK 19 304 SSH_FXP_LINK 21 305 SSH_FXP_BLOCK 22 306 SSH_FXP_UNBLOCK 23 308 SSH_FXP_STATUS 101 309 SSH_FXP_HANDLE 102 310 SSH_FXP_DATA 103 311 SSH_FXP_NAME 104 312 SSH_FXP_ATTRS 105 314 SSH_FXP_EXTENDED 200 315 SSH_FXP_EXTENDED_REPLY 201 317 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 318 implement extensions, which can be vendor specific. See Section 319 ''Extensions'' for more details. 321 Values 210-255 are reserved for use in conjunction with these 322 extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the 323 meaning of these reserved types. It is suggested that the actual 324 value to be used also be negotiated, since this will prevent 325 collision among multiple uncoordinated extensions. 327 The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if 328 it receives a packet it does not recognize. 330 The use of additional packet types in the non-extension range MUST be 331 introduced through IETF consensus. New packet types to be sent from 332 the client to the server MAY be introduced without changing the 333 protocol version (Section 5). Because the client has no way to 334 respond to unrecognized packet types, new packet types to be sent 335 from the server to the client the client MUST not used unless the 336 protocol version is changed or the client has negotiated to received 337 them. This negotiation MAY be explicit, through the use of 338 extensions, or MAY be implicit, by the client itself using a packet 339 type not defined above. 341 5. Protocol Initialization 343 When the file transfer protocol starts, the client first sends a 344 SSH_FXP_INIT (including its version number) packet to the server. 345 The server responds with a SSH_FXP_VERSION packet, supplying the 346 lowest of its own and the client's version number. Both parties 347 should from then on adhere to that particular version of the 348 protocol. 350 The version number of the protocol specified in this document is 6. 351 The version number should be incremented for each incompatible 352 revision of this protocol. 354 Note that these two packets DO NOT contain a request id. These are 355 the only such packets in the protocol. 357 5.1. Client Initialization 359 The SSH_FXP_INIT packet (from client to server) has the following 360 data: 362 uint32 version 364 'version' is the version number of the client. If the client wishes 365 to interoperate with servers that support discontinuous version 366 numbers it SHOULD send '3', and then use the 'version-select' 367 extension (see below.) Otherwise, this value is '6' for this version 368 of the protocol. 370 5.2. Server Initialization 372 The SSH_FXP_VERSION packet (from server to client) has the following 373 data: 375 uint32 version 376 extension-pair extensions[0..n] 378 'version' is the lower of the protocol version supported by the 379 server and the version number received from the client. 381 'extensions' is 0 or more extension-pairs (Section 4.2). 382 Implementations MUST silently ignore any extensions whose names they 383 do not recognize. 385 5.3. Determining Server Newline Convention 387 In order to correctly process text files in a cross platform 388 compatible way, newline sequences must be converted between client 389 and server conventions. 391 The SSH_FXF_ACCESS_TEXT_MODE file open flag (Section 8.1.1) makes it 392 possible to request that the server translate a file to a 'canonical' 393 wire format. This format uses CRLF as the line separator. 395 Servers for systems using other conventions MUST translate to and 396 from the canonical form. 398 However, to ease the burden of implementation on servers that use a 399 single, simple, separator sequence the following extension allows the 400 canonical format to be changed. 402 string "newline" 403 string new-canonical-separator (usually CR or LF or CRLF) 405 All clients MUST support this extension. 407 When processing text files, clients SHOULD NOT translate any 408 character or sequence that is not an exact match of the server's 409 newline separator. 411 In particular, if the newline sequence being used is the canonical 412 CRLF sequence, a lone CR or a lone LF SHOULD be written through 413 without change. 415 5.4. Supported Features 417 The sftp protocol has grown to be very rich, and now supports a 418 number of features that may not be available on all servers. 420 When a server receives a request for a feature it cannot support, it 421 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 422 specified. The following extension facilitates clients being able to 423 use the maximum available feature set, and yet not be overly burdened 424 by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST 425 include as part of their version packet. 427 string "supported2" 428 string supported-structure 429 uint32 supported-attribute-mask 430 uint32 supported-attribute-bits 431 uint32 supported-open-flags 432 uint32 supported-access-mask 433 uint32 max-read-size 434 uint16 supported-open-block-vector 435 uint16 supported-block-vector 436 uint32 attrib-extension-count 437 string attrib-extension-names[attrib_extension-count] 438 uint32 extension-count 439 string extension-names[extension-count] 441 Note that the name "supported2" is used here to avoid conflict with 442 the slightly different "supported" extension that was previously 443 used. 444 supported-attribute-mask 445 This mask MAY by applied to the 'File Attributes' valid-attribute- 446 flags field (Section 7.1) to ensure that no unsupported attributes 447 are present during a operation which writes attributes. 449 supported-attribute-bits 450 This mask MAY by applied to the 'File Attributes' attrib-bits 451 field (Section 7.9) to ensure that no unsupported attrib-bits are 452 present during a operation which writes attributes. 454 supported-open-flags 455 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN 456 (Section 8.1.1) flags field. 458 supported-access-mask 459 This mask may be applied to the ace-mask field of an ACL. 461 This mask SHOULD NOT be applied to the desired-access field of the 462 SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result 463 in not requesting the access required by the client. In this 464 case, the server is responsible for translating the clients 465 requested access to a mode it supports that is sufficient to grant 466 all access requested by the client. 468 max-read-size 469 This is the maximum read size that the server guarantees to 470 complete. For example, certain embedded server implementations 471 complete only the first 4K of a read, even if there is additional 472 data to be read from the file. 474 If the server specifies a non-zero value for max-read-size, it 475 MUST return the requested number of bytes for reads that are less 476 than or equal to the value, unless it encounters EOF or an ERROR. 478 The server MAY use this value to express that it is willing to 479 handle very large read requests, in excess of the standard 34000 480 bytes specified in Section 4. 482 supported-open-block-vector 483 supported-block-vector 484 16-bit masks specifying which combinations of blocking flags are 485 supported. Each bit corresponds to one combination of the 486 SSH_FXF_ACCESS_BLOCK_READ, SSH_FXF_ACCESS_BLOCK_WRITE, 487 SSH_FXF_ACCESS_BLOCK_DELETE, and SSH_FXF_ACCESS_BLOCK_ADVISORY 488 bits from Section 7.1.1.3, with a set bit corresponding to a 489 supported combination and a clear bit an unsupported combination. 490 The index of a bit, bit zero being the least significant bit, 491 viewed as a four-bit number, corresponds to a combination of flag 492 bits, shifted right so that BLOCK_READ is the least significant 493 bit. The combination `no blocking flags' MUST be supported, so 494 the low bit will always be set. 496 For example, a server supporting only the classic advisory read 497 (shared) and write (exclusive) locks would set the bits 498 corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, 499 0b1010, plus the always-set bit 0b0000, giving a mask value of 500 0b0000110000000001, or 0x0c01; a server supporting no locking at 501 all would set only bit zero, giving 0x0001. 503 'supported-open-block-masks' applies to the SSH_FXP_OPEN 504 (Section 8.1.1) flags field. 'supported-block-masks' applies to 505 the SSH_FXF_BLOCK request. 507 attrib-extension-count 508 Count of extension names in the attrib-extension-names array. 510 attrib-extension-names 511 Names of extensions that can be used in an ATTRS (Section 7.14) 512 structure. 514 extension-count 515 Count of extension names in the extension-names array. 517 extension-names 518 Names of extensions that can be used with the SSH_FXP_EXTEND 519 (Section 10) packet. 521 Naturally, if a given attribute field, attribute mask bit, open flag, 522 or extension is required for correct operation, the client MUST 523 either not allow the bit to be masked off, or MUST fail the operation 524 gracefully without sending the request to the server. 526 The client MAY send requests that are not supported by the server; 527 however, it is not normally expected to be productive to do so. The 528 client SHOULD apply the mask even to attrib structures received from 529 the server. The server MAY include attributes or attrib-bits that 530 are not included in the mask. Such attributes or attrib-bits are 531 effectively read-only. 533 5.5. Version re-negotiation 535 If the server supports other versions than what was negotiated, it 536 may wish to send the 'versions' extension to inform the client of 537 this fact. The client may then optionally choose to use one of the 538 other versions supported. 540 string "versions" 541 string comma-separated-versions 543 'comma-separated-versions' is a string of comma separated version 544 numbers. Defined versions are: "2", "3", "4", "5", "6". Any other 545 version advertised by the server must follow the DNS extensibility 546 naming convention outlined in [I-D.ietf-secsh-architecture]. 548 For example: "2,3,6,private@example.com". 550 If the client and server have negotiated a a version greater than or 551 equal to version '3' (the version at which SSH_FXP_EXTENDED was 552 introduced) in the initial VERSION/INIT exchange, the client may 553 select a new version to use from the list the server provided using 554 the following SSH_FXP_EXTENDED request. 556 string "version-select" 557 string version-from-list 559 If the 'version-from-list' is one of the versions on the servers 560 list, the server MUST respond with SSH_FX_OK. If the server did not 561 send the "versions" extension, or the version-from-list was not 562 included, the server MAY send a status response describing the 563 failure, but MUST then close the channel without processing any 564 further requests. 566 The 'version-select' MUST be the first request from the client to the 567 server; if it is not, the server MUST fail the request and close the 568 channel. 570 Although this request does take a full round trip, no client need 571 wait for the response before continuing, because any valid request 572 MUST succeed, and any invalid request results in a channel close. 573 Since the request is the first request, it is not possible for the 574 server to have already sent responses conforming to the old version. 576 Typically, the client SHOULD NOT down-grade the protocol version 577 using this extension; however, it is not forbidden to do so. One 578 reason a client might do so is to work around a buggy implementation. 580 6. File Names 582 This protocol represents file names as strings. File names are 583 assumed to use the slash ('/') character as a directory separator. 585 File names starting with a slash are "absolute", and are relative to 586 the root of the file system. Names starting with any other character 587 are relative to the user's default directory (home directory). Note 588 that identifying the user is assumed to take place outside of this 589 protocol. 591 Servers SHOULD interpret a path name component ".." (Section 12) as 592 referring to the parent directory, and "." as referring to the 593 current directory. 595 An empty path name is valid, and it refers to the user's default 596 directory (usually the user's home directory). 598 Otherwise, no syntax is defined for file names by this specification. 599 Clients should not make any other assumptions; however, they can 600 splice path name components returned by SSH_FXP_READDIR together 601 using a slash ('/') as the separator, and that will work as expected. 603 It is understood that the lack of well-defined semantics for file 604 names may cause interoperability problems between clients and servers 605 using radically different operating systems. However, this approach 606 is known to work acceptably with most systems, and alternative 607 approaches that e.g. treat file names as sequences of structured 608 components are quite complicated. 610 The preferred encoding for filenames is UTF-8. This is consistent 611 with IETF Policy on Character Sets and Languages [RFC2277] and it is 612 further supposed that the server is more likely to support any local 613 character set and be able to convert it to UTF-8. 615 However, because the server does not always know the encoding of 616 filenames, it is not always possible for the server to preform a 617 valid translation to UTF-8. When an invalid translation to UTF-8 is 618 preformed, it becomes impossible to manipulate the file, because the 619 translation is not reversible. Therefore, the following extensions 620 are provided in order to make it possible for the server to 621 communicate it's abilities to the client, and to allow the client to 622 control whether the server attempts the conversion. 624 A server MAY include the following extension with it's version 625 packet. 627 string "filename-charset" 628 string charset-name 630 A server that can always provide a valid UTF-8 translation for 631 filenames SHOULD NOT send this extension. Otherwise, the server 632 SHOULD send this extension and include the encoding most likely to be 633 used for filenames. This value will most likely be derived from the 634 LC_CTYPE on most unix-like systems. 636 A server that does not send this extension MUST send all filenames 637 encoded in UTF-8. All clients MUST support UTF-8 filenames. 639 If the server included the 'filename-charset' extension with its 640 VERSION packet, a client MAY send the following extension to turn off 641 server translation to UTF-8. 643 string "filename-translation-control" 644 bool do-translate 646 If the client does not send this extension, the server MUST continue 647 to attempt translation to UTF-8. When a client sends this extension, 648 the server MUST enable filename translation if 'do-translate' is 649 true, or disable filename translation if it is false. 651 The server MUST respond with a STATUS response; if the server sent a 652 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, 653 the status MUST be SSH_FX_OP_UNSUPPORTED. 655 When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE 656 data MUST be used. The server is responsible for converting the 657 UNICODE data to whatever canonical form it requires. For example, if 658 the server requires that precomposed characters always be used, the 659 server MUST NOT assume the filename as sent by the client has this 660 attribute, but must do this normalization itself. 662 7. File Attributes 663 A new compound data type, 'ATTRS', is defined for encoding file 664 attributes. The same encoding is used both when returning file 665 attributes from the server and when sending file attributes to the 666 server. 668 uint32 valid-attribute-flags 669 byte type always present 670 uint64 size if flag SIZE 671 uint64 allocation-size if flag ALLOCATION_SIZE 672 string owner if flag OWNERGROUP 673 string group if flag OWNERGROUP 674 uint32 permissions if flag PERMISSIONS 675 int64 atime if flag ACCESSTIME 676 uint32 atime-nseconds if flag SUBSECOND_TIMES 677 int64 createtime if flag CREATETIME 678 uint32 createtime-nseconds if flag SUBSECOND_TIMES 679 int64 mtime if flag MODIFYTIME 680 uint32 mtime-nseconds if flag SUBSECOND_TIMES 681 int64 ctime if flag CTIME 682 uint32 ctime-nseconds if flag SUBSECOND_TIMES 683 string acl if flag ACL 684 uint32 attrib-bits if flag BITS 685 uint32 attrib-bits-valid if flag BITS 686 byte text-hint if flag TEXT_HINT 687 string mime-type if flag MIME_TYPE 688 uint32 link-count if flag LINK_COUNT 689 string untranslated-name if flag UNTRANSLATED_NAME 690 uint32 extended-count if flag EXTENDED 691 extended-pair extensions 693 7.1. valid-attribute-flags 695 The 'valid-attribute-flags' specifies which of the fields are 696 present. Those fields for which the corresponding flag is not set 697 are not present (not included in the packet). 699 The server generally includes all attributes it knows about; however, 700 it may exclude attributes that are overly expensive to retrieve 701 unless the client explicitly requests them. 703 When writing attributes, the server SHOULD NOT modify attributes that 704 are not present in the structure. However, if necessary, the server 705 MAY use a default value for an absent attribute. 707 In general, unless otherwise specified, if a server cannot support 708 writing an attribute requested, it must fail the setstat operation. 709 In this case, none of the attributes SHOULD be changed. 711 New fields can only be added by incrementing the protocol version 712 number (or by using the extension mechanism described below). 714 The following values are defined: 716 SSH_FILEXFER_ATTR_SIZE 0x00000001 717 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 718 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 719 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 720 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 721 SSH_FILEXFER_ATTR_ACL 0x00000040 722 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 723 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 724 SSH_FILEXFER_ATTR_BITS 0x00000200 725 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 726 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 727 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 728 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 729 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 730 SSH_FILEXFER_ATTR_CTIME 0x00008000 731 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 733 0x00000002 was used in a previous version of this protocol. It is 734 now a reserved value and MUST NOT appear in the mask. Some future 735 version of this protocol may reuse this value. 737 7.2. Type 739 The type field is always present. The following types are defined: 741 SSH_FILEXFER_TYPE_REGULAR 1 742 SSH_FILEXFER_TYPE_DIRECTORY 2 743 SSH_FILEXFER_TYPE_SYMLINK 3 744 SSH_FILEXFER_TYPE_SPECIAL 4 745 SSH_FILEXFER_TYPE_UNKNOWN 5 746 SSH_FILEXFER_TYPE_SOCKET 6 747 SSH_FILEXFER_TYPE_CHAR_DEVICE 7 748 SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 749 SSH_FILEXFER_TYPE_FIFO 9 751 On a POSIX system, these values would be derived from the mode field 752 of the stat structure. SPECIAL should be used for files that are of 753 a known type which cannot be expressed in the protocol. UNKNOWN 754 should be used if the type is not known. 756 7.3. Size 758 The 'size' field specifies the number of bytes that can be read from 759 the file, or in other words, the location of the end-of-file. This 760 attribute MUST NOT be present during file creation. 762 If this field is present during a setstat operation, the file MUST be 763 extended or truncated to the specified size. 765 Files opened with the SSH_FXF_ACCESS_TEXT flag may have a size that 766 is greater or less than the value of the size field. The server MAY 767 fail setstat operations specifying size for files opened with the 768 SSH_FXF_ACCESS_TEXT flag. 770 7.4. allocation-size 772 The 'allocation-size' field specifies the number of bytes that the 773 file consumes on disk. This field MAY be less than the 'size' field 774 if the file is 'sparse' (Section 7.9). 776 When present during file creation, the file SHOULD be created and the 777 specified number of bytes preallocated. If the preallocation fails, 778 the file should be removed (if it was created) and an error returned. 780 If this field is present during a setstat operation, the file SHOULD 781 be extended or truncated to the specified size. The 'size' of the 782 file may be affected by this operation. If the operation succeeds, 783 the 'size' should be the minimum of the 'size' before the operation 784 and the new 'allocation-size'. 786 Querying the 'allocation-size' after setting it MUST return a value 787 that is greater-than or equal to the value set, but it MAY not return 788 the precise value set. 790 If both 'size' and 'allocation-size' are set during a setstat 791 operation, and 'allocation-size' is less than 'size', the server MUST 792 return SSH_FX_INVALID_PARAMETER. 794 7.5. Owner and Group 796 The 'owner' and 'group' fields are represented as UTF-8 strings; this 797 is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. 798 The following text is selected quotations from section 5.6. 800 To avoid a representation that is tied to a particular underlying 801 implementation at the client or server, the use of UTF-8 strings has 802 been chosen. The string should be of the form "user@dns_domain". 803 This will allow for a client and server that do not use the same 804 local representation the ability to translate to a common syntax that 805 can be interpreted by both. In the case where there is no 806 translation available to the client or server, the attribute value 807 must be constructed without the "@". Therefore, the absence of the @ 808 from the owner or owner_group attribute signifies that no translation 809 was available and the receiver of the attribute should not place any 810 special meaning on the attribute value. Even though the attribute 811 value cannot be translated, it may still be useful. In the case of a 812 client, the attribute string may be used for local display of 813 ownership. 815 user@localhost represents a user in the context of the server. 817 If either the owner or group field is zero length, the field should 818 be considered absent, and no change should be made to that specific 819 field during a modification operation. 821 7.6. Permissions 823 The 'permissions' field contains a bit mask specifying file 824 permissions. These permissions correspond to the st_mode field of 825 the stat structure defined by POSIX [IEEE.1003-1.1996]. 827 This protocol uses the following values for the symbols declared in 828 the POSIX standard. 830 S_IRUSR 0000400 (octal) 831 S_IWUSR 0000200 832 S_IXUSR 0000100 833 S_IRGRP 0000040 834 S_IWGRP 0000020 835 S_IXGRP 0000010 836 S_IROTH 0000004 837 S_IWOTH 0000002 838 S_IXOTH 0000001 839 S_ISUID 0004000 840 S_ISGID 0002000 841 S_ISVTX 0001000 843 Implementations MUST NOT send bits that are not defined. 845 The server SHOULD NOT apply a 'umask' to the mode bits; but should 846 set the mode bits as specified by the client. The client MUST apply 847 an appropriate 'umask' to the mode bits before sending them. 849 7.7. Times 851 The 'atime' field contains the last access time of the file. Many 852 operating systems either don't have this field, only optionally 853 maintain it, or maintain it with less resolution than other fields. 855 The 'mtime' contains the last time the file was written. 857 'createtime' contains the creation time of the file. 859 'ctime' contains the last time the file attributes were changed. The 860 exact meaning of this field depends on the server. 862 All times are represented as seconds from Jan 1, 1970 in UTC. A 863 negative value indicates number of seconds before Jan 1, 1970. In 864 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 865 nseconds field is to be added to the seconds field for the final time 866 representation. For example, if the time to be represented is one- 867 half second before 0 hour January 1, 1970, the seconds field would 868 have a value of negative one (-1) and the nseconds fields would have 869 a value of one-half second (500000000). Values greater than 870 999,999,999 for nseconds are considered invalid. 872 7.8. ACL 874 The 'ACL' field contains an ACL similar to that defined in section 875 5.9 of NFS version 4 Protocol [RFC3010]. 877 uint32 ace-count 879 repeated ace-count times: 880 uint32 ace-type 881 uint32 ace-flag 882 uint32 ace-mask 883 string who [UTF-8] 885 ace-type is one of the following four values (taken from NFS Version 886 4 Protocol [RFC3010]: 888 ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 889 ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 890 ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 891 ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 893 ace-flag is a combination of the following flag values. See NFS 894 Version 4 Protocol [RFC3010] section 5.9.2: 896 ACE4_FILE_INHERIT_ACE 0x00000001 897 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 898 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 899 ACE4_INHERIT_ONLY_ACE 0x00000008 900 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 901 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 902 ACE4_IDENTIFIER_GROUP 0x00000040 904 ace-mask is any combination of the following flags (taken from 905 [RFC3010], section 5.9.3. The semantic meaning of these flags is 906 also given in [RFC3010]. 908 ACE4_READ_DATA 0x00000001 909 ACE4_LIST_DIRECTORY 0x00000001 910 ACE4_WRITE_DATA 0x00000002 911 ACE4_ADD_FILE 0x00000002 912 ACE4_APPEND_DATA 0x00000004 913 ACE4_ADD_SUBDIRECTORY 0x00000004 914 ACE4_READ_NAMED_ATTRS 0x00000008 915 ACE4_WRITE_NAMED_ATTRS 0x00000010 916 ACE4_EXECUTE 0x00000020 917 ACE4_DELETE_CHILD 0x00000040 918 ACE4_READ_ATTRIBUTES 0x00000080 919 ACE4_WRITE_ATTRIBUTES 0x00000100 920 ACE4_DELETE 0x00010000 921 ACE4_READ_ACL 0x00020000 922 ACE4_WRITE_ACL 0x00040000 923 ACE4_WRITE_OWNER 0x00080000 924 ACE4_SYNCHRONIZE 0x00100000 926 who is a UTF-8 string of the form described in 'Owner and Group' 927 (Section 7.5) 929 Also, as per '5.9.4 ACE who' [RFC3010] there are several identifiers 930 that need to be understood universally. Some of these identifiers 931 cannot be understood when an client access the server, but have 932 meaning when a local process accesses the file. The ability to 933 display and modify these permissions is permitted over SFTP. 935 OWNER The owner of the file. 936 GROUP The group associated with the file. 937 EVERYONE The world. 938 INTERACTIVE Accessed from an interactive terminal. 939 NETWORK Accessed via the network. 940 DIALUP Accessed as a dialup user to the server. 941 BATCH Accessed from a batch job. 942 ANONYMOUS Accessed without any authentication. 943 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 944 SERVICE Access from a system service. 946 To avoid conflict, these special identifiers are distinguish by an 947 appended "@". For example: ANONYMOUS@. 949 7.9. attrib-bits and attrib-bits-valid 951 These fields, taken together, reflect various attributes of the file 952 or directory, on the server. 954 Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- 955 bits' field. This allows both the server and the client to 956 communicate only the bits it knows about without inadvertently 957 twiddling bits they don't understand. 959 The following attrib-bits are defined: 961 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 962 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 963 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 964 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 965 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 966 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 967 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 968 SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 969 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 970 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 971 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 972 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 974 SSH_FILEXFER_ATTR_FLAGS_READONLY 975 Advisory, read-only bit. This bit is not part of the access 976 control information on the file, but is rather an advisory field 977 indicating that the file should not be written. 979 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 980 The file is part of the operating system. 982 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 983 File SHOULD NOT be shown to user unless specifically requested. 984 For example, most UNIX systems SHOULD set this bit if the filename 985 begins with a 'period'. This bit may be read-only (Section 5.4). 986 Most UNIX systems will not allow this to be changed. 988 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 989 This attribute applies only to directories. This attribute is 990 always read-only, and cannot be modified. This attribute means 991 that files and directory names in this directory should be 992 compared without regard to case. 994 It is recommended that where possible, the server's filesystem be 995 allowed to do comparisons. For example, if a client wished to 996 prompt a user before overwriting a file, it should not compare the 997 new name with the previously retrieved list of names in the 998 directory. Rather, it should first try to create the new file by 999 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 1000 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 1001 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 1003 Unless otherwise specified, filenames are assumed to be case 1004 sensitive. 1006 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 1007 The file should be included in backup / archive operations. 1009 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 1010 The file is stored on disk using file-system level transparent 1011 encryption. This flag does not affect the file data on the wire 1012 (for either READ or WRITE requests.) 1014 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 1015 The file is stored on disk using file-system level transparent 1016 compression. This flag does not affect the file data on the wire. 1018 SSH_FILEXFER_ATTR_FLAGS_SPARSE 1019 The file is a sparse file; this means that file blocks that have 1020 not been explicitly written are not stored on disk. For example, 1021 if a client writes a buffer at 10 M from the beginning of the 1022 file, the blocks between the previous EOF marker and the 10 M 1023 offset would not consume physical disk space. 1025 Some servers may store all files as sparse files, in which case 1026 this bit will be unconditionally set. Other servers may not have 1027 a mechanism for determining if the file is sparse, and so the file 1028 MAY be stored sparse even if this flag is not set. 1030 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 1031 Opening the file without either the SSH_FXF_ACCESS_APPEND_DATA or 1032 the SSH_FXF_ACCESS_APPEND_DATA_ATOMIC flag (Section 8.1.1.3) MUST 1033 result in an SSH_FX_INVALID_PARAMETER error. 1035 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 1036 The file cannot be deleted or renamed, no hard link can be created 1037 to this file, and no data can be written to the file. 1039 This bit implies a stronger level of protection than 1040 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 1041 ACLs. Typically even the superuser cannot write to immutable 1042 files, and only the superuser can set or remove the bit. 1044 SSH_FILEXFER_ATTR_FLAGS_SYNC 1045 When the file is modified, the changes are written synchronously 1046 to the disk. 1048 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 1049 The server MAY include this bit in a directory listing or realpath 1050 response. It indicates there was a failure in the translation to 1051 UTF-8. If this flag is included, the server SHOULD also include 1052 the UNTRANSLATED_NAME attribute. 1054 7.10. text-hint 1056 The value is one of the following enumerations, and indicates what 1057 the server knows about the content of the file. 1059 SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 1060 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 1061 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 1062 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 1064 SSH_FILEXFER_ATTR_KNOWN_TEXT 1065 The server knows the file is a text file, and should be opened 1066 using the SSH_FXF_ACCESS_TEXT_MODE flag. 1068 SSH_FILEXFER_ATTR_GUESSED_TEXT 1069 The server has applied a heuristic or other mechanism and believes 1070 that the file should be opened with the SSH_FXF_ACCESS_TEXT_MODE 1071 flag. 1073 SSH_FILEXFER_ATTR_KNOWN_BINARY 1074 The server knows the file has binary content. 1076 SSH_FILEXFER_ATTR_GUESSED_BINARY 1077 The server has applied a heuristic or other mechanism and believes 1078 has binary content, and should not be opened with the 1079 SSH_FXF_ACCESS_TEXT_MODE flag. 1081 This flag MUST NOT be present during either a setstat or a fsetstat 1082 operation. 1084 7.11. mime-type 1086 The 'mime-type' field contains the mime-type [RFC1521] string. Most 1087 servers will not know this information and should not set the bit in 1088 their supported-attribute-mask. 1090 7.12. link-count 1092 This field contains the hard link count of the file. This attribute 1093 MUST NOT be present during a setstat operation. 1095 7.13. untranslated-name 1097 This field contains the name before filename translation was attempt. 1098 It MUST NOT be included unless the server also set the 1099 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 7.9) bit in the 1100 attrib-bits field. 1102 7.14. Extended Attributes 1104 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 1105 mechanism for the attrib structure. If the flag is specified, then 1106 the 'extended_count' field is present. It specifies the number of 1107 'extension-pair' items that follow. Each of these items specifies an 1108 extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED 1109 if there are any unrecognized extensions. Clients can avoid sending 1110 unsupported extensions by examining the attrib-extension-names of the 1111 "supported2" extension attrib-extension-names (Section 5.4). 1113 Additional fields can be added to the attributes by either defining 1114 additional bits to the flags field to indicate their presence, or by 1115 defining extended attributes for them. The extended attributes 1116 mechanism is recommended for most purposes; additional flags bits 1117 should be defined only by an IETF standards action that also 1118 increments the protocol version number. The use of such new fields 1119 MUST be negotiated by the version number in the protocol exchange. 1120 It is a protocol error if a packet with unsupported protocol bits is 1121 received. 1123 8. Requests From the Client to the Server 1125 Requests from the client to the server represent the various file 1126 system operations. 1128 8.1. Opening and Closing Files and Directories 1130 Many operations in the protocol operate on open files. The 1131 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 1132 an opaque, variable-length string) which may be used to access the 1133 file or directory later. The client MUST NOT send requests to the 1134 server with bogus or closed handles. However, the server MUST 1135 perform adequate checks on the handle in order to avoid security 1136 risks due to fabricated handles. 1138 This design allows either stateful and stateless server 1139 implementation, as well as an implementation which caches state 1140 between requests but may also flush it. The contents of the file 1141 handle string are entirely up to the server and its design. The 1142 client should not modify or attempt to interpret the file handle 1143 strings. 1145 The file handle strings MUST NOT be longer than 256 bytes. 1147 8.1.1. Opening a File 1149 Files are opened and created using the SSH_FXP_OPEN message. 1151 byte SSH_FXP_OPEN 1152 uint32 request-id 1153 string filename [UTF-8] 1154 uint32 desired-access 1155 uint32 flags 1156 ATTRS attrs 1158 The response to this message will be either SSH_FXP_HANDLE (if the 1159 operation is successful) or SSH_FXP_STATUS (if the operation fails.) 1161 8.1.1.1. filename 1163 The 'filename' field specifies the file name. See Section ''File 1164 Names'' for more information. If 'filename' is a directory file, the 1165 server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 1167 8.1.1.2. desired-access 1169 The 'desired-access' field is a bitmask containing a combination of 1170 values from the ace-mask flags (Section 7.8). Note that again, the 1171 meaning of these flags is given in [RFC3010]. 1173 The server MUST be prepared to translate the SFTP access flags into 1174 its local equivalents. If the server cannot grant the access 1175 desired, it MUST return SSH_FX_PERMISSION_DENIED. 1177 The server MAY open the file with greater access than requested if 1178 the user has such access and the server implementation requires it. 1179 For example, a server that does not distinguish between 1180 READ_ATTRIBUTE and READ_DATA will have to request full 'read' access 1181 to the file when the client only requested READ_ATTRIBUTE, resulting 1182 in greater access than the client originally requested. 1184 In such cases, it is possible, and permissible in the protocol, that 1185 the client could open a file requesting some limited access, and then 1186 access the file in a way not permitted by that limited access and the 1187 server would permit such action. However, the server MUST NOT ever 1188 grant access to the file that the client does not actually have the 1189 rights to. 1191 8.1.1.3. flags 1193 The 'flags' field controls various aspects of the operation, 1194 including whether or not the file is created and the kind of locking 1195 desired. 1197 The following 'flags' are defined: 1199 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 1200 SSH_FXF_CREATE_NEW = 0x00000000 1201 SSH_FXF_CREATE_TRUNCATE = 0x00000001 1202 SSH_FXF_OPEN_EXISTING = 0x00000002 1203 SSH_FXF_OPEN_OR_CREATE = 0x00000003 1204 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 1205 SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 1206 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 1207 SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 1208 SSH_FXF_ACCESS_BLOCK_READ = 0x00000040 1209 SSH_FXF_ACCESS_BLOCK_WRITE = 0x00000080 1210 SSH_FXF_ACCESS_BLOCK_DELETE = 0x00000100 1211 SSH_FXF_ACCESS_BLOCK_ADVISORY = 0x00000200 1212 SSH_FXF_ACCESS_NOFOLLOW = 0x00000400 1213 SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000800 1215 SSH_FXF_ACCESS_DISPOSITION 1216 Disposition is a 3 bit field that controls how the file is opened. 1217 The server MUST support these bits. Any one of the following 1218 enumeration is allowed: 1220 SSH_FXF_CREATE_NEW 1221 A new file is created; if the file already exists, the server 1222 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 1224 SSH_FXF_CREATE_TRUNCATE 1225 A new file is created; if the file already exists, it is opened 1226 and truncated. 1228 SSH_FXF_OPEN_EXISTING 1229 An existing file is opened. If the file does not exist, the 1230 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 1231 path does not exist, the server SHOULD return 1232 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 1233 returns SSH_FX_NO_SUCH_FILE in this case. 1235 SSH_FXF_OPEN_OR_CREATE 1236 If the file exists, it is opened. If the file does not exist, 1237 it is created. 1239 SSH_FXF_TRUNCATE_EXISTING 1240 An existing file is opened and truncated. If the file does not 1241 exist, the server MUST return the same error codes as defined 1242 for SSH_FXF_OPEN_EXISTING. 1244 SSH_FXF_ACCESS_APPEND_DATA 1245 Data is always written at the end of the file. The offset field 1246 of the SSH_FXP_WRITE requests are ignored. 1248 Data is not required to be appended atomically. This means that 1249 if multiple writers attempt to append data simultaneously, data 1250 from the first may be lost. However, data MAY be appended 1251 atomically. 1253 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1254 Data is always written at the end of the file. The offset field 1255 of the SSH_FXP_WRITE requests are ignored. 1257 Data MUST be written atomically so that there is no chance that 1258 multiple appenders can collide and result in data being lost. 1260 If both append flags are specified, the server SHOULD use atomic 1261 append if it is available, but SHOULD use non-atomic appends 1262 otherwise. The server SHOULD NOT fail the request in this case. 1264 SSH_FXF_ACCESS_TEXT_MODE 1265 Indicates that the server should treat the file as text and 1266 convert it to the canonical newline convention in use. (See 1267 Determining Server Newline Convention. (Section 5.3) 1269 When a file is opened with this flag, the offset field in the read 1270 and write functions is ignored. 1272 Servers MUST process multiple, parallel reads and writes correctly 1273 in this mode. Naturally, it is permissible for them to do this by 1274 serializing the requests. 1276 Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append 1277 data to a text file rather then using write with a calculated 1278 offset. 1280 To support seeks on text files the following SSH_FXP_EXTENDED 1281 packet is defined. 1283 string "text-seek" 1284 string file-handle 1285 uint64 line-number 1287 line-number is the index of the line number to seek to, where byte 1288 0 in the file is line number 0, and the byte directly following 1289 the first newline sequence in the file is line number 1 and so on. 1291 The response to a "text-seek" request is an SSH_FXP_STATUS 1292 message. 1294 An attempt to seek past the end-of-file should result in a 1295 SSH_FX_EOF status. 1297 Servers SHOULD support at least one "text-seek" in order to 1298 support resume. However, a client MUST be prepared to receive 1299 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 1300 The client can then try a fall-back strategy, if it has one. 1302 SSH_FXF_ACCESS_BLOCK_READ 1303 The server MUST guarantee that no other handle has been opened 1304 with ACE4_READ_DATA access, and that no other handle will be 1305 opened with ACE4_READ_DATA access until the client closes the 1306 handle. (This MUST apply both to other clients and to other 1307 processes on the server.) 1309 If there is a conflicting lock the server MUST return 1310 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1311 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1313 Other handles MAY be opened for ACE4_WRITE_DATA or any other 1314 combination of accesses, as long as ACE4_READ_DATA is not included 1315 in the mask. 1317 SSH_FXF_ACCESS_BLOCK_WRITE 1318 The server MUST guarantee that no other handle has been opened 1319 with ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other 1320 handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA 1321 access until the client closes the handle. (This MUST apply both 1322 to other clients and to other processes on the server.) 1323 If there is a conflicting lock the server MUST return 1324 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1325 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1327 Other handles MAY be opened for ACE4_READ_DATA or any other 1328 combination of accesses, as long as neither ACE4_WRITE_DATA nor 1329 ACE4_APPEND_DATA are included in the mask. 1331 SSH_FXF_ACCESS_BLOCK_DELETE 1332 The server MUST guarantee that no other handle has been opened 1333 with ACE4_DELETE access, opened with the 1334 SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that no other handle 1335 will be opened with ACE4_DELETE access or with the 1336 SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that the file itself 1337 is not deleted in any other way until the client closes the 1338 handle. 1340 If there is a conflicting lock the server MUST return 1341 SSH_FX_LOCK_CONFLICT. If the server cannot make the locking 1342 guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. 1344 SSH_FXF_ACCESS_BLOCK_ADVISORY 1345 If this bit is set, the above BLOCK modes are advisory. In 1346 advisory mode, only other accesses that specify a BLOCK mode need 1347 be considered when determining whether the BLOCK can be granted, 1348 and the server need not prevent I/O operations that violate the 1349 block mode. 1351 The server MAY perform mandatory locking even if the 1352 BLOCK_ADVISORY bit is set. 1354 SSH_FXF_ACCESS_NOFOLLOW 1355 If the final component of the path is a symlink, then the open 1356 MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. 1358 SSH_FXF_ACCESS_DELETE_ON_CLOSE 1359 The file should be deleted when the last handle to it is closed. 1360 (The last handle may not be an sftp-handle.) This MAY be emulated 1361 by a server if the OS doesn't support it by deleting the file when 1362 this handle is closed. 1364 It is implementation specific whether the directory entry is 1365 removed immediately or when the handle is closed. 1367 The 'attrs' field specifies the initial attributes for the file. 1368 Default values MUST be supplied by the server for those attributes 1369 that are not specified. See Section ''File Attributes'' for more 1370 information. 1372 The 'attrs' field is ignored if an existing file is opened. 1374 The following table is provided to assist in mapping POSIX semantics 1375 to equivalent SFTP file open parameters: 1376 O_RDONLY 1377 desired-access = READ_DATA|READ_ATTRIBUTES 1379 O_WRONLY 1380 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1382 O_RDWR 1383 desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA| 1384 WRITE_ATTRIBUTES 1386 O_APPEND 1387 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1388 flags = SSH_FXF_ACCESS_APPEND_DATA and or 1389 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1391 O_CREAT 1392 flags = SSH_FXF_OPEN_OR_CREATE 1394 O_TRUNC 1395 flags = SSH_FXF_TRUNCATE_EXISTING 1397 O_TRUNC|O_CREATE 1398 flags = SSH_FXF_CREATE_TRUNCATE 1400 8.1.2. Opening a Directory 1402 To enumerate a directory, the client first obtains a handle and then 1403 issues directory read requests. When enumeration is complete, the 1404 handle MUST be closed. 1406 byte SSH_FXP_OPENDIR 1407 uint32 request-id 1408 string path [UTF-8] 1410 path 1411 The 'path' field is the path name of the directory to be listed 1412 (without any trailing slash). See Section 'File Names' for more 1413 information on file names. 1415 If 'path' does not refer to a directory, the server MUST return 1416 SSH_FX_NOT_A_DIRECTORY. 1418 The response to this message will be either SSH_FXP_HANDLE (if the 1419 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1421 8.1.3. Closing Handles 1423 A handle is closed using the following request. 1425 byte SSH_FXP_CLOSE 1426 uint32 request-id 1427 string handle 1429 handle 1430 'handle' is a handle previously returned in the response to 1431 SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid 1432 immediately after this request has been sent. 1434 The response to this request will be a SSH_FXP_STATUS message. Note 1435 that on some server platforms even a close can fail. For example, if 1436 the server operating system caches writes, and an error occurs while 1437 flushing cached writes, the close operation may fail. 1439 Note that the handle is invalid regardless of the SSH_FXP_STATUS 1440 result. There is no way for the client to recover a handle that 1441 fails to close. The client MUST release all resources associated 1442 with the handle regardless of the status. The server SHOULD take 1443 whatever steps it can to recover from a close failure and to ensure 1444 that all resources associated with the handle on the server are 1445 correctly released. 1447 8.2. Reading and Writing 1449 8.2.1. Reading Files 1451 The following request can be used to read file data: 1453 byte SSH_FXP_READ 1454 uint32 request-id 1455 string handle 1456 uint64 offset 1457 uint32 length 1459 handle 1460 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1461 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1462 return SSH_FX_INVALID_HANDLE. 1464 offset 1465 The offset (in bytes) relative to the beginning of the file that 1466 the read MUST start at. This field is ignored if 1467 SSH_FXF_ACCESS_TEXT_MODE was specified during the open. 1469 length 1470 'length' is the maximum number of bytes to read. 1472 The server MUST not respond with more data than is specified by 1473 the 'length' parameter. However, the server MAY respond with less 1474 data if EOF is reached, an error is encountered, or the servers 1475 internal buffers can not handle such a large request. 1477 If the server specified a non-zero 'max-read-size' in its 1478 'supported2' (Section 5.4) extension, then failure to return 1479 'length' bytes indicates that EOF or an error occurred. 1481 8.2.2. Reading Directories 1483 In order to retrieve a directory listing, the client issues one or 1484 more SSH_FXP_READDIR requests. In order to obtain a complete 1485 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1486 requests until the server responds with an SSH_FXP_STATUS message. 1488 byte SSH_FXP_READDIR 1489 uint32 request-id 1490 string handle 1492 handle 1493 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is 1494 an ordinary file handle returned by SSH_FXP_OPEN, the server MUST 1495 return SSH_FX_INVALID_HANDLE. 1497 The server responds to this request with either a SSH_FXP_NAME or a 1498 SSH_FXP_STATUS message. One or more names may be returned at a time. 1499 Full status information is returned for each name in order to speed 1500 up typical directory listings. 1502 If there are no more names available to be read, the server MUST 1503 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1505 8.2.3. Writing Files 1507 Writing to a file is achieved using the following message: 1509 byte SSH_FXP_WRITE 1510 uint32 request-id 1511 string handle 1512 uint64 offset 1513 string data 1515 handle 1516 'handle' is an open file handle returned by SSH_FXP_OPEN. If 1517 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST 1518 return SSH_FX_INVALID_HANDLE. 1520 offset 1521 The offset (in bytes) relative to the beginning of the file that 1522 the write MUST start at. This field is ignored if 1523 SSH_FXF_ACCESS_TEXT_MODE was specified during the open. 1525 The write will extend the file if writing beyond the end of the 1526 file. It is legal to write to an offset that extends beyond the 1527 end of the file; the semantics are to write the byte value 0x00 1528 from the end of the file to the specified offset and then the 1529 data. On most operating systems, such writes do not allocate disk 1530 space but instead create a sparse file. 1532 data 1533 The data to write to the file. 1535 The server responds to a write request with a SSH_FXP_STATUS message. 1537 8.3. Removing and Renaming Files 1539 The following request can be used to remove a file: 1541 byte SSH_FXP_REMOVE 1542 uint32 request-id 1543 string filename [UTF-8] 1545 filename 1546 'filename' is the name of the file to be removed. See Section 1547 'File Names' for more information. 1549 This request cannot be used to remove directories. The server 1550 MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. 1552 The server will respond to this request with a SSH_FXP_STATUS 1553 message. 1555 Files (and directories) can be renamed using the SSH_FXP_RENAME 1556 message. 1558 byte SSH_FXP_RENAME 1559 uint32 request-id 1560 string oldpath [UTF-8] 1561 string newpath [UTF-8] 1562 uint32 flags 1564 where 'request-id' is the request identifier, 'oldpath' is the name 1565 of an existing file or directory, and 'newpath' is the new name for 1566 the file or directory. 1568 'flags' is 0 or a combination of: 1570 SSH_FXF_RENAME_OVERWRITE 0x00000001 1571 SSH_FXF_RENAME_ATOMIC 0x00000002 1572 SSH_FXF_RENAME_NATIVE 0x00000004 1574 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1575 exists a file with the name specified by newpath, the server MUST 1576 respond with SSH_FX_FILE_ALREADY_EXISTS. 1578 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1579 already exists, it is replaced in an atomic fashion. I.e., there is 1580 no observable instant in time where the name does not refer to either 1581 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1582 SSH_FXP_RENAME_OVERWRITE. 1584 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace 1585 the destination in an atomic fashion, then the server MUST respond 1586 with SSH_FX_OP_UNSUPPORTED. 1588 Because some servers cannot provide atomic rename, clients should 1589 only specify atomic rename if correct operation requires it. If 1590 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1591 atomic rename even if it is not requested. 1593 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1594 rename operation in whatever fashion it deems appropriate. Other 1595 flag values are considered hints as to desired behavior, but not 1596 requirements. 1598 The server will respond to this request with a SSH_FXP_STATUS 1599 message. 1601 8.4. Creating and Deleting Directories 1603 New directories can be created using the SSH_FXP_MKDIR request. It 1604 has the following format: 1606 byte SSH_FXP_MKDIR 1607 uint32 request-id 1608 string path [UTF-8] 1609 ATTRS attrs 1611 where 'request-id' is the request identifier. 1613 'path' specifies the directory to be created. See Section ''File 1614 Names'' for more information on file names. 1616 'attrs' specifies the attributes that should be applied to it upon 1617 creation. Attributes are discussed in more detail in Section ''File 1618 Attributes''. 1620 The server will respond to this request with a SSH_FXP_STATUS 1621 message. If a file or directory with the specified path already 1622 exists, an error will be returned. 1624 Directories can be removed using the SSH_FXP_RMDIR request, which has 1625 the following format: 1627 byte SSH_FXP_RMDIR 1628 uint32 request-id 1629 string path [UTF-8] 1631 where 'request-id' is the request identifier, and 'path' specifies 1632 the directory to be removed. See Section ''File Names'' for more 1633 information on file names. 1635 The server responds to this request with a SSH_FXP_STATUS message. 1637 8.5. Retrieving File Attributes 1639 Very often, file attributes are automatically returned by 1640 SSH_FXP_READDIR. However, sometimes there is need to specifically 1641 retrieve the attributes for a named file. This can be done using the 1642 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1644 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1645 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1646 follow symbolic links. Both have the same format: 1648 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1649 uint32 request-id 1650 string path [UTF-8] 1651 uint32 flags 1653 where 'request-id' is the request identifier, and 'path' specifies 1654 the file system object for which status is to be returned. The 1655 server responds to this request with either SSH_FXP_ATTRS or 1656 SSH_FXP_STATUS. 1658 The flags field specify the attribute flags in which the client has 1659 particular interest. This is a hint to the server. For example, 1660 because retrieving owner / group and acl information can be an 1661 expensive operation under some operating systems, the server may 1662 choose not to retrieve this information unless the client expresses a 1663 specific interest in it. 1665 The client has no guarantee the server will provide all the fields 1666 that it has expressed an interest in. 1668 SSH_FXP_FSTAT differs from the others in that it returns status 1669 information for an open file (identified by the file handle). 1671 byte SSH_FXP_FSTAT 1672 uint32 request-id 1673 string handle 1674 uint32 flags 1676 handle 1677 'handle' is an open file handle from either SSH_FXP_OPEN or 1678 SSH_FXP_OPENDIR. 1680 The server responds to this request with SSH_FXP_ATTRS or 1681 SSH_FXP_STATUS. 1683 8.6. Setting File Attributes 1685 File attributes may be modified using the SSH_FXP_SETSTAT and 1686 SSH_FXP_FSETSTAT requests. 1688 byte SSH_FXP_SETSTAT 1689 uint32 request-id 1690 string path [UTF-8] 1691 ATTRS attrs 1693 byte SSH_FXP_FSETSTAT 1694 uint32 request-id 1695 string handle 1696 ATTRS attrs 1698 path 1699 The file system object (e.g. file or directory) whose attributes 1700 are to be modified. If this object does not exist, or the user 1701 does not have sufficient access to write the attributes, the 1702 request MUST fail. 1704 handle 1705 'handle' is an open file handle from either SSH_FXP_OPEN or 1706 SSH_FXP_OPENDIR. If the handle was not opened with sufficient 1707 access to write the requested attributes, the request MUST fail. 1709 attrs 1710 Specifies the modified attributes to be applied. Attributes are 1711 discussed in more detail in Section ''File Attributes''. 1713 The server will respond with a SSH_FXP_STATUS message. 1715 Because some systems must use separate system calls to set various 1716 attributes, it is possible that a failure response will be returned, 1717 but yet some of the attributes may be have been successfully 1718 modified. If possible, servers SHOULD avoid this situation; however, 1719 clients MUST be aware that this is possible. 1721 8.7. Dealing with Links 1723 The SSH_FXP_READLINK request reads the target of a symbolic link. 1725 byte SSH_FXP_READLINK 1726 uint32 request-id 1727 string path [UTF-8] 1729 where 'request-id' is the request identifier and 'path' specifies the 1730 path name of the symlink to be read. 1732 The server will respond with a SSH_FXP_NAME packet containing only 1733 one name and a dummy attributes value. The name in the returned 1734 packet contains the target of the link. If an error occurs, the 1735 server MAY respond with SSH_FXP_STATUS. 1737 The SSH_FXP_LINK request creates a link (either hard or symbolic) on 1738 the server. 1740 byte SSH_FXP_LINK 1741 uint32 request-id 1742 string new-link-path [UTF-8] 1743 string existing-path [UTF-8] 1744 bool sym-link 1746 new-link-path 1747 Specifies the path name of the new link to create. 1749 existing-path 1750 Specifies the path of an existing file system object to which the 1751 new-link-path will refer. 1753 sym-link 1754 Specifies that the link should be a symbolic link, or a special 1755 file that redirects file system parsing to the resulting path. It 1756 is generally possible to create symbolic links across device 1757 boundaries; however, it is not required that a server support 1758 this. 1760 If 'sym-link' is false, the link should be a hard link, or a 1761 second directory entry referring to the same file or directory 1762 object. It is generally not possible to create hard links across 1763 devices. 1765 The server shall respond with a SSH_FXP_STATUS. Clients should be 1766 aware that some servers may return SSH_FX_OP_UNSUPPORTED for either 1767 the hard-link, sym-link, or both operations. 1769 8.8. Byte-range locks 1771 SSH_FXP_BLOCK creates a byte-range lock on the file specified by the 1772 handle. The lock can be either mandatory (meaning that the server 1773 enforces that no other process or client can perform operations in 1774 violation of the lock) or advisory (meaning that no other process can 1775 obtain a conflicting lock, but the server does not enforce that no 1776 operation violates the lock. 1778 A server MAY implement an advisory lock in a mandatory fashion; in 1779 other words, the server MAY enforce that no operation violates the 1780 lock even when operating in advisory mode. 1782 The result is a SSH_FXP_STATUS return. 1784 byte SSH_FXP_BLOCK 1785 uint32 request-id 1786 string handle 1787 uint64 offset 1788 uint64 length 1789 uint32 uLockMask 1791 handle 1792 'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. 1793 Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the 1794 handle is a directory handle. 1796 offset 1797 Beginning of the byte-range to lock. 1799 length 1800 Number of bytes in the range to lock. The special value 0 means 1801 lock from 'offset' to the end of the file. 1803 uLockMask 1804 A bit mask of SSH_FXF_ACCESS_BLOCK_* values; the meanings are 1805 described in Section 8.1.1.3. 1807 SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the 1808 specified handle. 1810 The result is a SSH_FXP_STATUS return. 1812 byte SSH_FXP_UNBLOCK 1813 uint32 request-id 1814 string handle 1815 uint64 offset 1816 uint64 length 1818 handle 1819 'handle' on which a SSH_FXP_BLOCK request has previously been 1820 issued. 1822 offset 1823 Beginning of the byte-range to lock. 1825 length 1826 Number of bytes in the range to lock. The special value 0 means 1827 lock from 'offset' to the end of the file. 1829 8.9. Canonicalizing the Server-Side Path Name 1831 The SSH_FXP_REALPATH request can be used to have the server 1832 canonicalize any given path name to an absolute path. This is useful 1833 for converting path names containing ".." components or relative 1834 pathnames without a leading slash into absolute paths. The format of 1835 the request is as follows: 1837 byte SSH_FXP_REALPATH 1838 uint32 request-id 1839 string original-path [UTF-8] 1840 byte control-byte [optional] 1841 string compose-path[0..n] [optional] 1843 original-path 1844 The first component of the path which the client wishes resolved 1845 into a absolute canonical path. This may be the entire path. 1847 control-byte 1849 SSH_FXP_REALPATH_NO_CHECK 0x00000001 1850 SSH_FXP_REALPATH_STAT_IF 0x00000002 1851 SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 1853 This field is optional, and if it is not present in the packet, it 1854 is assumed to be SSH_FXP_REALPATH_NO_CHECK. 1856 If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT 1857 fail the request if the path does not exist, is hidden, or the 1858 user does not have access to the path or some component thereof. 1859 However, the path MAY NOT be completely resolved to it's component 1860 form. For example, symlinks may not be followed in this case. 1861 The server MAY fail the request if the path is not syntactically 1862 valid, or for other reasons. 1864 If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the 1865 path if it exists and is accessible to the client. However, if 1866 the path does not exist, isn't visible, or isn't accessible, the 1867 server MUST NOT fail the request. If the stat failed, the file 1868 type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to 1869 distinguish between files that are actually 1870 SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will have 1871 to issue a separate stat command in this case. 1873 If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat 1874 the path. If the stat operation fails, the server MUST fail the 1875 request. 1877 compose-path 1878 A path which the client wishes the server to compose with the 1879 original path to form the new path. This field is optional, and 1880 if it is not present in the packet, it is assumed to be a zero 1881 length string. 1883 The client may specify multiple 'compose-path' elements, in which 1884 case the server should build the resultant path up by applying 1885 each compose path to the accumulated result until all 'compose- 1886 path' elements have been applied. 1888 The server MUST take the 'original-path' and apply the 'compose-path' 1889 as a modification to it. 'compose-path' MAY be relative to 'original- 1890 path' or may be an absolute path, in which case 'original-path' will 1891 be discarded. The 'compose-path' MAY be zero length. 1893 The server will respond with a SSH_FXP_NAME packet containing the 1894 canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK 1895 is specified, the attributes are dummy values. 1897 8.9.1. Best Practice for Dealing with Paths 1899 BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING 1901 Previous to this version, clients typically composed new paths 1902 themselves and then called both realpath and stat on the resulting 1903 path to get its canonical name and see if it really existed and was a 1904 directory. 1906 This required clients to assume certain things about how a relative 1907 vs. realpath looked. The new realpath allows clients to no longer 1908 make those assumptions and to remove one round trip from the process 1909 and get deterministic behavior from all servers. 1911 END: RFCEDITOR REMOVE BEFORE PUBLISHING 1913 The client SHOULD treat the results of SSH_FXP_REALPATH as a 1914 canonical absolute path, even if the path does not appear to be 1915 absolute. A client that uses REALPATH(".", "") and treats the result 1916 as absolute, even if there is no leading slash, will continue to 1917 function correctly, even when talking to a Windows NT or VMS style 1918 system, where absolute paths may not begin with a slash. 1920 The client SHOULD also use SSH_FXP_REALPATH call to compose paths so 1921 that it does not need to know when a path is absolute or relative. 1923 For example, if the client wishes to change directory up, and the 1924 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 1925 REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) 1927 As a second example, if the client wishes transfer local file "a" to 1928 remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the 1929 canonical path of the current directory, the client SHOULD send 1930 REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This 1931 call will determine the correct path to use for the open request and 1932 whether the /b/d/e represents a directory. 1934 9. Responses from the Server to the Client 1936 The server responds to the client using one of a few response 1937 packets. All requests can return a SSH_FXP_STATUS response upon 1938 failure. When the operation is successful, and no data needs to be 1939 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 1940 appropriate. 1942 Exactly one response will be returned for each request. Each 1943 response packet contains a request identifier which can be used to 1944 match each response with the corresponding request. Note that it is 1945 legal to have several requests outstanding simultaneously, and the 1946 server is allowed to send responses to them in a different order from 1947 the order in which the requests were sent (the result of their 1948 execution, however, is guaranteed to be as if they had been processed 1949 one at a time in the order in which the requests were sent). 1951 Response packets are of the same general format as request packets. 1952 Each response packet begins with the request identifier. 1954 9.1. Status Response 1956 The format of the data portion of the SSH_FXP_STATUS response is as 1957 follows: 1959 byte SSH_FXP_STATUS 1960 uint32 request-id 1961 uint32 error/status code 1962 string error message (ISO-10646 UTF-8 [RFC-2279]) 1963 string language tag (as defined in [RFC-1766]) 1964 error-specific data 1966 request-id 1967 The 'request-id' specified by the client in the request the server 1968 is responding to. 1970 error/status code 1971 Machine readable status code indicating the result of the request. 1972 Error code values are defined below. The value SSH_FX_OK 1973 indicates success, and all other values indicate failure. 1975 Implementations MUST be prepared to receive unexpected error codes 1976 and handle them sensibly (such as by treating them as equivalent 1977 to SSH_FX_FAILURE). Future protocol revisions will add additional 1978 error codes without changing the version number. 1980 error message 1981 Human readable description of the error. 1983 language tag 1984 'language tag' specifies the language the error is in. 1986 error-specific data 1987 The error-specific data may be empty, or may contain additional 1988 information about the error. For error codes that send error- 1989 specific data, the format of the data is defined below. 1991 Error codes: 1993 SSH_FX_OK 0 1994 SSH_FX_EOF 1 1995 SSH_FX_NO_SUCH_FILE 2 1996 SSH_FX_PERMISSION_DENIED 3 1997 SSH_FX_FAILURE 4 1998 SSH_FX_BAD_MESSAGE 5 1999 SSH_FX_NO_CONNECTION 6 2000 SSH_FX_CONNECTION_LOST 7 2001 SSH_FX_OP_UNSUPPORTED 8 2002 SSH_FX_INVALID_HANDLE 9 2003 SSH_FX_NO_SUCH_PATH 10 2004 SSH_FX_FILE_ALREADY_EXISTS 11 2005 SSH_FX_WRITE_PROTECT 12 2006 SSH_FX_NO_MEDIA 13 2007 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 2008 SSH_FX_QUOTA_EXCEEDED 15 2009 SSH_FX_UNKNOWN_PRINCIPAL 16 2010 SSH_FX_LOCK_CONFLICT 17 2011 SSH_FX_DIR_NOT_EMPTY 18 2012 SSH_FX_NOT_A_DIRECTORY 19 2013 SSH_FX_INVALID_FILENAME 20 2014 SSH_FX_LINK_LOOP 21 2015 SSH_FX_CANNOT_DELETE 22 2016 SSH_FX_INVALID_PARAMETER 23 2017 SSH_FX_FILE_IS_A_DIRECTORY 24 2018 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 2019 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 2020 SSH_FX_DELETE_PENDING 27 2021 SSH_FX_FILE_CORRUPT 28 2022 SSH_FX_OWNER_INVALID 29 2023 SSH_FX_GROUP_INVALID 30 2025 SSH_FX_OK 2026 Indicates successful completion of the operation. 2028 SSH_FX_EOF 2029 An attempt to read past the end-of-file was made; or, there are no 2030 more directory entries to return. 2032 SSH_FX_NO_SUCH_FILE 2033 A reference was made to a file which does not exist. 2035 SSH_FX_PERMISSION_DENIED 2036 The user does not have sufficient permissions to perform the 2037 operation. 2039 SSH_FX_FAILURE 2040 An error occurred, but no specific error code exists to describe 2041 the failure. 2043 This error message SHOULD always have meaningful text in the the 2044 'error message' field. 2046 SSH_FX_BAD_MESSAGE 2047 A badly formatted packet or other SFTP protocol incompatibility 2048 was detected. 2050 SSH_FX_NO_CONNECTION 2051 There is no connection to the server. This error MAY be used 2052 locally, but MUST NOT be return by a server. 2054 SSH_FX_CONNECTION_LOST 2055 The connection to the server was lost. This error MAY be used 2056 locally, but MUST NOT be return by a server. 2058 SSH_FX_OP_UNSUPPORTED 2059 An attempted operation could not be completed by the server 2060 because the server does not support the operation. 2062 This error MAY be generated locally by the client if e.g. the 2063 version number exchange indicates that a required feature is not 2064 supported by the server, or it may be returned by the server if 2065 the server does not implement an operation. 2067 SSH_FX_INVALID_HANDLE 2068 The handle value was invalid. 2070 SSH_FX_NO_SUCH_PATH 2071 The file path does not exist or is invalid. 2073 SSH_FX_FILE_ALREADY_EXISTS 2074 The file already exists. 2076 SSH_FX_WRITE_PROTECT 2077 The file is on read-only media, or the media is write protected. 2079 SSH_FX_NO_MEDIA 2080 The requested operation cannot be completed because there is no 2081 media available in the drive. 2083 SSH_FX_NO_SPACE_ON_FILESYSTEM 2084 The requested operation cannot be completed because there is no 2085 free space on the filesystem. 2087 SSH_FX_QUOTA_EXCEEDED 2088 The operation cannot be completed because it would exceed the 2089 user's storage quota. 2091 SSH_FX_UNKNOWN_PRINCIPAL 2092 A principal referenced by the request (either the 'owner', 2093 'group', or 'who' field of an ACL), was unknown. The error 2094 specific data contains the problematic names. The format is one 2095 or more: 2097 string unknown-name 2099 Each string contains the name of a principal that was unknown. 2101 SSH_FX_LOCK_CONFLICT 2102 The file could not be opened because it is locked by another 2103 process. 2105 SSH_FX_DIR_NOT_EMPTY 2106 The directory is not empty. 2108 SSH_FX_NOT_A_DIRECTORY 2109 The specified file is not a directory. 2111 SSH_FX_INVALID_FILENAME 2112 The filename is not valid. 2114 SSH_FX_LINK_LOOP 2115 Too many symbolic links encountered. 2117 SSH_FX_CANNOT_DELETE 2118 The file cannot be deleted. One possible reason is that the 2119 advisory READONLY attribute-bit is set. 2121 SSH_FX_INVALID_PARAMETER 2122 On of the parameters was out of range, or the parameters specified 2123 cannot be used together. 2125 SSH_FX_FILE_IS_A_DIRECTORY 2126 The specified file was a directory in a context where a directory 2127 cannot be used. 2129 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 2130 A read or write operation failed because another process's 2131 mandatory byte-range lock overlaps with the request. 2133 SSH_FX_BYTE_RANGE_LOCK_REFUSED 2134 A request for a byte range lock was refused. 2136 SSH_FX_DELETE_PENDING 2137 An operation was attempted on a file for which a delete operation 2138 is pending. 2140 SSH_FX_FILE_CORRUPT 2141 The file is corrupt; an filesystem integrity check should be run. 2143 SSH_FX_OWNER_INVALID 2144 The principal specified can not be assigned as an owner of a file. 2146 SSH_FX_GROUP_INVALID 2147 The principal specified can not be assigned as the primary group 2148 of a file. 2150 9.2. Handle Response 2152 The SSH_FXP_HANDLE response has the following format: 2154 byte SSH_FXP_HANDLE 2155 uint32 request-id 2156 string handle 2158 'handle' 2159 An arbitrary string that identifies an open file or directory on 2160 the server. The handle is opaque to the client; the client MUST 2161 NOT attempt to interpret or modify it in any way. The length of 2162 the handle string MUST NOT exceed 256 data bytes. 2164 9.3. Data Response 2166 The SSH_FXP_DATA response has the following format: 2168 byte SSH_FXP_DATA 2169 uint32 request-id 2170 string data 2171 bool end-of-file [optional] 2173 data 2174 'data' is an arbitrary byte string containing the requested data. 2175 The data string may be at most the number of bytes requested in a 2176 SSH_FXP_READ request, but may also be shorter. (See 2177 Section 8.2.1.) 2179 end-of-file 2180 This field is optional. If it is present in the packet, it MUST 2181 be true, and it indicates that EOF was reached during this read. 2182 This can help the client avoid a round trip to determine whether a 2183 short read was normal (due to EOF) or some other problem (limited 2184 server buffer for example.) 2186 9.4. Name Response 2188 The SSH_FXP_NAME response has the following format: 2190 byte SSH_FXP_NAME 2191 uint32 request-id 2192 uint32 count 2193 repeats count times: 2194 string filename [UTF-8] 2195 ATTRS attrs 2196 bool end-of-list [optional] 2198 count 2199 The number of names returned in this response, and the 'filename' 2200 and 'attrs' field repeat 'count' times. 2202 filename 2203 A file name being returned (for SSH_FXP_READDIR, it will be a 2204 relative name within the directory, without any path components; 2205 for SSH_FXP_REALPATH it will be an absolute path name.) 2207 attrs 2208 The attributes of the file as described in Section ''File 2209 Attributes''. 2211 end-of-list 2212 This field is optional. If present in the packet, it MUST be 2213 true, and indicates that there are no more entries to be read. 2214 This can save the client a round trip to determine if there are 2215 more entries to be read. 2217 9.5. Attrs Response 2219 The SSH_FXP_ATTRS response has the following format: 2221 byte SSH_FXP_ATTRS 2222 uint32 request-id 2223 ATTRS attrs 2225 attrs 2226 The returned file attributes as described in Section ''File 2227 Attributes''. 2229 10. Extensions 2231 The SSH_FXP_EXTENDED request provides a generic extension mechanism 2232 for adding additional commands. 2234 byte SSH_FXP_EXTENDED 2235 uint32 request-id 2236 string extended-request 2237 ... any request-specific data ... 2239 request-id 2240 Identifier to be returned from the server with the response. 2242 extended-request 2243 A string naming the extension, following the the DNS extensibility 2244 naming convention outlined in [I-D.ietf-secsh-architecture], or 2245 defined by IETF consensus. 2247 request-specific data 2248 The rest of the request is defined by the extension; servers 2249 SHOULD NOT attempt to interpret it if they do not recognize the 2250 'extended-request' name. 2252 The server may respond to such requests using any of the response 2253 packets defined in Section ''Responses from the Server to the 2254 Client''. Additionally, the server may also respond with a 2255 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 2256 not recognize the 'extended-request' name, then the server MUST 2257 respond with SSH_FXP_STATUS with error/status set to 2258 SSH_FX_OP_UNSUPPORTED. 2260 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 2261 extension-specific data from the server to the client. It is of the 2262 following format: 2264 byte SSH_FXP_EXTENDED_REPLY 2265 uint32 request-id 2266 ... any request-specific data ... 2268 There is a range of packet types reserved for use by extensions. In 2269 order to avoid collision, extensions that that use additional packet 2270 types should determine those numbers dynamically. 2272 The suggested way of doing this is have an extension request from the 2273 client to the server that enables the extension; the extension 2274 response from the server to the client would specify the actual type 2275 values to use, in addition to any other data. 2277 Extension authors should be mindful of the limited range of packet 2278 types available (there are only 45 values available) and avoid 2279 requiring a new packet type where possible. 2281 11. Implementation Considerations 2283 In order for this protocol to perform well, especially over high 2284 latency networks, multiple read and write requests should be queued 2285 to the server. 2287 The data size of requests should match the maximum packet size for 2288 the next layer up in the protocol chain. 2290 When implemented over ssh, the best performance should be achieved 2291 when the data size matches the channel's max packet, and the channel 2292 window is a multiple of the channel packet size. 2294 Implementations MUST be aware that requests do not have to be 2295 satisfied in the order issued. (See Request Synchronization and 2296 Reordering (Section 4.1).) 2298 Implementations MUST also be aware that read requests may not return 2299 all the requested data, even if the data is available. 2301 12. Security Considerations 2303 It is assumed that both ends of the connection have been 2304 authenticated and that the connection has privacy and integrity 2305 features. Such security issues are left to the underlying transport 2306 protocol, except to note that if this is not the case, an attacker 2307 could manipulate files on the server at will and thus wholly 2308 compromise the server. 2310 This protocol provides file system access to arbitrary files on the 2311 server (constrained only by the server implementation). It is the 2312 responsibility of the server implementation to enforce any access 2313 controls that may be required to limit the access allowed for any 2314 particular user (the user being authenticated externally to this 2315 protocol, typically using [I-D.ietf-secsh-userauth]. 2317 Extreme care must be used when interpreting file handle strings. In 2318 particular, care must be taken that a file handle string is valid in 2319 the context of a given 'file-share' session. For example, the 'file- 2320 share' server daemon may have files which it has opened for its own 2321 purposes, and the client must not be able to access these files by 2322 specifying an arbitrary file handle string. 2324 The permission field of the attrib structure (Section 7.6) may 2325 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 2326 extreme caution when setting these bits on either remote or local 2327 files. (I.e., just because a file was SUID on the remote system does 2328 not necessarily imply that it should be SUID on the local system.) 2330 Filesystems often contain entries for objects that are not files at 2331 all, but are rather devices. For example, it may be possible to 2332 access serial ports, tape devices, or named pipes using this 2333 protocol. Servers should exercise caution when granting access to 2334 such resources. In addition to the dangers inherent in allowing 2335 access to such a device, some devices may be 'slow', and could cause 2336 denial of service by causing the server to block for a long period of 2337 time while I/O is performed to such a device. 2339 Servers should take care that file-system quotas are respected for 2340 users. In addition, implementations should be aware that attacks may 2341 be possible, or facilitated, by filling a filesystem. For example, 2342 filling the filesystem where event logging and auditing occurs may, 2343 at best, cause the system to crash, or at worst, allow the attacker 2344 to take untraceable actions in the future. 2346 Servers should take care that filenames are in their appropriate 2347 canonical form, and to ensure that filenames not in canonical form 2348 cannot be used to bypass access checks or controls. 2350 If the server implementation limits access to certain parts of the 2351 file system, extra care must be taken in parsing file names which 2352 contain the '..' path element, and when following symbolic links, 2353 shortcuts, or other filesystem objects which might transpose the path 2354 to refer to an object outside of the restricted area. There have 2355 been numerous reported security bugs where a ".." in a path name has 2356 allowed access outside the intended area. 2358 13. Changes from Previous Protocol Versions 2360 RFC EDITOR: PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2362 Please refer to the following web page for pervious versions of the 2363 protocol: 2365 http://tools.ietf.org/wg/secsh/draft-ietf-secsh-filexfer/ 2367 RFC EDITOR: END PLEASE REMOVE ENTIRE SECTION BEFORE PUBLISHING 2369 14. References 2371 14.1. Normative References 2373 [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., 2374 Beame, C., Eisler, M., and D. Noveck, "NFS version 4 2375 Protocol", RFC 3010, December 2000. 2377 [I-D.ietf-secsh-architecture] 2378 Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", 2379 draft-ietf-secsh-architecture-22 (work in progress), 2380 March 2005. 2382 [I-D.ietf-secsh-transport] 2383 Lonvick, C., "SSH Transport Layer Protocol", 2384 draft-ietf-secsh-transport-24 (work in progress), 2385 March 2005. 2387 [I-D.ietf-secsh-connect] 2388 Lonvick, C. and T. Ylonen, "SSH Connection Protocol", 2389 draft-ietf-secsh-connect-25 (work in progress), 2390 March 2005. 2392 [IEEE.1003-1.1996] 2393 Institute of Electrical and Electronics Engineers, 2394 "Information Technology - Portable Operating System 2395 Interface (POSIX) - Part 1: System Application Program 2396 Interface (API) [C Language]", IEEE Standard 1003.2, 1996. 2398 14.2. Informative References 2400 [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet 2401 Mail Extensions) Part One: Mechanisms for Specifying and 2402 Describing the Format of Internet Message Bodies", 2403 RFC 1521, September 1993. 2405 [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", 2406 RFC 2246, January 1999. 2408 [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and 2409 Languages", BCP 18, RFC 2277, January 1998. 2411 [I-D.ietf-secsh-userauth] 2412 Lonvick, C. and T. Ylonen, "SSH Authentication Protocol", 2413 draft-ietf-secsh-userauth-27 (work in progress), 2414 March 2005. 2416 Trademark notice 2418 "ssh" is a registered trademark in the United States and/or other 2419 countries. 2421 Authors' Addresses 2423 Joseph Galbraith 2424 VanDyke Software 2425 4848 Tramway Ridge Blvd 2426 Suite 101 2427 Albuquerque, NM 87111 2428 US 2430 Phone: +1 505 332 5700 2431 Email: galb-list@vandyke.com 2433 Oskari Saarenmaa 2434 F-Secure 2435 Tammasaarenkatu 7 2436 Helsinki 00180 2437 FI 2439 Email: oskari.saarenmaa@f-secure.com 2441 Intellectual Property Statement 2443 The IETF takes no position regarding the validity or scope of any 2444 Intellectual Property Rights or other rights that might be claimed to 2445 pertain to the implementation or use of the technology described in 2446 this document or the extent to which any license under such rights 2447 might or might not be available; nor does it represent that it has 2448 made any independent effort to identify any such rights. Information 2449 on the procedures with respect to rights in RFC documents can be 2450 found in BCP 78 and BCP 79. 2452 Copies of IPR disclosures made to the IETF Secretariat and any 2453 assurances of licenses to be made available, or the result of an 2454 attempt made to obtain a general license or permission for the use of 2455 such proprietary rights by implementers or users of this 2456 specification can be obtained from the IETF on-line IPR repository at 2457 http://www.ietf.org/ipr. 2459 The IETF invites any interested party to bring to its attention any 2460 copyrights, patents or patent applications, or other proprietary 2461 rights that may cover technology that may be required to implement 2462 this standard. Please address the information to the IETF at 2463 ietf-ipr@ietf.org. 2465 Disclaimer of Validity 2467 This document and the information contained herein are provided on an 2468 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 2469 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 2470 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 2471 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 2472 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 2473 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 2475 Copyright Statement 2477 Copyright (C) The Internet Society (2005). This document is subject 2478 to the rights, licenses and restrictions contained in BCP 78, and 2479 except as set forth therein, the authors retain all their rights. 2481 Acknowledgment 2483 Funding for the RFC Editor function is currently provided by the 2484 Internet Society.