idnits 2.17.1 draft-ietf-secsh-filexfer-02.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.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 4 instances of too long lines in the document, the longest one being 6 characters in excess of 72. ** There are 136 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 135: '...d). All servers SHOULD support packet...' RFC 2119 keyword, line 182: '...d, and their use MUST be negotiated us...' RFC 2119 keyword, line 217: '...rs (both strings MUST always be presen...' RFC 2119 keyword, line 224: '... Implementations MUST silently ignore ...' RFC 2119 keyword, line 284: '... Implementations SHOULD ignore extende...' (18 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 247 has weird spacing: '...issions pre...' == Line 251 has weird spacing: '... string exte...' == Line 252 has weird spacing: '... string exte...' -- 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 (October 2001) is 8229 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) -- Looks like a reference, but probably isn't: 'RFC-2279' on line 761 -- Looks like a reference, but probably isn't: 'RFC-1766' on line 762 == Unused Reference: '2' is defined on line 985, but no explicit reference was found in the text == Unused Reference: '4' is defined on line 994, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2246 (ref. '1') (Obsoleted by RFC 4346) -- Possible downref: Non-RFC (?) normative reference: ref. '2' == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-09 == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-09 -- Duplicate reference: draft-ietf-secsh-architecture, mentioned in '4', was also mentioned in '3'. == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-11 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-11 Summary: 7 errors (**), 0 flaws (~~), 11 warnings (==), 6 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group T. Ylonen 3 Internet-Draft S. Lehtinen 4 Expires: April 1, 2002 SSH Communications Security Corp 5 October 2001 7 SSH File Transfer Protocol 8 draft-ietf-secsh-filexfer-02.txt 10 Status of this Memo 12 This document is an Internet-Draft and is in full conformance with 13 all provisions of Section 10 of RFC2026. 15 Internet-Drafts are working documents of the Internet Engineering 16 Task Force (IETF), its areas, and its working groups. Note that 17 other groups may also distribute working documents as Internet- 18 Drafts. 20 Internet-Drafts are draft documents valid for a maximum of six months 21 and may be updated, replaced, or obsoleted by other documents at any 22 time. It is inappropriate to use Internet-Drafts as reference 23 material or to cite them other than as "work in progress." 25 The list of current Internet-Drafts can be accessed at http:// 26 www.ietf.org/ietf/1id-abstracts.txt. 28 The list of Internet-Draft Shadow Directories can be accessed at 29 http://www.ietf.org/shadow.html. 31 This Internet-Draft will expire on April 1, 2002. 33 Copyright Notice 35 Copyright (C) The Internet Society (2001). All Rights Reserved. 37 Abstract 39 The SSH File Transfer Protocol provides secure file transfer 40 functionality over any reliable data stream. It is the standard file 41 transfer protocol for use with the SSH2 protocol. This document 42 describes the file transfer protocol and its interface to the SSH2 43 protocol suite. 45 Table of Contents 47 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 48 2. Use with the SSH Connection Protocol . . . . . . . . . . . . 4 49 3. General Packet Format . . . . . . . . . . . . . . . . . . . 5 50 4. Protocol Initialization . . . . . . . . . . . . . . . . . . 7 51 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . 8 52 6. Requests From the Client to the Server . . . . . . . . . . . 10 53 6.1 Request Synchronization and Reordering . . . . . . . . . . . 10 54 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . . 11 55 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . . 11 56 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . . 13 57 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . . 14 58 6.6 Creating and Deleting Directories . . . . . . . . . . . . . 15 59 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . . 15 60 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . . 16 61 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . . 17 62 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . . 18 63 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . . 18 64 7. Responses from the Server to the Client . . . . . . . . . . 20 65 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . 24 66 9. Security Considerations . . . . . . . . . . . . . . . . . . 25 67 10. Changes from previous protocol versions . . . . . . . . . . 26 68 10.1 Changes between versions 3 and 2 . . . . . . . . . . . . . . 26 69 10.2 Changes between versions 2 and 1 . . . . . . . . . . . . . . 26 70 10.3 Changes between versions 1 and 0 . . . . . . . . . . . . . . 26 71 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 27 72 References . . . . . . . . . . . . . . . . . . . . . . . . . 28 73 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . 28 74 Full Copyright Statement . . . . . . . . . . . . . . . . . . 29 76 1. Introduction 78 This protocol provides secure file transfer (and more generally file 79 system access) functionality over a reliable data stream, such as a 80 channel in the SSH2 protocol [3]. 82 This protocol is designed so that it could be used to implement a 83 secure remote file system service, as well as a secure file transfer 84 service. 86 This protocol assumes that it runs over a secure channel, and that 87 the server has already authenticated the user at the client end, and 88 that the identity of the client user is externally available to the 89 server implementation. 91 In general, this protocol follows a simple request-response model. 92 Each request and response contains a sequence number and multiple 93 requests may be pending simultaneously. There are a relatively large 94 number of different request messages, but a small number of possible 95 response messages. Each request has one or more response messages 96 that may be returned in result (e.g., a read either returns data or 97 reports error status). 99 The packet format descriptions in this specification follow the 100 notation presented in the secsh architecture draft.[3]. 102 Even though this protocol is described in the context of the SSH2 103 protocol, this protocol is general and independent of the rest of the 104 SSH2 protocol suite. It could be used in a number of different 105 applications, such as secure file transfer over TLS RFC 2246 [1] and 106 transfer of management information in VPN applications. 108 2. Use with the SSH Connection Protocol 110 When used with the SSH2 Protocol suite, this protocol is intended to 111 be used from the SSH Connection Protocol [5] as a subsystem, as 112 described in section ``Starting a Shell or a Command''. The 113 subsystem name used with this protocol is "sftp". 115 3. General Packet Format 117 All packets transmitted over the secure connection are of the 118 following format: 120 uint32 length 121 byte type 122 byte[length - 1] data payload 124 That is, they are just data preceded by 32-bit length and 8-bit type 125 fields. The `length' is the length of the data area, and does not 126 include the `length' field itself. The format and interpretation of 127 the data area depends on the packet type. 129 All packet descriptions below only specify the packet type and the 130 data that goes into the data field. Thus, they should be prefixed by 131 the `length' and `type' fields. 133 The maximum size of a packet is in practice determined by the client 134 (the maximum size of read or write requests that it sends, plus a few 135 bytes of packet overhead). All servers SHOULD support packets of at 136 least 34000 bytes (where the packet size refers to the full length, 137 including the header above). This should allow for reads and writes 138 of at most 32768 bytes. 140 There is no limit on the number of outstanding (non-acknowledged) 141 requests that the client may send to the server. In practice this is 142 limited by the buffering available on the data stream and the queuing 143 performed by the server. If the server's queues are full, it should 144 not read any more data from the stream, and flow control will prevent 145 the client from sending more requests. Note, however, that while 146 there is no restriction on the protocol level, the client's API may 147 provide a limit in order to prevent infinite queuing of outgoing 148 requests at the client. 150 The following values are defined for packet types. 152 #define SSH_FXP_INIT 1 153 #define SSH_FXP_VERSION 2 154 #define SSH_FXP_OPEN 3 155 #define SSH_FXP_CLOSE 4 156 #define SSH_FXP_READ 5 157 #define SSH_FXP_WRITE 6 158 #define SSH_FXP_LSTAT 7 159 #define SSH_FXP_FSTAT 8 160 #define SSH_FXP_SETSTAT 9 161 #define SSH_FXP_FSETSTAT 10 162 #define SSH_FXP_OPENDIR 11 163 #define SSH_FXP_READDIR 12 164 #define SSH_FXP_REMOVE 13 165 #define SSH_FXP_MKDIR 14 166 #define SSH_FXP_RMDIR 15 167 #define SSH_FXP_REALPATH 16 168 #define SSH_FXP_STAT 17 169 #define SSH_FXP_RENAME 18 170 #define SSH_FXP_READLINK 19 171 #define SSH_FXP_SYMLINK 20 172 #define SSH_FXP_STATUS 101 173 #define SSH_FXP_HANDLE 102 174 #define SSH_FXP_DATA 103 175 #define SSH_FXP_NAME 104 176 #define SSH_FXP_ATTRS 105 177 #define SSH_FXP_EXTENDED 200 178 #define SSH_FXP_EXTENDED_REPLY 201 180 Additional packet types should only be defined if the protocol 181 version number (see Section ``Protocol Initialization'') is 182 incremented, and their use MUST be negotiated using the version 183 number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY 184 packets can be used to implement vendor-specific extensions. See 185 Section ``Vendor-Specific-Extensions'' for more details. 187 4. Protocol Initialization 189 When the file transfer protocol starts, it first sends a SSH_FXP_INIT 190 (including its version number) packet to the server. The server 191 responds with a SSH_FXP_VERSION packet, supplying the lowest of its 192 own and the client's version number. Both parties should from then 193 on adhere to particular version of the protocol. 195 The SSH_FXP_INIT packet (from client to server) has the following 196 data: 198 uint32 version 199 201 The SSH_FXP_VERSION packet (from server to client) has the following 202 data: 204 uint32 version 205 207 The version number of the protocol specified in this document is 3. 208 The version number should be incremented for each incompatible 209 revision of this protocol. 211 The extension data in the above packets may be empty, or may be a 212 sequence of 214 string extension_name 215 string extension_data 217 pairs (both strings MUST always be present if one is, but the 218 `extension_data' string may be of zero length). If present, these 219 strings indicate extensions to the baseline protocol. The 220 `extension_name' field(s) identify the name of the extension. The 221 name should be of the form "name@domain", where the domain is the DNS 222 domain name of the organization defining the extension. Additional 223 names that are not of this format may be defined later by the IETF. 224 Implementations MUST silently ignore any extensions whose name they 225 do not recognize. 227 5. File Attributes 229 A new compound data type is defined for encoding file attributes. It 230 is basically just a combination of elementary types, but is defined 231 once because of the non-trivial description of the fields and to 232 ensure maintainability. 234 The same encoding is used both when returning file attributes from 235 the server and when sending file attributes to the server. When 236 sending it to the server, the flags field specifies which attributes 237 are included, and the server will use default values for the 238 remaining attributes (or will not modify the values of remaining 239 attributes). When receiving attributes from the server, the flags 240 specify which attributes are included in the returned data. The 241 server normally returns all attributes it knows about. 243 uint32 flags 244 uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE 245 uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID 246 uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID 247 uint32 permissions present only if flag SSH_FILEXFER_ATTR_PERMISSIONS 248 uint32 atime present only if flag SSH_FILEXFER_ACMODTIME 249 uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME 250 uint32 extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED 251 string extended_type 252 string extended_data 253 ... more extended data (extended_type - extended_data pairs), 254 so that number of pairs equals extended_count 256 The `flags' specify which of the fields are present. Those fields 257 for which the corresponding flag is not set are not present (not 258 included in the packet). New flags can only be added by incrementing 259 the protocol version number (or by using the extension mechanism 260 described below). 262 The `size' field specifies the size of the file in bytes. 264 The `uid' and `gid' fields contain numeric Unix-like user and group 265 identifiers, respectively. 267 The `permissions' field contains a bit mask of file permissions as 268 defined by posix [1]. 270 The `atime' and `mtime' contain the access and modification times of 271 the files, respectively. They are represented as seconds from Jan 1, 272 1970 in UTC. 274 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 275 mechanism for vendor-specific extensions. If the flag is specified, 276 then the `extended_count' field is present. It specifies the number 277 of extended_type-extended_data pairs that follow. Each of these 278 pairs specifies an extended attribute. For each of the attributes, 279 the extended_type field should be a string of the format 280 "name@domain", where "domain" is a valid, registered domain name and 281 "name" identifies the method. The IETF may later standardize certain 282 names that deviate from this format (e.g., that do not contain the 283 "@" sign). The interpretation of `extended_data' depends on the 284 type. Implementations SHOULD ignore extended data fields that they 285 do not understand. 287 Additional fields can be added to the attributes by either defining 288 additional bits to the flags field to indicate their presence, or by 289 defining extended attributes for them. The extended attributes 290 mechanism is recommended for most purposes; additional flags bits 291 should only be defined by an IETF standards action that also 292 increments the protocol version number. The use of such new fields 293 MUST be negotiated by the version number in the protocol exchange. 294 It is a protocol error if a packet with unsupported protocol bits is 295 received. 297 The flags bits are defined to have the following values: 299 #define SSH_FILEXFER_ATTR_SIZE 0x00000001 300 #define SSH_FILEXFER_ATTR_UIDGID 0x00000002 301 #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 302 #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008 303 #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 305 6. Requests From the Client to the Server 307 Requests from the client to the server represent the various file 308 system operations. Each request begins with an `id' field, which is 309 a 32-bit identifier identifying the request (selected by the client). 310 The same identifier will be returned in the response to the request. 311 One possible implementation of it is a monotonically increasing 312 request sequence number (modulo 2^32). 314 Many operations in the protocol operate on open files. The 315 SSH_FXP_OPEN request can return a file handle (which is an opaque 316 variable-length string) which may be used to access the file later 317 (e.g. in a read operation). The client MUST NOT send requests the 318 server with bogus or closed handles. However, the server MUST 319 perform adequate checks on the handle in order to avoid security 320 risks due to fabricated handles. 322 This design allows either stateful and stateless server 323 implementation, as well as an implementation which caches state 324 between requests but may also flush it. The contents of the file 325 handle string are entirely up to the server and its design. The 326 client should not modify or attempt to interpret the file handle 327 strings. 329 The file handle strings MUST NOT be longer than 256 bytes. 331 6.1 Request Synchronization and Reordering 333 The protocol and implementations MUST process requests relating to 334 the same file in the order in which they are received. In other 335 words, if an application submits multiple requests to the server, the 336 results in the responses will be the same as if it had sent the 337 requests one at a time and waited for the response in each case. For 338 example, the server may process non-overlapping read/write requests 339 to the same file in parallel, but overlapping reads and writes cannot 340 be reordered or parallelized. However, there are no ordering 341 restrictions on the server for processing requests from two different 342 file transfer connections. The server may interleave and parallelize 343 them at will. 345 There are no restrictions on the order in which responses to 346 outstanding requests are delivered to the client, except that the 347 server must ensure fairness in the sense that processing of no 348 request will be indefinitely delayed even if the client is sending 349 other requests so that there are multiple outstanding requests all 350 the time. 352 6.2 File Names 354 This protocol represents file names as strings. File names are 355 assumed to use the slash ('/') character as a directory separator. 357 File names starting with a slash are "absolute", and are relative to 358 the root of the file system. Names starting with any other character 359 are relative to the user's default directory (home directory). Note 360 that identifying the user is assumed to take place outside of this 361 protocol. 363 Servers SHOULD interpret a path name component ".." as referring to 364 the parent directory, and "." as referring to the current directory. 365 If the server implementation limits access to certain parts of the 366 file system, it must be extra careful in parsing file names when 367 enforcing such restrictions. There have been numerous reported 368 security bugs where a ".." in a path name has allowed access outside 369 the intended area. 371 An empty path name is valid, and it refers to the user's default 372 directory (usually the user's home directory). 374 Otherwise, no syntax is defined for file names by this specification. 375 Clients should not make any other assumptions; however, they can 376 splice path name components returned by SSH_FXP_READDIR together 377 using a slash ('/') as the separator, and that will work as expected. 379 It is understood that the lack of well-defined semantics for file 380 names may cause interoperability problems between clients and servers 381 using radically different operating systems. However, this approach 382 is known to work acceptably with most systems, and alternative 383 approaches that e.g. treat file names as sequences of structured 384 components are quite complicated. 386 6.3 Opening, Creating, and Closing Files 388 Files are opened and created using the SSH_FXP_OPEN message, whose 389 data part is as follows: 391 uint32 id 392 string filename 393 uint32 pflags 394 ATTRS attrs 396 The `id' field is the request identifier as for all requests. 398 The `filename' field specifies the file name. See Section ``File 399 Names'' for more information. 401 The `pflags' field is a bitmask. The following bits have been 402 defined. 404 #define SSH_FXF_READ 0x00000001 405 #define SSH_FXF_WRITE 0x00000002 406 #define SSH_FXF_APPEND 0x00000004 407 #define SSH_FXF_CREAT 0x00000008 408 #define SSH_FXF_TRUNC 0x00000010 409 #define SSH_FXF_EXCL 0x00000020 411 These have the following meanings: 413 SSH_FXF_READ 414 Open the file for reading. 416 SSH_FXF_WRITE 417 Open the file for writing. If both this and SSH_FXF_READ are 418 specified, the file is opened for both reading and writing. 420 SSH_FXF_APPEND 421 Force all writes to append data at the end of the file. 423 SSH_FXF_CREAT 424 If this flag is specified, then a new file will be created if one 425 does not already exist (if O_TRUNC is specified, the new file will 426 be truncated to zero length if it previously exists). 428 SSH_FXF_TRUNC 429 Forces an existing file with the same name to be truncated to zero 430 length when creating a file by specifying SSH_FXF_CREAT. 431 SSH_FXF_CREAT MUST also be specified if this flag is used. 433 SSH_FXF_EXCL 434 Causes the request to fail if the named file already exists. 435 SSH_FXF_CREAT MUST also be specified if this flag is used. 437 The `attrs' field specifies the initial attributes for the file. 438 Default values will be used for those attributes that are not 439 specified. See Section ``File Attributes'' for more information. 441 Regardless the server operating system, the file will always be 442 opened in "binary" mode (i.e., no translations between different 443 character sets and newline encodings). 445 The response to this message will be either SSH_FXP_HANDLE (if the 446 operation is successful) or SSH_FXP_STATUS (if the operation fails). 448 A file is closed by using the SSH_FXP_CLOSE request. Its data field 449 has the following format: 451 uint32 id 452 string handle 454 where `id' is the request identifier, and `handle' is a handle 455 previously returned in the response to SSH_FXP_OPEN or 456 SSH_FXP_OPENDIR. The handle becomes invalid immediately after this 457 request has been sent. 459 The response to this request will be a SSH_FXP_STATUS message. One 460 should note that on some server platforms even a close can fail. 461 This can happen e.g. if the server operating system caches writes, 462 and an error occurs while flushing cached writes during the close. 464 6.4 Reading and Writing 466 Once a file has been opened, it can be read using the SSH_FXP_READ 467 message, which has the following format: 469 uint32 id 470 string handle 471 uint64 offset 472 uint32 len 474 where `id' is the request identifier, `handle' is an open file handle 475 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative 476 to the beginning of the file from where to start reading, and `len' 477 is the maximum number of bytes to read. 479 In response to this request, the server will read as many bytes as it 480 can from the file (up to `len'), and return them in a SSH_FXP_DATA 481 message. If an error occurs or EOF is encountered before reading any 482 data, the server will respond with SSH_FXP_STATUS. For normal disk 483 files, it is guaranteed that this will read the specified number of 484 bytes, or up to end of file. For e.g. device files this may return 485 fewer bytes than requested. 487 Writing to a file is achieved using the SSH_FXP_WRITE message, which 488 has the following format: 490 uint32 id 491 string handle 492 uint64 offset 493 string data 495 where `id' is a request identifier, `handle' is a file handle 496 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the 497 beginning of the file where to start writing, and `data' is the data 498 to be written. 500 The write will extend the file if writing beyond the end of the file. 501 It is legal to write way beyond the end of the file; the semantics 502 are to write zeroes from the end of the file to the specified offset 503 and then the data. On most operating systems, such writes do not 504 allocate disk space but instead leave "holes" in the file. 506 The server responds to a write request with a SSH_FXP_STATUS message. 508 6.5 Removing and Renaming Files 510 Files can be removed using the SSH_FXP_REMOVE message. It has the 511 following format: 513 uint32 id 514 string filename 516 where `id' is the request identifier and `filename' is the name of 517 the file to be removed. See Section ``File Names'' for more 518 information. This request cannot be used to remove directories. 520 The server will respond to this request with a SSH_FXP_STATUS 521 message. 523 Files (and directories) can be renamed using the SSH_FXP_RENAME 524 message. Its data is as follows: 526 uint32 id 527 string oldpath 528 string newpath 530 where `id' is the request identifier, `oldpath' is the name of an 531 existing file or directory, and `newpath' is the new name for the 532 file or directory. It is an error if there already exists a file 533 with the name specified by newpath. The server may also fail rename 534 requests in other situations, for example if `oldpath' and `newpath' 535 point to different file systems on the server. 537 The server will respond to this request with a SSH_FXP_STATUS 538 message. 540 6.6 Creating and Deleting Directories 542 New directories can be created using the SSH_FXP_MKDIR request. It 543 has the following format: 545 uint32 id 546 string path 547 ATTRS attrs 549 where `id' is the request identifier, `path' and `attrs' specifies 550 the modifications to be made to its attributes. See Section ``File 551 Names'' for more information on file names. Attributes are discussed 552 in more detail in Section ``File Attributes''. specifies the 553 directory to be created. An error will be returned if a file or 554 directory with the specified path already exists. The server will 555 respond to this request with a SSH_FXP_STATUS message. 557 Directories can be removed using the SSH_FXP_RMDIR request, which 558 has the following format: 560 uint32 id 561 string path 563 where `id' is the request identifier, and `path' specifies the 564 directory to be removed. See Section ``File Names'' for more 565 information on file names. An error will be returned if no directory 566 with the specified path exists, or if the specified directory is not 567 empty, or if the path specified a file system object other than a 568 directory. The server responds to this request with a SSH_FXP_STATUS 569 message. 571 6.7 Scanning Directories 573 The files in a directory can be listed using the SSH_FXP_OPENDIR and 574 SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one 575 or more file names with full file attributes for each file. The 576 client should call SSH_FXP_READDIR repeatedly until it has found the 577 file it is looking for or until the server responds with a 578 SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if 579 there are no more files in the directory). The client should then 580 close the handle using the SSH_FXP_CLOSE request. 582 The SSH_FXP_OPENDIR opens a directory for reading. It has the 583 following format: 585 uint32 id 586 string path 588 where `id' is the request identifier and `path' is the path name of 589 the directory to be listed (without any trailing slash). See Section 590 ``File Names'' for more information on file names. This will return 591 an error if the path does not specify a directory or if the directory 592 is not readable. The server will respond to this request with either 593 a SSH_FXP_HANDLE or a SSH_FXP_STATUS message. 595 Once the directory has been successfully opened, files (and 596 directories) contained in it can be listed using SSH_FXP_READDIR 597 requests. These are of the format 599 uint32 id 600 string handle 602 where `id' is the request identifier, and `handle' is a handle 603 returned by SSH_FXP_OPENDIR. (It is a protocol error to attempt to 604 use an ordinary file handle returned by SSH_FXP_OPEN.) 606 The server responds to this request with either a SSH_FXP_NAME or a 607 SSH_FXP_STATUS message. One or more names may be returned at a time. 608 Full status information is returned for each name in order to speed 609 up typical directory listings. 611 When the client no longer wishes to read more names from the 612 directory, it SHOULD call SSH_FXP_CLOSE for the handle. The handle 613 should be closed regardless of whether an error has occurred or not. 615 6.8 Retrieving File Attributes 617 Very often, file attributes are automatically returned by 618 SSH_FXP_READDIR. However, sometimes there is need to specifically 619 retrieve the attributes for a named file. This can be done using the 620 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 622 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT 623 follows symbolic links on the server, whereas SSH_FXP_LSTAT does not 624 follow symbolic links. Both have the same format: 626 uint32 id 627 string path 629 where `id' is the request identifier, and `path' specifies the file 630 system object for which status is to be returned. The server 631 responds to this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS. 633 SSH_FXP_FSTAT differs from the others in that it returns status 634 information for an open file (identified by the file handle). Its 635 format is as follows: 637 uint32 id 638 string handle 640 where `id' is the request identifier and `handle' is a file handle 641 returned by SSH_FXP_OPEN. The server responds to this request with 642 SSH_FXP_ATTRS or SSH_FXP_STATUS. 644 6.9 Setting File Attributes 646 File attributes may be modified using the SSH_FXP_SETSTAT and 647 SSH_FXP_FSETSTAT requests. These requests are used for operations 648 such as changing the ownership, permissions or access times, as well 649 as for truncating a file. 651 The SSH_FXP_SETSTAT request is of the following format: 653 uint32 id 654 string path 655 ATTRS attrs 657 where `id' is the request identifier, `path' specifies the file 658 system object (e.g. file or directory) whose attributes are to be 659 modified, and `attrs' specifies the modifications to be made to its 660 attributes. Attributes are discussed in more detail in Section 661 ``File Attributes''. 663 An error will be returned if the specified file system object does 664 not exist or the user does not have sufficient rights to modify the 665 specified attributes. The server responds to this request with a 666 SSH_FXP_STATUS message. 668 The SSH_FXP_FSETSTAT request modifies the attributes of a file which 669 is already open. It has the following format: 671 uint32 id 672 string handle 673 ATTRS attrs 675 where `id' is the request identifier, `handle' (MUST be returned by 676 SSH_FXP_OPEN) identifies the file whose attributes are to be 677 modified, and `attrs' specifies the modifications to be made to its 678 attributes. Attributes are discussed in more detail in Section 679 ``File Attributes''. The server will respond to this request with 680 SSH_FXP_STATUS. 682 6.10 Dealing with Symbolic links 684 The SSH_FXP_READLINK request may be used to read the target of a 685 symbolic link. It would have a data part as follows: 687 uint32 id 688 string path 690 where `id' is the request identifier and `path' specifies the path 691 name of the symlink to be read. 693 The server will respond with a SSH_FXP_NAME packet containing only 694 one name and a dummy attributes value. The name in the returned 695 packet contains the target of the link. If an error occurs, the 696 server may respond with SSH_FXP_STATUS. 698 The SSH_FXP_SYMLINK request will create a symbolic link on the 699 server. It is of the following format 701 uint32 id 702 string linkpath 703 string targetpath 705 where `id' is the request identifier, `linkpath' specifies the path 706 name of the symlink to be created and `targetpath' specifies the 707 target of the symlink. The server shall respond with a 708 SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error 709 condition. 711 6.11 Canonicalizing the Server-Side Path Name 713 The SSH_FXP_REALPATH request can be used to have the server 714 canonicalize any given path name to an absolute path. This is useful 715 for converting path names containing ".." components or relative 716 pathnames without a leading slash into absolute paths. The format of 717 the request is as follows: 719 uint32 id 720 string path 722 where `id' is the request identifier and `path' specifies the path 723 name to be canonicalized. The server will respond with a 724 SSH_FXP_NAME packet containing only one name and a dummy attributes 725 value. The name is the returned packet will be in canonical form. 727 If an error occurs, the server may also respond with SSH_FXP_STATUS. 729 7. Responses from the Server to the Client 731 The server responds to the client using one of a few response 732 packets. All requests can return a SSH_FXP_STATUS response upon 733 failure. When the operation is successful, any of the responses may 734 be returned (depending on the operation). If no data needs to be 735 returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK 736 status is appropriate. Otherwise, the SSH_FXP_HANDLE message is used 737 to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR 738 requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ, 739 SSH_FXP_NAME is used to return one or more file names from a 740 SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is 741 used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and 742 SSH_FXP_FSTAT requests. 744 Exactly one response will be returned for each request. Each 745 response packet contains a request identifier which can be used to 746 match each response with the corresponding request. Note that it is 747 legal to have several requests outstanding simultaneously, and the 748 server is allowed to send responses to them in a different order from 749 the order in which the requests were sent (the result of their 750 execution, however, is guaranteed to be as if they had been processed 751 one at a time in the order in which the requests were sent). 753 Response packets are of the same general format as request packets. 754 Each response packet begins with the request identifier. 756 The format of the data portion of the SSH_FXP_STATUS response is as 757 follows: 759 uint32 id 760 uint32 error/status code 761 string error message (ISO-10646 UTF-8 [RFC-2279]) 762 string language tag (as defined in [RFC-1766]) 764 where `id' is the request identifier, and `error/status code' 765 indicates the result of the requested operation. The value SSH_FX_OK 766 indicates success, and all other values indicate failure. 768 Currently, the following values are defined (other values may be 769 defined by future versions of this protocol): 771 #define SSH_FX_OK 0 772 #define SSH_FX_EOF 1 773 #define SSH_FX_NO_SUCH_FILE 2 774 #define SSH_FX_PERMISSION_DENIED 3 775 #define SSH_FX_FAILURE 4 776 #define SSH_FX_BAD_MESSAGE 5 777 #define SSH_FX_NO_CONNECTION 6 778 #define SSH_FX_CONNECTION_LOST 7 779 #define SSH_FX_OP_UNSUPPORTED 8 781 SSH_FX_OK 782 Indicates successful completion of the operation. 784 SSH_FX_EOF 785 indicates end-of-file condition; for SSH_FX_READ it means that no 786 more data is available in the file, and for SSH_FX_READDIR it 787 indicates that no more files are contained in the directory. 789 SSH_FX_NO_SUCH_FILE 790 is returned when a reference is made to a file which should exist 791 but doesn't. 793 SSH_FX_PERMISSION_DENIED 794 is returned when the authenticated user does not have sufficient 795 permissions to perform the operation. 797 SSH_FX_FAILURE 798 is a generic catch-all error message; it should be returned if an 799 error occurs for which there is no more specific error code 800 defined. 802 SSH_FX_BAD_MESSAGE 803 may be returned if a badly formatted packet or protocol 804 incompatibility is detected. 806 SSH_FX_NO_CONNECTION 807 is a pseudo-error which indicates that the client has no 808 connection to the server (it can only be generated locally by the 809 client, and MUST NOT be returned by servers). 811 SSH_FX_CONNECTION_LOST 812 is a pseudo-error which indicates that the connection to the 813 server has been lost (it can only be generated locally by the 814 client, and MUST NOT be returned by servers). 816 SSH_FX_OP_UNSUPPORTED 817 indicates that an attempt was made to perform an operation which 818 is not supported for the server (it may be generated locally by 819 the client if e.g. the version number exchange indicates that a 820 required feature is not supported by the server, or it may be 821 returned by the server if the server does not implement an 822 operation). 824 The SSH_FXP_HANDLE response has the following format: 826 uint32 id 827 string handle 829 where `id' is the request identifier, and `handle' is an arbitrary 830 string that identifies an open file or directory on the server. The 831 handle is opaque to the client; the client MUST NOT attempt to 832 interpret or modify it in any way. The length of the handle string 833 MUST NOT exceed 256 data bytes. 835 The SSH_FXP_DATA response has the following format: 837 uint32 id 838 string data 840 where `id' is the request identifier, and `data' is an arbitrary byte 841 string containing the requested data. The data string may be at most 842 the number of bytes requested in a SSH_FXP_READ request, but may also 843 be shorter if end of file is reached or if the read is from something 844 other than a regular file. 846 The SSH_FXP_NAME response has the following format: 848 uint32 id 849 uint32 count 850 repeats count times: 851 string filename 852 string longname 853 ATTRS attrs 855 where `id' is the request identifier, `count' is the number of names 856 returned in this response, and the remaining fields repeat `count' 857 times (so that all three fields are first included for the first 858 file, then for the second file, etc). In the repeated part, 859 `filename' is a file name being returned (for SSH_FXP_READDIR, it 860 will be a relative name within the directory, without any path 861 components; for SSH_FXP_REALPATH it will be an absolute path name), 862 `longname' is an expanded format for the file name, similar to what 863 is returned by "ls -l" on Unix systems, and `attrs' is the attributes 864 of the file as described in Section ``File Attributes''. 866 The format of the `longname' field is unspecified by this protocol. 867 It MUST be suitable for use in the output of a directory listing 868 command (in fact, the recommended operation for a directory listing 869 command is to simply display this data). However, clients SHOULD NOT 870 attempt to parse the longname field for file attributes; they SHOULD 871 use the attrs field instead. 873 The recommended format for the longname field is as follows: 875 -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer 876 1234567890 123 12345678 12345678 12345678 123456789012 878 Here, the first line is sample output, and the second field indicates 879 widths of the various fields. Fields are separated by spaces. The 880 first field lists file permissions for user, group, and others; the 881 second field is link count; the third field is the name of the user 882 who owns the file; the fourth field is the name of the group that 883 owns the file; the fifth field is the size of the file in bytes; the 884 sixth field (which actually may contain spaces, but is fixed to 12 885 characters) is the file modification time, and the seventh field is 886 the file name. Each field is specified to be a minimum of certain 887 number of character positions (indicated by the second line above), 888 but may also be longer if the data does not fit in the specified 889 length. 891 The SSH_FXP_ATTRS response has the following format: 893 uint32 id 894 ATTRS attrs 896 where `id' is the request identifier, and `attrs' is the returned 897 file attributes as described in Section ``File Attributes''. 899 8. Vendor-Specific Extensions 901 The SSH_FXP_EXTENDED request provides a generic extension mechanism 902 for adding vendor-specific commands. The request has the following 903 format: 905 uint32 id 906 string extended-request 907 ... any request-specific data ... 909 where `id' is the request identifier, and `extended-request' is a 910 string of the format "name@domain", where domain is an internet 911 domain name of the vendor defining the request. The rest of the 912 request is completely vendor-specific, and servers should only 913 attempt to interpret it if they recognize the `extended-request' 914 name. 916 The server may respond to such requests using any of the response 917 packets defined in Section ``Responses from the Server to the 918 Client''. Additionally, the server may also respond with a 919 SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does 920 not recognize the `extended-request' name, then the server MUST 921 respond with SSH_FXP_STATUS with error/status set to 922 SSH_FX_OP_UNSUPPORTED. 924 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 925 extension-specific data from the server to the client. It is of the 926 following format: 928 uint32 id 929 ... any request-specific data ... 931 9. Security Considerations 933 This protocol assumes that it is run over a secure channel and that 934 the endpoints of the channel have been authenticated. Thus, this 935 protocol assumes that it is externally protected from network-level 936 attacks. 938 This protocol provides file system access to arbitrary files on the 939 server (only constrained by the server implementation). It is the 940 responsibility of the server implementation to enforce any access 941 controls that may be required to limit the access allowed for any 942 particular user (the user being authenticated externally to this 943 protocol, typically using the SSH User Authentication Protocol [6]. 945 Care must be taken in the server implementation to check the validity 946 of received file handle strings. The server should not rely on them 947 directly; it MUST check the validity of each handle before relying on 948 it. 950 10. Changes from previous protocol versions 952 The SSH File Transfer Protocol has changed over time, before it's 953 standardization. The following is a description of the incompatible 954 changes between different versions. 956 10.1 Changes between versions 3 and 2 958 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. 960 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were 961 added. 963 o The SSH_FXP_STATUS message was changed to include fields `error 964 message' and `language tag'. 966 10.2 Changes between versions 2 and 1 968 o The SSH_FXP_RENAME message was added. 970 10.3 Changes between versions 1 and 0 972 o Implementation changes, no actual protocol changes. 974 11. Trademark Issues 976 "ssh" is a registered trademark of SSH Communications Security Corp 977 in the United States and/or other countries. 979 References 981 [1] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and 982 P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January 983 1999. 985 [2] Institute of Electrical and Electronics Engineers, "Information 986 Technology - Portable Operating System Interface (POSIX) - Part 987 1: System Application Program Interface (API) [C Language]", 988 IEEE Standard 1003.2, 1996. 990 [3] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 991 Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh- 992 architecture-09 (work in progress), July 2001. 994 [4] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 995 Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh- 996 architecture-09 (work in progress), July 2001. 998 [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 999 Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-11 1000 (work in progress), July 2001. 1002 [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. 1003 Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh- 1004 userauth-11 (work in progress), July 2001. 1006 Authors' Addresses 1008 Tatu Ylonen 1009 SSH Communications Security Corp 1010 Fredrikinkatu 42 1011 HELSINKI FIN-00100 1012 Finland 1014 EMail: ylo@ssh.com 1016 Sami Lehtinen 1017 SSH Communications Security Corp 1018 Fredrikinkatu 42 1019 HELSINKI FIN-00100 1020 Finland 1022 EMail: sjl@ssh.com 1024 Full Copyright Statement 1026 Copyright (C) The Internet Society (2001). All Rights Reserved. 1028 This document and translations of it may be copied and furnished to 1029 others, and derivative works that comment on or otherwise explain it 1030 or assist in its implementation may be prepared, copied, published 1031 and distributed, in whole or in part, without restriction of any 1032 kind, provided that the above copyright notice and this paragraph are 1033 included on all such copies and derivative works. However, this 1034 document itself may not be modified in any way, such as by removing 1035 the copyright notice or references to the Internet Society or other 1036 Internet organizations, except as needed for the purpose of 1037 developing Internet standards in which case the procedures for 1038 copyrights defined in the Internet Standards process must be 1039 followed, or as required to translate it into languages other than 1040 English. 1042 The limited permissions granted above are perpetual and will not be 1043 revoked by the Internet Society or its successors or assigns. 1045 This document and the information contained herein is provided on an 1046 "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING 1047 TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING 1048 BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION 1049 HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF 1050 MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1052 Acknowledgement 1054 Funding for the RFC Editor function is currently provided by the 1055 Internet Society.