idnits 2.17.1 draft-ietf-secsh-filexfer-01.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 126: '...d). All servers SHOULD support packet...' RFC 2119 keyword, line 173: '...their use MUST be negotiated using the...' RFC 2119 keyword, line 207: '...rs (both strings MUST always be presen...' RFC 2119 keyword, line 213: '...e IETF. Implementations MUST silently...' RFC 2119 keyword, line 281: '... of such new fields MUST be negotiated...' (16 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 236 has weird spacing: '...issions pre...' == Line 242 has weird spacing: '... string exte...' == Line 243 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: 'SECSH-CONN' is mentioned on line 103, but not defined == Missing Reference: 'RFC-2279' is mentioned on line 324, but not defined ** Obsolete undefined reference: RFC 2279 (Obsoleted by RFC 3629) == Missing Reference: 'RFC-1766' is mentioned on line 325, but not defined ** Obsolete undefined reference: RFC 1766 (Obsoleted by RFC 3066, RFC 3282) == Unused Reference: 'SECSH-TRANSPORT' is defined on line 956, but no explicit reference was found in the text == Unused Reference: 'SECSH-CONNECT' is defined on line 962, 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-08 == Outdated reference: A later version (-24) exists of draft-ietf-secsh-transport-10 == Outdated reference: A later version (-27) exists of draft-ietf-secsh-userauth-10 == Outdated reference: A later version (-25) exists of draft-ietf-secsh-connect-10 Summary: 7 errors (**), 0 flaws (~~), 13 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-01.txt 2 March, 2001 4 Expires: 2 September, 2001 6 Secure Shell 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 Secure Shell File Transfer Protocol provides secure file transfer 33 functionality over any reliable data stream. It is the standard file 34 transfer protocol for use with the Secure Shell Remote Login Protocol. 35 This document describes the file transfer protocol and its interface to 36 the Secure Shell protocol suite. 38 Table of Contents 40 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . 2 41 2. Use with the Secure Shell Connection Protocol . . . . . . . . . 3 42 3. General Packet Format . . . . . . . . . . . . . . . . . . . . . 3 43 4. Protocol Initialization . . . . . . . . . . . . . . . . . . . . 4 44 5. File Attributes . . . . . . . . . . . . . . . . . . . . . . . . 5 45 6. Responses from the Server to the Client . . . . . . . . . . . . 6 46 7. Requests From the Client to the Server . . . . . . . . . . . . . 9 47 7.1. Request Synchronization and Reordering . . . . . . . . . . . 10 48 7.2. File Names . . . . . . . . . . . . . . . . . . . . . . . . . 10 49 7.3. Opening, Creating, and Closing Files . . . . . . . . . . . . 11 50 7.4. Reading and Writing . . . . . . . . . . . . . . . . . . . . 12 51 7.5. Removing and Renaming Files . . . . . . . . . . . . . . . . 13 52 7.6. Creating and Deleting Directories . . . . . . . . . . . . . 14 53 7.7. Scanning Directories . . . . . . . . . . . . . . . . . . . . 14 54 7.8. Retrieving File Attributes . . . . . . . . . . . . . . . . . 15 55 7.9. Setting File Attributes . . . . . . . . . . . . . . . . . . 16 56 7.10. Dealing with Symbolic links . . . . . . . . . . . . . . . . 16 57 7.11. Canonicalizing the Server-Side Path Name . . . . . . . . . 17 58 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . . . . 17 59 9. Security Considerations . . . . . . . . . . . . . . . . . . . . 18 60 10. Changes from previous protocol versions . . . . . . . . . . . . 18 61 10.1. Changes between versions 3 and 2 . . . . . . . . . . . . . 18 62 10.2. Changes between versions 2 and 1 . . . . . . . . . . . . . 18 63 10.3. Changes between versions 1 and 0 . . . . . . . . . . . . . 18 64 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . . 18 65 12. References . . . . . . . . . . . . . . . . . . . . . . . . . . 19 66 13. Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 19 68 1. Introduction 70 This protocol provides secure file transfer (and more generally file 71 system access) functionality over a reliable data stream, such as a 72 channel in the Secure Shell Remote Login Protocol [SECSH-ARCH]. 74 This protocol is designed so that it could be used to implement a secure 75 remote file system service, as well as a secure file transfer service. 77 This protocol assumes that it runs over a secure channel, and that the 78 server has already authenticated the user at the client end, and that 79 the identity of the client user is externally available to the server 80 implementation. 82 In general, this protocol follows a simple request-response model. Each 83 request and response contains a sequence number and multiple requests 84 may be pending simultaneously. There are a relatively large number of 85 different request messages, but a small number of possible response 86 messages. Each request has one or more response messages that may be 87 returned in result (e.g., a read either returns data or reports error 88 status). 90 The packet format descriptions in this specification follow the notation 91 presented in [SECSH-ARCH]. 93 Even though this protocol is described in the context of the Secure 94 Shell Remote Login Protocol, this protocol is general and independent of 95 the rest of the Secure Shell protocol suite. It could be used in a 96 number of different applications, such as secure file transfer over TLS 97 [RFC-2246] and transfer of management information in VPN applications. 99 2. Use with the Secure Shell Connection Protocol 101 When used with the Secure Shell protocol suite, this protocol is 102 intended to be used from the Secure Shell Connection Protocol as a 103 subsystem, as described in [SECSH-CONN], Section ``Starting a Shell or a 104 Command''. The subsystem name used with this protocol is "sftp". 106 3. General Packet Format 108 All packets transmitted over the secure connection are of the following 109 format: 111 uint32 length 112 byte type 113 byte[length - 1] data payload 115 That is, they are just data preceded by 32-bit length and 8-bit type 116 fields. The `length' is the length of the data area, and does not 117 include the `length' field itself. The format and interpretation of the 118 data area depends on the packet type. 120 All packet descriptions below only specify the packet type and the data 121 that goes into the data field. Thus, they should be prefixed by the 122 `length' and `type' fields. 124 The maximum size of a packet is in practise determined by the client 125 (the maximum size of read or write requests that it sends, plus a few 126 bytes of packet overhead). All servers SHOULD support packets of at 127 least 34000 bytes (where the packet size refers to the full length, 128 including the header above). This should allow for reads and writes of 129 at most 32768 bytes. 131 There is no limit on the number of outstanding (non-acknowledged) 132 requests that the client may send to the server. In practise this is 133 limited by the buffering available on the data stream and the queuing 134 performed by the server. If the server's queues are full, it should not 135 read any more data from the stream, and flow control will prevent the 136 client from sending more requests. Note, however, that while there is 137 no restriction on the protocol level, the client's API may provide a 138 limit in order to prevent infinite queueing of outgoing requests at the 139 client. 141 The following values are defined for packet types. 143 #define SSH_FXP_INIT 1 144 #define SSH_FXP_VERSION 2 145 #define SSH_FXP_OPEN 3 146 #define SSH_FXP_CLOSE 4 147 #define SSH_FXP_READ 5 148 #define SSH_FXP_WRITE 6 149 #define SSH_FXP_LSTAT 7 150 #define SSH_FXP_FSTAT 8 151 #define SSH_FXP_SETSTAT 9 152 #define SSH_FXP_FSETSTAT 10 153 #define SSH_FXP_OPENDIR 11 154 #define SSH_FXP_READDIR 12 155 #define SSH_FXP_REMOVE 13 156 #define SSH_FXP_MKDIR 14 157 #define SSH_FXP_RMDIR 15 158 #define SSH_FXP_REALPATH 16 159 #define SSH_FXP_STAT 17 160 #define SSH_FXP_RENAME 18 161 #define SSH_FXP_READLINK 19 162 #define SSH_FXP_SYMLINK 20 163 #define SSH_FXP_STATUS 101 164 #define SSH_FXP_HANDLE 102 165 #define SSH_FXP_DATA 103 166 #define SSH_FXP_NAME 104 167 #define SSH_FXP_ATTRS 105 168 #define SSH_FXP_EXTENDED 200 169 #define SSH_FXP_EXTENDED_REPLY 201 171 Additional packet types should only be defined if the protocol version 172 number (see Section ``Protocol Initialization'') is incremented, and 173 their use MUST be negotiated using the version number. However, the 174 SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to 175 implement vendor-specific extensions. See Section ``Vendor-Specific 176 Extensions'' for more details. 178 4. Protocol Initialization 180 When the file transfer protocol starts, it first sends a SSH_FXP_INIT 181 (including its version number) packet to the server. The server 182 responds with a SSH_FXP_VERSION packet, supplying the lowest of its own 183 and the client's version number. Both parties should from then on 184 adhere to particular version of the protocol. 186 The SSH_FXP_INIT packet (from client to server) has the following data: 188 uint32 version 189 191 The SSH_FXP_VERSION packet (from server to client) has the following 192 data: 194 uint32 version 195 197 The version number of the protocol specified in this document is 3. The 198 version number should be incremented for each incompatible revision of 199 this protocol. 201 The extension data in the above packets may be empty, or may be a 202 sequence of 204 string extension_name 205 string extension_data 207 pairs (both strings MUST always be present if one is, but the `exten- 208 sion_data' string may be of zero length). If present, these strings 209 indicate extensions to the baseline protocol. The `extension_name' 210 field(s) identify the name of the extension. The name should be of the 211 form "name@domain", where the domain is the DNS domain name of the orga- 212 nization defining the extension. Additional names that are not of this 213 format may be defined later by the IETF. Implementations MUST silently 214 ignore any extensions whose name they do not recognize. 216 5. File Attributes 218 A new compound data type is defined for encoding file attributes. It is 219 basically just a combination of elementary types, but is defined once 220 because of the non-trivial description of the fields and to ensure 221 maintainability. 223 The same encoding is used both when returning file attributes from the 224 server and when sending file attributes to the server. When sending it 225 to the server, the flags field specifies which attributes are included, 226 and the server will use default values for the remaining attributes (or 227 will not modify the values of remaining attributes). When receiving 228 attributes from the server, the flags specify which attributes are 229 included in the returned data. The server normally returns all 230 attributes it knows about. 232 uint32 flags 233 uint64 size present only if flag SSH_FILEXFER_ATTR_SIZE 234 uint32 uid present only if flag SSH_FILEXFER_ATTR_UIDGID 235 uint32 gid present only if flag SSH_FILEXFER_ATTR_UIDGID 236 uint32 permissions present only if flag 237 SSH_FILEXFER_ATTR_PERMISSIONS 238 uint32 atime present only if flag SSH_FILEXFER_ACMODTIME 239 uint32 mtime present only if flag SSH_FILEXFER_ACMODTIME 240 uint32 extended_count present only if flag 241 SSH_FILEXFER_ATTR_EXTENDED 242 string extended_type 243 string extended_data 244 ... more extended data (extended_type - extended_data pairs), 245 so that number of pairs equals extended_count 247 The `flags' specify which of the fields are present. Those fields for 248 which the corresponding flag is not set are not present (not included in 249 the packet). New flags can only be added by incrementing the protocol 250 version number (or by using the extension mechanism described below). 252 The `size' field specifies the size of the file in bytes. 254 The `uid' and `gid' fields contain numeric Unix-like user and group 255 identifiers, respectively. 257 The `permissions' field contains a bit mask of file permissions as 258 defined by [POSIX]. 260 The `atime' and `mtime' contain the access and modification times of the 261 files, respectively. They are represented as seconds from Jan 1, 1970 262 in UTC. 264 The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension 265 mechanism for vendor-specific extensions. If the flag is specified, 266 then the `extended_count' field is present. It specifies the number of 267 extended_type-extended_data pairs that follow. Each of these pairs 268 specifies an extended attribute. For each of the attributes, the 269 extended_type field should be a string of the format "name@domain", 270 where "domain" is a valid, registered domain name and "name" identifies 271 the method. The IETF may later standardize certain names that deviate 272 from this format (e.g., that do not contain the "@" sign). The 273 interpretation of `extended_data' depends on the type. Implementations 274 SHOULD ignore extended data fields that they do not understand. 276 Additional fields can be added to the attributes by either defining 277 additional bits to the flags field to indicate their presence, or by 278 defining extended attributes for them. The extended attributes 279 mechanism is recommended for most purposes; additional flags bits should 280 only be defined by an IETF standards action that also increments the 281 protocol version number. The use of such new fields MUST be negotiated 282 by the version number in the protocol exchange. It is a protocol error 283 if a packet with unsupported protocol bits is received. 285 The flags bits are defined to have the following values: 287 #define SSH_FILEXFER_ATTR_SIZE 0x00000001 288 #define SSH_FILEXFER_ATTR_UIDGID 0x00000002 289 #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 290 #define SSH_FILEXFER_ATTR_ACMODTIME 0x00000008 291 #define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 293 6. Responses from the Server to the Client 295 The server responds to the client using one of a few response packets. 296 All requests can return a SSH_FXP_STATUS response upon failure. When 297 the operation is successful, any of the responses may be returned 298 (depending on the operation). If no data needs to be returned to the 299 client, the SSH_FXP_STATUS response with SSH_FX_OK status is 300 appropriate. Otherwise, the SSH_FXP_HANDLE message is used to return a 301 file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR requests), 302 SSH_FXP_DATA is used to return data from SSH_FXP_READ, SSH_FXP_NAME is 303 used to return one or more file names from a SSH_FXP_READDIR or 304 SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is used to return file 305 attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and SSH_FXP_FSTAT requests. 307 Exactly one response will be returned for each request. Each response 308 packet contains a request identifier which can be used to match each 309 response with the corresponding request. Note that it is legal to have 310 several requests outstanding simultaneously, and the server is allowed 311 to send responses to them in a different order from the order in which 312 the requests were sent (the result of their execution, however, is 313 guaranteed to be as if they had been processed one at a time in the 314 order in which the requests were sent). 316 Response packets are of the same general format as request packets. 317 Each response packet begins with the request identifier. 319 The format of the data portion of the SSH_FXP_STATUS response is as 320 follows: 322 uint32 id 323 uint32 error/status code 324 string error message (ISO-10646 UTF-8 [RFC-2279]) 325 string language tag (as defined in [RFC-1766]) 327 where `id' is the request identifier, and `error/status code' indicates 328 the result of the requested operation. The value SSH_FX_OK indicates 329 success, and all other values indicate failure. Currently, the follow- 330 ing values are defined (other values may be defined by future versions 331 of this protocol): 333 #define SSH_FX_OK 0 334 #define SSH_FX_EOF 1 335 #define SSH_FX_NO_SUCH_FILE 2 336 #define SSH_FX_PERMISSION_DENIED 3 337 #define SSH_FX_FAILURE 4 338 #define SSH_FX_BAD_MESSAGE 5 339 #define SSH_FX_NO_CONNECTION 6 340 #define SSH_FX_CONNECTION_LOST 7 341 #define SSH_FX_OP_UNSUPPORTED 8 343 SSH_FX_OK 344 Indicates successful completion of the operation. 346 SSH_FX_EOF 347 indicates end-of-file condition; for SSH_FX_READ it means that no 348 more data is available in the file, and for SSH_FX_READDIR it 349 indicates that no more files are contained in the directory. 351 SSH_FX_NO_SUCH_FILE 352 is returned when a reference is made to a file which should exist 353 but doesn't. 355 SSH_FX_PERMISSION_DENIED 356 is returned when the authenticated user does not have sufficient 357 permissions to perform the operation. 359 SSH_FX_FAILURE 360 is a generic catch-all error message; it should be returned if an 361 error occurs for which there is no more specific error code 362 defined. 364 SSH_FX_BAD_MESSAGE 365 may be returned if a badly formatted packet or protocol 366 incompatibility is detected. 368 SSH_FX_NO_CONNECTION 369 is a pseudo-error which indicates that the client has no 370 connection to the server (it can only be generated locally by the 371 client, and MUST NOT be returned by servers). 373 SSH_FX_CONNECTION_LOST 374 is a pseudo-error which indicates that the connection to the 375 server has been lost (it can only be generated locally by the 376 client, and MUST NOT be returned by servers). 378 SSH_FX_OP_UNSUPPORTED 379 indicates that an attempt was made to perform an operation which 380 is not supported for the server (it may be generated locally by 381 the client if e.g. the version number exchange indicates that a 382 required feature is not supported by the server, or it may be 383 returned by the server if the server does not implement an 384 operation). 386 The SSH_FXP_HANDLE response has the following format: 388 uint32 id 389 string handle 391 where `id' is the request identifier, and `handle' is an arbitrary 392 string that identifies an open file or directory on the server. The 393 handle is opaque to the client; the client MUST NOT attempt to interpret 394 or modify it in any way. The length of the handle string MUST NOT 395 exceed 256 data bytes. 397 The SSH_FXP_DATA response has the following format: 399 uint32 id 400 string data 402 where `id' is the request identifier, and `data' is an arbitrary byte 403 string containing the requested data. The data string may be at most 404 the number of bytes requested in a SSH_FXP_READ request, but may also be 405 shorter if end of file is reached or if the read is from something other 406 than a regular file. 408 The SSH_FXP_NAME response has the following format: 410 uint32 id 411 uint32 count 412 repeats count times: 413 string filename 414 string longname 415 ATTRS attrs 417 where `id' is the request identifier, `count' is the number of names 418 returned in this response, and the remaining fields repeat `count' times 419 (so that all three fields are first included for the first file, then 420 for the second file, etc). In the repeated part, `filename' is a file 421 name being returned (for SSH_FXP_READDIR, it will be a relative name 422 within the directory, without any path components; for SSH_FXP_REALPATH 423 it will be an absolute path name), `longname' is an expanded format for 424 the file name, similar to what is returned by "ls -l" on Unix systems, 425 and `attrs' is the attributes of the file as described in Section ``File 426 Attributes''. 428 The format of the `longname' field is unspecified by this protocol. It 429 MUST be suitable for use in the output of a directory listing command 430 (in fact, the recommended operation for a directory listing command is 431 to simply display this data). However, clients SHOULD NOT attempt to 432 parse the longname field for file attributes; they SHOULD use the attrs 433 field instead. 435 The recommended format for the longname field is as follows: 437 -rwxr-xr-x 1 mjos staff 348911 Mar 25 14:29 t-filexfer 438 1234567890 123 12345678 12345678 12345678 123456789012 440 Here, the first line is sample output, and the second field indicates 441 widths of the various fields. Fields are separated by spaces. The 442 first field lists file permissions for user, group, and others; the sec- 443 ond field is link count; the third field is the name of the user who 444 owns the file; the fourth field is the name of the group that owns the 445 file; the fifth field is the size of the file in bytes; the sixth field 446 (which actually may contain spaces, but is fixed to 12 characters) is 447 the file modification time, and the seventh field is the file name. 448 Each field is specified to be a minimum of certain number of character 449 positions (indicated by the second line above), but may also be longer 450 if the data does not fit in the specified length. 452 The SSH_FXP_ATTRS response has the following format: 454 uint32 id 455 ATTRS attrs 457 where `id' is the request identifier, and `attrs' is the returned file 458 attributes as described in Section ``File Attributes''. 460 7. Requests From the Client to the Server 462 Requests from the client to the server represent the various file system 463 operations. Each request begins with an `id' field, which is a 32-bit 464 identifier identifying the request (selected by the client). The same 465 identifier will be returned in the response to the request. One 466 possible implementation of it is a monotonically increasing request 467 sequence number (modulo 2^32). 469 Many operations in the protocol operate on open files. The SSH_FXP_OPEN 470 request can return a file handle (which is an opaque variable-length 471 string) which may be used to access the file later (e.g. in a read 472 operation). The client MUST NOT send requests the server with bogus or 473 closed handles. However, the server MUST perform adequate checks on the 474 handle in order to avoid security risks due to fabricated handles. 476 This design allows either stateful and stateless server implementation, 477 as well as an implementation which caches state between requests but may 478 also flush it. The contents of the file handle string are entirely up 479 to the server and its design. The client should not modify or attempt 480 to interpret the file handle strings. 482 The file handle strings MUST NOT be longer than 256 bytes. 484 7.1. Request Synchronization and Reordering 486 The protocol and implementations MUST process requests relating to the 487 same file in the order in which they are received. In other words, if 488 an application submits multiple requests to the server, the results in 489 the responses will be the same as if it had sent the requests one at a 490 time and waited for the response in each case. For example, the server 491 may process non-overlapping read/write requests to the same file in 492 parallel, but overlapping reads and writes cannot be reordered or 493 parallelized. However, there are no ordering restrictions on the server 494 for processing requests from two different file transfer connections. 495 The server may interleave and parallelize them at will. 497 There are no restrictions on the order in which responses to outstanding 498 requests are delivered to the client, except that the server must ensure 499 fairness in the sense that processing of no request will be indefinitely 500 delayed even if the client is sending other requests so that there are 501 multiple outstanding requests all the time. 503 7.2. File Names 505 This protocol represents file names as strings. File names are assumed 506 to use the slash ('/') character as a directory separator. 508 File names starting with a slash are "absolute", and are relative to the 509 root of the file system. Names starting with any other character are 510 relative to the user's default directory (home directory). Note that 511 identifying the user is assumed to take place outside of this protocol. 513 Servers SHOULD interpret a path name component ".." as referring to the 514 parent directory, and "." as referring to the current directory. If the 515 server implementation limits access to certain parts of the file system, 516 it must be extra careful in parsing file names when enforcing such 517 restrictions. There have been numerous reported security bugs where a 518 ".." in a path name has allowed access outside the intended area. 520 An empty path name is valid, and it refers to the user's default 521 directory (usually the user's home directory). 523 Otherwise, no syntax is defined for file names by this specification. 524 Clients should not make any other assumptions; however, they can splice 525 path name components returned by SSH_FXP_READDIR together using a slash 526 ('/') as the separator, and that will work as expected. 528 It is understood that the lack of well-defined semantics for file names 529 may cause interoperability problems between clients and servers using 530 radically different operating systems. However, this approach is known 531 to work acceptably with most systems, and alternative approaches that 532 e.g. treat file names as sequences of structured components are quite 533 complicated. 535 7.3. Opening, Creating, and Closing Files 537 Files are opened and created using the SSH_FXP_OPEN message, whose data 538 part is as follows: 540 uint32 id 541 string filename 542 uint32 pflags 543 ATTRS attrs 545 The `id' field is the request identifier as for all requests. 547 The `filename' field specifies the file name. See Section ``File 548 Names'' for more information. 550 The `pflags' field is a bitmask. The following bits have been defined. 552 #define SSH_FXF_READ 0x00000001 553 #define SSH_FXF_WRITE 0x00000002 554 #define SSH_FXF_APPEND 0x00000004 555 #define SSH_FXF_CREAT 0x00000008 556 #define SSH_FXF_TRUNC 0x00000010 557 #define SSH_FXF_EXCL 0x00000020 559 These have the following meanings: 561 SSH_FXF_READ 562 Open the file for reading. 564 SSH_FXF_WRITE 565 Open the file for writing. If both this and SSH_FXF_READ are 566 specified, the file is opened for both reading and writing. 568 SSH_FXF_APPEND 569 Force all writes to append data at the end of the file. 571 SSH_FXF_CREAT 572 If this flag is specified, then a new file will be created if one 573 does not alread exist (if O_TRUNC is specified, the new file will 574 be truncated to zero length if it previously exists). 576 SSH_FXF_TRUNC 577 Forces an existing file with the same name to be truncated to zero 578 length when creating a file by specifying SSH_FXF_CREAT. 579 SSH_FXF_CREAT MUST also be specified if this flag is used. 581 SSH_FXF_EXCL 582 Causes the request to fail if the named file already exists. 583 SSH_FXF_CREAT MUST also be specified if this flag is used. 585 The `attrs' field specifies the initial attributes for the file. 586 Default values will be used for those attributes that are not specified. 587 See Section ``File Attributes'' for more information. 589 Regardless the server operating system, the file will always be opened 590 in "binary" mode (i.e., no translations between different character sets 591 and newline encodings). 593 The response to this message will be either SSH_FXP_HANDLE (if the 594 operation is successful) or SSH_FXP_STATUS (if the operation fails). 596 A file is closed by using the SSH_FXP_CLOSE request. Its data field has 597 the following format: 599 uint32 id 600 string handle 602 where `id' is the request identifier, and `handle' is a handle previ- 603 ously returned in the response to SSH_FXP_OPEN or SSH_FXP_OPENDIR. The 604 handle becomes invalid immediately after this request has been sent. 606 The response to this request will be a SSH_FXP_STATUS message. One 607 should note that on some server platforms even a close can fail. This 608 can happen e.g. if the server operating system caches writes, and an 609 error occurs while flushing cached writes during the close. 611 7.4. Reading and Writing 613 Once a file has been opened, it can be read using the SSH_FXP_READ 614 message, which has the following format: 616 uint32 id 617 string handle 618 uint64 offset 619 uint32 len 621 where `id' is the request identifier, `handle' is an open file handle 622 returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative to 623 the beginning of the file from where to start reading, and `len' is the 624 maximum number of bytes to read. 626 In response to this request, the server will read as many bytes as it 627 can from the file (up to `len'), and return them in a SSH_FXP_DATA 628 message. If an error occurs or EOF is encountered before reading any 629 data, the server will respond with SSH_FXP_STATUS. For normal disk 630 files, it is guaranteed that this will read the specified number of 631 bytes, or up to end of file. For e.g. device files this may return 632 fewer bytes than requested. 634 Writing to a file is achieved using the SSH_FXP_WRITE message, which has 635 the following format: 637 uint32 id 638 string handle 639 uint64 offset 640 string data 642 where `id' is a request identifier, `handle' is a file handle returned 643 by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the beginning of 644 the file where to start writing, and `data' is the data to be written. 646 The write will extend the file if writing beyond the end of the file. 647 It is legal to write way beyond the end of the file; the semantics are 648 to write zeroes from the end of the file to the specified offset and 649 then the data. On most operating systems, such writes do not allocate 650 disk space but instead leave "holes" in the file. 652 The server responds to a write request with a SSH_FXP_STATUS message. 654 7.5. Removing and Renaming Files 656 Files can be removed using the SSH_FXP_REMOVE message. It has the 657 following format: 659 uint32 id 660 string filename 662 where `id' is the request identifier and `filename' is the name of the 663 file to be removed. See Section ``File Names'' for more information. 664 This request cannot be used to remove directories. 666 The server will respond to this request with a SSH_FXP_STATUS message. 668 Files (and directories) can be renamed using the SSH_FXP_RENAME message. 669 Its data is as follows: 671 uint32 id 672 string oldpath 673 string newpath 675 where `id' is the request identifier, `oldpath' is the name of an exist- 676 ing file or directory, and `newpath' is the new name for the file or 677 directory. It is an error if there already exists a file with the name 678 specified by newpath. The server may also fail rename requests in other 679 situations, for example if `oldpath' and `newpath' point to different 680 file systems on the server. 682 The server will respond to this request with a SSH_FXP_STATUS message. 684 7.6. Creating and Deleting Directories 686 New directories can be created using the SSH_FXP_MKDIR request. It has 687 the following format: 689 uint32 id 690 string path 691 ATTRS attrs 693 where `id' is the request identifier, `path'and `attrs' specifies the 694 modifications to be made to its attributes. See Section ``File Names'' 695 for more information on file names. Attributes are discussed in more 696 detail in Section ``File Attributes''. specifies the directory to be 697 created. An error will be returned if a file or directory with the 698 specified path already exists. The server will respond to this request 699 with a SSH_FXP_STATUS message. 701 Directories can be removed using the SSH_FXP_RMDIR request, which has 702 the following format: 704 uint32 id 705 string path 707 where `id' is the request identifier, and `path' specifies the directory 708 to be removed. See Section ``File Names'' for more information on file 709 names. An error will be returned if no directory with the specified 710 path exists, or if the specified directory is not empty, or if the path 711 specified a file system object other than a directory. The server 712 responds to this request with a SSH_FXP_STATUS message. 714 7.7. Scanning Directories 716 The files in a directory can be listed using the SSH_FXP_OPENDIR and 717 SSH_FXP_READDIR requests. Each SSH_FXP_READDIR request returns one or 718 more file names with full file attributes for each file. The client 719 should call SSH_FXP_READDIR repeatedly until it has found the file it is 720 looking for or until the server responds with a SSH_FXP_STATUS message 721 indicating an error (normally SSH_FX_EOF if there are no more files in 722 the directory). The client should then close the handle using the 723 SSH_FXP_CLOSE request. 725 The SSH_FXP_OPENDIR opens a directory for reading. It has the following 726 format: 728 uint32 id 729 string path 731 where `id' is the request identifier and `path' is the path name of the 732 directory to be listed (without any trailing slash). See Section ``File 733 Names'' for more information on file names. This will return an error 734 if the path does not specify a directory or if the directory is not 735 readable. The server will respond to this request with either a 736 SSH_FXP_HANDLE or a SSH_FXP_STATUS message. 738 Once the directory has been successfully opened, files (and directories) 739 contained in it can be listed using SSH_FXP_READDIR requests. These are 740 of the format 742 uint32 id 743 string handle 745 where `id' is the request identifier, and `handle' is a handle returned 746 by SSH_FXP_OPENDIR. (It is a protocol error to attempt to use an ordi- 747 nary file handle returned by SSH_FXP_OPEN.) 749 The server responds to this request with either a SSH_FXP_NAME or a 750 SSH_FXP_STATUS message. One or more names may be returned at a time. 751 Full status information is returned for each name in order to speed up 752 typical directory listings. 754 When the client no longer wishes to read more names from the directory, 755 it SHOULD call SSH_FXP_CLOSE for the handle. The handle should be 756 closed regardless of whether an error has occurred or not. 758 7.8. Retrieving File Attributes 760 Very often, file attributes are automatically returned by 761 SSH_FXP_READDIR. However, sometimes there is need to specifically 762 retrieve the attributes for a named file. This can be done using the 763 SSH_FXP_STAT, SSH_FXP_LSTAT and SSH_FXP_FSTAT requests. 765 SSH_FXP_STAT and SSH_FXP_LSTAT only differ in that SSH_FXP_STAT follows 766 symbolic links on the server, whereas SSH_FXP_LSTAT does not follow 767 symbolic links. Both have the same format: 769 uint32 id 770 string path 772 where `id' is the request identifier, and `path' spefifies the file sys- 773 tem object for which status is to be returned. The server responds to 774 this request with either SSH_FXP_ATTRS or SSH_FXP_STATUS. 776 SSH_FXP_FSTAT differs from the others in that it returns status 777 information for an open file (identified by the file handle). Its 778 format is as follows: 780 uint32 id 781 string handle 783 where `id' is the request identifier and `handle' is a file handle 784 returned by SSH_FXP_OPEN. The server responds to this request with 785 SSH_FXP_ATTRS or SSH_FXP_STATUS. 787 7.9. Setting File Attributes 789 File attributes may be modified using the SSH_FXP_SETSTAT and 790 SSH_FXP_FSETSTAT requests. These requests are used for operations such 791 as changing the ownership, permissions or access times, as well as for 792 truncating a file. 794 The SSH_FXP_SETSTAT request is of the following format: 796 uint32 id 797 string path 798 ATTRS attrs 800 where `id' is the request identifier, `path' specifies the file system 801 object (e.g. file or directory) whose attributes are to be modified, and 802 `attrs' specifies the modifications to be made to its attributes. 803 Attributes are discussed in more detail in Section ``File Attributes''. 805 An error will be returned if the specified file system object does not 806 exist or the user does not have sufficient rights to modify the 807 specified attributes. The server responds to this request with a 808 SSH_FXP_STATUS message. 810 The SSH_FXP_FSETSTAT request modifies the attributes of a file which is 811 already open. It has the following format: 813 uint32 id 814 string handle 815 ATTRS attrs 817 where `id' is the request identifier, `handle' (MUST be returned by 818 SSH_FXP_OPEN) identifies the file whose attributes are to be modified, 819 and `attrs' specifies the modifications to be made to its attributes. 820 Attributes are discussed in more detail in Section ``File Attributes''. 821 The server will respond to this request with SSH_FXP_STATUS. 823 7.10. Dealing with Symbolic links 825 The SSH_FXP_READLINK request may be used to read the target of a 826 symbolic link. It would have a data part as follows: 828 uint32 id 829 string path 831 where `id' is the request identifier and `path' specifies the path name 832 of the symlink to be read. 834 The server will respond with a SSH_FXP_NAME packet containing only one 835 name and a dummy attributes value. The name in the returned packet 836 contains the target of the link. If an error occurs, the server may 837 respond with SSH_FXP_STATUS. 839 The SSH_FXP_SYMLINK request will create a symbolic link on the server. 840 It is of the following format 842 uint32 id 843 string linkpath 844 string targetpath 846 where `id' is the request identifier, `linkpath' specifies the path name 847 of the symlink to be created and `targetpath' specifies the target of 848 the symlink. The server shall respond with a SSH_FXP_STATUS indicating 849 either success (SSH_FX_OK) or an error condition. 851 7.11. Canonicalizing the Server-Side Path Name 853 The SSH_FXP_REALPATH request can be used to have the server canonicalize 854 any given path name to an absolute path. This is useful for converting 855 path names containing ".." components or relative pathnames without a 856 leading slash into absolute paths. The format of the request is as 857 follows: 859 uint32 id 860 string path 862 where `id' is the request identifier and `path' specifies the path name 863 to be canonicalized. The server will respond with a SSH_FXP_NAME packet 864 containing only one name and a dummy attributes value. The name is the 865 returned packet will be in canonical form. If an error occurs, the 866 server may also respond with SSH_FXP_STATUS. 868 8. Vendor-Specific Extensions 870 The SSH_FXP_EXTENDED request provides a generic extension mechanism for 871 adding vendor-specific commands. The request has the following format: 873 uint32 id 874 string extended-request 875 ... any request-specific data ... 877 where `id' is the request identifier, and `extended-request' is a string 878 of the format "name@domain", where domain is an internet domain name of 879 the vendor defining the request. The rest of the request is completely 880 vendor-specific, and servers should only attempt to interpret it if they 881 recognize the `extended-request' name. 883 The server may respond to such requests using any of the response 884 packets defined in Section ``Responses from the Server to the Client''. 885 Additionally, the server may also respond with a SSH_FXP_EXTENDED_REPLY 886 packet, as defined below. If the server does not recognize the 887 `extended-request' name, then the server MUST respond with 888 SSH_FXP_STATUS with error/status set to SSH_FX_OP_UNSUPPORTED. 890 The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary 891 extension-specific data from the server to the client. It is of the 892 following format: 894 uint32 id 895 ... any request-specific data ... 897 9. Security Considerations 899 This protocol assumes that it is run over a secure channel and that the 900 endpoints of the channel have been authenticated. Thus, this protocol 901 assumes that it is externally protected from network-level attacks. 903 This protocol provides file system access to arbitrary files on the 904 server (only constrained by the server implementation). It is the 905 responsibility of the server implementation to enforce any access 906 controls that may be required to limit the access allowed for any 907 particular user (the user being authenticated externally to this 908 protocol, typically using the Secure Shell User Authentication Protocol 909 [SECSH-USERAUTH]. 911 Care must be taken in the server implementation to check the validity of 912 received file handle strings. The server should not rely on them 913 directly; it MUST check the validity of each handle before relying on 914 it. 916 10. Changes from previous protocol versions 918 The Secure Shell File Transfer Protocol has changed over time, before 919 it's standardization. The following is a description of the 920 incompatible changes between different versions. 922 10.1. Changes between versions 3 and 2 924 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK mesages were added. 926 o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were added. 928 o The SSH_FXP_STATUS message was changed to include fields `error 929 message' and `language tag'. 931 10.2. Changes between versions 2 and 1 933 o The SSH_FXP_RENAME message was added. 935 10.3. Changes between versions 1 and 0 937 o Implementation changes, no actual protocol changes. 939 11. Trademark Issues 941 "ssh" is a registered trademark of SSH Communications Security Corp in 942 the United States and/or other countries. 944 12. References 946 [RFC-2246] Dierks, T. and Allen, C.: "The TLS Protocol Version 1.0", 947 January 1999 949 [POSIX] ISO/IEC Std 9945-1, ANSI/IEEE Std 1003.1 Information technology 950 -- Portable Operating System Interface (POSIX)-Part 1: System 951 Application Program Interface (API) [C Language], July 1996. 953 [SECSH-ARCH] Ylonen, T., et al: "Secure Shell Protocol Architecture", 954 Internet-Draft, draft-ietf-secsh-architecture-08.txt 956 [SECSH-TRANSPORT] Ylonen, T., et al: "Secure Shell Transport Protocol", 957 Internet-Draft, draft-ietf-secsh-transport-10.txt 959 [SECSH-USERAUTH] Ylonen, T., et al: "Secure Shell Authentication 960 Protocol", Internet-Draft, draft-ietf-secsh-userauth-10.txt 962 [SECSH-CONNECT] Ylonen, T., et al: "Secure Shell Connection Protocol", 963 Internet-Draft, draft-ietf-secsh-connect-10.txt 965 13. Authors' Addresses 967 Tatu Ylonen 968 SSH Communications Security Corp 969 Fredrikinkatu 42 970 FIN-00100 HELSINKI 971 Finland 972 E-mail: ylo@ssh.com 974 Sami Lehtinen 975 SSH Communications Security Corp 976 Fredrikinkatu 42 977 FIN-00100 HELSINKI 978 Finland 979 E-mail: sjl@ssh.com