Subject: Please publish the attached draft-galb-filexfer-extensions-00.txt

From: Joseph Galbraith <[email-masked]>
Date: Wed, 05 Oct 2005 18:28:56 -0600

Thanks,

Joseph

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: [email-masked]

   Oskari Saarenmaa
   F-Secure
   Tammasaarenkatu 7
   Helsinki  00180
   FI

   Email: [email-masked]

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
   [email-masked].

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]