idnits 2.17.1 draft-ietf-secsh-filexfer-extensions-00.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 16. -- Found old boilerplate from RFC 3978, Section 5.5 on line 442. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 419. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 426. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 432. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 111: '... The status SHOULD be SSH_FX_OK....' RFC 2119 keyword, line 130: '...OPEN, the server MUST return SSH_FX_IN...' RFC 2119 keyword, line 132: '... server MUST return STATUS_PERMIS...' RFC 2119 keyword, line 141: '... SHOULD be returned. If 'check-f...' RFC 2119 keyword, line 146: '... The file MUST be opened without ...' (15 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 185 has weird spacing: '... byte hash...' == Line 276 has weird spacing: '... bool over...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (January 18, 2006) is 6644 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'UTF-8' is mentioned on line 259, but not defined ** Downref: Normative reference to an Informational RFC: RFC 1321 ** Obsolete normative reference: RFC 1510 (Obsoleted by RFC 4120, RFC 6649) == Outdated reference: A later version (-13) exists of draft-ietf-secsh-filexfer-10 -- Possible downref: Normative reference to a draft: ref. 'I-D.ietf-secsh-filexfer' -- Possible downref: Non-RFC (?) normative reference: ref. 'FIPS-180-2' Summary: 7 errors (**), 0 flaws (~~), 6 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Secure Shell Working Group J. Galbraith 3 Internet-Draft VanDyke Software 4 Expires: July 22, 2006 O. Saarenmaa 5 F-Secure 6 January 18, 2006 8 SSH File Transfer Protocol 9 draft-ietf-secsh-filexfer-extensions-00.txt 11 Status of this Memo 13 By submitting this Internet-Draft, each author represents that any 14 applicable patent or other IPR claims of which he or she is aware 15 have been or will be disclosed, and any of which he or she becomes 16 aware will be disclosed, in accordance with Section 6 of BCP 79. 18 Internet-Drafts are working documents of the Internet Engineering 19 Task Force (IETF), its areas, and its working groups. Note that 20 other groups may also distribute working documents as Internet- 21 Drafts. 23 Internet-Drafts are draft documents valid for a maximum of six months 24 and may be updated, replaced, or obsoleted by other documents at any 25 time. It is inappropriate to use Internet-Drafts as reference 26 material or to cite them other than as "work in progress." 28 The list of current Internet-Drafts can be accessed at 29 http://www.ietf.org/ietf/1id-abstracts.txt. 31 The list of Internet-Draft Shadow Directories can be accessed at 32 http://www.ietf.org/shadow.html. 34 This Internet-Draft will expire on July 22, 2006. 36 Copyright Notice 38 Copyright (C) The Internet Society (2006). 40 Abstract 42 The SSH File Transfer Protocol provides a rich infrastructure for 43 sharing information about files. This document describes several 44 optional extensions that build on this infrastructure. 46 Table of Contents 48 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 49 2. Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . . . 3 50 3. File Hashing . . . . . . . . . . . . . . . . . . . . . . . . . 4 51 4. Querying Available Space . . . . . . . . . . . . . . . . . . . 6 52 5. Querying User Home Directory . . . . . . . . . . . . . . . . . 7 53 6. Copying Remote Files . . . . . . . . . . . . . . . . . . . . . 7 54 7. Copying remote data . . . . . . . . . . . . . . . . . . . . . 7 55 8. Temporary files & directories . . . . . . . . . . . . . . . . 8 56 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 57 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 58 10.1. Normative References . . . . . . . . . . . . . . . . . . 9 59 10.2. Informative References . . . . . . . . . . . . . . . . . 9 60 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 61 Intellectual Property and Copyright Statements . . . . . . . . . . 12 63 1. Introduction 65 This is a collection of optional extensions to the SSH File Transfer 66 Protocol [I-D.ietf-secsh-filexfer]. This extensions make it possible 67 for clients to query the server for additional information which may 68 not be widely supported, but can increase the quality of the users 69 experience when the server can support them. 71 2. Vendor Id 73 It is often necessary to detect the version of the server so that 74 bugs can be worked around. This extension allows the client to do 75 so. 77 string "vendor-id" 78 string vendor-structure 79 string vendor-name [UTF-8] 80 string product-name [UTF-8] 81 string product-version [UTF-8] 82 uint64 product-build-number 84 vendor-name 85 Arbitrary name identifying the maker of the product. 87 product-name 88 Arbitrary name identifying the product. 90 product-name 91 Arbitrary string identifying the version of the product. 93 product-build-number 94 A build-number for the product, such that if a bug is fixed in 95 build-number 'x', it can be assumed that (barring regression in 96 the product) it is fixed in all build-numbers > 'x'. 98 This extension may also be sent by the client as a SSH_FXP_EXTENDED 99 packet; in this case the contents of the vendor-structure become the 100 extension-specific data: 102 byte SSH_FXP_EXTENDED 103 uint32 request-id 104 string "vendor-id" 105 string vendor-name [UTF-8] 106 string product-name [UTF-8] 107 string product-version [UTF-8] 108 uint64 product-build-number 110 The server responds to this request with a SSH_FXP_STATUS message. 111 The status SHOULD be SSH_FX_OK. 113 3. File Hashing 115 This extension allows a client to easily check if a file (or portion 116 thereof) that it already has matches what is on the server. 118 byte SSH_FXP_EXTENDED 119 uint32 request-id 120 string "check-file-handle" / "check-file-name" 121 string handle / name 122 string hash-algorithm-list 123 uint64 start-offset 124 uint64 length 125 uint32 block-size 127 handle 128 For "check-file-handle", 'handle' is an open file handle returned 129 by SSH_FXP_OPEN. If 'handle' is not a handle returned by 130 SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. If 131 ACE4_READ_DATA was not included when the file was opened, the 132 server MUST return STATUS_PERMISSION_DENIED. 134 If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode, 135 the check must be performed on the data as it would be sent on the 136 wire. 138 name 139 For "check-file-name", 'name' is the path to the file to check. 140 If 'check-file-name' is a directory, SSH_FX_FILE_IS_A_DIRECTORY 141 SHOULD be returned. If 'check-file-name' refers to a 142 SSH_FILEXFER_TYPE_SYMLINK, the target should be opened. The 143 results are undefined file types other than 144 SSH_FILEXFER_TYPE_REGULAR. 146 The file MUST be opened without the SSH_FXF_ACCESS_TEXT_MODE 147 access flag (in binary mode.) 149 hash-algorithm-list 150 A comma separated list of hash algorithms the client is willing to 151 accept for this operation. The server MUST pick the first hash on 152 the list that it supports. 154 Currently defined algorithms are "md5", "sha1", "sha224", 155 "sha256", "sha384", "sha512", and "crc32". Additional algorithms 156 may be added by following the DNS extensibility naming convention 157 outlined in [RFC4251]. 159 MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384, 160 and SHA-512 are described in [FIPS-180-2]. [ISO.3309.1991] 161 describes crc32, and is the same algorithm used in [RFC1510] 163 start-offset 164 The starting offset of the data to include in the hash. 166 length 167 The length of data to include in the hash. If length is zero, all 168 the data from start-offset to the end-of-file should be included. 170 block-size 171 An independent hash MUST be computed over every block in the file. 172 The size of blocks is specified by block-size. The block-size 173 MUST NOT be smaller than 256 bytes. If the block-size is 0, then 174 only one hash, over the entire range, MUST be made. 176 The response is either a SSH_FXP_STATUS packet, indicating an error, 177 or the following extended reply packet: 179 This extension MUST be represented in the "supported2" extension as 180 "check-file" and both version MUST either be support or neither. 182 byte SSH_FXP_EXTENDED_REPLY 183 uint32 request-id 184 string hash-algo-used 185 byte hash[n][block-count] 187 hash-algo-used 188 The hash algorithm that was actually used. 190 hash 191 The computed hashes. The hash algorithm used determines the size 192 of n. The number of block-size chunks of data in the file 193 determines block-count. The hashes are placed in the packet one 194 after another, with no decoration. 196 Note that if the length of the range is not an even multiple of 197 block-size, the last hash will have been computed over only the 198 remainder of the range instead of a full block. 200 4. Querying Available Space 202 The following extension provides a way to discover the available 203 space for an arbitrary path. 205 byte SSH_FXP_EXTENDED 206 uint32 request-id 207 string "space-available" 208 string path [UTF-8] 210 path 211 'path' for which the available space should be reported. This 212 'path' is not required to be the mount point path, but MAY be a 213 directory or file contained within the mount. 215 The reply to the request is as follows: 217 byte SSH_FXP_EXTENDED_REPLY 218 uint32 request-id 219 uint64 bytes-on-device 220 uint64 unused-bytes-on-device 221 uint64 bytes-available-to-user 222 uint64 unused-bytes-available-to-user 223 uint32 bytes-per-allocation-unit 225 bytes-on-device 226 The total number of bytes on the device which stores 'path', both 227 used and unused, or 0 if unknown. 229 unused-bytes-on-device 230 The total number of unused bytes available on the device which 231 stores 'path', or 0 if unknown. 233 bytes-available-to-user 234 The total number of bytes, both used and unused, available to the 235 authenticated user on the device which stores 'path', or 0 if 236 unknown. 238 unused-bytes-available-to-user 239 The total number of unused bytes available to the authenticated 240 user on the device which stores 'path', or 0 if unknown. 242 bytes-per-allocation-unit 243 The number of bytes in each allocation unit on the device, or in 244 other words, the minimum number of bytes that a file allocation 245 size can grow or shrink by. If the server does not know this 246 information, or the file-system in use does not use allocation 247 blocks, this value MUST be 0. 249 5. Querying User Home Directory 251 Many users are used to being able to type '~' as an alias for their 252 home directory, or ~username as an alias for another user's home 253 directory. To support this feature, a server MAY support following 254 extension. 256 byte SSH_FXP_EXTENDED 257 uint32 request-id 258 string "home-directory" 259 string username [UTF-8] 261 username 262 Username whose home directory path is being requested. An empty 263 string implies the current user. 265 The reply to the request is either a SSH_FXP_STATUS packet or a 266 SSH_FXP_NAME packet containing the absolute real-path of the home 267 directory. 269 6. Copying Remote Files 271 byte SSH_FXP_EXTENDED 272 uint32 request-id 273 string "copy-file" 274 string source-file 275 string destination-file 276 bool overwrite-destination 278 This request copies a file from one location to another on the 279 server. The server responds with SSH_FXP_STATUS. 281 7. Copying remote data 283 byte SSH_FXP_EXTENDED 284 uint32 request-id 285 string "copy-data" 286 string read-from-handle 287 uint64 read-from-offset 288 uint64 read-data-length 289 string write-to-handle 290 uint64 write-to-offset 292 Copy data from one handle to another on the server. The server 293 responds with SSH_FXP_STATUS. 295 The server MUST copy the data exactly as if the client had issued a 296 series of SSH_FXP_READ requests on the read-from-handle starting at 297 read-from-offset and totaling read-data-length bytes, and issued a 298 series of SSH_FXP_WRITE packets on the write-to-handle, starting at 299 the write-from-offset, and totaling the total number of bytes read by 300 the SSH_FXP_READ packets. 302 If one of the files is open using SSH_FXF_TEXT_MODE, then operation 303 on that handle honors all of the SSH_FXF_TEXT_MODE behaviors. 305 The server SHOULD allow 'read-from-handle' and 'write-to-handle' to 306 be the same handle as long as the range of data is not overlapping. 307 This allows data to efficiently be moved within a file. The server 308 MUST fail the request with a SSH_FX_INVALID_PARAMETER if the range is 309 overlapping and it doesn't correctly handle this case. The server is 310 not required to detect overlapping ranges if read-from-handle and 311 write-to-handle are different handles referring to the same file. 313 If 'data-length' is 0, this imples data should be read until EOF is 314 encountered. 316 There are no protocol restictions on this operation; however, the 317 server MUST ensure that the user does not exceed quota, etc. The 318 server is, as always, free to complete this operation out of order if 319 it is too large to complete immediately, or to refuse a request that 320 is too large. 322 8. Temporary files & directories 324 byte SSH_FXP_EXTENDED 325 uint32 request-id 326 string "get-temp-folder" 328 Retrieves the users preferred location for temporary files and 329 folders. The server responds with SSH_FXP_STATUS or SSH_FXP_NAME 330 containing the realpath of the preferred location. 332 byte SSH_FXP_EXTENDED 333 uint32 request-id 334 string "make-temp-folder" 336 Requests that the server create a folder in the users preferred 337 location for temporary files and folders for use by the client. The 338 server responds with SSH_FXP_STATUS or SSH_FXP_NAME containing the 339 realpath of the new folder. 341 It is the clients responsibility to cleanup and remove the folder 342 when it is done with it. However, the server MAY remove the folder 343 and it's contents when the client closes the connection. 345 9. Security Considerations 347 The home directory extension could be used to discover whether a 348 given user is valid; however, since users are assumed to be 349 authenticated by the underlying protocol, this is probably not 350 significant in most situations. If a server would not normally allow 351 an authenticated user to query the existance of another user, the 352 server MUST NOT allow the "home-directory" extension. 354 10. References 356 10.1. Normative References 358 [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, 359 April 1992. 361 [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network 362 Authentication Service (V5)", RFC 1510, September 1993. 364 [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) 365 Protocol Architecture", RFC 4251, January 2006. 367 [I-D.ietf-secsh-filexfer] 368 Galbraith, J. and O. Saarenmaa, "SSH File Transfer 369 Protocol", draft-ietf-secsh-filexfer-10 (work in 370 progress), October 2005. 372 [FIPS-180-2] 373 National Institute of Standards and Technology, "Secure 374 Hash Standard (SHS)", Federal Information Processing 375 Standards Publication 180-2, August 2002. 377 [ISO.3309.1991] 378 International Organization for Standardization, 379 "Information Technology - Telecommunications and 380 information exchange between systems - High-level data 381 link control (HDLC) procedures - Frame structure", 382 ISO Standard 3309, June 1991. 384 10.2. Informative References 386 Trademark notice 387 "ssh" is a registered trademark in the United States and/or other 388 countries. 390 Authors' Addresses 392 Joseph Galbraith 393 VanDyke Software 394 4848 Tramway Ridge Blvd 395 Suite 101 396 Albuquerque, NM 87111 397 US 399 Phone: +1 505 332 5700 400 Email: galb-list@vandyke.com 402 Oskari Saarenmaa 403 F-Secure 404 Tammasaarenkatu 7 405 Helsinki 00180 406 FI 408 Email: oskari.saarenmaa@f-secure.com 410 Intellectual Property Statement 412 The IETF takes no position regarding the validity or scope of any 413 Intellectual Property Rights or other rights that might be claimed to 414 pertain to the implementation or use of the technology described in 415 this document or the extent to which any license under such rights 416 might or might not be available; nor does it represent that it has 417 made any independent effort to identify any such rights. Information 418 on the procedures with respect to rights in RFC documents can be 419 found in BCP 78 and BCP 79. 421 Copies of IPR disclosures made to the IETF Secretariat and any 422 assurances of licenses to be made available, or the result of an 423 attempt made to obtain a general license or permission for the use of 424 such proprietary rights by implementers or users of this 425 specification can be obtained from the IETF on-line IPR repository at 426 http://www.ietf.org/ipr. 428 The IETF invites any interested party to bring to its attention any 429 copyrights, patents or patent applications, or other proprietary 430 rights that may cover technology that may be required to implement 431 this standard. Please address the information to the IETF at 432 ietf-ipr@ietf.org. 434 Disclaimer of Validity 436 This document and the information contained herein are provided on an 437 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 438 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 439 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 440 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 441 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 442 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 444 Copyright Statement 446 Copyright (C) The Internet Society (2006). This document is subject 447 to the rights, licenses and restrictions contained in BCP 78, and 448 except as set forth therein, the authors retain all their rights. 450 Acknowledgment 452 Funding for the RFC Editor function is currently provided by the 453 Internet Society.