Secure Shell Working Group J. Galbraith Internet-Draft VanDyke Software Expires: April 8, 2006 O. Saarenmaa F-Secure October 5, 2005 SSH File Transfer Protocol draft-galb-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 April 8, 2006. Copyright Notice Copyright (C) The Internet Society (2005). 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 April 8, 2006 [Page 1] Internet-Draft SSH File Transfer Protocol October 2005 Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. File Hashing . . . . . . . . . . . . . . . . . . . . . . . . . 3 4. Querying Available Space . . . . . . . . . . . . . . . . . . . 5 5. Querying User Home Directory . . . . . . . . . . . . . . . . . 6 6. Security Considerations . . . . . . . . . . . . . . . . . . . 7 7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 7 7.1. Normative References . . . . . . . . . . . . . . . . . . . 7 7.2. Informative References . . . . . . . . . . . . . . . . . . 8 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 9 Intellectual Property and Copyright Statements . . . . . . . . . . 10 Galbraith & Saarenmaa Expires April 8, 2006 [Page 2] Internet-Draft SSH File Transfer Protocol October 2005 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. (It may also be sent by the client using an EXTENDED request.) 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'. 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. Galbraith & Saarenmaa Expires April 8, 2006 [Page 3] Internet-Draft SSH File Transfer Protocol October 2005 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. 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 [I-D.ietf-secsh-architecture]. 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] Galbraith & Saarenmaa Expires April 8, 2006 [Page 4] Internet-Draft SSH File Transfer Protocol October 2005 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: byte SSH_FXP_EXTENDED_REPLY uint32 request-id string "check-file" 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. 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] Galbraith & Saarenmaa Expires April 8, 2006 [Page 5] Internet-Draft SSH File Transfer Protocol October 2005 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. 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. Galbraith & Saarenmaa Expires April 8, 2006 [Page 6] Internet-Draft SSH File Transfer Protocol October 2005 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 the following extended reply: byte SSH_FXP_EXTENDED_REPLY uint32 request-id string "home-directory" string absolute-pathname absolute-pathname Absolute pathname of the specified user's home directory, suitable for use in operations such as REALPATH or OPENDIR. 6. 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. 7. References 7.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. [I-D.ietf-secsh-architecture] Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", draft-ietf-secsh-architecture-22 (work in progress), March 2005. Galbraith & Saarenmaa Expires April 8, 2006 [Page 7] Internet-Draft SSH File Transfer Protocol October 2005 [I-D.ietf-secsh-transport] Lonvick, C., "SSH Transport Layer Protocol", draft-ietf-secsh-transport-24 (work in progress), March 2005. [I-D.ietf-secsh-filexfer] Galbraith, J., "SSH File Transfer Protocol", draft-ietf-secsh-filexfer-09 (work in progress), June 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. 7.2. Informative References Trademark notice "ssh" is a registered trademark in the United States and/or other countries. Galbraith & Saarenmaa Expires April 8, 2006 [Page 8] Internet-Draft SSH File Transfer Protocol October 2005 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 April 8, 2006 [Page 9] Internet-Draft SSH File Transfer Protocol October 2005 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 (2005). 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 April 8, 2006 [Page 10]