draft-ietf-secsh-filexfer-03.txt

来自「OTP是开放电信平台的简称」· 文本 代码 · 共 1,963 行 · 第 1/5 页

   modified, and `attrs' specifies the modifications to be made to its
   attributes.  Attributes are discussed in more detail in Section
   ``File Attributes''.

   An error will be returned if the specified file system object does
   not exist or the user does not have sufficient rights to modify the
   specified attributes.  The server responds to this request with a
   SSH_FXP_STATUS message.

   The SSH_FXP_FSETSTAT request modifies the attributes of a file which
   is already open.  It has the following format:

   	uint32     id
   	string     handle
   	ATTRS      attrs

   where `id' is the request identifier, `handle' (MUST be returned by
   SSH_FXP_OPEN) identifies the file whose attributes are to be
   modified, and `attrs' specifies the modifications to be made to its
   attributes.  Attributes are discussed in more detail in Section
   ``File Attributes''.  The server will respond to this request with
   SSH_FXP_STATUS.

6.10 Dealing with Symbolic links

   The SSH_FXP_READLINK request may be used to read the target of a
   symbolic link.  It would have a data part as follows:

   	uint32     id
   	string     path [UTF-8]

   where `id' is the request identifier and `path' specifies the path
   name of the symlink to be read.

   The server will respond with a SSH_FXP_NAME packet containing only
   one name and a dummy attributes value.  The name in the returned
   packet contains the target of the link.  If an error occurs, the
   server may respond with SSH_FXP_STATUS.

   The SSH_FXP_SYMLINK request will create a symbolic link on the
   server.  It is of the following format

   	uint32     id
   	string     linkpath   [UTF-8]
   	string     targetpath [UTF-8]

   where `id' is the request identifier, `linkpath' specifies the path
   name of the symlink to be created and `targetpath' specifies the



Galbraith, et al.        Expires April 16, 2003                [Page 22]

Internet-Draft         SSH File Transfer Protocol           October 2002


   target of the symlink.  The server shall respond with a
   SSH_FXP_STATUS indicating either success (SSH_FX_OK) or an error
   condition.

6.11 Canonicalizing the Server-Side Path Name

   The SSH_FXP_REALPATH request can be used to have the server
   canonicalize any given path name to an absolute path.  This is useful
   for converting path names containing ".." components or relative
   pathnames without a leading slash into absolute paths.  The format of
   the request is as follows:

   	uint32     id
   	string     path [UTF-8]

   where `id' is the request identifier and `path' specifies the path
   name to be canonicalized.  The server will respond with a
   SSH_FXP_NAME packet containing the name in canonical form and a dummy
   attributes value.  If an error occurs, the server may also respond
   with SSH_FXP_STATUS.

6.11.1 Best practice for dealing with paths

   The client SHOULD treat the results of SSH_FXP_REALPATH as a
   canonical absolute path, even if the path does not appear to be
   absolute.  A client that use REALPATH(".") and treats the result as
   absolute, even if there is no leading slash, will continue to
   function correctly, even when talking to a Windows NT or VMS style
   system, where absolute paths may not begin with a slash.

   For example, if the client wishes to change directory up, and the
   server has returned "c:/x/y/z" from REALPATH, the client SHOULD use
   "c:/x/y/z/..".

   As a second example, if the client wishes to open the file "x.txt" in
   the current directory, and server has returned "dka100:/x/y/z" as the
   canonical path of the directory, the client SHOULD open "dka100:/x/y/
   z/x.txt"













Galbraith, et al.        Expires April 16, 2003                [Page 23]

Internet-Draft         SSH File Transfer Protocol           October 2002


7. Responses from the Server to the Client

   The server responds to the client using one of a few response
   packets.  All requests can return a SSH_FXP_STATUS response upon
   failure.  When the operation is successful, any of the responses may
   be returned (depending on the operation).  If no data needs to be
   returned to the client, the SSH_FXP_STATUS response with SSH_FX_OK
   status is appropriate.  Otherwise, the SSH_FXP_HANDLE message is used
   to return a file handle (for SSH_FXP_OPEN and SSH_FXP_OPENDIR
   requests), SSH_FXP_DATA is used to return data from SSH_FXP_READ,
   SSH_FXP_NAME is used to return one or more file names from a
   SSH_FXP_READDIR or SSH_FXP_REALPATH request, and SSH_FXP_ATTRS is
   used to return file attributes from SSH_FXP_STAT, SSH_FXP_LSTAT, and
   SSH_FXP_FSTAT requests.

   Exactly one response will be returned for each request.  Each
   response packet contains a request identifier which can be used to
   match each response with the corresponding request.  Note that it is
   legal to have several requests outstanding simultaneously, and the
   server is allowed to send responses to them in a different order from
   the order in which the requests were sent (the result of their
   execution, however, is guaranteed to be as if they had been processed
   one at a time in the order in which the requests were sent).

   Response packets are of the same general format as request packets.
   Each response packet begins with the request identifier.

   The format of the data portion of the SSH_FXP_STATUS response is as
   follows:

   	uint32     id
   	uint32     error/status code
   	string     error message (ISO-10646 UTF-8 [RFC-2279])
   	string     language tag (as defined in [RFC-1766])

   where `id' is the request identifier, and `error/status code'
   indicates the result of the requested operation.  The value SSH_FX_OK
   indicates success, and all other values indicate failure.

   Currently, the following values are defined (other values may be
   defined by future versions of this protocol):










Galbraith, et al.        Expires April 16, 2003                [Page 24]

Internet-Draft         SSH File Transfer Protocol           October 2002


   	#define SSH_FX_OK                            0
   	#define SSH_FX_EOF                           1
   	#define SSH_FX_NO_SUCH_FILE                  2
   	#define SSH_FX_PERMISSION_DENIED             3
   	#define SSH_FX_FAILURE                       4
   	#define SSH_FX_BAD_MESSAGE                   5
   	#define SSH_FX_NO_CONNECTION                 6
   	#define SSH_FX_CONNECTION_LOST               7
   	#define SSH_FX_OP_UNSUPPORTED                8
   	#define SSH_FX_INVALID_HANDLE                9
   	#define SSH_FX_NO_SUCH_PATH                  10
   	#define SSH_FX_FILE_ALREADY_EXISTS			 11
   	#define SSH_FX_WRITE_PROTECT				 12

   SSH_FX_OK
      Indicates successful completion of the operation.

   SSH_FX_EOF
      indicates end-of-file condition; for SSH_FX_READ it means that no
      more data is available in the file, and for SSH_FX_READDIR it
      indicates that no more files are contained in the directory.

   SSH_FX_NO_SUCH_FILE
      is returned when a reference is made to a file which does not
      exist.

   SSH_FX_PERMISSION_DENIED
      is returned when the authenticated user does not have sufficient
      permissions to perform the operation.

   SSH_FX_FAILURE
      is a generic catch-all error message; it should be returned if an
      error occurs for which there is no more specific error code
      defined.

   SSH_FX_BAD_MESSAGE
      may be returned if a badly formatted packet or protocol
      incompatibility is detected.

   SSH_FX_NO_CONNECTION
      is a pseudo-error which indicates that the client has no
      connection to the server (it can only be generated locally by the
      client, and MUST NOT be returned by servers).

   SSH_FX_CONNECTION_LOST
      is a pseudo-error which indicates that the connection to the
      server has been lost (it can only be generated locally by the
      client, and MUST NOT be returned by servers).



Galbraith, et al.        Expires April 16, 2003                [Page 25]

Internet-Draft         SSH File Transfer Protocol           October 2002


   SSH_FX_OP_UNSUPPORTED
      indicates that an attempt was made to perform an operation which
      is not supported for the server (it may be generated locally by
      the client if e.g.  the version number exchange indicates that a
      required feature is not supported by the server, or it may be
      returned by the server if the server does not implement an
      operation).

   SSH_FX_INVALID_HANDLE
      The handle value was invalid.

   SSH_FX_NO_SUCH_PATH
      The file path does not exist or is invalid.

   SSH_FX_FILE_ALREADY_EXISTS
      The file already exists.

   SSH_FX_WRITE_PROTECT
      The file is on read only media, or the media is write protected.

   The SSH_FXP_HANDLE response has the following format:

   	uint32     id
   	string     handle

   where `id' is the request identifier, and `handle' is an arbitrary
   string that identifies an open file or directory on the server.  The
   handle is opaque to the client; the client MUST NOT attempt to
   interpret or modify it in any way.  The length of the handle string
   MUST NOT exceed 256 data bytes.

   The SSH_FXP_DATA response has the following format:

   	uint32     id
   	string     data

   where `id' is the request identifier, and `data' is an arbitrary byte
   string containing the requested data.  The data string may be at most
   the number of bytes requested in a SSH_FXP_READ request, but may also
   be shorter if end of file is reached or if the read is from something
   other than a regular file.

   The SSH_FXP_NAME response has the following format:








Galbraith, et al.        Expires April 16, 2003                [Page 26]

Internet-Draft         SSH File Transfer Protocol           October 2002


   	uint32     id
   	uint32     count
   	repeats count times:
   		string     filename [UTF-8]
   		ATTRS      attrs

   where `id' is the request identifier, `count' is the number of names
   returned in this response, and the remaining fields repeat `count'
   times (so that all three fields are first included for the first
   file, then for the second file, etc).  In the repeated part,
   `filename' is a file name being returned (for SSH_FXP_READDIR, it
   will be a relative name within the directory, without any path
   components; for SSH_FXP_REALPATH it will be an absolute path name),
   and `attrs' is the attributes of the file as described in Section
   ``File Attributes''.

   The SSH_FXP_ATTRS response has the following format:

   	uint32     id
   	ATTRS      attrs

   where `id' is the request identifier, and `attrs' is the returned
   file attributes as described in Section ``File Attributes''.




























Galbraith, et al.        Expires April 16, 2003                [Page 27]

Internet-Draft         SSH File Transfer Protocol           October 2002


8. Vendor-Specific Extensions

   The SSH_FXP_EXTENDED request provides a generic extension mechanism
   for adding vendor-specific commands.  The request has the following
   format:

   	uint32     id
   	string     extended-request
   	... any request-specific data ...

   where `id' is the request identifier, and `extended-request' is a
   string of the format "name@domain", where domain is an internet
   domain name of the vendor defining the request.  The rest of the
   request is completely vendor-specific, and servers should only
   attempt to interpret it if they recognize the `extended-request'
   name.

   The server may respond to such requests using any of the response
   packets defined in Section ``Responses from the Server to the
   Client''.  Additionally, the server may also respond with a
   SSH_FXP_EXTENDED_REPLY packet, as defined below.  If the server does
   not recognize the `extended-request' name, then the server MUST
   respond with SSH_FXP_STATUS with error/status set to
   SSH_FX_OP_UNSUPPORTED.

   The SSH_FXP_EXTENDED_REPLY packet can be used to carry arbitrary
   extension-specific data from the server to the client.  It is of the
   following format:

   	uint32     id
   	... any request-specific data ...

   There is a range of packet types reserved for use by extensions.  In
   order to avoid collision, extensions that turn on the use of
   additional packet types should determine those numbers dynamically.

   The suggested way of doing this is have an extension request from the
   client to the server that enables the extension; the extension
   response from the server to the client would specify the actual type
   values to use, in additional to any other data.

   Extension authors should be mindful of the limited range of packet
   types available (there are only 45 values available) and avoid
   requiring a new packet type where possible.







Galbraith, et al.        Expires April 16, 2003                [Page 28]

Internet-Draft         SSH File Transfer Protocol           October 2002