draft-ietf-secsh-filexfer-04.txt

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

   revision of this protocol.

4.1 Client Initialization

   The SSH_FXP_INIT packet (from client to server) has the following
   data:

   		uint32 version

   Version 3 of this protocol allowed clients to include extensions in
   the SSH_FXP_INIT packet; however, this can cause interoperability
   problems with version 1 and version 2 servers because the client must
   send this packet before knowing the servers version.

   In this version of the protocol, clients MUST use the
   SSH_FXP_EXTENDED packet to send extensions to the server after
   version exchange has completed.  Clients MUST NOT include extensions
   in the version packet.  This will prevent interoperability problems
   with older servers

4.2 Server Initialization

   The SSH_FXP_VERSION packet (from server to client) has the following
   data:

   		uint32 version
   		<extension data>

   'version' is the lower of the protocol version supported by the
   server and the version number received from the client.

   The extension data may be empty, or may be a sequence of

   		string extension_name
   		string extension_data

   pairs (both strings MUST always be present if one is, but the
   `extension_data' string may be of zero length).  If present, these



Galbraith, et al.        Expires June 18, 2003                  [Page 8]

Internet-Draft         SSH File Transfer Protocol          December 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 June 18, 2003                  [Page 9]

Internet-Draft         SSH File Transfer Protocol          December 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 SIZE
   	string   owner                present only if flag OWNERGROUP
   	string   group                present only if flag OWNERGROUP
   	uint32   permissions          present only if flag PERMISSIONS
   	uint64   atime                present only if flag ACCESSTIME
   	uint32   atime_nseconds       present only if flag SUBSECOND_TIMES
   	uint64   createtime           present only if flag CREATETIME
   	uint32   createtime_nseconds  present only if flag SUBSECOND_TIMES
   	uint64   mtime                present only if flag MODIFYTIME
   	uint32   mtime_nseconds       present only if flag SUBSECOND_TIMES
   	string   acl                  present only if flag ACL
   	uint32   extended_count       present only if flag 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:










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


   	#define SSH_FILEXFER_ATTR_SIZE              0x00000001
   	#define SSH_FILEXFER_ATTR_PERMISSIONS       0x00000040
   	#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_SUBSECOND_TIMES	0x00000100
   	#define SSH_FILEXFER_ATTR_EXTENDED          0x80000000

   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



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


   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.

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.

   A negative value indicates number of seconds before Jan 1, 1970.  In
   both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the
   nseconds field is to be added to the seconds field for the final time
   representation.  For example, if the time to be represented is
   one-half second before 0 hour January 1, 1970, the seconds field
   would have a value of negative one (-1) and the nseconds fields would
   have a value of one-half second (500000000).  Values greater than
   999,999,999 for nseconds are considered invalid.

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]:





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


   	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:

   	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)

   Also, as per '5.9.4 ACE who' [3] there are several identifiers that
   need to be understood universally.  Some of these identifiers cannot
   be understood when an client access the server, but have meaning when
   a local process accesses the file.  The ability to display and modify
   these permissions is permitted over SFTP.

      OWNER         The owner of the file.




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


      GROUP         The group associated with the file.

      EVERYONE      The world.

      INTERACTIVE   Accessed from an interactive terminal.

      NETWORK       Accessed via the network.

      DIALUP        Accessed as a dialup user to the server.

      BATCH         Accessed from a batch job.

      ANONYMOUS     Accessed without any authentication.

      AUTHENTICATED Any authenticated user (opposite of ANONYMOUS).

      SERVICE       Access from a system service.

   To avoid conflict, these special identifiers are distinguish by an
   appended "@" and should appear in the form "xxxx@" (note: no domain
   name after the "@").  For example: ANONYMOUS@.

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 June 18, 2003                 [Page 14]

Internet-Draft         SSH File Transfer Protocol          December 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.