draft-ietf-secsh-filexfer-04.txt

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

   The file handle strings MUST NOT be longer than 256 bytes.

6.1 Request Synchronization and Reordering

   The protocol and implementations MUST process requests relating to
   the same file in the order in which they are received.  In other
   words, if an application submits multiple requests to the server, the
   results in the responses will be the same as if it had sent the
   requests one at a time and waited for the response in each case.  For
   example, the server may process non-overlapping read/write requests
   to the same file in parallel, but overlapping reads and writes cannot
   be reordered or parallelized.  However, there are no ordering
   restrictions on the server for processing requests from two different
   file transfer connections.  The server may interleave and parallelize
   them at will.

   There are no restrictions on the order in which responses to
   outstanding requests are delivered to the client, except that the
   server must ensure fairness in the sense that processing of no
   request will be indefinitely delayed even if the client is sending
   other requests so that there are multiple outstanding requests all
   the time.





Galbraith, et al.        Expires June 18, 2003                 [Page 15]

Internet-Draft         SSH File Transfer Protocol          December 2002


6.2 File Names

   This protocol represents file names as strings.  File names are
   assumed to use the slash ('/') character as a directory separator.

   File names starting with a slash are "absolute", and are relative to
   the root of the file system.  Names starting with any other character
   are relative to the user's default directory (home directory).  Note
   that identifying the user is assumed to take place outside of this
   protocol.

   Servers SHOULD interpret a path name component ".." as referring to
   the parent directory, and "." as referring to the current directory.
   If the server implementation limits access to certain parts of the
   file system, it must be extra careful in parsing file names when
   enforcing such restrictions.  There have been numerous reported
   security bugs where a ".." in a path name has allowed access outside
   the intended area.

   An empty path name is valid, and it refers to the user's default
   directory (usually the user's home directory).

   Otherwise, no syntax is defined for file names by this specification.
   Clients should not make any other assumptions; however, they can
   splice path name components returned by SSH_FXP_READDIR together
   using a slash ('/') as the separator, and that will work as expected.

   In order to comply with IETF Policy on Character Sets and Languages
   [2], all filenames are to be encoded in UTF-8.  The shortest valid
   UTF-8 encoding of the UNICODE data MUST be used.  The server is
   responsible for converting the UNICODE data to whatever canonical
   form it requires.

   For example, if the server requires that precomposed characters
   always be used, the server MUST NOT assume the filename as sent by
   the client has this attribute, but must do this normalization itself.

   It is understood that the lack of well-defined semantics for file
   names may cause interoperability problems between clients and servers
   using radically different operating systems.  However, this approach
   is known to work acceptably with most systems, and alternative
   approaches that e.g.  treat file names as sequences of structured
   components are quite complicated.

6.3 Opening, Creating, and Closing Files

   Files are opened and created using the SSH_FXP_OPEN message, whose
   data part is as follows:



Galbraith, et al.        Expires June 18, 2003                 [Page 16]

Internet-Draft         SSH File Transfer Protocol          December 2002


   	uint32        id
   	string        filename [UTF-8]
   	uint32        pflags
   	ATTRS         attrs

   The `id' field is the request identifier as for all requests.

   The `filename' field specifies the file name.  See Section ``File
   Names'' for more information.

   The `pflags' field is a bitmask.  The following bits have been
   defined.

   	#define SSH_FXF_READ            0x00000001
   	#define SSH_FXF_WRITE           0x00000002
   	#define SSH_FXF_APPEND          0x00000004
   	#define SSH_FXF_CREAT           0x00000008
   	#define SSH_FXF_TRUNC           0x00000010
   	#define SSH_FXF_EXCL            0x00000020
   	#define SSH_FXF_TEXT            0x00000040

   These have the following meanings:

   SSH_FXF_READ
      Open the file for reading.

   SSH_FXF_WRITE
      Open the file for writing.  If both this and SSH_FXF_READ are
      specified, the file is opened for both reading and writing.

   SSH_FXF_APPEND
      Force all writes to append data at the end of the file.  The
      offset parameter to write will be ignored.

   SSH_FXF_CREAT
      If this flag is specified, then a new file will be created if one
      does not already exist (if O_TRUNC is specified, the new file will
      be truncated to zero length if it previously exists).

   SSH_FXF_TRUNC
      Forces an existing file with the same name to be truncated to zero
      length when creating a file by specifying SSH_FXF_CREAT.
      SSH_FXF_CREAT MUST also be specified if this flag is used.

   SSH_FXF_EXCL
      Causes the request to fail if the named file already exists.
      SSH_FXF_CREAT MUST also be specified if this flag is used.




Galbraith, et al.        Expires June 18, 2003                 [Page 17]

Internet-Draft         SSH File Transfer Protocol          December 2002


   SSH_FXF_TEXT
      Indicates that the server should treat the file as text and
      convert it to the canonical newline convention in use.  (See
      Determining Server Newline Convention. (Section 4.3)

      When a file is opened with the FXF_TEXT flag, the offset field in
      both the read and write function are ignored.

      Servers MUST correctly process multiple parallel reads and writes
      correctly in this mode.  Naturally, it is permissible for them to
      do this by serializing the requests.  It would not be possible for
      a client to reliably detect a server that does not implement
      parallel writes in time to prevent damage.

      Clients SHOULD use the SSH_FXF_APPEND flag to append data to a
      text file rather then using write with a calculated offset.

      To support seeks on text file the following SSH_FXP_EXTENDED
      packet is defined.



   	string "text-seek"
   	string file-handle
   	uint64 line-number

      line-number is the index of the line number to seek to, where byte
      0 in the file is line number 0, and the byte directly following
      the first newline sequence in the file is line number 1 and so on.

      The response to a "text-seek" request is an SSH_FXP_STATUS
      message.

      An attempt to seek past the end-of-file should result in a
      SSH_FX_EOF status.

      Servers SHOULD support at least one "text-seek" in order to
      support resume.  However, a client MUST be prepared to receive
      SSH_FX_OP_UNSUPPORTED when attempting a "text-seek" operation.
      The client can then try a fall-back strategy, if it has one.

      Clients MUST be prepared to handle SSH_FX_OP_UNSUPPORTED returned
      for read or write operations that are not sequential.

   The `attrs' field specifies the initial attributes for the file.
   Default values will be used for those attributes that are not
   specified.  See Section ``File Attributes'' for more information.




Galbraith, et al.        Expires June 18, 2003                 [Page 18]

Internet-Draft         SSH File Transfer Protocol          December 2002


   The response to this message will be either SSH_FXP_HANDLE (if the
   operation is successful) or SSH_FXP_STATUS (if the operation fails).

   A file is closed by using the SSH_FXP_CLOSE request.  Its data field
   has the following format:

   	uint32     id
   	string     handle

   where `id' is the request identifier, and `handle' is a handle
   previously returned in the response to SSH_FXP_OPEN or
   SSH_FXP_OPENDIR.  The handle becomes invalid immediately after this
   request has been sent.

   The response to this request will be a SSH_FXP_STATUS message.  One
   should note that on some server platforms even a close can fail.
   This can happen e.g.  if the server operating system caches writes,
   and an error occurs while flushing cached writes during the close.

6.4 Reading and Writing

   Once a file has been opened, it can be read using the following
   message:

   	byte       SSH_FXP_READ
   	uint32     id
   	string     handle
   	uint64     offset
   	uint32     len

   where `id' is the request identifier, `handle' is an open file handle
   returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) relative
   to the beginning of the file from where to start reading, and `len'
   is the maximum number of bytes to read.

   In response to this request, the server will read as many bytes as it
   can from the file (up to `len'), and return them in a SSH_FXP_DATA
   message.  If an error occurs or EOF is encountered before reading any
   data, the server will respond with SSH_FXP_STATUS.

   For normal disk files, it is normally guaranteed that this will read
   the specified number of bytes, or up to end of file.  However, if the
   read length is very long, the server may truncate it if it doesn't
   support packets of that length.  See General Packet Format (Section
   3).

   For e.g.  device files this may return fewer bytes than requested.




Galbraith, et al.        Expires June 18, 2003                 [Page 19]

Internet-Draft         SSH File Transfer Protocol          December 2002


   Writing to a file is achieved using the following message:

   	byte       SSH_FXP_WRITE
   	uint32     id
   	string     handle
   	uint64     offset
   	string     data

   where `id' is a request identifier, `handle' is a file handle
   returned by SSH_FXP_OPEN, `offset' is the offset (in bytes) from the
   beginning of the file where to start writing, and `data' is the data
   to be written.

   The write will extend the file if writing beyond the end of the file.
   It is legal to write way beyond the end of the file; the semantics
   are to write zeroes from the end of the file to the specified offset
   and then the data.  On most operating systems, such writes do not
   allocate disk space but instead leave "holes" in the file.

   The server responds to a write request with a SSH_FXP_STATUS message.

6.5 Removing and Renaming Files

   Files can be removed using the SSH_FXP_REMOVE message.  It has the
   following format:

   	uint32     id
   	string     filename [UTF-8]

   where `id' is the request identifier and `filename' is the name of
   the file to be removed.  See Section ``File Names'' for more
   information.  This request cannot be used to remove directories.

   The server will respond to this request with a SSH_FXP_STATUS
   message.

   Files (and directories) can be renamed using the SSH_FXP_RENAME
   message.  Its data is as follows:

   	uint32     id
   	string     oldpath [UTF-8]
   	string     newpath [UTF-8]

   where `id' is the request identifier, `oldpath' is the name of an
   existing file or directory, and `newpath' is the new name for the
   file or directory.  It is an error if there already exists a file
   with the name specified by newpath.  The server may also fail rename
   requests in other situations, for example if `oldpath' and `newpath'



Galbraith, et al.        Expires June 18, 2003                 [Page 20]

Internet-Draft         SSH File Transfer Protocol          December 2002


   point to different file systems on the server.

   The server will respond to this request with a SSH_FXP_STATUS
   message.

6.6 Creating and Deleting Directories

   New directories can be created using the SSH_FXP_MKDIR request.  It
   has the following format:

   	uint32     id
   	string     path [UTF-8]
   	ATTRS      attrs

   where `id' is the request identifier.

   `path' specifies the directory to be created.  See Section ``File
   Names'' for more information on file names.

   `attrs' specifies the attributes that should be applied to it upon
   creation.  Attributes are discussed in more detail in Section ``File
   Attributes''.

   The server will respond to this request with a SSH_FXP_STATUS
   message.  If a file or directory with the specified path already
   exists, an error will be returned.

   Directories can be removed using the SSH_FXP_RMDIR request, which has
   the following format:

   	uint32     id
   	string     path [UTF-8]

   where `id' is the request identifier, and `path' specifies the
   directory to be removed.  See Section ``File Names'' for more
   information on file names.

   The server responds to this request with a SSH_FXP_STATUS message.
   Errors may be returned from this operation for various reasons,
   including, but not limited to, the path does not exist, the path does
   not refer to a directory object, the directory is not empty, or the
   user has insufficient access or permission to perform the requested
   operation.

6.7 Scanning Directories

   The files in a directory can be listed using the SSH_FXP_OPENDIR and
   SSH_FXP_READDIR requests.  Each SSH_FXP_READDIR request returns one



Galbraith, et al.        Expires June 18, 2003                 [Page 21]

Internet-Draft         SSH File Transfer Protocol          December 2002


   or more file names with full file attributes for each file.  The
   client should call SSH_FXP_READDIR repeatedly until it has found the
   file it is looking for or until the server responds with a
   SSH_FXP_STATUS message indicating an error (normally SSH_FX_EOF if
   there are no more files in the directory).  The client should then
   close the handle using the SSH_FXP_CLOSE request.

   The SSH_FXP_OPENDIR opens a directory for reading.  It has the
   following format:

   	uint32     id
   	string     path [UTF-8]

   where `id' is the request identifier and `path' is the path name of
   the directory to be listed (without any trailing slash).  See Section
   ``File Names'' for more information on file names.  This will return
   an error if the path does not specify a directory or if the directory
   is not readable.  The server will respond to this request with either
   a SSH_FXP_HANDLE or a SSH_FXP_STATUS message.

   Once the directory has been successfully opened, files (and
   directories) contained in it can be listed using SSH_FXP_READDIR
   requests.  These are of the format

   	uint32     id
   	string     handle

   where `id' is the request identifier, and `handle' is a handle
   returned by SSH_FXP_OPENDIR.  (It is a protocol error to attempt to
   use an ordinary file handle returned by SSH_FXP_OPEN.)

   The server responds to this request with either a SSH_FXP_NAME or a
   SSH_FXP_STATUS message.  One or more names may be returned at a time.
   Full status information is returned for each name in order to speed
   up typical directory listings.

   If there are no more names available to be read, the server MUST
   respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF.