draft-ietf-secsh-filexfer-02.txt

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

   remaining attributes (or will not modify the values of remaining
   attributes).  When receiving attributes from the server, the flags
   specify which attributes are included in the returned data.  The
   server normally returns all attributes it knows about.

   	uint32   flags
   	uint64   size           present only if flag SSH_FILEXFER_ATTR_SIZE
   	uint32   uid            present only if flag SSH_FILEXFER_ATTR_UIDGID
   	uint32   gid            present only if flag SSH_FILEXFER_ATTR_UIDGID
   	uint32   permissions    present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
   	uint32   atime          present only if flag SSH_FILEXFER_ACMODTIME
   	uint32   mtime          present only if flag SSH_FILEXFER_ACMODTIME
   	uint32   extended_count present only if flag SSH_FILEXFER_ATTR_EXTENDED
   	string   extended_type
   	string   extended_data
   	...      more extended data (extended_type - extended_data pairs),
   		   so that number of pairs equals extended_count

   The `flags' specify which of the fields are present.  Those fields
   for which the corresponding flag is not set are not present (not
   included in the packet).  New flags can only be added by incrementing
   the protocol version number (or by using the extension mechanism
   described below).

   The `size' field specifies the size of the file in bytes.

   The `uid' and `gid' fields contain numeric Unix-like user and group
   identifiers, respectively.

   The `permissions' field contains a bit mask of file permissions as
   defined by posix [1].

   The `atime' and `mtime' contain the access and modification times of
   the files, respectively.  They are represented as seconds from Jan 1,
   1970 in UTC.

   The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension



Ylonen & Lehtinen         Expires April 1, 2002                 [Page 8]

Internet-Draft         SSH File Transfer Protocol           October 2001


   mechanism for vendor-specific extensions.  If the flag is specified,
   then the `extended_count' field is present.  It specifies the number
   of extended_type-extended_data pairs that follow.  Each of these
   pairs specifies an extended attribute.  For each of the attributes,
   the extended_type field should be a string of the format
   "name@domain", where "domain" is a valid, registered domain name and
   "name" identifies the method.  The IETF may later standardize certain
   names that deviate from this format (e.g., that do not contain the
   "@" sign).  The interpretation of `extended_data' depends on the
   type.  Implementations SHOULD ignore extended data fields that they
   do not understand.

   Additional fields can be added to the attributes by either defining
   additional bits to the flags field to indicate their presence, or by
   defining extended attributes for them.  The extended attributes
   mechanism is recommended for most purposes; additional flags bits
   should only be defined by an IETF standards action that also
   increments the protocol version number.  The use of such new fields
   MUST be negotiated by the version number in the protocol exchange.
   It is a protocol error if a packet with unsupported protocol bits is
   received.

    The flags bits are defined to have the following values:

   	#define SSH_FILEXFER_ATTR_SIZE          0x00000001
   	#define SSH_FILEXFER_ATTR_UIDGID        0x00000002
   	#define SSH_FILEXFER_ATTR_PERMISSIONS   0x00000004
   	#define SSH_FILEXFER_ATTR_ACMODTIME     0x00000008
   	#define SSH_FILEXFER_ATTR_EXTENDED      0x80000000






















Ylonen & Lehtinen         Expires April 1, 2002                 [Page 9]

Internet-Draft         SSH File Transfer Protocol           October 2001


6. Requests From the Client to the Server

   Requests from the client to the server represent the various file
   system operations.  Each request begins with an `id' field, which is
   a 32-bit identifier identifying the request (selected by the client).
   The same identifier will be returned in the response to the request.
   One possible implementation of it is a monotonically increasing
   request sequence number (modulo 2^32).

   Many operations in the protocol operate on open files.  The
   SSH_FXP_OPEN request can return a file handle (which is an opaque
   variable-length string) which may be used to access the file later
   (e.g.  in a read operation).  The client MUST NOT send requests the
   server with bogus or closed handles.  However, the server MUST
   perform adequate checks on the handle in order to avoid security
   risks due to fabricated handles.

   This design allows either stateful and stateless server
   implementation, as well as an implementation which caches state
   between requests but may also flush it.  The contents of the file
   handle string are entirely up to the server and its design.  The
   client should not modify or attempt to interpret the file handle
   strings.

   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.





Ylonen & Lehtinen         Expires April 1, 2002                [Page 10]

Internet-Draft         SSH File Transfer Protocol           October 2001


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.

   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:

   	uint32        id
   	string        filename
   	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.



Ylonen & Lehtinen         Expires April 1, 2002                [Page 11]

Internet-Draft         SSH File Transfer Protocol           October 2001


    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

   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.

   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.

   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.

   Regardless the server operating system, the file will always be
   opened in "binary" mode (i.e., no translations between different
   character sets and newline encodings).

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





Ylonen & Lehtinen         Expires April 1, 2002                [Page 12]

Internet-Draft         SSH File Transfer Protocol           October 2001


    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 SSH_FXP_READ
   message, which has the following format:

   	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 guaranteed that this will read the specified number of
   bytes, or up to end of file.  For e.g.  device files this may return
   fewer bytes than requested.

    Writing to a file is achieved using the SSH_FXP_WRITE message, which
   has the following format:

   	uint32     id
   	string     handle
   	uint64     offset
   	string     data

   where `id' is a request identifier, `handle' is a file handle



Ylonen & Lehtinen         Expires April 1, 2002                [Page 13]

Internet-Draft         SSH File Transfer Protocol           October 2001


   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

   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
   	string     newpath

   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'
   point to different file systems on the server.

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








Ylonen & Lehtinen         Expires April 1, 2002                [Page 14]

Internet-Draft         SSH File Transfer Protocol           October 2001


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
   	ATTRS      attrs

   where `id' is the request identifier, `path' and `attrs' specifies
   the modifications to be made to its attributes.  See Section ``File
   Names'' for more information on file names.  Attributes are discussed
   in more detail in Section ``File Attributes''.  specifies the
   directory to be created.  An error will be returned if a file or
   directory with the specified path already exists.  The server will
   respond to this request with a SSH_FXP_STATUS message.

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

   	uint32     id
   	string     path

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