idnits 2.17.1 draft-ietf-secsh-filexfer-00.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. ** 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 120: '...d). All servers SHOULD support packet...' RFC 2119 keyword, line 165: '...their use MUST be negotiated using the...' RFC 2119 keyword, line 199: '...rs (both strings MUST always be presen...' RFC 2119 keyword, line 205: '...e IETF. Implementations MUST silently...' RFC 2119 keyword, line 272: '... of such new fields MUST be negotiated...' (16 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 228 has weird spacing: '...issions pre...' == Line 234 has weird spacing: '... string exte...' == Line 235 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.) -- Couldn't find a document date in the document -- date freshness check skipped. -- 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) == Missing Reference: 'SSH-CONN' is mentioned on line 97, but not defined == Unused Reference: 'SSH-TRANSPORT' is defined on line 896, but no explicit reference was found in the text == Unused Reference: 'SSH-CONNECT' is defined on line 902, but no explicit reference was found in the text ** Obsolete normative reference: RFC 2246 (Obsoleted by RFC 4346) -- Possible downref: Non-RFC (?) normative reference: ref. 'POSIX' == Outdated reference: A later version (-22) exists of draft-ietf-secsh-architecture-07 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-09 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-09 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-09 Summary: 5 errors (**), 0 flaws (~~), 11 warnings (==), 4 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Network Working Group T. Ylonen and S. Lehtinen 2 INTERNET-DRAFT SSH Communications Security 3 draft-ietf-secsh-filexfer-00.txt 9 January, 2001 4 Expires: 9 July, 2001 6 SSH File Transfer Protocol 8 Status of This Memo 10 This document is an Internet-Draft and is in full conformance 11 with all provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that 15 other groups may also distribute working documents as 16 Internet-Drafts. 18 Internet-Drafts are draft documents valid for a maximum of six 19 months and may be updated, replaced, or obsoleted by other 20 documents at any time. It is inappropriate to use Internet- 21 Drafts as reference material or to cite them other than as 22 "work in progress." 24 The list of current Internet-Drafts can be accessed at 25 http://www.ietf.org/ietf/1id-abstracts.txt 27 The list of Internet-Draft Shadow Directories can be accessed at 28 http://www.ietf.org/shadow.html. 30 Abstract 32 The SSH File Transfer Protocol provides secure file transfer functional- 33 ity over any reliable data stream. It is the standard file transfer 34 protocol for use with the SSH2 protocol. This document describes the 35 file transfer protocol and its interface to the SSH2 protocol suite. 37 Table of Contents 39 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 40 2. Use with the SSH Connection Protocol . . . . . . . . . . . . . . 3 41 3. General Packet Format . . . . . . . . . . . . . . . . . . . . . 3 42 4. Protocol Initialization . . . . . . . . . . . . . . . . . . . . 4 43 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . . 5 44 6. Requests From the Client to the Server . . . . . . . . . . . . . 6 45 6.1. Request Synchronization and Reordering . . . . . . . . . . . 7 46 6.2. File Names . . . . . . . . . . . . . . . . . . . . . . . . . 7 47 6.3. Opening, Creating, and Closing Files . . . . . . . . . . . . 8 48 6.4. Reading and Writing . . . . . . . . . . . . . . . . . . . . 9 49 6.5. Removing and Renaming Files . . . . . . . . . . . . . . . . 10 50 6.6. Creating and Deleting Directories . . . . . . . . . . . . . 10 51 6.7. Scanning Directories . . . . . . . . . . . . . . . . . . . . 11 52 6.8. Retrieving File Attributes . . . . . . . . . . . . . . . . . 12 53 6.9. Setting File Attributes . . . . . . . . . . . . . . . . . . 12 54 6.10. Canonicalizing the Server-Side Path Name . . . . . . . . . 13 55 7. Responses from the Server to the Client . . . . . . . . . . . . 13 56 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . . . 16 57 9. Security Considerations . . . . . . . . . . . . . . . . . . . . 17 58 10. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . 17 59 11. References . . . . . . . . . . . . . . . . . . . . . . . . . . 17 60 12. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 18 62 1. Introduction 64 This protocol provides secure file transfer (and more generally file 65 system access) functionality over a reliable data stream, such as a 66 channel in the SSH2 protocol [SSH-ARCH]. 68 This protocol is designed so that it could be used to implement a secure 69 remote file system service, as well as a secure file transfer service. 71 This protocol assumes that it runs over a secure channel, and that the 72 server has already authenticated the user at the client end, and that 73 the identity of the client user is externally available to the server 74 implementation. 76 In general, this protocol follows a simple request-response model. Each 77 request and response contains a sequence number and multiple requests 78 may be pending simultaneously. There are a relatively large number of 79 different request messages, but a small number of possible response 80 messages. Each request has one or more response messages that may be 81 returned in result (e.g., a read either returns data or reports error 82 status). 84 The packet format descriptions in this specification follow the notation 85 presented in [SSH-ARCH]. 87 Even though this protocol is described in the context of the SSH2 88 protocol, this protocol is general and independent of the rest of the 89 SSH2 protocol suite. It could be used in a number of different 90 applications, such as secure file transfer over TLS [RFC-2246] and 91 transfer of management information in VPN applications. 93 2. Use with the SSH Connection Protocol 95 When used with the SSH2 Protocol suite, this protocol is intended to be 96 used from the SSH Connection Protocol as a subsystem, as described in 97 [SSH-CONN], Section ``Starting a Shell or a Command''. The subsystem 98 name used with this protocol is "sftp". 100 3. General Packet Format 102 All packets transmitted over the secure connection are of the following 103 format: 105 uint32 length 106 byte type 107 byte[length - 1] data payload 109 That is, they are just data preceded by 32-bit length and 8-bit type 110 fields. The `length' is the length of the data area, and does not 111 include the `length' field itself. The format and interpretation of the 112 data area depends on the packet type. 114 All packet descriptions below only specify the packet type and the data 115 that goes into the data field. Thus, they should be prefixed by the 116 `length' and `type' fields. 118 The maximum size of a packet is in practise determined by the client 119 (the maximum size of read or write requests that it sends, plus a few 120 bytes of packet overhead). All servers SHOULD support packets of at 121 least 34000 bytes (where the packet size refers to the full length, 122 including the header above). This should allow for reads and writes of 123 at most 32768 bytes. 125 There is no limit on the number of outstanding (non-acknowledged) 126 requests that the client may send to the server. In practise this is 127 limited by the buffering available on the data stream and the queuing 128 performed by the server. If the server's queues are full, it should not 129 read any more data from the stream, and flow control will prevent the 130 client from sending more requests. Note, however, that while there is 131 no restriction on the protocol level, the client's API may provide a 132 limit in order to prevent infinite queueing of outgoing requests at the 133 client. 135 The following values are defined for packet types. 137 #define SSH_FXP_INIT 1 138 #define SSH_FXP_VERSION 2 139 #define SSH_FXP_OPEN 3 140 #define SSH_FXP_CLOSE 4 141 #define SSH_FXP_READ 5 142 #define SSH_FXP_WRITE 6 143 #define SSH_FXP_LSTAT 7 144 #define SSH_FXP_FSTAT 8 145 #define SSH_FXP_SETSTAT 9 146 #define SSH_FXP_FSETSTAT 10 147 #define SSH_FXP_OPENDIR 11 148 #define SSH_FXP_READDIR 12 149 #define SSH_FXP_REMOVE 13 150 #define SSH_FXP_MKDIR 14 151 #define SSH_FXP_RMDIR 15 152 #define SSH_FXP_REALPATH 16 153 #define SSH_FXP_STAT 17 154 #define SSH_FXP_RENAME 18 155 #define SSH_FXP_STATUS 101 156 #define SSH_FXP_HANDLE 102 157 #define SSH_FXP_DATA 103 158 #define SSH_FXP_NAME 104 159 #define SSH_FXP_ATTRS 105 160 #define SSH_FXP_EXTENDED 200 161 #define SSH_FXP_EXTENDED_REPLY 201 163 Additional packet types should only be defined if the protocol version 164 number (see Section ``Protocol Initialization'') is incremented, and 165 their use MUST be negotiated using the version number. However, the 166 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 167 implement vendor-specific extensions. See Section ``Vendor-Specific 168 Extensions'' for more details. 170 4. Protocol Initialization 172 When the file transfer protocol starts, it first sends a SSH_FXP_INIT 173 (including its version number) packet to the server. The server 174 responds with a SSH_FXP_VERSION packet, supplying the lowest of its own 175 and the client's version number. Both parties should from then on 176 adhere to particular version of the protocol. 178 The SSH_FXP_INIT packet (from client to server) has the following data: 180 uint32 version 181 183 The SSH_FXP_VERSION packet (from server to client) has the following 184 data: 186 uint32 version 187 189 The version number of the protocol specified in this document is 3. The 190 version number should be incremented for each incompatible revision of 191 this protocol. 193 The extension data in the above packets may be empty, or may be a 194 sequence of 196 string extension_name 197 string extension_data 199 pairs (both strings MUST always be present if one is, but the `exten- 200 sion_data' string may be of zero length). If present, these strings 201 indicate extensions to the baseline protocol. The `extension_name' 202 field(s) identify the name of the extension. The name should be of the 203 form "name@domain", where the domain is the DNS domain name of the orga- 204 nization defining the extension. Additional names that are not of this 205 format may be defined later by the IETF. Implementations MUST silently 206 ignore any extensions whose name they do not recognize. 208 5. File Attributes 210 A new compound data type is defined for encoding file attributes. It is 211 basically just a combination of elementary types, but is defined once 212 because of the non-trivial description of the fields and to ensure 213 maintainability. 215 The same encoding is used both when returning file attributes from the 216 server and when sending file attributes to the server. When sending it 217 to the server, the flags field specifies which attributes are included, 218 and the server will use default values for the remaining attributes (or 219 will not modify the values of remaining attributes). When receiving 220 attributes from the server, the flags specify which attributes are 221 included in the returned data. The server normally returns all 222 attributes it knows about. 224 uint32 flags 225 uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE 226 uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID 227 uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID 228 uint32 permissions present only if flag 229 SSH_FILEXFER_ATTR_PERMISSIONS 230 uint32 atime present only if flag SSH_FILEXFER_ACMODTIME 231 uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME 232 uint32 extended_count present only if flag 233 SSH_FILEXFER_ATTR_EXTENDED 234 string extended_type 235 string extended_data 236 ... more extended data (extended_type - extended_data pairs), 237 so that number of pairs equals extended_count 239 The `flags' specify which of the fields are present. Those fields for 240 which the corresponding flag is not set are not present (not included in 241 the packet). New flags can only be added by incrementing the protocol 242 version number (or by using the extension mechanism described below). 244 The `size' field specifies the size of the file in bytes. 246 The `uid' and `gid' fields contain numeric Unix-like user and group 247 identifiers, respectively. 249 The `permissions' field contains a bit mask of file permissions as 250 defined by [POSIX]. 252 The `atime' and `mtime' contain the access and modification times of the 253 files, respectively. They are represented as seconds from Jan 1, 1970. 255 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 256 mechanism for vendor-specific extensions. If the flag is specified, 257 then the `extended_count' field is present. It specifies the number of 258 extended_type-extended_data pairs that follow. Each of these pairs 259 specifies an extended attribute. For each of the attributes, the 260 extended_type field should be a string of the format "name@domain", 261 where "domain" is a valid, registered domain name and "name" identifies 262 the method. The IETF may later standardize certain names that deviate 263 from this format (e.g., that do not contain the "@" sign). The 264 interpretation of `extended_data' depends on the type. Implementations 265 SHOULD ignore extended data fields that they do not understand. 267 Additional fields can be added to the attributes by either defining 268 additional bits to the flags field to indicate their presence, or by 269 defining extended attributes for them. The extended attributes 270 mechanism is recommended for most purposes; additional flags bits should 271 only be defined by an IETF standards action that also increments the 272 protocol version number. The use of such new fields MUST be negotiated 273 by the version number in the protocol exchange. It is a protocol error 274 if a packet with unsupported protocol bits is received. 276 The flags bits are defined to have the following values: 278 #define SSH_FILEXFER_ATTR_SIZE 0x00000001 279 #define SSH_FILEXFER_ATTR_UIDGID 0x00000002 280 #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 281 #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008 282 #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 284 6. Requests From the Client to the Server 286 Requests from the client to the server represent the various file system 287 operations. Each request begins with an `id' field, which is a 32-bit 288 identifier identifying the request (selected by the client). The same 289 identifier will be returned in the response to the request. One 290 possible implementation of it is a monotonically increasing request 291 sequence number (modulo 2^32). 293 Many operations in the protocol operate on open files. The SSH_FXP_OPEN 294 request can return a file handle (which is an opaque variable-length 295 string) which may be used to access the file later (e.g. in a read 296 operation). The client MUST NOT send requests the server with bogus or 297 closed handles. However, the server MUST perform adequate checks on the 298 handle in order to avoid security risks due to fabricated handles. 300 This design allows either stateful and stateless server implementation, 301 as well as an implementation which caches state between requests but may 302 also flush it. The contents of the file handle string are entirely up 303 to the server and its design. The client should not modify or attempt 304 to interpret the file handle strings. 306 The file handle strings MUST NOT be longer than 256 bytes. 308 6.1. Request Synchronization and Reordering 310 The protocol and implementations MUST process requests relating to the 311 same file in the order in which they are received. In other words, if 312 an application submits multiple requests to the server, the results in 313 the responses will be the same as if it had sent the requests one at a 314 time and waited for the response in each case. For example, the server 315 may process non-overlapping read/write requests to the same file in 316 parallel, but overlapping reads and writes cannot be reordered or 317 parallelized. However, there are no ordering restrictions on the server 318 for processing requests from two different file transfer connections. 319 The server may interleave and parallelize them at will. 321 There are no restrictions on the order in which responses to outstanding 322 requests are delivered to the client, except that the server must ensure 323 fairness in the sense that processing of no request will be indefinitely 324 delayed even if the client is sending other requests so that there are 325 multiple outstanding requests all the time. 327 6.2. File Names 329 This protocol represents file names as strings. File names are assumed 330 to use the slash ('/') character as a directory separator. 332 File names starting with a slash are "absolute", and are relative to the 333 root of the file system. Names starting with any other character are 334 relative to the user's default directory (home directory). Note that 335 identifying the user is assumed to take place outside of this protocol. 337 Servers SHOULD interpret a path name component ".." as referring to the 338 parent directory, and "." as referring to the current directory. If the 339 server implementation limits access to certain parts of the file system, 340 it must be extra careful in parsing file names when enforcing such 341 restrictions. There have been numerous reported security bugs where a 342 ".." in a path name has allowed access outside the intended area. 344 An empty path name is valid, and it refers to the user's default 345 directory (usually the user's home directory). 347 Otherwise, no syntax is defined for file names by this specification. 348 Clients should not make any other assumptions; however, they can splice 349 path name components returned by SSH_FXP_READDIR together using a slash 350 ('/') as the separator, and that will work as expected. 352 It is understood that the lack of well-defined semantics for file names 353 may cause interoperability problems between clients and servers using 354 radically different operating systems. However, this approach is known 355 to work acceptably with most systems, and alternative approaches that 356 e.g. treat file names as sequences of structured components are quite 357 complicated. 359 6.3. Opening, Creating, and Closing Files 361 Files are opened and created using the SSH_FXP_OPEN message, whose data 362 part is as follows: 364 uint32 id 365 string filename 366 uint32 pflags 367 ATTRS attrs 369 The `id' field is the request identifier as for all requests. 371 The `filename' field specifies the file name. See Section ``File 372 Names'' for more information. 373 The `pflags' field is a bitmask. The following bits have been defined. 375 #define SSH_FXF_READ 0x00000001 376 #define SSH_FXF_WRITE 0x00000002 377 #define SSH_FXF_APPEND 0x00000004 378 #define SSH_FXF_CREAT 0x00000008 379 #define SSH_FXF_TRUNC 0x00000010 380 #define SSH_FXF_EXCL 0x00000020 382 These have the following meanings: 384 SSH_FXF_READ 385 Open the file for reading. 387 SSH_FXF_WRITE 388 Open the file for writing. If both this and SSH_FXF_READ are 389 specified, the file is opened for both reading and writing. 391 SSH_FXF_APPEND 392 Force all writes to append data at the end of the file. 394 SSH_FXF_CREAT 395 If this flag is specified, then a new file will be created if one 396 does not alread exist (if O_TRUNC is specified, the new file will 397 be truncated to zero length if it previously exists). 399 SSH_FXF_TRUNC 400 Forces an existing file with the same name to be truncated to zero 401 length when creating a file by specifying SSH_FXF_CREAT. 402 SSH_FXF_CREAT MUST also be specified if this flag is used. 404 SSH_FXF_EXCL 405 Causes the request to fail if the named file already exists. 407 SSH_FXF_CREAT MUST also be specified if this flag is used. 409 The `attrs' field specifies the initial attributes for the file. 410 Default values will be used for those attributes that are not specified. 411 See Section ``File Attributes'' for more information. 413 Regardless the server operating system, the file will always be opened 414 in "binary" mode (i.e., no translations between different character sets 415 and newline encodings). 417 The response to this message will be either SSH_FXP_HANDLE (if the 418 operation is successful) or SSH_FXP_STATUS (if the operation fails). 420 A file is closed by using the SSH_FXP_CLOSE request. Its data field has 421 the following format: 423 uint32 id 424 string handle 426 where `id' is the request identifier, and `handle' is a handle previ- 427 ously returned in the response to SSH_FXP_OPEN or SSH_FXP_OPENDIR. The 428 handle becomes invalid immediately after this request has been sent. 429 The response to this request will be a SSH_FXP_STATUS message. One 430 should note that on some server platforms even a close can fail. This 431 can happen e.g. if the server operating system caches writes, and an 432 error occurs while flushing cached writes during the close. 434 6.4. Reading and Writing 436 Once a file has been opened, it can be read using the SSH_FXP_READ 437 message, which has the following format: 439 uint32 id 440 string handle 441 uint64 offset 442 uint32 len 444 where `id' is the request identifier, `handle' is an open file handle 445 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative to 446 the beginning of the file from where to start reading, and `len' is the 447 maximum number of bytes to read. 449 In response to this request, the server will read as many bytes as it 450 can from the file (up to `len'), and return them in a SSH_FXP_DATA 451 message. If an error occurs or EOF is encountered before reading any 452 data, the server will respond with SSH_FXP_STATUS. For normal disk 453 files, it is guaranteed that this will read the specified number of 454 bytes, or up to end of file. For e.g. device files this may return 455 fewer bytes than requested. 457 Writing to a file is achieved using the SSH_FXP_WRITE message, which has 458 the following format: 460 uint32 id 461 string handle 462 uint64 offset 463 string data 465 where `id' is a request identifier, `handle' is a file handle returned 466 by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the beginning of 467 the file where to start writing, and `data' is the data to be written. 469 The write will extend the file if writing beyond the end of the file. 470 It is legal to write way beyond the end of the file; the semantics are 471 to write zeroes from the end of the file to the specified offset and 472 then the data. On most operating systems, such writes do not allocate 473 disk space but instead leave "holes" in the file. 475 The server responds to a write request with a SSH_FXP_STATUS message. 477 6.5. Removing and Renaming Files 479 Files can be removed using the SSH_FXP_REMOVE message. It has the 480 following format: 482 uint32 id 483 string filename 485 where `id' is the request identifier and `filename' is the name of the 486 file to be removed. See Section ``File Names'' for more information. 487 This request cannot be used to remove directories. 489 The server will respond to this request with a SSH_FXP_STATUS message. 491 Files (and directories) can be renamed using the SSH_FXP_RENAME message. 492 Its data is as follows: 494 uint32 id 495 string oldpath 496 string newpath 498 where `id' is the request identifier, `oldpath' is the name of an exist- 499 ing file or directory, and `newpath' is the new name for the file or 500 directory. It is an error if there already exists a file with the name 501 specified by newpath. The server may also fail rename requests in other 502 situations, for example if `oldpath' and `newpath' point to different 503 file systems on the server. 505 The server will respond to this request with a SSH_FXP_STATUS message. 507 6.6. Creating and Deleting Directories 509 New directories can be created using the SSH_FXP_MKDIR request. It has 510 the following format: 512 uint32 id 513 string path 515 where `id' is the request identifier and `path' specifies the directory 516 to be created. See Section ``File Names'' for more information on file 517 names. An error will be returned if a file or directory with the speci- 518 fied path already exists. The server will respond to this request with 519 a SSH_FXP_STATUS message. 521 Directories can be removed using the SSH_FXP_RMDIR request, which has 522 the following format: 524 uint32 id 525 string path 527 where `id' is the request identifier, and `path' specifies the directory 528 to be removed. See Section ``File Names'' for more information on file 529 names. An error will be returned if no directory with the specified 530 path exists, or if the specified directory is not empty, or if the path 531 specified a file system object other than a directory. The server 532 responds to this request with a SSH_FXP_STATUS message. 534 6.7. Scanning Directories 536 The files in a directory can be listed using the SSH_FXP_OPENDIR and 537 SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one or 538 more file names with full file attributes for each file. The client 539 should call SSH_FXP_READDIR repeatedly until it has found the file it is 540 looking for or until the server responds with a SSH_FXP_STATUS message 541 indicating an error (normally SSH_FX_EOF if there are no more files in 542 the directory). The client should then close the handle using the 543 SSH_FXP_CLOSE request. 545 The SSH_FXP_OPENDIR opens a directory for reading. It has the following 546 format: 548 uint32 id 549 string path 551 where `id' is the request identifier and `path' is the path name of the 552 directory to be listed (without any trailing slash). See Section ``File 553 Names'' for more information on file names. This will return an error 554 if the path does not specify a directory or if the directory is not 555 readable. The server will respond to this request with either a 556 SSH_FXP_HANDLE or a SSH_FXP_STATUS message. 558 Once the directory has been successfully opened, files (and directories) 559 contained in it can be listed using SSH_FXP_READDIR requests. These are 560 of the format 562 uint32 id 563 string handle 565 where `id' is the request identifier, and `handle' is a handle returned 566 by SSH_FXP_OPENDIR. (It is a protocol error to attempt to use an ordi- 567 nary file handle returned by SSH_FXP_OPEN.) 569 The server responds to this request with either a SSH_FXP_NAME or a 570 SSH_FXP_STATUS message. One or more names may be returned at a time. 571 Full status information is returned for each name in order to speed up 572 typical directory listings. 574 When the client no longer wishes to read more names from the directory, 575 it SHOULD call SSH_FXP_CLOSE for the handle. The handle should be 576 closed regardless of whether an error has occurred or not. 578 6.8. Retrieving File Attributes 580 Very often, file attributes are automatically returned by 581 SSH_FXP_READDIR. However, sometimes there is need to specifically 582 retrieve the attributes for a named file. This can be done using the 583 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 585 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT follows 586 symbolic links on the server, whereas SSH_FXP_LSTAT does not follow 587 symbolic links. Both have the same format: 589 uint32 id 590 string path 592 where `id' is the request identifier, and `path' spefifies the file sys- 593 tem object for which status is to be returned. The server responds to 594 this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS. 596 SSH_FXP_FSTAT differs from the others in that it returns status 597 information for an open file (identified by the file handle). Its 598 format is as follows: 600 uint32 id 601 string handle 603 where `id' is the request identifier and `handle' is a file handle 604 returned by SSH_FXP_OPEN. The server responds to this request with 605 SSH_FXP_ATTRS or SSH_FXP_STATUS. 607 6.9. Setting File Attributes 609 File attributes may be modified using the SSH_FXP_SETSTAT and 610 SSH_FXP_FSETSTAT requests. These requests are used for operations such 611 as changing the ownership, permissions or access times, as well as for 612 truncating a file. 614 The SSH_FXP_SETSTAT request is of the following format: 616 uint32 id 617 string path 618 ATTRS attrs 620 where `id' is the request identifier, `path' specifies the file system 621 object (e.g. file or directory) whose attributes are to be modified, and 622 `attrs' specifies the modifications to be made to its attributes. 623 Attributes are discussed in more detail in Section ``File Attributes''. 625 An error will be returned if the specified file system object does not 626 exist or the user does not have sufficient rights to modify the 627 specified attributes. The server responds to this request with a 628 SSH_FXP_STATUS message. 630 The SSH_FXP_FSETSTAT request modifies the attributes of a file which is 631 already open. It has the following format: 633 uint32 id 634 string handle 635 ATTRS attrs 637 where `id' is the request identifier, `handle' (MUST be returned by 638 SSH_FXP_OPEN) identifies the file whose attributes are to be modified, 639 and `attrs' specifies the modifications to be made to its attributes. 640 Attributes are discussed in more detail in Section ``File Attributes''. 641 The server will respond to this request with SSH_FXP_STATUS. 643 6.10. Canonicalizing the Server-Side Path Name 645 The SSH_FXP_REALPATH request can be used to have the server canonicalize 646 any given path name to an absolute path. This is useful for converting 647 path names containing ".." components or relative pathnames without a 648 leading slash into absolute paths. The format of the request is as 649 follows: 651 uint32 id 652 string path 654 where `id' is the request identifier and `path' specifies the path name 655 to be canonicalized. The server will respond with a SSH_FXP_NAME packet 656 containing only one name and a dummy attributes value. The name is the 657 returned packet will be in canonical form. If an error occurs, the 658 server may also respond with SSH_FXP_STATUS. 660 7. Responses from the Server to the Client 662 The server responds to the client using one of a few response packets. 663 All requests can return a SSH_FXP_STATUS response upon failure. When 664 the operation is successful, any of the responses may be returned 665 (depending on the operation). If no data needs to be returned to the 666 client, the SSH_FXP_STATUS response with SSH_FX_OK status is 667 appropriate. Otherwise, the SSH_FXP_HANDLE message is used to return a 668 file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR requests), 669 SSH_FXP_DATA is used to return data from SSH_FXP_READ, SSH_FXP_NAME is 670 used to return one or more file names from a SSH_FXP_READDIR or 671 SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is used to return file 672 attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and SSH_FXP_FSTAT requests. 674 Exactly one response will be returned for each request. Each response 675 packet contains a request identifier which can be used to match each 676 response with the corresponding request. Note that it is legal to have 677 several requests outstanding simultaneously, and the server is allowed 678 to send responses to them in a different order from the order in which 679 the requests were sent (the result of their execution, however, is 680 guaranteed to be as if they had been processed one at a time in the 681 order in which the requests were sent). 683 Response packets are of the same general format as request packets. 684 Each response packet begins with the request identifier. 686 The format of the data portion of the SSH_FXP_STATUS response is as 687 follows: 689 uint32 id 690 uint32 error/status code 692 where `id' is the request identifier, and `error/status code' indicates 693 the result of the requested operation. The value SSH_FX_OK indicates 694 success, and all other values indicate failure. Currently, the follow- 695 ing values are defined (other values may be defined by future versions 696 of this protocol): 698 #define SSH_FX_OK 0 699 #define SSH_FX_EOF 1 700 #define SSH_FX_NO_SUCH_FILE 2 701 #define SSH_FX_PERMISSION_DENIED 3 702 #define SSH_FX_FAILURE 4 703 #define SSH_FX_BAD_MESSAGE 5 704 #define SSH_FX_NO_CONNECTION 6 705 #define SSH_FX_CONNECTION_LOST 7 706 #define SSH_FX_OP_UNSUPPORTED 8 708 SSH_FX_OK 709 Indicates successful completion of the operation. 711 SSH_FX_EOF 712 indicates end-of-file condition; for SSH_FX_READ it means that no 713 more data is available in the file, and for SSH_FX_READDIR it 714 indicates that no more files are contained in the directory. 716 SSH_FX_NO_SUCH_FILE 717 is returned when a reference is made to a file which should exist 718 but doesn't. 720 SSH_FX_PERMISSION_DENIED 721 is returned when the authenticated user does not have sufficient 722 permissions to perform the operation. 723 SSH_FX_FAILURE 724 is a generic catch-all error message; it should be returned if an 725 error occurs for which there is no more specific error code 726 defined. 728 SSH_FX_BAD_MESSAGE 729 may be returned if a badly formatted packet or protocol 730 incompatibility is detected. 732 SSH_FX_NO_CONNECTION 733 is a pseudo-error which indicates that the client has no 734 connection to the server (it can only be generated locally by the 735 client, and MUST NOT be returned by servers). 737 SSH_FX_CONNECTION_LOST 738 is a pseudo-error which indicates that the connection to the 739 server has been lost (it can only be generated locally by the 740 client, and MUST NOT be returned by servers). 742 SSH_FX_OP_UNSUPPORTED 743 indicates that an attempt was made to perform an operation which 744 is not supported for the server (it may be generated locally by 745 the client if e.g. the version number exchange indicates that a 746 required feature is not supported by the server, or it may be 747 returned by the server if the server does not implement an 748 operation). 750 The SSH_FXP_HANDLE response has the following format: 752 uint32 id 753 string handle 755 where `id' is the request identifier, and `handle' is an arbitrary 756 string that identifies an open file or directory on the server. The 757 handle is opaque to the client; the client MUST NOT attempt to interpret 758 or modify it in any way. The length of the handle string MUST NOT 759 exceed 256 data bytes. 761 The SSH_FXP_DATA response has the following format: 763 uint32 id 764 string data 766 where `id' is the request identifier, and `data' is an arbitrary byte 767 string containing the requested data. The data string may be at most 768 the number of bytes requested in a SSH_FXP_READ request, but may also be 769 shorter if end of file is reached or if the read is from something other 770 than a regular file. 772 The SSH_FXP_NAME response has the following format: 774 uint32 id 775 uint32 count 776 repeats count times: 777 string filename 778 string longname 779 ATTRS attrs 781 where `id' is the request identifier, `count' is the number of names 782 returned in this response, and the remaining fields repeat `count' times 783 (so that all three fields are first included for the first file, then 784 for the second file, etc). In the repeated part, `filename' is a file 785 name being returned (for SSH_FXP_READDIR, it will be a relative name 786 within the directory, without any path components; for SSH_FXP_REALPATH 787 it will be an absolute path name), `longname' is an expanded format for 788 the file name, similar to what is returned by "ls -l" on Unix systems, 789 and `attrs' is the attributes of the file as described in Section ``File 790 Attributes''. 792 The format of the `longname' field is unspecified by this protocol. It 793 MUST be suitable for use in the output of a directory listing command 794 (in fact, the recommended operation for a directory listing command is 795 to simply display this data). However, clients SHOULD NOT attempt to 796 parse the longname field for file attributes; they SHOULD use the attrs 797 field instead. 799 The recommended format for the longname field is as follows: 801 -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer 802 1234567890 123 12345678 12345678 12345678 123456789012 804 Here, the first line is sample output, and the second field indicates 805 widths of the various fields. Fields are separated by spaces. The 806 first field lists file permissions for user, group, and others; the sec- 807 ond field is link count; the third field is the name of the user who 808 owns the file; the fourth field is the name of the group that owns the 809 file; the fifth field is the size of the file in bytes; the sixth field 810 (which actually may contain spaces, but is fixed to 12 characters) is 811 the file modification time, and the seventh field is the file name. 812 Each file is specified to be a minimum of certain number of character 813 positions (indicated by the second line above), but may also be longer 814 if the data does not fit in the specified length. 816 The SSH_FXP_ATTRS response has the following format: 818 uint32 id 819 ATTRS attrs 821 where `id' is the request identifier, and `attrs' is the returned file 822 attributes as described in Section ``File Attributes''. 824 8. Vendor-Specific Extensions 826 The SSH_FXP_EXTENDED request provides a generic extension mechanism for 827 adding vendor-specific commands. The request has the following format: 829 uint32 id 830 string extended-request 831 ... any request-specific data ... 833 where `id' is the request identifier, and `extended-request' is a string 834 of the format "name@domain", where domain is an internet domain name of 835 the vendor defining the request. The rest of the request is completely 836 vendor-specific, and servers should only attempt to interpret it if they 837 recognize the `extended-request' name. 839 The server may respond to such requests using any of the response 840 packets defined in Section ``Responses from the Server to the Client''. 841 Additionally, the server may also respond with a SSH_FXP_EXTENDED_REPLY 842 packet, as defined below. If the server does not recognize the 843 `extended-request' name, then the server MUST respond with 844 SSH_FXP_STATUS with error/status set to SSH_FX_OP_UNSUPPORTED. 846 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 847 extension-specific data from the server to the client. It is of the 848 following format: 850 uint32 id 851 ... any request-specific data ... 853 9. Security Considerations 855 This protocol assumes that it is run over a secure channel and that the 856 endpoints of the channel have been authenticated. Thus, this protocol 857 assumes that it is externally protected from network-level attacks. 859 This protocol provides file system access to arbitrary files on the 860 server (only constrained by the server implementation). It is the 861 responsibility of the server implementation to enforce any access 862 controls that may be required to limit the access allowed for any 863 particular user (the user being authenticated externally to this 864 protocol, typically using the SSH User Authentication Protocol [SSH- 865 USERAUTH]. 867 Care must be taken in the server implementation to check the validity of 868 received file handle strings. The server should not rely on them 869 directly; it MUST check the validity of each handle before relying on 870 it. 872 10. Trademark Issues 874 SSH is a registered trademark and Secure Shell is a trademark of SSH 875 Communications Security Corp. SSH Communications Security Corp permits 876 the use of these trademarks as the name of this standard and protocol, 877 and permits their use to describe that a product conforms to this 878 standard, provided that the following acknowledgement is included where 879 the trademarks are used: ``SSH is a registered trademark and Secure 880 Shell is a trademark of SSH Communications Security Corp 881 (www.ssh.com)''. These trademarks may not be used as part of a product 882 name or in otherwise confusing manner without prior written permission 883 of SSH Communications Security Corp. 885 11. References 886 [RFC-2246] Dierks, T. and Allen, C.: "The TLS Protocol Version 1.0", 887 January 1999 889 [POSIX] ISO/IEC Std 9945-1, ANSI/IEEE Std 1003.1 Information technology 890 -- Portable Operating System Interface (POSIX)-Part 1: System 891 Application Program Interface (API) [C Language], July 1996. 893 [SSH-ARCH] Ylonen, T., et al: "SSH Protocol Architecture", Internet- 894 Draft, draft-ietf-secsh-architecture-07.txt 896 [SSH-TRANSPORT] Ylonen, T., et al: "SSH Transport Protocol", Internet- 897 Draft, draft-ietf-secsh-transport-09.txt 899 [SSH-USERAUTH] Ylonen, T., et al: "SSH Authentication Protocol", 900 Internet-Draft, draft-ietf-secsh-userauth-09.txt 902 [SSH-CONNECT] Ylonen, T., et al: "SSH Connection Protocol", Internet- 903 Draft, draft-ietf-secsh-connect-09.txt 905 12. Authors' Addresses 907 Tatu Ylonen 908 SSH Communications Security Corp 909 Fredrikinkatu 42 910 FIN-00100 HELSINKI 911 Finland 912 E-mail: ylo@ssh.com 914 Sami Lehtinen 915 SSH Communications Security Corp 916 Fredrikinkatu 42 917 FIN-00100 HELSINKI 918 Finland 919 E-mail: sjl@ssh.com