Internet DRAFT - draft-ietf-secsh-filexfer-extensions

draft-ietf-secsh-filexfer-extensions







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]