Secure Shell Working Group J. Galbraith Internet-Draft VanDyke Software Expires: July 22, 2006 O. Saarenmaa F-Secure January 18, 2006 SSH File Transfer Protocol draft-ietf-secsh-filexfer-extensions-00.txt Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on July 22, 2006. Copyright Notice Copyright (C) The Internet Society (2006). Abstract The SSH File Transfer Protocol provides a rich infrastructure for sharing information about files. This document describes several optional extensions that build on this infrastructure. Galbraith & Saarenmaa Expires July 22, 2006 [Page 1] Internet-Draft SSH File Transfer Protocol January 2006 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. File Hashing . . . . . . . . . . . . . . . . . . . . . . . . . 4 4. Querying Available Space . . . . . . . . . . . . . . . . . . . 6 5. Querying User Home Directory . . . . . . . . . . . . . . . . . 7 6. Copying Remote Files . . . . . . . . . . . . . . . . . . . . . 7 7. Copying remote data . . . . . . . . . . . . . . . . . . . . . 7 8. Temporary files & directories . . . . . . . . . . . . . . . . 8 9. Security Considerations . . . . . . . . . . . . . . . . . . . 9 10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 9 10.1. Normative References . . . . . . . . . . . . . . . . . . 9 10.2. Informative References . . . . . . . . . . . . . . . . . 9 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 11 Intellectual Property and Copyright Statements . . . . . . . . . . 12 Galbraith & Saarenmaa Expires July 22, 2006 [Page 2] Internet-Draft SSH File Transfer Protocol January 2006 1. Introduction This is a collection of optional extensions to the SSH File Transfer Protocol [I-D.ietf-secsh-filexfer]. This extensions make it possible for clients to query the server for additional information which may not be widely supported, but can increase the quality of the users experience when the server can support them. 2. Vendor Id It is often necessary to detect the version of the server so that bugs can be worked around. This extension allows the client to do so. string "vendor-id" string vendor-structure string vendor-name [UTF-8] string product-name [UTF-8] string product-version [UTF-8] uint64 product-build-number vendor-name Arbitrary name identifying the maker of the product. product-name Arbitrary name identifying the product. product-name Arbitrary string identifying the version of the product. product-build-number A build-number for the product, such that if a bug is fixed in build-number 'x', it can be assumed that (barring regression in the product) it is fixed in all build-numbers > 'x'. This extension may also be sent by the client as a SSH_FXP_EXTENDED packet; in this case the contents of the vendor-structure become the extension-specific data: byte SSH_FXP_EXTENDED uint32 request-id string "vendor-id" string vendor-name [UTF-8] string product-name [UTF-8] string product-version [UTF-8] uint64 product-build-number Galbraith & Saarenmaa Expires July 22, 2006 [Page 3] Internet-Draft SSH File Transfer Protocol January 2006 The server responds to this request with a SSH_FXP_STATUS message. The status SHOULD be SSH_FX_OK. 3. File Hashing This extension allows a client to easily check if a file (or portion thereof) that it already has matches what is on the server. byte SSH_FXP_EXTENDED uint32 request-id string "check-file-handle" / "check-file-name" string handle / name string hash-algorithm-list uint64 start-offset uint64 length uint32 block-size handle For "check-file-handle", 'handle' is an open file handle returned by SSH_FXP_OPEN. If 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. If ACE4_READ_DATA was not included when the file was opened, the server MUST return STATUS_PERMISSION_DENIED. If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode, the check must be performed on the data as it would be sent on the wire. name For "check-file-name", 'name' is the path to the file to check. If 'check-file-name' is a directory, SSH_FX_FILE_IS_A_DIRECTORY SHOULD be returned. If 'check-file-name' refers to a SSH_FILEXFER_TYPE_SYMLINK, the target should be opened. The results are undefined file types other than SSH_FILEXFER_TYPE_REGULAR. The file MUST be opened without the SSH_FXF_ACCESS_TEXT_MODE access flag (in binary mode.) hash-algorithm-list A comma separated list of hash algorithms the client is willing to accept for this operation. The server MUST pick the first hash on the list that it supports. Galbraith & Saarenmaa Expires July 22, 2006 [Page 4] Internet-Draft SSH File Transfer Protocol January 2006 Currently defined algorithms are "md5", "sha1", "sha224", "sha256", "sha384", "sha512", and "crc32". Additional algorithms may be added by following the DNS extensibility naming convention outlined in [RFC4251]. MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 are described in [FIPS-180-2]. [ISO.3309.1991] describes crc32, and is the same algorithm used in [RFC1510] start-offset The starting offset of the data to include in the hash. length The length of data to include in the hash. If length is zero, all the data from start-offset to the end-of-file should be included. block-size An independent hash MUST be computed over every block in the file. The size of blocks is specified by block-size. The block-size MUST NOT be smaller than 256 bytes. If the block-size is 0, then only one hash, over the entire range, MUST be made. The response is either a SSH_FXP_STATUS packet, indicating an error, or the following extended reply packet: This extension MUST be represented in the "supported2" extension as "check-file" and both version MUST either be support or neither. byte SSH_FXP_EXTENDED_REPLY uint32 request-id string hash-algo-used byte hash[n][block-count] hash-algo-used The hash algorithm that was actually used. hash The computed hashes. The hash algorithm used determines the size of n. The number of block-size chunks of data in the file determines block-count. The hashes are placed in the packet one after another, with no decoration. Note that if the length of the range is not an even multiple of block-size, the last hash will have been computed over only the remainder of the range instead of a full block. Galbraith & Saarenmaa Expires July 22, 2006 [Page 5] Internet-Draft SSH File Transfer Protocol January 2006 4. Querying Available Space The following extension provides a way to discover the available space for an arbitrary path. byte SSH_FXP_EXTENDED uint32 request-id string "space-available" string path [UTF-8] path 'path' for which the available space should be reported. This 'path' is not required to be the mount point path, but MAY be a directory or file contained within the mount. The reply to the request is as follows: byte SSH_FXP_EXTENDED_REPLY uint32 request-id uint64 bytes-on-device uint64 unused-bytes-on-device uint64 bytes-available-to-user uint64 unused-bytes-available-to-user uint32 bytes-per-allocation-unit bytes-on-device The total number of bytes on the device which stores 'path', both used and unused, or 0 if unknown. unused-bytes-on-device The total number of unused bytes available on the device which stores 'path', or 0 if unknown. bytes-available-to-user The total number of bytes, both used and unused, available to the authenticated user on the device which stores 'path', or 0 if unknown. unused-bytes-available-to-user The total number of unused bytes available to the authenticated user on the device which stores 'path', or 0 if unknown. bytes-per-allocation-unit The number of bytes in each allocation unit on the device, or in other words, the minimum number of bytes that a file allocation size can grow or shrink by. If the server does not know this information, or the file-system in use does not use allocation blocks, this value MUST be 0. Galbraith & Saarenmaa Expires July 22, 2006 [Page 6] Internet-Draft SSH File Transfer Protocol January 2006 5. Querying User Home Directory Many users are used to being able to type '~' as an alias for their home directory, or ~username as an alias for another user's home directory. To support this feature, a server MAY support following extension. byte SSH_FXP_EXTENDED uint32 request-id string "home-directory" string username [UTF-8] username Username whose home directory path is being requested. An empty string implies the current user. The reply to the request is either a SSH_FXP_STATUS packet or a SSH_FXP_NAME packet containing the absolute real-path of the home directory. 6. Copying Remote Files byte SSH_FXP_EXTENDED uint32 request-id string "copy-file" string source-file string destination-file bool overwrite-destination This request copies a file from one location to another on the server. The server responds with SSH_FXP_STATUS. 7. Copying remote data byte SSH_FXP_EXTENDED uint32 request-id string "copy-data" string read-from-handle uint64 read-from-offset uint64 read-data-length string write-to-handle uint64 write-to-offset Copy data from one handle to another on the server. The server responds with SSH_FXP_STATUS. Galbraith & Saarenmaa Expires July 22, 2006 [Page 7] Internet-Draft SSH File Transfer Protocol January 2006 The server MUST copy the data exactly as if the client had issued a series of SSH_FXP_READ requests on the read-from-handle starting at read-from-offset and totaling read-data-length bytes, and issued a series of SSH_FXP_WRITE packets on the write-to-handle, starting at the write-from-offset, and totaling the total number of bytes read by the SSH_FXP_READ packets. If one of the files is open using SSH_FXF_TEXT_MODE, then operation on that handle honors all of the SSH_FXF_TEXT_MODE behaviors. The server SHOULD allow 'read-from-handle' and 'write-to-handle' to be the same handle as long as the range of data is not overlapping. This allows data to efficiently be moved within a file. The server MUST fail the request with a SSH_FX_INVALID_PARAMETER if the range is overlapping and it doesn't correctly handle this case. The server is not required to detect overlapping ranges if read-from-handle and write-to-handle are different handles referring to the same file. If 'data-length' is 0, this imples data should be read until EOF is encountered. There are no protocol restictions on this operation; however, the server MUST ensure that the user does not exceed quota, etc. The server is, as always, free to complete this operation out of order if it is too large to complete immediately, or to refuse a request that is too large. 8. Temporary files & directories byte SSH_FXP_EXTENDED uint32 request-id string "get-temp-folder" Retrieves the users preferred location for temporary files and folders. The server responds with SSH_FXP_STATUS or SSH_FXP_NAME containing the realpath of the preferred location. byte SSH_FXP_EXTENDED uint32 request-id string "make-temp-folder" Requests that the server create a folder in the users preferred location for temporary files and folders for use by the client. The server responds with SSH_FXP_STATUS or SSH_FXP_NAME containing the realpath of the new folder. It is the clients responsibility to cleanup and remove the folder Galbraith & Saarenmaa Expires July 22, 2006 [Page 8] Internet-Draft SSH File Transfer Protocol January 2006 when it is done with it. However, the server MAY remove the folder and it's contents when the client closes the connection. 9. Security Considerations The home directory extension could be used to discover whether a given user is valid; however, since users are assumed to be authenticated by the underlying protocol, this is probably not significant in most situations. If a server would not normally allow an authenticated user to query the existance of another user, the server MUST NOT allow the "home-directory" extension. 10. References 10.1. Normative References [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April 1992. [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network Authentication Service (V5)", RFC 1510, September 1993. [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol Architecture", RFC 4251, January 2006. [I-D.ietf-secsh-filexfer] Galbraith, J. and O. Saarenmaa, "SSH File Transfer Protocol", draft-ietf-secsh-filexfer-10 (work in progress), October 2005. [FIPS-180-2] National Institute of Standards and Technology, "Secure Hash Standard (SHS)", Federal Information Processing Standards Publication 180-2, August 2002. [ISO.3309.1991] International Organization for Standardization, "Information Technology - Telecommunications and information exchange between systems - High-level data link control (HDLC) procedures - Frame structure", ISO Standard 3309, June 1991. 10.2. Informative References Trademark notice Galbraith & Saarenmaa Expires July 22, 2006 [Page 9] Internet-Draft SSH File Transfer Protocol January 2006 "ssh" is a registered trademark in the United States and/or other countries. Galbraith & Saarenmaa Expires July 22, 2006 [Page 10] Internet-Draft SSH File Transfer Protocol January 2006 Authors' Addresses Joseph Galbraith VanDyke Software 4848 Tramway Ridge Blvd Suite 101 Albuquerque, NM 87111 US Phone: +1 505 332 5700 Email: galb-list@vandyke.com Oskari Saarenmaa F-Secure Tammasaarenkatu 7 Helsinki 00180 FI Email: oskari.saarenmaa@f-secure.com Galbraith & Saarenmaa Expires July 22, 2006 [Page 11] Internet-Draft SSH File Transfer Protocol January 2006 Intellectual Property Statement The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Disclaimer of Validity This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Copyright Statement Copyright (C) The Internet Society (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. Acknowledgment Funding for the RFC Editor function is currently provided by the Internet Society. Galbraith & Saarenmaa Expires July 22, 2006 [Page 12]