idnits 2.17.1 draft-ietf-secsh-filexfer-05.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by 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.) ** There are 4 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** There are 24 instances of lines with control characters in the document. ** 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 144: '...rr by the server SHOULD be considered ...' RFC 2119 keyword, line 145: '...information, and MAY be displayed to t...' RFC 2119 keyword, line 151: '...rors or warnings MAY be sent as stderr...' RFC 2119 keyword, line 180: '...d). All servers SHOULD support packet...' RFC 2119 keyword, line 233: '...d, and their use MUST be negotiated us...' (85 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 408 has weird spacing: '... string owne...' == Line 409 has weird spacing: '... string grou...' == Line 414 has weird spacing: '...seconds prese...' == Line 417 has weird spacing: '... string acl ...' == Line 420 has weird spacing: '... string exte...' == (2 more instances...) -- 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 (January 2004) is 7400 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: 'UTF-8' on line 1568 -- Looks like a reference, but probably isn't: 'RFC-2279' on line 1415 -- Looks like a reference, but probably isn't: 'RFC-1766' on line 1416 == Unused Reference: '4' is defined on line 1870, but no explicit reference was found in the text ** Obsolete normative reference: RFC 3010 (ref. '1') (Obsoleted by RFC 3530) -- Possible downref: Non-RFC (?) normative reference: ref. '2' == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-13 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-15 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-16 -- Obsolete informational reference (is this intentional?): RFC 2246 (ref. '6') (Obsoleted by RFC 4346) == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-16 Summary: 6 errors (**), 0 flaws (~~), 13 warnings (==), 8 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: July 1, 2004 T. Ylonen 5 S. Lehtinen 6 SSH Communications Security Corp 7 January 2004 9 SSH File Transfer Protocol 10 draft-ietf-secsh-filexfer-05.txt 12 Status of this Memo 14 This document is an Internet-Draft and is in full conformance with 15 all provisions of Section 10 of RFC2026. 17 Internet-Drafts are working documents of the Internet Engineering 18 Task Force (IETF), its areas, and its working groups. Note that other 19 groups may also distribute working documents as Internet-Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six months 22 and may be updated, replaced, or obsoleted by other documents at any 23 time. It is inappropriate to use Internet-Drafts as reference 24 material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at http:// 27 www.ietf.org/ietf/1id-abstracts.txt. 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 This Internet-Draft will expire on July 1, 2004. 34 Copyright Notice 36 Copyright (C) The Internet Society (2004). All Rights Reserved. 38 Abstract 40 The SSH File Transfer Protocol provides secure file transfer 41 functionality over any reliable data stream. It is the standard file 42 transfer protocol for use with the SSH2 protocol. This document 43 describes the file transfer protocol and its interface to the SSH2 44 protocol suite. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 4 49 2. Use with the SSH Connection Protocol . . . . . . . . . . . 5 50 2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 5 51 3. General Packet Format . . . . . . . . . . . . . . . . . . 6 52 3.1 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 6 53 4. Protocol Initialization . . . . . . . . . . . . . . . . . 8 54 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 55 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8 56 4.3 Determining Server Newline Convention . . . . . . . . . . 9 57 4.4 Supported Features . . . . . . . . . . . . . . . . . . . . 9 58 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 12 59 5.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 12 60 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 61 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 62 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 14 63 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 14 64 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 15 65 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 66 5.8 attrib-bits . . . . . . . . . . . . . . . . . . . . . . . 17 67 5.9 Extended Attributes . . . . . . . . . . . . . . . . . . . 19 68 6. Requests From the Client to the Server . . . . . . . . . . 20 69 6.1 Request Synchronization and Reordering . . . . . . . . . . 20 70 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 20 71 6.3 Opening and Closing Files and Directories . . . . . . . . 21 72 6.3.1 Opening a File . . . . . . . . . . . . . . . . . . . . . . 21 73 6.3.2 Opening a Directory . . . . . . . . . . . . . . . . . . . 25 74 6.3.3 Closing Handles . . . . . . . . . . . . . . . . . . . . . 26 75 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 26 76 6.4.1 Reading Files . . . . . . . . . . . . . . . . . . . . . . 26 77 6.4.2 Reading Directories . . . . . . . . . . . . . . . . . . . 27 78 6.4.3 Writing Files . . . . . . . . . . . . . . . . . . . . . . 27 79 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 28 80 6.6 Creating and Deleting Directories . . . . . . . . . . . . 29 81 6.7 Retrieving File Attributes . . . . . . . . . . . . . . . . 30 82 6.8 Setting File Attributes . . . . . . . . . . . . . . . . . 30 83 6.9 Dealing with Symbolic Links . . . . . . . . . . . . . . . 31 84 6.10 Canonicalizing the Server-Side Path Name . . . . . . . . . 32 85 6.10.1 Best Practice for Dealing with Paths . . . . . . . . . . . 32 86 7. Responses from the Server to the Client . . . . . . . . . 34 87 8. Extensions . . . . . . . . . . . . . . . . . . . . . . . . 39 88 8.1 Checking File Contents . . . . . . . . . . . . . . . . . . 40 89 9. Security Considerations . . . . . . . . . . . . . . . . . 42 90 10. Changes from Previous Protocol Versions . . . . . . . . . 43 91 10.1 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 43 92 10.2 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 44 93 10.3 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 44 94 10.4 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 45 95 10.5 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 45 96 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 46 97 Normative References . . . . . . . . . . . . . . . . . . . 47 98 Informative References . . . . . . . . . . . . . . . . . . 48 99 Authors' Addresses . . . . . . . . . . . . . . . . . . . . 48 100 Intellectual Property and Copyright Statements . . . . . . 49 102 1. Introduction 104 This protocol provides secure file transfer (and more generally file 105 system access.) It is designed so that it could be used to implement 106 a secure remote file system service, as well as a secure file 107 transfer service. 109 This protocol assumes that it runs over a secure channel, such as a 110 channel in the SSH2 protocol [3]. and that the server has already 111 authenticated the client, and that the identity of the client user is 112 available to the protocol. 114 In general, this protocol follows a simple request-response model. 115 Each request and response contains a sequence number and multiple 116 requests may be pending simultaneously. There are a relatively large 117 number of different request messages, but a small number of possible 118 response messages. Each request has one or more response messages 119 that may be returned in result (e.g., a read either returns data or 120 reports error status). 122 The packet format descriptions in this specification follow the 123 notation presented in the secsh architecture draft. [3] 125 Even though this protocol is described in the context of the SSH2 126 protocol, this protocol is general and independent of the rest of the 127 SSH2 protocol suite. It could be used in a number of different 128 applications, such as secure file transfer over TLS RFC 2246 [6] and 129 transfer of management information in VPN applications. 131 2. Use with the SSH Connection Protocol 133 When used with the SSH2 Protocol suite, this protocol is intended to 134 be used from the SSH Connection Protocol [5] as a subsystem, as 135 described in section ''Starting a Shell or a Command''. The subsystem 136 name used with this protocol is "sftp". 138 2.1 The Use of 'stderr' in the server 140 This protocol uses stdout and stdin to transmit binary protocol data. 141 The "session" channel SSH Connection Protocol [5], which is used by 142 the subsystem, also supports the use of stderr. 144 Data sent on stderr by the server SHOULD be considered free format 145 debug or supplemental error information, and MAY be displayed to the 146 user. 148 For example, during initialization, there is no client request 149 active, so errors or warning information cannot be sent to the client 150 as part of the SFTP protocol at this early stage. However, the 151 errors or warnings MAY be sent as stderr text. 153 3. General Packet Format 155 All packets transmitted over the secure connection are of the 156 following format: 158 uint32 length 159 byte type 160 byte[length - 1] data payload 162 That is, they are data preceded by 32-bit length and 8-bit type 163 fields. The 'length' is the length of the data area, and does not 164 include the 'length' field itself. The format and interpretation of 165 the data area depends on the packet type. 167 All packet descriptions specify the packet type and the data that 168 goes into the data field. Thus, they should be prefixed by the 169 'length' fields. 171 This document defines one data type in addition to those defined in 172 secsh architecture draft. [3] 174 int64 175 Represents a 64-bit signed integer. Stored as eight bytes in the 176 order of decreasing significance (network byte order). 178 The maximum size of a packet is in practice determined by the client 179 (the maximum size of read or write requests that it sends, plus a few 180 bytes of packet overhead). All servers SHOULD support packets of at 181 least 34000 bytes (where the packet size refers to the full length, 182 including the header above). This should allow for reads and writes 183 of at most 32768 bytes. 185 There is no limit on the number of outstanding (non-acknowledged) 186 requests that the client may send to the server. In practice this is 187 limited by the buffering available on the data stream and the queuing 188 performed by the server. If the server's queues are full, it should 189 not read any more data from the stream, and flow control will prevent 190 the client from sending more requests. Note, however, that while 191 there is no restriction on the protocol level, the client's API may 192 provide a limit in order to prevent infinite queuing of outgoing 193 requests at the client. 195 3.1 Packet Types 197 The following values are defined for packet types. 199 #define SSH_FXP_INIT 1 200 #define SSH_FXP_VERSION 2 201 #define SSH_FXP_OPEN 3 202 #define SSH_FXP_CLOSE 4 203 #define SSH_FXP_READ 5 204 #define SSH_FXP_WRITE 6 205 #define SSH_FXP_LSTAT 7 206 #define SSH_FXP_FSTAT 8 207 #define SSH_FXP_SETSTAT 9 208 #define SSH_FXP_FSETSTAT 10 209 #define SSH_FXP_OPENDIR 11 210 #define SSH_FXP_READDIR 12 211 #define SSH_FXP_REMOVE 13 212 #define SSH_FXP_MKDIR 14 213 #define SSH_FXP_RMDIR 15 214 #define SSH_FXP_REALPATH 16 215 #define SSH_FXP_STAT 17 216 #define SSH_FXP_RENAME 18 217 #define SSH_FXP_READLINK 19 218 #define SSH_FXP_SYMLINK 20 220 #define SSH_FXP_STATUS 101 221 #define SSH_FXP_HANDLE 102 222 #define SSH_FXP_DATA 103 223 #define SSH_FXP_NAME 104 224 #define SSH_FXP_ATTRS 105 226 #define SSH_FXP_EXTENDED 200 227 #define SSH_FXP_EXTENDED_REPLY 201 229 RESERVED_FOR_EXTENSIONS 210-255 231 Additional packet types should only be defined if the protocol 232 version number (see Section ''Protocol Initialization'') is 233 incremented, and their use MUST be negotiated using the version 234 number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY 235 packets can be used to implement extensions, which can be vendor 236 specific. See Section ''Extensions'' for more details. 238 4. Protocol Initialization 240 When the file transfer protocol starts, the client first sends a 241 SSH_FXP_INIT (including its version number) packet to the server. The 242 server responds with a SSH_FXP_VERSION packet, supplying the lowest 243 of its own and the client's version number. Both parties should from 244 then on adhere to particular version of the protocol. 246 The version number of the protocol specified in this document is 5. 247 The version number should be incremented for each incompatible 248 revision of this protocol. 250 4.1 Client Initialization 252 The SSH_FXP_INIT packet (from client to server) has the following 253 data: 255 uint32 version 257 Version 3 of this protocol allowed clients to include extensions in 258 the SSH_FXP_INIT packet; however, this can cause interoperability 259 problems with version 1 and version 2 servers because the client must 260 send this packet before knowing the servers version. 262 In this version of the protocol, clients MUST use the 263 SSH_FXP_EXTENDED packet to send extensions to the server after 264 version exchange has completed. Clients MUST NOT include extensions 265 in the version packet. This will prevent interoperability problems 266 with older servers 268 4.2 Server Initialization 270 The SSH_FXP_VERSION packet (from server to client) has the following 271 data: 273 uint32 version 274 276 'version' is the lower of the protocol version supported by the 277 server and the version number received from the client. 279 The extension data may be empty, or may be a sequence of 281 string extension_name 282 string extension_data 284 pairs (both strings MUST always be present if one is, but the 285 'extension_data' string may be of zero length). If present, these 286 strings indicate extensions to the baseline protocol. The 287 'extension_name' field(s) identify the name of the extension. The 288 name should be of the form "name@domain", where the domain is the DNS 289 domain name of the organization defining the extension. Additional 290 names that are not of this format may be defined later by the IETF. 291 Implementations MUST silently ignore any extensions whose name they 292 do not recognize. 294 4.3 Determining Server Newline Convention 296 In order to correctly process text files in a cross platform 297 compatible way, newline sequences must be converted between client 298 and server conventions. 300 The SSH_FXF_TEXT file open flag (Section 6.3.1) makes it possible to 301 request that the server translate a file to a 'canonical' wire 302 format. This format uses \r\n as the line separator. 304 Servers for systems using multiple newline characters (for example, 305 Mac OS X or VMS) or systems using counted records, MUST translate to 306 the canonical form. 308 However, to ease the burden of implementation on servers that use a 309 single, simple separator sequence, the following extension allows the 310 canonical format to be changed. 312 string "newline" 313 string new-canonical-separator (usually "\r" or "\n" or "\r\n") 315 All clients MUST support this extension. 317 When processing text files, clients SHOULD NOT translate any 318 character or sequence that is not an exact match of the server's 319 newline separator. 321 In particular, if the newline sequence being used is the canonical 322 "\r\n" sequence, a lone "\r" or a lone "\n" SHOULD be written through 323 without change. 325 4.4 Supported Features 327 The sftp protocol has grown to be very rich, and now supports a 328 number of features that may not be available on all servers. 330 When a server receives a request for a feature it cannot support, it 331 MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise 332 specified. In order to facilitate clients being able to use the 333 maximum available feature set, and yet not be overly burdened by 334 dealing with SSH_FX_OP_UNSUPPORTED status codes, the following 335 extension is introduced. 337 string "supported" 338 string supported-structure 339 uint32 supported-attribute-mask 340 uint32 supported-attribute-bits 341 uint32 supported-open-flags 342 uint32 supported-access-mask 343 uint32 max-read-size 344 string extension-names[0..n] 346 supported-attribute-mask 347 This mask MAY by applied to the 'File Attributes' 348 valid-attribute-flags field (Section 5.1) to ensure that no 349 unsupported attributes are present during a operation which writes 350 attributes. 352 supported-attribute-bits 353 This mask MAY by applied to the 'File Attributes' attrib-bits 354 field (Section 5.8) to ensure that no unsupported attrib-bits are 355 present during a operation which writes attributes. 357 supported-open-flags 358 The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN 359 (Section 6.3.1) flags field. 361 supported-access-mask 362 The supported-access-mask mask MAY be applied to the SSH_FXP_OPEN 363 (Section 6.3.1) desired-access field or the ace-mask field of an 364 ACL. 366 max-read-size 367 This is the maximum read size that the server gaurantees to 368 complete. For example, certain embedded server implementations 369 only complete the first 4K of a read, even if there is additional 370 data to be read from the file. 372 If the server specifies a non-zero value, it MUST return at least 373 the max-read-size number of bytes for any read requesting 374 max-read-size bytes. Failure to return max-read-size bytes in 375 such a case indicates either EOF or another error condition 376 occurred. 378 extension names 379 The extension names may be empty (contains zero strings), or it 380 may contain any named extensions that the server wishes to 381 advertise. 383 The client must be able to differentiate between attribute 384 extensions (Section 5.9) and extended requests (Section 8) by the 385 extension name. 387 Naturally, if a given attribute field, attribute mask bit, open flag, 388 or extension is required for correct operation, the client MUST 389 either not allow the bit to be masked off, or MUST fail the operation 390 gracefully without sending the request to the server. 392 The client MAY send requests that are not supported by the server; 393 however, it is not normally expected to be productive to do so. The 394 client SHOULD apply the mask even to attrib structures received from 395 the server. The server MAY include attributes or attrib-bits that 396 are not included in the mask. Such attributes or attrib-bits are 397 effectively read-only. 399 5. File Attributes 401 A new compound data type is defined for encoding file attributes. The 402 same encoding is used both when returning file attributes from the 403 server and when sending file attributes to the server. 405 uint32 valid-attribute-flags 406 byte type always present 407 uint64 size present only if flag SIZE 408 string owner present only if flag OWNERGROUP 409 string group present only if flag OWNERGROUP 410 uint32 permissions present only if flag PERMISSIONS 411 int64 atime present only if flag ACCESSTIME 412 uint32 atime_nseconds present only if flag SUBSECOND_TIMES 413 int64 createtime present only if flag CREATETIME 414 uint32 createtime_nseconds present only if flag SUBSECOND_TIMES 415 int64 mtime present only if flag MODIFYTIME 416 uint32 mtime_nseconds present only if flag SUBSECOND_TIMES 417 string acl present only if flag ACL 418 uint32 attrib-bits present only if flag BITS 419 uint32 extended_count present only if flag EXTENDED 420 string extended_type 421 string extended_data 422 ... more extended data (extended_type - extended_data pairs), 423 so that number of pairs equals extended_count 425 5.1 valid-attribute-flags 427 The 'valid-attribute-flags' specifies which of the fields are 428 present. Those fields for which the corresponding flag is not set are 429 not present (not included in the packet). 431 The server generally includes all attributes it knows about; however, 432 it may exclude attributes that are overly expensive to retrieve 433 unless the client explicitly requests them. 435 When writing attributes, the server SHOULD NOT modify attributes that 436 are not present in the structure. However, if necessary, the server 437 MAY use a default value for an absent attribute. 439 New fields can only be added by incrementing the protocol version 440 number (or by using the extension mechanism described below). 442 The following values are defined: 444 #define SSH_FILEXFER_ATTR_SIZE 0x00000001 445 #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 446 #define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 447 #define SSH_FILEXFER_ATTR_CREATETIME 0x00000010 448 #define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 449 #define SSH_FILEXFER_ATTR_ACL 0x00000040 450 #define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 451 #define SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 452 #define SSH_FILEXFER_ATTR_BITS 0x00000200 453 #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 455 0x00000002 was used in a previous version of this protocol. It is 456 now a reserved value and MUST NOT appear in the mask. Some future 457 version of this protocol may reuse this value. 459 5.2 Type 461 The type field is always present. The following types are defined: 463 #define SSH_FILEXFER_TYPE_REGULAR 1 464 #define SSH_FILEXFER_TYPE_DIRECTORY 2 465 #define SSH_FILEXFER_TYPE_SYMLINK 3 466 #define SSH_FILEXFER_TYPE_SPECIAL 4 467 #define SSH_FILEXFER_TYPE_UNKNOWN 5 468 #define SSH_FILEXFER_TYPE_SOCKET 6 469 #define SSH_FILEXFER_TYPE_CHAR_DEVICE 7 470 #define SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 471 #define SSH_FILEXFER_TYPE_FIFO 9 473 On a POSIX system, these values would be derived from the mode field 474 of the stat structure. SPECIAL should be used for files that are of 475 a known type which cannot be expressed in the protocol. UNKNOWN 476 should be used if the type is not known. 478 5.3 Size 480 The 'size' field specifies the size of the file on disk, in bytes. If 481 it is present during file creation, it SHOULD be considered a hint as 482 to the file's eventual size. 484 If this field is present during a setstat operation, the file MUST be 485 extended or truncated to the specified size. Clients SHOULD 486 therefore be careful specifying size during a setstat operation. 488 Files opened with the SSH_FXF_TEXT flag may have a size that is 489 greater or less than the value of the size field. 491 5.4 Owner and Group 493 The 'owner' and 'group' fields are represented as UTF-8 strings; this 494 is the form used by NFS v4. See NFS version 4 Protocol [1]. The 495 following text is selected quotations from section 5.6. 497 To avoid a representation that is tied to a particular underlying 498 implementation at the client or server, the use of UTF-8 strings has 499 been chosen. The string should be of the form user@dns_domain". This 500 will allow for a client and server that do not use the same local 501 representation the ability to translate to a common syntax that can 502 be interpreted by both. In the case where there is no translation 503 available to the client or server, the attribute value must be 504 constructed without the "@". Therefore, the absence of the @ from 505 the owner or owner_group attribute signifies that no translation was 506 available and the receiver of the attribute should not place any 507 special meaning with the attribute value. Even though the attribute 508 value cannot be translated, it may still be useful. In the case of a 509 client, the attribute string may be used for local display of 510 ownership. 512 user@localhost represents a user in the context of the server. 514 If either the owner or group field is zero length, the field should 515 be considered absent, and no change should be made to that specific 516 field. 518 5.5 Permissions 520 The 'permissions' field contains a bit mask specifying file 521 permissions. These permissions correspond to the st_mode field of 522 the stat structure defined by POSIX [2]. 524 This protocol uses the following values for the symbols declared in 525 the posix standard. 527 #define S_IRUSR 0000400 (octal) 528 #define S_IWUSR 0000200 529 #define S_IXUSR 0000100 530 #define S_IRGRP 0000040 531 #define S_IWGRP 0000020 532 #define S_IXGRP 0000010 533 #define S_IROTH 0000004 534 #define S_IWOTH 0000002 535 #define S_IXOTH 0000001 536 #define S_ISUID 0004000 537 #define S_ISGID 0002000 538 #define S_ISVTX 0001000 540 Implementations MUST NOT send bits that are not defined. 542 5.6 Times 544 The 'atime', 'createtime', and 'mtime' contain the accesses, 545 creation, and modification times of the files, respectively. They 546 are represented as seconds from Jan 1, 1970 in UTC. 548 A negative value indicates number of seconds before Jan 1, 1970. In 549 both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the 550 nseconds field is to be added to the seconds field for the final time 551 representation. For example, if the time to be represented is 552 one-half second before 0 hour January 1, 1970, the seconds field 553 would have a value of negative one (-1) and the nseconds fields would 554 have a value of one-half second (500000000). Values greater than 555 999,999,999 for nseconds are considered invalid. 557 5.7 ACL 559 The 'ACL' field contains an ACL similar to that defined in section 560 5.9 of NFS version 4 Protocol [1]. 562 uint32 ace-count 564 repeated ace-count time: 565 uint32 ace-type 566 uint32 ace-flag 567 uint32 ace-mask 568 string who [UTF-8] 570 ace-type is one of the following four values (taken from NFS Version 571 4 Protocol [1]: 573 #define ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000; 574 #define ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001; 575 #define ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002; 576 #define ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003; 578 ace-flag is a combination of the following flag values. See NFS 579 Version 4 Protocol [1] section 5.9.2: 581 #define ACE4_FILE_INHERIT_ACE 0x00000001; 582 #define ACE4_DIRECTORY_INHERIT_ACE 0x00000002; 583 #define ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004; 584 #define ACE4_INHERIT_ONLY_ACE 0x00000008; 585 #define ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010; 586 #define ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020; 587 #define ACE4_IDENTIFIER_GROUP 0x00000040; 589 ace-mask is any combination of the following flags (taken from NFS 590 Version 4 Protocol [1] section 5.9.3: 592 #define ACE4_READ_DATA 0x00000001; 593 #define ACE4_LIST_DIRECTORY 0x00000001; 594 #define ACE4_WRITE_DATA 0x00000002; 595 #define ACE4_ADD_FILE 0x00000002; 596 #define ACE4_APPEND_DATA 0x00000004; 597 #define ACE4_ADD_SUBDIRECTORY 0x00000004; 598 #define ACE4_READ_NAMED_ATTRS 0x00000008; 599 #define ACE4_WRITE_NAMED_ATTRS 0x00000010; 600 #define ACE4_EXECUTE 0x00000020; 601 #define ACE4_DELETE_CHILD 0x00000040; 602 #define ACE4_READ_ATTRIBUTES 0x00000080; 603 #define ACE4_WRITE_ATTRIBUTES 0x00000100; 604 #define ACE4_DELETE 0x00010000; 605 #define ACE4_READ_ACL 0x00020000; 606 #define ACE4_WRITE_ACL 0x00040000; 607 #define ACE4_WRITE_OWNER 0x00080000; 608 #define ACE4_SYNCHRONIZE 0x00100000; 610 who is a UTF-8 string of the form described in 'Owner and Group' 611 (Section 5.4) 613 Also, as per '5.9.4 ACE who' [1] there are several identifiers that 614 need to be understood universally. Some of these identifiers cannot 615 be understood when an client access the server, but have meaning when 616 a local process accesses the file. The ability to display and modify 617 these permissions is permitted over SFTP. 619 OWNER The owner of the file. 621 GROUP The group associated with the file. 623 EVERYONE The world. 625 INTERACTIVE Accessed from an interactive terminal. 627 NETWORK Accessed via the network. 629 DIALUP Accessed as a dialup user to the server. 631 BATCH Accessed from a batch job. 633 ANONYMOUS Accessed without any authentication. 635 AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). 637 SERVICE Access from a system service. 639 To avoid conflict, these special identifiers are distinguish by an 640 appended "@". For example: ANONYMOUS@. 642 5.8 attrib-bits 644 These bits reflect various attributes of the file or directory on the 645 server. 647 The following attrib-bits are defined: 649 #define SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 650 #define SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 651 #define SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 652 #define SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 653 #define SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 654 #define SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 655 #define SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 656 #define SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 657 #define SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 658 #define SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 659 #define SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 661 SSH_FILEXFER_ATTR_FLAGS_READONLY 662 Advisory, read-only bit. This bit is not part of the access 663 control information on the file, but is rather an advisory field 664 indicating that the file should not be written. 666 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 667 The file is part of operating system. 669 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 670 File SHOULD NOT be shown to user unless specifically requested. 671 For example, most UNIX systems SHOULD set this bit if the filename 672 begins with a 'period'. This bit may be read-only (Section 4.4). 673 Most UNIX systems will not allow this to be changed. 675 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 676 This attribute can only apply to directories. This attribute is 677 always read-only, and cannot be modified. This attribute means 678 that files and directory names in this directory should be 679 compared without regard to case. 681 It is recommended that where possible, the server's filesystem be 682 allowed to do comparisons. For example, if a client wished to 683 prompt a user before overwriting a file, it should not compare the 684 new name with the previously retrieved list of names in the 685 directory. Rather, it should first try to create the new file by 686 specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and 687 returns SSH_FX_FILE_ALREADY_EXISTS, it should prompt the user and 688 then retry the create specifying SSH_FXF_CREATE_TRUNCATE. 690 Unless otherwise specified, filenames are assumed to be case 691 sensitive. 693 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 694 The file should be included in backup / archive operations. 696 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 697 The file is encrypted. 699 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 700 The file is compressed. 702 SSH_FILEXFER_ATTR_FLAGS_SPARSE 703 The file is a sparse file; this means that file blocks that have 704 not been explicitly written are not stored on disk. For example, 705 if a client writes a buffer at 10 M from the beginning of the 706 file, the blocks between the previous EOF marker and the 10 M 707 offset would not consume physical disk space. 709 Some server may store all files as sparse files, in which case 710 this bit will be unconditionally set. Other servers may not have 711 a mechanism for determining if the file is sparse, and so the file 712 MAY be stored sparse even if this flag is not set. 714 SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 715 The file can only be opened for writing in append mode. 717 SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 718 The file cannot be deleted or renamed, no hard link can be created 719 to this file and no data can be written to the file. 721 This bit implies a stronger level of protection than 722 SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or 723 ACLs. Typically even the superuser cannot write to immutable 724 files, and only the superuser can set or remove the bit. 726 SSH_FILEXFER_ATTR_FLAGS_SYNC 727 When the file is modified, the changes are written synchronously 728 to the disk. 730 5.9 Extended Attributes 732 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 733 mechanism for the attrib structure. If the flag is specified, then 734 the 'extended_count' field is present. It specifies the number of 735 extended_type-extended_data pairs that follow. Each of these pairs 736 specifies an extended attribute. For each of the attributes, the 737 extended_type field should be a string of the format "name@domain", 738 where "domain" is a valid, registered domain name and "name" 739 identifies the method. The IETF may later standardize certain names 740 that deviate from this format (e.g., that do not contain the "@" 741 sign). The interpretation of 'extended_data' depends on the type. 742 Implementations SHOULD ignore extended data fields that they do not 743 understand. 745 Additional fields can be added to the attributes by either defining 746 additional bits to the flags field to indicate their presence, or by 747 defining extended attributes for them. The extended attributes 748 mechanism is recommended for most purposes; additional flags bits 749 should only be defined by an IETF standards action that also 750 increments the protocol version number. The use of such new fields 751 MUST be negotiated by the version number in the protocol exchange. 752 It is a protocol error if a packet with unsupported protocol bits is 753 received. 755 6. Requests From the Client to the Server 757 Requests from the client to the server represent the various file 758 system operations. Each request begins with an 'request-id' field, 759 which is a 32-bit identifier identifying the request (selected by the 760 client). The same identifier will be returned in the response to the 761 request. One possible implementation is a monotonically increasing 762 request sequence number (modulo 2^32). 764 6.1 Request Synchronization and Reordering 766 The protocol and implementations MUST process requests relating to 767 the same file in the order in which they are received. In other 768 words, if an application submits multiple requests to the server, the 769 results in the responses will be the same as if it had sent the 770 requests one at a time and waited for the response in each case. For 771 example, the server may process non-overlapping read/write requests 772 to the same file in parallel, but overlapping reads and writes cannot 773 be reordered or parallelized. However, there are no ordering 774 restrictions on the server for processing requests from two different 775 file transfer connections. The server may interleave and parallelize 776 them at will. 778 There are no restrictions on the order in which responses to 779 outstanding requests are delivered to the client, except that the 780 server must ensure fairness in the sense that processing of no 781 request will be indefinitely delayed even if the client is sending 782 other requests so that there are multiple outstanding requests all 783 the time. 785 6.2 File Names 787 This protocol represents file names as strings. File names are 788 assumed to use the slash ('/') character as a directory separator. 790 File names starting with a slash are "absolute", and are relative to 791 the root of the file system. Names starting with any other character 792 are relative to the user's default directory (home directory). Note 793 that identifying the user is assumed to take place outside of this 794 protocol. 796 Servers SHOULD interpret a path name component ".." as referring to 797 the parent directory, and "." as referring to the current directory. 798 If the server implementation limits access to certain parts of the 799 file system, it must be extra careful in parsing file names when 800 enforcing such restrictions. There have been numerous reported 801 security bugs where a ".." in a path name has allowed access outside 802 the intended area. 804 An empty path name is valid, and it refers to the user's default 805 directory (usually the user's home directory). 807 Otherwise, no syntax is defined for file names by this specification. 808 Clients should not make any other assumptions; however, they can 809 splice path name components returned by SSH_FXP_READDIR together 810 using a slash ('/') as the separator, and that will work as expected. 812 In order to comply with IETF Policy on Character Sets and Languages 813 [7], all filenames MUST be encoded in UTF-8. The shortest valid UTF-8 814 encoding of the UNICODE data MUST be used. The server is responsible 815 for converting the UNICODE data to whatever canonical form it 816 requires. 818 For example, if the server requires that precomposed characters 819 always be used, the server MUST NOT assume the filename as sent by 820 the client has this attribute, but must do this normalization itself. 822 It is understood that the lack of well-defined semantics for file 823 names may cause interoperability problems between clients and servers 824 using radically different operating systems. However, this approach 825 is known to work acceptably with most systems, and alternative 826 approaches that e.g. treat file names as sequences of structured 827 components are quite complicated. 829 6.3 Opening and Closing Files and Directories 831 Many operations in the protocol operate on open files. The 832 SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 833 an opaque, variable-length string) which may be used to access the 834 file or directory later. The client MUST NOT send requests the 835 server with bogus or closed handles. However, the server MUST 836 perform adequate checks on the handle in order to avoid security 837 risks due to fabricated handles. 839 This design allows either stateful and stateless server 840 implementation, as well as an implementation which caches state 841 between requests but may also flush it. The contents of the file 842 handle string are entirely up to the server and its design. The 843 client should not modify or attempt to interpret the file handle 844 strings. 846 The file handle strings MUST NOT be longer than 256 bytes. 848 6.3.1 Opening a File 850 Files are opened and created using the SSH_FXP_OPEN message: 852 byte SSH_FXP_OPEN 853 uint32 request-id 854 string filename [UTF-8] 855 uint32 desired-access 856 uint32 flags 857 ATTRS attrs 859 The response to this message will be either SSH_FXP_HANDLE (if the 860 operation is successful) or SSH_FXP_STATUS (if the operation fails). 862 The 'request-id' field is the request identifier as for all requests. 864 The 'filename' field specifies the file name. See Section ''File 865 Names'' for more information. 867 The 'desired-access' field is a bitmask containing a combination of 868 values from the ace-mask flags from section 5.7. 870 The 'flags' field controls various aspects of the operation, 871 including whether or not the file is created and the kind of locking 872 desired. 874 The following 'flags' are defined: 876 SSH_FXF_ACCESS_DISPOSITION = 0x00000007 877 SSH_FXF_CREATE_NEW = 0x00000000 878 SSH_FXF_CREATE_TRUNCATE = 0x00000001 879 SSH_FXF_OPEN_EXISTING = 0x00000002 880 SSH_FXF_OPEN_OR_CREATE = 0x00000003 881 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 882 SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 883 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 884 SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 885 SSH_FXF_ACCESS_READ_LOCK = 0x00000040 886 SSH_FXF_ACCESS_WRITE_LOCK = 0x00000080 887 SSH_FXF_ACCESS_DELETE_LOCK = 0x00000100 889 SSH_FXF_ACCESS_DISPOSITION 890 Disposition is a 3 bit field that controls how the file is opened. 891 The server MUST support these bits. Any one of the following 892 enumeration is allowed: 894 SSH_FXF_CREATE_NEW 895 A new file is created; if the file already exists, the server 896 MUST return status SSH_FX_FILE_ALREADY_EXISTS. 898 SSH_FXF_CREATE_TRUNCATE 899 A new file is create; if the file already exists, it is 900 truncated. 902 SSH_FXF_OPEN_EXISTING 903 An existing file is opened. If the file does not exist, the 904 server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the 905 path does not exist, the server SHOULD return 906 SSH_FX_NO_SUCH_PATH. It is also acceptable if the server 907 returns SSH_FX_NO_SUCH_FILE in this case. 909 SSH_FXF_OPEN_OR_CREATE 910 If the file exists, it is opened. If the file does not exist, 911 it is created. 913 SSH_FXF_TRUNCATE_EXISTING 914 An existing file is opened and truncated. If the file does not 915 exist, the server MUST return the same error codes as defined 916 for SSH_FXF_OPEN_EXISTING. 918 SSH_FXF_ACCESS_APPEND_DATA 919 Data is always written at the end of the file. The offset field 920 of the SSH_FXP_WRITE requests are ignored. 922 Data is not required to be appended atomically. This means that 923 if multiple writers attempt to append data simultaneously, data 924 from the first may be lost. However, data MAY be appended 925 atomically. 927 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 928 Data is always written at the end of the file. The offset field 929 of the SSH_FXP_WRITE requests are ignored. 931 Date MUST be written atomically so that there is no chance that 932 multiple appenders can collide and result in data being lost. 934 If both append flags are specified, the server SHOULD use atomic 935 append if it is available, but SHOULD use non-atomic appends 936 otherwise. The server SHOULD NOT fail the request in this case. 938 SSH_FXF_TEXT 939 Indicates that the server should treat the file as text and 940 convert it to the canonical newline convention in use. (See 941 Determining Server Newline Convention. (Section 4.3) 943 When a file is opened with the FXF_TEXT flag, the offset field in 944 both the read and write function are ignored. 946 Servers MUST correctly process multiple, parallel reads and writes 947 correctly in this mode. Naturally, it is permissible for them to 948 do this by serializing the requests. 950 Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append 951 data to a text file rather then using write with a calculated 952 offset. 954 To support seeks on text files the following SSH_FXP_EXTENDED 955 packet is defined. 957 string "text-seek" 958 string file-handle 959 uint64 line-number 961 line-number is the index of the line number to seek to, where byte 962 0 in the file is line number 0, and the byte directly following 963 the first newline sequence in the file is line number 1 and so on. 965 The response to a "text-seek" request is an SSH_FXP_STATUS 966 message. 968 An attempt to seek past the end-of-file should result in a 969 SSH_FX_EOF status. 971 Servers SHOULD support at least one "text-seek" in order to 972 support resume. However, a client MUST be prepared to receive 973 SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation. 974 The client can then try a fall-back strategy, if it has one. 976 Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned 977 for read or write operations that are not sequential. 979 SSH_FXF_ACCESS_READ_LOCK 980 The file should be opened with a read lock. The server MUST 981 gaurantee that the client will be the exclusive reader of the file 982 until the client closes the handle. If there is a conflicting lock 983 the server MUST return SSH_FX_LOCK_CONFlICT. If the server cannot 984 make the locking gaurantee, it MUST return SSH_FX_OP_UNSUPPORTED. 986 SSH_FXF_ACCESS_WRITE_LOCK 987 The file should be opened with a write lock. The server MUST 988 gaurantee that the client will be the exclusive writer of the file 989 until the client closes the handle. 991 SSH_FXF_ACCESS_DELETE_LOCK 992 The file should be opened with a delete lock. The server MUST 993 gaurantee that the file will not be deleted until the client 994 closes the handle. 996 The 'attrs' field specifies the initial attributes for the file. 997 Default values MUST be supplied by the server for those attributes 998 that are not specified. See Section ''File Attributes'' for more 999 information. 1001 The following table is provided to assist in mapping posix semantics 1002 to equivalent SFTP file open parameters: 1004 O_RDONLY 1005 desired-access = READ_DATA|READ_ATTRIBUTES 1007 O_WRONLY 1008 desired-access = WRITE_DATA|WRITE_ATTRIBUTES 1010 O_RDWR 1011 desired-access = 1012 READ_DATA|READ_ATTRIBUTES|WRITE_DATA|WRITE_ATTRIBUTES 1014 O_APPEND 1015 desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA 1016 flags = SSH_FXF_ACCESS_APPEND_DATA and or 1017 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC 1019 O_CREAT 1020 flags = SSH_FXF_OPEN_OR_CREATE 1022 O_TRUNC 1023 flags = SSH_FXF_TRUNCATE_EXISTING 1025 O_TRUNC|O_CREATE 1026 flags = SSH_FXF_CREATE_TRUNCATE 1028 6.3.2 Opening a Directory 1030 To enumerate a directory, the client first obtains a handle and then 1031 issues directory read requests. When enumeration is complete, the 1032 handle MUST be closed. 1034 byte SSH_FXP_OPENDIR 1035 uint32 request-id 1036 string path [UTF-8] 1038 'request-id' is the request identifier. 1040 'path' is the path name of the directory to be listed (without any 1041 trailing slash). See Section 'File Names' for more information on 1042 file names. 1044 The response to this message will be either SSH_FXP_HANDLE (if the 1045 operation is successful) or SSH_FXP_STATUS (if the operation fails). 1047 6.3.3 Closing Handles 1049 A handle is closed using the following request. 1051 byte SSH_FXP_CLOSE 1052 uint32 request-id 1053 string handle 1055 'request-id' is the request identifier, and 'handle' is a handle 1056 previously returned in the response to SSH_FXP_OPEN or 1057 SSH_FXP_OPENDIR. The handle becomes invalid immediately after this 1058 request has been sent. 1060 The response to this request will be a SSH_FXP_STATUS message. Note 1061 that on some server platforms even a close can fail. For example, if 1062 the server operating system caches writes, and an error occurs while 1063 flushing cached writes, the close operation may fail. 1065 6.4 Reading and Writing 1067 6.4.1 Reading Files 1069 The following request can be used to read file data: 1071 byte SSH_FXP_READ 1072 uint32 request-id 1073 string handle 1074 uint64 offset 1075 uint32 length 1077 where 'request-id' is the request identifier, 'handle' is an open 1078 file handle returned by SSH_FXP_OPEN, 'offset' is the offset (in 1079 bytes) relative to the beginning of the file from where to start 1080 reading, and 'length' is the maximum number of bytes to read. 1082 In response to this request, the server will read as many bytes as it 1083 can from the file (up to 'length'), and return them in a SSH_FXP_DATA 1084 message. If an error occurs or EOF is encountered before reading any 1085 data, the server will respond with SSH_FXP_STATUS. 1087 For normal disk files, it is normally guaranteed that this will read 1088 the specified number of bytes, or up to end of file. However, if the 1089 read length is very long, the server may truncate it if it doesn't 1090 support packets of that length. See General Packet Format (Section 1091 3). 1093 6.4.2 Reading Directories 1095 In order to retrieve a directory listing, the client issues one or 1096 more SSH_FXP_READDIR requests. In order to obtain a complete 1097 directory listing, the client MUST issue repeated SSH_FXP_READDIR 1098 requests until the server responds with an SSH_FXP_STATUS message. 1100 byte SSH_FXP_READDIR 1101 uint32 request-id 1102 string handle 1104 where 'request-id' is the request identifier, and 'handle' is a 1105 handle returned by SSH_FXP_OPENDIR. (It is a protocol error to 1106 attempt to use an ordinary file handle returned by SSH_FXP_OPEN.) 1108 The server responds to this request with either a SSH_FXP_NAME or a 1109 SSH_FXP_STATUS message. One or more names may be returned at a time. 1110 Full status information is returned for each name in order to speed 1111 up typical directory listings. 1113 If there are no more names available to be read, the server MUST 1114 respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. 1116 6.4.3 Writing Files 1118 Writing to a file is achieved using the following message: 1120 byte SSH_FXP_WRITE 1121 uint32 request-id 1122 string handle 1123 uint64 offset 1124 string data 1126 where 'request-id' is a request identifier, 'handle' is a file handle 1127 returned by SSH_FXP_OPEN, 'offset' is the offset (in bytes) from the 1128 beginning of the file where to start writing, and 'data' is the data 1129 to be written. 1131 The write will extend the file if writing beyond the end of the file. 1132 It is legal to write to an offset that extends beyond the end of the 1133 file; the semantics are to write zeroes from the end of the file to 1134 the specified offset and then the data. On most operating systems, 1135 such writes do not allocate disk space but instead create a sparse 1136 file. 1138 The server responds to a write request with a SSH_FXP_STATUS message. 1140 6.5 Removing and Renaming Files 1142 The following request can be used to remove a file: 1144 byte SSH_FXP_REMOVE 1145 uint32 request-id 1146 string filename [UTF-8] 1148 where 'request-id' is the request identifier and 'filename' is the 1149 name of the file to be removed. See Section ''File Names'' for more 1150 information. This request cannot be used to remove directories. 1152 The server will respond to this request with a SSH_FXP_STATUS 1153 message. 1155 Files (and directories) can be renamed using the SSH_FXP_RENAME 1156 message. 1158 byte SSH_FXP_RENAME 1159 uint32 request-id 1160 string oldpath [UTF-8] 1161 string newpath [UTF-8] 1162 uint32 flags 1164 where 'request-id' is the request identifier, 'oldpath' is the name 1165 of an existing file or directory, and 'newpath' is the new name for 1166 the file or directory. 1168 'flags' is 0 or a combination of: 1170 SSH_FXP_RENAME_OVERWRITE 0x00000001 1171 SSH_FXP_RENAME_ATOMIC 0x00000002 1172 SSH_FXP_RENAME_NATIVE 0x00000004 1174 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already 1175 exists a file with the name specified by newpath, the server MUST 1176 respond with SSH_FX_FILE_ALREADY_EXISTS. 1178 If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file 1179 already exists, it is replaced in an atomic fashion. I.e., there is 1180 no observable instant in time where the name does not refer to either 1181 the old or the new file. SSH_FXP_RENAME_ATOMIC implies 1182 SSH_FXP_RENAME_OVERWRITE. 1184 If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace 1185 the destination in an atomic fashion, then the server MUST respond 1186 with SSH_FX_OP_UNSUPPORTED. 1188 Because some servers cannot provide atomic rename, clients should 1189 only specify atomic rename if correct operation requires it. If 1190 SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an 1191 atomic rename even if it is not requested. 1193 If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the 1194 rename operation in whatever fashion it deems appropriate. Other 1195 flag values are considered hints as to desired behavior, but not 1196 requirements. 1198 The server will respond to this request with a SSH_FXP_STATUS 1199 message. 1201 6.6 Creating and Deleting Directories 1203 New directories can be created using the SSH_FXP_MKDIR request. It 1204 has the following format: 1206 byte SSH_FXP_MKDIR 1207 uint32 request-id 1208 string path [UTF-8] 1209 ATTRS attrs 1211 where 'request-id' is the request identifier. 1213 'path' specifies the directory to be created. See Section ''File 1214 Names'' for more information on file names. 1216 'attrs' specifies the attributes that should be applied to it upon 1217 creation. Attributes are discussed in more detail in Section ''File 1218 Attributes''. 1220 The server will respond to this request with a SSH_FXP_STATUS 1221 message. If a file or directory with the specified path already 1222 exists, an error will be returned. 1224 Directories can be removed using the SSH_FXP_RMDIR request, which has 1225 the following format: 1227 byte SSH_FXP_RMDIR 1228 uint32 request-id 1229 string path [UTF-8] 1231 where 'request-id' is the request identifier, and 'path' specifies 1232 the directory to be removed. See Section ''File Names'' for more 1233 information on file names. 1235 The server responds to this request with a SSH_FXP_STATUS message. 1237 6.7 Retrieving File Attributes 1239 Very often, file attributes are automatically returned by 1240 SSH_FXP_READDIR. However, sometimes there is need to specifically 1241 retrieve the attributes for a named file. This can be done using the 1242 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 1244 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 1245 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 1246 follow symbolic links. Both have the same format: 1248 byte SSH_FXP_STAT or SSH_FXP_LSTAT 1249 uint32 request-id 1250 string path [UTF-8] 1251 uint32 flags 1253 where 'request-id' is the request identifier, and 'path' specifies 1254 the file system object for which status is to be returned. The 1255 server responds to this request with either SSH_FXP_ATTRS or 1256 SSH_FXP_STATUS. 1258 The flags field specify the attribute flags in which the client has 1259 particular interest. This is a hint to the server. For example, 1260 because retrieving owner / group and acl information can be an 1261 expensive operation under some operating systems, the server may 1262 choose not to retrieve this information unless the client expresses a 1263 specific interest in it. 1265 The client has no guarantee the server will provide all the fields 1266 that it has expressed an interest in. 1268 SSH_FXP_FSTAT differs from the others in that it returns status 1269 information for an open file (identified by the file handle). 1271 byte SSH_FXP_FSTAT 1272 uint32 request-id 1273 string handle 1274 uint32 flags 1276 where 'request-id' is the request identifier and 'handle' is a file 1277 handle returned by SSH_FXP_OPEN. The server responds to this request 1278 with SSH_FXP_ATTRS or SSH_FXP_STATUS. 1280 6.8 Setting File Attributes 1282 File attributes may be modified using the SSH_FXP_SETSTAT and 1283 SSH_FXP_FSETSTAT requests. 1285 byte SSH_FXP_SETSTAT 1286 uint32 request-id 1287 string path [UTF-8] 1288 ATTRS attrs 1290 byte SSH_FXP_FSETSTAT 1291 uint32 request-id 1292 string handle 1293 ATTRS attrs 1295 request-id 1296 The request identifier to be returned as part of the response. 1298 path 1299 The file system object (e.g. file or directory) whose attributes 1300 are to be modified. If this object does not exist, or the user 1301 does not have sufficient access to write the attributes, the 1302 request MUST fail. 1304 handle 1305 The handle is a handle previously returned from a SSH_FXP_OPEN 1306 request which identifies the file whose attributes are to be 1307 modified. If the handle was not opened with sufficient access to 1308 write the requested attributes, the request MUST fail. 1310 attrs 1311 Specifies the modified attributes to be applied. Attributes are 1312 discussed in more detail in Section ''File Attributes''. 1314 The server will respond with a SSH_FXP_STATUS message. 1316 Because some systems must use separate system calls to set various 1317 attributes, it is possible that a failure response will be returned, 1318 but yet some of the attributes may be have been successfully 1319 modified. If possible, servers SHOULD avoid this situation; however, 1320 client MUST be aware that this is possible. 1322 6.9 Dealing with Symbolic Links 1324 The SSH_FXP_READLINK request reads the target of a symbolic link. 1326 byte SSH_FXP_READLINK 1327 uint32 request-id 1328 string path [UTF-8] 1330 where 'request-id' is the request identifier and 'path' specifies the 1331 path name of the symlink to be read. 1333 The server will respond with a SSH_FXP_NAME packet containing only 1334 one name and a dummy attributes value. The name in the returned 1335 packet contains the target of the link. If an error occurs, the 1336 server MAY respond with SSH_FXP_STATUS. 1338 The SSH_FXP_SYMLINK request creates a symbolic link on the server. 1340 byte SSH_FXP_SYMLINK 1341 uint32 request-id 1342 string linkpath [UTF-8] 1343 string targetpath [UTF-8] 1345 where 'request-id' is the request identifier, 'linkpath' specifies 1346 the path name of the symlink to be created and 'targetpath' specifies 1347 the target of the symlink. The server shall respond with a 1348 SSH_FXP_STATUS. 1350 6.10 Canonicalizing the Server-Side Path Name 1352 The SSH_FXP_REALPATH request can be used to have the server 1353 canonicalize any given path name to an absolute path. This is useful 1354 for converting path names containing ".." components or relative 1355 pathnames without a leading slash into absolute paths. The format of 1356 the request is as follows: 1358 byte SSH_FXP_REALPATH 1359 uint32 request-id 1360 string path [UTF-8] 1362 where 'request-id' is the request identifier and 'path' specifies the 1363 path name to be canonicalized. The server will respond with a 1364 SSH_FXP_NAME packet containing the name in canonical form and a dummy 1365 attributes value. If an error occurs, the server may also respond 1366 with SSH_FXP_STATUS. 1368 The server SHOULD fail the request if the path is not present on the 1369 server. 1371 6.10.1 Best Practice for Dealing with Paths 1373 The client SHOULD treat the results of SSH_FXP_REALPATH as a 1374 canonical absolute path, even if the path does not appear to be 1375 absolute. A client that use REALPATH(".") and treats the result as 1376 absolute, even if there is no leading slash, will continue to 1377 function correctly, even when talking to a Windows NT or VMS style 1378 system, where absolute paths may not begin with a slash. 1380 For example, if the client wishes to change directory up, and the 1381 server has returned "c:/x/y/z" from REALPATH, the client SHOULD use 1382 "c:/x/y/z/..". 1384 As a second example, if the client wishes to open the file "x.txt" in 1385 the current directory, and server has returned "dka100:/x/y/z" as the 1386 canonical path of the directory, the client SHOULD open "dka100:/x/y/ 1387 z/x.txt" 1389 7. Responses from the Server to the Client 1391 The server responds to the client using one of a few response 1392 packets. All requests can return a SSH_FXP_STATUS response upon 1393 failure. When the operation is successful, and no data needs to be 1394 returned, the SSH_FXP_STATUS response with SSH_FX_OK status is 1395 appropriate. 1397 Exactly one response will be returned for each request. Each 1398 response packet contains a request identifier which can be used to 1399 match each response with the corresponding request. Note that it is 1400 legal to have several requests outstanding simultaneously, and the 1401 server is allowed to send responses to them in a different order from 1402 the order in which the requests were sent (the result of their 1403 execution, however, is guaranteed to be as if they had been processed 1404 one at a time in the order in which the requests were sent). 1406 Response packets are of the same general format as request packets. 1407 Each response packet begins with the request identifier. 1409 The format of the data portion of the SSH_FXP_STATUS response is as 1410 follows: 1412 byte SSH_FXP_STATUS 1413 uint32 request-id 1414 uint32 error/status code 1415 string error message (ISO-10646 UTF-8 [RFC-2279]) 1416 string language tag (as defined in [RFC-1766]) 1417 1419 request-id 1420 The 'request-id' specified by the client in the request the server 1421 is responding to. 1423 error/status code 1424 Machine readable status code indicating the result of the request. 1425 Error code values are defined below. The value SSH_FX_OK 1426 indicates success, and all other values indicate failure. 1428 error message 1429 Human readable description of the error. 'language tag' specifies 1430 the language the error is in. 1432 1433 The error-specific data may be empty, or may contain additional 1434 information about the error. For error codes that send 1435 error-specific data, the format of the data is defined below. 1437 Error codes: 1439 #define SSH_FX_OK 0 1440 #define SSH_FX_EOF 1 1441 #define SSH_FX_NO_SUCH_FILE 2 1442 #define SSH_FX_PERMISSION_DENIED 3 1443 #define SSH_FX_FAILURE 4 1444 #define SSH_FX_BAD_MESSAGE 5 1445 #define SSH_FX_NO_CONNECTION 6 1446 #define SSH_FX_CONNECTION_LOST 7 1447 #define SSH_FX_OP_UNSUPPORTED 8 1448 #define SSH_FX_INVALID_HANDLE 9 1449 #define SSH_FX_NO_SUCH_PATH 10 1450 #define SSH_FX_FILE_ALREADY_EXISTS 11 1451 #define SSH_FX_WRITE_PROTECT 12 1452 #define SSH_FX_NO_MEDIA 13 1453 #define SSH_FX_NO_SPACE_ON_FILESYSTEM 14 1454 #define SSH_FX_QUOTA_EXCEEDED 15 1455 #define SSH_FX_UNKNOWN_PRINCIPLE 16 1456 #define SSH_FX_LOCK_CONFlICT 17 1458 SSH_FX_OK 1459 Indicates successful completion of the operation. 1461 SSH_FX_EOF 1462 An attempt to read past the end-of-file was made; or, there are no 1463 more directory entries to return. 1465 SSH_FX_NO_SUCH_FILE 1466 A reference was made to a file which does not exist. 1468 SSH_FX_PERMISSION_DENIED 1469 The user does not have sufficient permissions to perform the 1470 operation. 1472 SSH_FX_FAILURE 1473 An error occured, but no specific error code exists to describe 1474 the failure. 1476 This error message SHOULD always have meaningful text in the the 1477 'error message' field. 1479 SSH_FX_BAD_MESSAGE 1480 A badly formatted packet or other SFTP protocol incompatibility 1481 was detected. 1483 SSH_FX_NO_CONNECTION 1484 There is no connection to the server. This error can only be 1485 generated locally, and MUST NOT be return by a server. 1487 SSH_FX_CONNECTION_LOST 1488 The connection to the server was lost. This error can only be 1489 generated locally, and MUST NOT be return by a server. 1491 SSH_FX_OP_UNSUPPORTED 1492 An attempted operation could not be completed by the server 1493 because the server does not support the operation. 1495 This error MAY be generated locally by the client if e.g. the 1496 version number exchange indicates that a required feature is not 1497 supported by the server, or it may be returned by the server if 1498 the server does not implement an operation). 1500 SSH_FX_INVALID_HANDLE 1501 The handle value was invalid. 1503 SSH_FX_NO_SUCH_PATH 1504 The file path does not exist or is invalid. 1506 SSH_FX_FILE_ALREADY_EXISTS 1507 The file already exists. 1509 SSH_FX_WRITE_PROTECT 1510 The file is on read-only media, or the media is write protected. 1512 SSH_FX_NO_MEDIA 1513 The requested operation cannot be completed because there is no 1514 media available in the drive. 1516 SSH_FX_NO_SPACE_ON_FILESYSTEM 1517 The requested operation cannot be completed because there is no 1518 free space on the filesystem. 1520 SSH_FX_QUOTA_EXCEEDED 1521 The operation cannot be completed because the it would exceed the 1522 users storage quota. 1524 SSH_FX_UNKNOWN_PRINCIPLE 1525 A principle referenced by the request (either the 'owner', 1526 'group', or 'who' field of an ACL), was unknown. The error 1527 specific data contains the problematic names. The format is one 1528 or more: 1530 string unknown-name 1532 Each string contains the name of a principle that was unknown. 1534 SSH_FX_LOCK_CONFlICT 1535 The file could not be opened because it is locked by another 1536 process. 1538 The SSH_FXP_HANDLE response has the following format: 1540 byte SSH_FXP_HANDLE 1541 uint32 request-id 1542 string handle 1544 where 'request-id' is the request identifier, and 'handle' is an 1545 arbitrary string that identifies an open file or directory on the 1546 server. The handle is opaque to the client; the client MUST NOT 1547 attempt to interpret or modify it in any way. The length of the 1548 handle string MUST NOT exceed 256 data bytes. 1550 The SSH_FXP_DATA response has the following format: 1552 byte SSH_FXP_DATA 1553 uint32 request-id 1554 string data 1556 where 'request-id' is the request identifier, and 'data' is an 1557 arbitrary byte string containing the requested data. The data string 1558 may be at most the number of bytes requested in a SSH_FXP_READ 1559 request, but may also be shorter if end of file is reached or if the 1560 read is from something other than a regular file. 1562 The SSH_FXP_NAME response has the following format: 1564 byte SSH_FXP_NAME 1565 uint32 request-id 1566 uint32 count 1567 repeats count times: 1568 string filename [UTF-8] 1569 ATTRS attrs 1571 where 'request-id' is the request identifier, 'count' is the number 1572 of names returned in this response, and the remaining fields repeat 1573 'count' times. In the repeated part, 'filename' is a file name being 1574 returned (for SSH_FXP_READDIR, it will be a relative name within the 1575 directory, without any path components; for SSH_FXP_REALPATH it will 1576 be an absolute path name), and 'attrs' is the attributes of the file 1577 as described in Section ''File Attributes''. 1579 The SSH_FXP_ATTRS response has the following format: 1581 byte SSH_FXP_ATTRS 1582 uint32 request-id 1583 ATTRS attrs 1585 where 'request-id' is the request identifier, and 'attrs' is the 1586 returned file attributes as described in Section ''File Attributes''. 1588 8. Extensions 1590 The SSH_FXP_EXTENDED request provides a generic extension mechanism 1591 for adding additional commands. 1593 byte SSH_FXP_EXTENDED 1594 uint32 request-id 1595 string extended-request 1596 ... any request-specific data ... 1598 request-id 1599 Identifier to be returned from the server with the response. 1601 extended-request 1602 A string naming the extension. Vendor-specific extensions have 1603 use the "name@domain" syntax, where domain is an internet domain 1604 name of the vendor defining the request. 1606 The IETF may also define extensions to the protocol. These 1607 extension names will not have an '@' in them. 1609 request-specific data 1610 The rest of the request is defined by the extension, and servers 1611 should only attempt to interpret it if they recognize the 1612 'extended-request' name. 1614 The server may respond to such requests using any of the response 1615 packets defined in Section ''Responses from the Server to the 1616 Client''. Additionally, the server may also respond with a 1617 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 1618 not recognize the 'extended-request' name, then the server MUST 1619 respond with SSH_FXP_STATUS with error/status set to 1620 SSH_FX_OP_UNSUPPORTED. 1622 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 1623 extension-specific data from the server to the client. It is of the 1624 following format: 1626 byte SSH_FXP_EXTENDED_REPLY 1627 uint32 request-id 1628 ... any request-specific data ... 1630 There is a range of packet types reserved for use by extensions. In 1631 order to avoid collision, extensions that that use additional packet 1632 types should determine those numbers dynamically. 1634 The suggested way of doing this is have an extension request from the 1635 client to the server that enables the extension; the extension 1636 response from the server to the client would specify the actual type 1637 values to use, in additional to any other data. 1639 Extension authors should be mindful of the limited range of packet 1640 types available (there are only 45 values available) and avoid 1641 requiring a new packet type where possible. 1643 8.1 Checking File Contents 1645 This extension allows a client to easily check if a file (or portion 1646 thereof) that it already has matches what is on the server. 1648 byte SSH_FXP_EXTENDED 1649 uint32 request-id 1650 string "md5-hash" / "md5-hash-handle" 1651 string filename / file-handle 1652 uint64 start-offset 1653 uint64 length 1654 string quick-check-hash 1656 filename 1657 Used if "md5-hash" is specified; indicates the name of the file to 1658 use. 1660 file-handle 1661 Used if "md5-hash-handle" is specified; specifies a file handle to 1662 read the data from. The handle MUST be a file handle, and 1663 ACE4_READ_DATA MUST have been included in the desired-access when 1664 the fail was opened. 1666 start-offset 1667 The starting offset of the data to hash. 1669 length 1670 The length of data to include in the hash. If both start-offset 1671 and length are zero, the entire file should be included. 1673 quick-check-hash 1674 The hash over the first 2048 bytes of the data range as the client 1675 knows it, or the entire range, if it is less than 2048 bytes. 1676 This allows the server to quickly check if it is worth the 1677 resources to hash a big file. 1679 If this is a zero length string, the client does not have the 1680 data, and is requesting the hash for reasons other than comparing 1681 with a local file. The server MAY return SSH_FX_OP_UNSUPPORTED in 1682 this case. 1684 The response is either a SSH_FXP_STATUS packet, indicating an error, 1685 or the following extended reply packet: 1687 byte SSH_FXP_EXTENDED_REPLY 1688 uint32 request-id 1689 string "md5-hash" 1690 string hash 1692 If 'hash' is zero length, then the 'quick-check-hash' did not match, 1693 and no hash operation was preformed. Otherwise, 'hash' contains the 1694 hash of the entire data range (including the first 2048 bytes that 1695 were included in the 'quick-check-hash'.) 1697 9. Security Considerations 1699 It is assumed that both ends of the connection have been 1700 authenticated and that the connection has privacy and integrity 1701 features. Such security issues are left to the underlying transport 1702 protocol, except to note that if this is not the case, an attacker 1703 could manipulate files on the server at will and thus wholly 1704 compromise the server. 1706 This protocol provides file system access to arbitrary files on the 1707 server (only constrained by the server implementation). It is the 1708 responsibility of the server implementation to enforce any access 1709 controls that may be required to limit the access allowed for any 1710 particular user (the user being authenticated externally to this 1711 protocol, typically using the SSH User Authentication Protocol [8]. 1713 Extreme care must be used when interpreting file handle strings. In 1714 particular, care must be taken that a file handle string is valid in 1715 the context of a given SFTP session. For example, the sftp server 1716 daemon may have files which it has opened for its own purposes, and 1717 the client must not be able to access these files by specifying an 1718 arbitrary file handle string. 1720 The permission field of the attrib structure (Section 5.5) may 1721 include the SUID, SGID, and SVTX (sticky) bits. Clients should use 1722 extreme caution when setting these bits on either remote or local 1723 files. (I.e., just because a file was SUID on the remote system does 1724 not necessarily imply that it should be SUID on the local system.) 1726 Filesystems often contain entries for objects that are not files at 1727 all, but are rather devices. For example, it may be possible to 1728 access serial ports, tape devices, or named pipes using this 1729 protocol. Servers should exercise caution when granting access to 1730 such resources. In addition to the dangers inherent in allowing 1731 access to such a device, some devices may be 'slow', and could cause 1732 denial of service by causing the server to block for a long period of 1733 time while I/O is performed to such a device. 1735 Servers should take care that file-system quotas are respected for 1736 users. In addition, implementations should be aware that attacks may 1737 be possible, or facilitated, by filling a filesystem. For example, 1738 filling the filesystem where event logging and auditing occurs may, 1739 at best, cause the system to crash, or at worst, allow the attacker 1740 to take untraceable actions in the future. 1742 Servers should take care that filenames are in their appropriate 1743 canonical form, and to insure that filenames not in canonical form 1744 cannot be used to bypass access checks or controls. 1746 10. Changes from Previous Protocol Versions 1748 The SSH File Transfer Protocol has changed over time, before its 1749 standardization. The following is a description of the incompatible 1750 changes between different versions. 1752 10.1 Changes Between Versions 5 and 4 1754 Many of the changes between version 5 and version 4 are to better 1755 support the changes in version 4, and to better specify error 1756 conditions. 1758 o Add "supported" extension to communicate features supported. 1760 o Clarify error handling when client requests unsupported feature. 1761 (For example, attempts to write an unsupported attribute.) 1763 o Add attrib-bits field to the attribute structure, which specifies 1764 a number of boolean attributes related to files and directories, 1765 including advisory read-only and case-sensitivity bits. 1767 o Clarify the actual bit values to be used for the permissions field 1768 (since posix doesn't define values) and correct the value of 1769 ATTR_PERMISSIONS flag. 1771 o Some reordering of sections to attempt to get a better grouping of 1772 related functionality. 1774 o Open request explicitly specifies the access desired for the file. 1776 o Add support for explicitly requesting file locking. 1778 o Add support for better control of the rename operation. 1780 o Add SSH_FX_NO_SPACE_ON_FILESYSTEM, SSH_FX_QUOTA_EXCEEDED, and 1781 SSH_FX_UNKNOWN_PRINCIPLE error codes. 1783 o Add support for error specific data. This is used by a new 1784 SSH_FX_UNKNOWN_PRINCIPLE error to communicate which principles are 1785 unknown. 1787 o Add support for retrieving md5-hash of file contents. 1789 o Update security section. 1791 10.2 Changes Between Versions 4 and 3 1793 Many of the changes between version 4 and version 3 are to the 1794 attribute structure to make it more flexible for non-unix platforms. 1796 o Clarify the use of stderr by the server. 1798 o Clarify handling of very large read requests by the server. 1800 o Make all filenames UTF-8. 1802 o Added 'newline' extension. 1804 o Made time fields 64 bit, and optionally have nanosecond 1805 resolution. 1807 o Made file attribute owner and group strings so they can actually 1808 be used on disparate systems. 1810 o Added createtime field, and added separate flags for atime, 1811 createtime, and mtime so they can be set separately. 1813 o Split the file type out of the permissions field and into its own 1814 field (which is always present.) 1816 o Added acl attribute. 1818 o Added SSH_FXF_TEXT file open flag. 1820 o Added flags field to the get stat commands so that the client can 1821 specifically request information the server might not normally 1822 included for performance reasons. 1824 o Removed the long filename from the names structure-- it can now be 1825 built from information available in the attrs structure. 1827 o Added reserved range of packet numbers for extensions. 1829 o Added several additional error codes. 1831 10.3 Changes Between Versions 3 and 2 1833 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. 1835 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were 1836 added. 1838 o The SSH_FXP_STATUS message was changed to include fields 'error 1839 message' and 'language tag'. 1841 10.4 Changes Between Versions 2 and 1 1843 o The SSH_FXP_RENAME message was added. 1845 10.5 Changes Between Versions 1 and 0 1847 o Implementation changes, no actual protocol changes. 1849 11. Trademark Issues 1851 "ssh" is a registered trademark of SSH Communications Security Corp 1852 in the United States and/or other countries. 1854 Normative References 1856 [1] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, 1857 C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC 1858 3010, December 2000. 1860 [2] Institute of Electrical and Electronics Engineers, "Information 1861 Technology - Portable Operating System Interface (POSIX) - Part 1862 1: System Application Program Interface (API) [C Language]", 1863 IEEE Standard 1003.2, 1996. 1865 [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 1866 Lehtinen, "SSH Protocol Architecture", 1867 draft-ietf-secsh-architecture-13 (work in progress), September 1868 2002. 1870 [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 1871 Lehtinen, "SSH Protocol Transport Protocol", 1872 draft-ietf-secsh-transport-15 (work in progress), September 1873 2002. 1875 [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 1876 Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16 1877 (work in progress), September 2002. 1879 Informative References 1881 [6] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and 1882 P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January 1883 1999. 1885 [7] Alvestrand, H., "IETF Policy on Character Sets and Languages", 1886 BCP 18, RFC 2277, January 1998. 1888 [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 1889 Lehtinen, "SSH Authentication Protocol", 1890 draft-ietf-secsh-userauth-16 (work in progress), September 2002. 1892 Authors' Addresses 1894 Joseph Galbraith 1895 VanDyke Software 1896 4848 Tramway Ridge Blvd 1897 Suite 101 1898 Albuquerque, NM 87111 1899 US 1901 Phone: +1 505 332 5700 1902 EMail: galb-list@vandyke.com 1904 Tatu Ylonen 1905 SSH Communications Security Corp 1906 Fredrikinkatu 42 1907 HELSINKI FIN-00100 1908 Finland 1910 EMail: ylo@ssh.com 1912 Sami Lehtinen 1913 SSH Communications Security Corp 1914 Fredrikinkatu 42 1915 HELSINKI FIN-00100 1916 Finland 1918 EMail: sjl@ssh.com 1920 Intellectual Property Statement 1922 The IETF takes no position regarding the validity or scope of any 1923 intellectual property or other rights that might be claimed to 1924 pertain to the implementation or use of the technology described in 1925 this document or the extent to which any license under such rights 1926 might or might not be available; neither does it represent that it 1927 has made any effort to identify any such rights. Information on the 1928 IETF's procedures with respect to rights in standards-track and 1929 standards-related documentation can be found in BCP-11. Copies of 1930 claims of rights made available for publication and any assurances of 1931 licenses to be made available, or the result of an attempt made to 1932 obtain a general license or permission for the use of such 1933 proprietary rights by implementors or users of this specification can 1934 be obtained from the IETF Secretariat. 1936 The IETF invites any interested party to bring to its attention any 1937 copyrights, patents or patent applications, or other proprietary 1938 rights which may cover technology that may be required to practice 1939 this standard. Please address the information to the IETF Executive 1940 Director. 1942 Full Copyright Statement 1944 Copyright (C) The Internet Society (2004). All Rights Reserved. 1946 This document and translations of it may be copied and furnished to 1947 others, and derivative works that comment on or otherwise explain it 1948 or assist in its implementation may be prepared, copied, published 1949 and distributed, in whole or in part, without restriction of any 1950 kind, provided that the above copyright notice and this paragraph are 1951 included on all such copies and derivative works. However, this 1952 document itself may not be modified in any way, such as by removing 1953 the copyright notice or references to the Internet Society or other 1954 Internet organizations, except as needed for the purpose of 1955 developing Internet standards in which case the procedures for 1956 copyrights defined in the Internet Standards process must be 1957 followed, or as required to translate it into languages other than 1958 English. 1960 The limited permissions granted above are perpetual and will not be 1961 revoked by the Internet Society or its successors or assignees. 1963 This document and the information contained herein is provided on an 1964 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1965 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1966 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1967 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1968 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1970 Acknowledgment 1972 Funding for the RFC Editor function is currently provided by the 1973 Internet Society.