draft-ietf-secsh-filexfer-03.txt

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

Internet-Draft         SSH File Transfer Protocol           October 2002


   strings indicate extensions to the baseline protocol.  The
   `extension_name' field(s) identify the name of the extension.  The
   name should be of the form "name@domain", where the domain is the DNS
   domain name of the organization defining the extension.  Additional
   names that are not of this format may be defined later by the IETF.
   Implementations MUST silently ignore any extensions whose name they
   do not recognize.

4.3 Determining Server Newline Convention

   In order to correctly process text files in a cross platform
   compatible way, the newline convention must be converted from that of
   the server to that of the client, or, during an upload, from that of
   the client to that of the server.

   Versions 3 and prior of this protocol made no provisions for
   processing text files.  Many clients implemented some sort of
   conversion algorithm, but without either a 'canonical' on the wire
   format or knowledge of the servers newline convention, correct
   conversion was not always possible.

   Starting with Version 4, the SSH_FXF_TEXT file open flag (Section
   6.3) makes it possible to request that the server translate a file to
   a 'canonical' on the wire format.  This format uses \r\n as the line
   separator.

   Servers for systems using multiple newline characters (for example,
   Mac OS X or VMS) or systems using counted records, MUST translate to
   the canonical form.

   However, to ease the burden of implementation on servers that use a
   single, simple separator sequence, the following extension allows the
   canonical format to be changed.

   	string "newline"
   	string new-canonical-separator (usually "\r" or "\n" or "\r\n")

   All clients MUST support this extension.

   When processing text files, clients SHOULD NOT translate any
   character or sequence that is not an exact match of the servers
   newline separator.

   In particular, if the newline sequence being used is the canonical
   "\r\n" sequence, a lone \r or a lone \n SHOULD be written through
   without change.





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


5. File Attributes

   A new compound data type is defined for encoding file attributes.
   The same encoding is used both when returning file attributes from
   the server and when sending file attributes to the server.  When
   sending it to the server, the flags field specifies which attributes
   are included, and the server will use default values for the
   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
   	byte     type           always present
   	uint64   size           present only if flag SSH_FILEXFER_ATTR_SIZE
   	string   owner          present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
   	string   group          present only if flag SSH_FILEXFER_ATTR_OWNERGROUP
   	uint32   permissions    present only if flag SSH_FILEXFER_ATTR_PERMISSIONS
   	uint32   atime          present only if flag SSH_FILEXFER_ATTR_ACCESSTIME
   	uint32   createtime     present only if flag SSH_FILEXFER_ATTR_CREATETIME
   	uint32   mtime          present only if flag SSH_FILEXFER_ATTR_MODIFYTIME
   	string   acl            present only if flag SSH_FILEXFER_ATTR_ACL
   	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


5.1 Flags

   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 flags bits are defined to have the following values:

   	#define SSH_FILEXFER_ATTR_SIZE            0x00000001
   	#define SSH_FILEXFER_ATTR_PERMISSIONS     0x00000004
   	#define SSH_FILEXFER_ATTR_ACCESSTIME      0x00000008
   	#define SSH_FILEXFER_ATTR_CREATETIME      0x00000010
   	#define SSH_FILEXFER_ATTR_MODIFYTIME      0x00000020
   	#define SSH_FILEXFER_ATTR_ACL             0x00000040
   	#define SSH_FILEXFER_ATTR_OWNERGROUP      0x00000080
   	#define SSH_FILEXFER_ATTR_EXTENDED        0x80000000




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


   In previous versions of this protocol flags value 0x00000002 was
   SSH_FILEXFER_ATTR_UIDGID.  This value is now unused, and OWNERGROUP
   was given a new value in order to ease implementation burden.
   0x00000002 MUST NOT appear in the mask.  Some future version of this
   protocol may reuse flag 0x00000002.

5.2 Type

   The type field is always present.  The following types are defined:

   	#define SSH_FILEXFER_TYPE_REGULAR          1
   	#define SSH_FILEXFER_TYPE_DIRECTORY        2
   	#define SSH_FILEXFER_TYPE_SYMLINK          3
   	#define SSH_FILEXFER_TYPE_SPECIAL          4
   	#define SSH_FILEXFER_TYPE_UNKNOWN          5

   On a POSIX system, these values would be derived from the permission
   field.

5.3 Size

   The `size' field specifies the size of the file on disk, in bytes.
   If it is present during file creation, it should be considered a hint
   as to the files eventual size.

   Files opened with the SSH_FXF_TEXT flag may have a size that is
   greater or less than the value of the size field.

5.4 Owner and Group

   The `owner' and `group' fields are represented as UTF-8 strings; this
   is the form used by NFS v4.  See NFS version 4 Protocol.  [3] The
   following text is selected quotations from section 5.6.

   To avoid a representation that is tied to a particular underlying
   implementation at the client or server, the use of UTF-8 strings has
   been chosen.  The string should be of the form user@dns_domain".
   This will allow for a client and server that do not use the same
   local representation the ability to translate to a common syntax that
   can be interpreted by both.  In the case where there is no
   translation available to the client or server, the attribute value
   must be constructed without the "@".  Therefore, the absence of the @
   from the owner or owner_group attribute signifies that no translation
   was available and the receiver of the attribute should not place any
   special meaning with the attribute value.  Even though the attribute
   value can not be translated, it may still be useful.  In the case of
   a client, the attribute string may be used for local display of
   ownership.



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


5.5 Permissions

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

5.6 Times

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

5.7 ACL

   The 'ACL' field contains an ACL similar to that defined in section
   5.9 of NFS version 4 Protocol [3].

           uint32   ace-count

           repeated ace-count time:
   		uint32   ace-type
   		uint32   ace-flag
   		uint32   ace-mask
   		string   who [UTF-8]

   ace-type is one of the following four values (taken from NFS Version
   4 Protocol [3]:

   	const ACE4_ACCESS_ALLOWED_ACE_TYPE      = 0x00000000;
   	const ACE4_ACCESS_DENIED_ACE_TYPE       = 0x00000001;
   	const ACE4_SYSTEM_AUDIT_ACE_TYPE        = 0x00000002;
   	const ACE4_SYSTEM_ALARM_ACE_TYPE        = 0x00000003;

   ace-flag is a combination of the following flag values.  See NFS
   Version 4 Protocol [3] section 5.9.2:

   	const ACE4_FILE_INHERIT_ACE             = 0x00000001;
   	const ACE4_DIRECTORY_INHERIT_ACE        = 0x00000002;
   	const ACE4_NO_PROPAGATE_INHERIT_ACE     = 0x00000004;
   	const ACE4_INHERIT_ONLY_ACE             = 0x00000008;
   	const ACE4_SUCCESSFUL_ACCESS_ACE_FLAG   = 0x00000010;
   	const ACE4_FAILED_ACCESS_ACE_FLAG       = 0x00000020;
   	const ACE4_IDENTIFIER_GROUP             = 0x00000040;

   ace-mask is any combination of the following flags (taken from NFS
   Version 4 Protocol [3] section 5.9.3:






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


   	const ACE4_READ_DATA            = 0x00000001;
   	const ACE4_LIST_DIRECTORY       = 0x00000001;
   	const ACE4_WRITE_DATA           = 0x00000002;
   	const ACE4_ADD_FILE             = 0x00000002;
   	const ACE4_APPEND_DATA          = 0x00000004;
   	const ACE4_ADD_SUBDIRECTORY     = 0x00000004;
   	const ACE4_READ_NAMED_ATTRS     = 0x00000008;
   	const ACE4_WRITE_NAMED_ATTRS    = 0x00000010;
   	const ACE4_EXECUTE              = 0x00000020;
   	const ACE4_DELETE_CHILD         = 0x00000040;
   	const ACE4_READ_ATTRIBUTES      = 0x00000080;
   	const ACE4_WRITE_ATTRIBUTES     = 0x00000100;
   	const ACE4_DELETE               = 0x00010000;
   	const ACE4_READ_ACL             = 0x00020000;
   	const ACE4_WRITE_ACL            = 0x00040000;
   	const ACE4_WRITE_OWNER          = 0x00080000;
   	const ACE4_SYNCHRONIZE          = 0x00100000;

   who is a UTF-8 string of the form described in 'Owner and Group'
   (Section 5.4)

5.8 Extended attributes

   The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension
   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.






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


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 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.





Galbraith, et al.        Expires April 16, 2003                [Page 13]

Internet-Draft         SSH File Transfer Protocol           October 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 April 16, 2003                [Page 14]

Internet-Draft         SSH File Transfer Protocol           October 2002