--- 1/draft-ietf-secsh-filexfer-03.txt 2006-02-05 01:34:09.000000000 +0100 +++ 2/draft-ietf-secsh-filexfer-04.txt 2006-02-05 01:34:10.000000000 +0100 @@ -1,99 +1,100 @@ Secure Shell Working Group J. Galbraith Internet-Draft VanDyke Software -Expires: April 16, 2003 T. Ylonen +Expires: June 18, 2003 T. Ylonen S. Lehtinen SSH Communications Security Corp - October 16, 2002 + December 18, 2002 SSH File Transfer Protocol - draft-ietf-secsh-filexfer-03.txt + draft-ietf-secsh-filexfer-04.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that - other groups may also distribute working documents as Internet- - Drafts. + other groups may also distribute working documents as + Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http:// www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on April 16, 2003. + This Internet-Draft will expire on June 18, 2003. Copyright Notice Copyright (C) The Internet Society (2002). All Rights Reserved. Abstract The SSH File Transfer Protocol provides secure file transfer functionality over any reliable data stream. It is the standard file transfer protocol for use with the SSH2 protocol. This document describes the file transfer protocol and its interface to the SSH2 protocol suite. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . 3 2. Use with the SSH Connection Protocol . . . . . . . . . . . 4 3. General Packet Format . . . . . . . . . . . . . . . . . . 5 - 4. Protocol Initialization . . . . . . . . . . . . . . . . . 7 - 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 7 - 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 7 - 4.3 Determining Server Newline Convention . . . . . . . . . . 8 - 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 9 - 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 9 - 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 - 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 10 - 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 12 - 6. Requests From the Client to the Server . . . . . . . . . . 13 - 6.1 Request Synchronization and Reordering . . . . . . . . . . 13 - 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 14 - 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 14 - 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 17 - 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 18 - 6.6 Creating and Deleting Directories . . . . . . . . . . . . 19 - 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 19 - 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 20 - 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 21 - 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 22 - 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 23 - 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 23 - 7. Responses from the Server to the Client . . . . . . . . . 24 - 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 28 - 9. Security Considerations . . . . . . . . . . . . . . . . . 29 - 10. Changes from previous protocol versions . . . . . . . . . 30 - 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 30 - 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 31 - 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 31 - 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 31 - 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 32 - References . . . . . . . . . . . . . . . . . . . . . . . . 33 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . 33 - Full Copyright Statement . . . . . . . . . . . . . . . . . 35 + 3.1 The use of stderr in the server . . . . . . . . . . . . . 6 + 4. Protocol Initialization . . . . . . . . . . . . . . . . . 8 + 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 + 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8 + 4.3 Determining Server Newline Convention . . . . . . . . . . 9 + 5. File Attributes . . . . . . . . . . . . . . . . . . . . . 10 + 5.1 Flags . . . . . . . . . . . . . . . . . . . . . . . . . . 10 + 5.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 + 5.4 Owner and Group . . . . . . . . . . . . . . . . . . . . . 11 + 5.5 Permissions . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.6 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.7 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 12 + 5.8 Extended attributes . . . . . . . . . . . . . . . . . . . 14 + 6. Requests From the Client to the Server . . . . . . . . . . 15 + 6.1 Request Synchronization and Reordering . . . . . . . . . . 15 + 6.2 File Names . . . . . . . . . . . . . . . . . . . . . . . . 16 + 6.3 Opening, Creating, and Closing Files . . . . . . . . . . . 16 + 6.4 Reading and Writing . . . . . . . . . . . . . . . . . . . 19 + 6.5 Removing and Renaming Files . . . . . . . . . . . . . . . 20 + 6.6 Creating and Deleting Directories . . . . . . . . . . . . 21 + 6.7 Scanning Directories . . . . . . . . . . . . . . . . . . . 21 + 6.8 Retrieving File Attributes . . . . . . . . . . . . . . . . 22 + 6.9 Setting File Attributes . . . . . . . . . . . . . . . . . 23 + 6.10 Dealing with Symbolic links . . . . . . . . . . . . . . . 24 + 6.11 Canonicalizing the Server-Side Path Name . . . . . . . . . 25 + 6.11.1 Best practice for dealing with paths . . . . . . . . . . . 25 + 7. Responses from the Server to the Client . . . . . . . . . 26 + 8. Vendor-Specific Extensions . . . . . . . . . . . . . . . . 30 + 9. Security Considerations . . . . . . . . . . . . . . . . . 31 + 10. Changes from previous protocol versions . . . . . . . . . 32 + 10.1 Changes between versions 4 and 3 . . . . . . . . . . . . . 32 + 10.2 Changes between versions 3 and 2 . . . . . . . . . . . . . 33 + 10.3 Changes between versions 2 and 1 . . . . . . . . . . . . . 33 + 10.4 Changes between versions 1 and 0 . . . . . . . . . . . . . 33 + 11. Trademark Issues . . . . . . . . . . . . . . . . . . . . . 34 + References . . . . . . . . . . . . . . . . . . . . . . . . 35 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . 35 + Intellectual Property and Copyright Statements . . . . . . 37 1. Introduction This protocol provides secure file transfer (and more generally file system access) functionality over a reliable data stream, such as a channel in the SSH2 protocol [5]. This protocol is designed so that it could be used to implement a secure remote file system service, as well as a secure file transfer service. @@ -196,20 +197,31 @@ RESERVED_FOR_EXTENSIONS 210-255 Additional packet types should only be defined if the protocol version number (see Section ``Protocol Initialization'') is incremented, and their use MUST be negotiated using the version number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to implement vendor-specific extensions. See Section ``Vendor-Specific-Extensions'' for more details. +3.1 The use of stderr in the server + + Packets are sent and received on stdout and stdin. Data sent on + stderr by the server SHOULD be considered debug or supplemental error + information, and MAY be displayed to the user. + + For example, during initialization, there is no client request + active, so errors or warning information cannot be sent to the client + as part of the SFTP protocol at this early stage. However, the + errors or warnings MAY be sent as stderr text. + 4. Protocol Initialization When the file transfer protocol starts, the client first sends a SSH_FXP_INIT (including its version number) packet to the server. The server responds with a SSH_FXP_VERSION packet, supplying the lowest of its own and the client's version number. Both parties should from then on adhere to particular version of the protocol. The version number of the protocol specified in this document is 4. The version number should be incremented for each incompatible @@ -305,52 +317,57 @@ 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 + 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: #define SSH_FILEXFER_ATTR_SIZE 0x00000001 - #define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 + #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: @@ -397,20 +414,29 @@ 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 @@ -453,20 +479,50 @@ 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. + + 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 @@ -689,44 +745,50 @@ 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: + 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 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. + data, the server will respond with SSH_FXP_STATUS. - Writing to a file is achieved using the SSH_FXP_WRITE message, which - has the following format: + 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. + + 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. @@ -1047,20 +1108,21 @@ #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 + #define SSH_FX_NO_MEDIA 13 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 @@ -1103,20 +1165,24 @@ 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. + SSH_FX_NO_MEDIA + The requested operation can not be completed because there is no + media available in the drive. + 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. @@ -1226,24 +1292,30 @@ The SSH File Transfer Protocol has changed over time, before it's standardization. The following is a description of the incompatible changes between different versions. 10.1 Changes between versions 4 and 3 Many of the changes between version 4 and version 3 are to the attribute structure to make it more flexible for non-unix platforms. + o Clarify the use of stderr by the server. + + o Clarify handling of very large read requests by the server. + o Make all filenames UTF-8. o Added 'newline' extension. + o Made time fields 64 bit, and optionally have nanosecond resultion. + o Made file attribute owner and group strings so they can actually be used on disparate systems. o Added createtime field, and added separate flags for atime, createtime, and mtime so they can be set separately. o Split the file type out of the permissions field and into it's own field (which is always present.) o Added acl attribute. @@ -1254,26 +1326,20 @@ specifically request information the server might not normally included for performance reasons. o Removed the long filename from the names structure-- it can now be built from information available in the attrs structure. o Added reserved range of packet numbers for extensions. o Added several additional error codes. - o Change the way version negotiate works slightly. Previously, if - the client version were higher than the server version, the server - was supposed to 'echo back' the clients version. The server now - sends it's own version and the lower of the two is considered to - be the one in use. - 10.2 Changes between versions 3 and 2 o The SSH_FXP_READLINK and SSH_FXP_SYMLINK messages were added. o The SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY messages were added. o The SSH_FXP_STATUS message was changed to include fields `error message' and `language tag'. @@ -1302,34 +1368,36 @@ [3] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC 3010, December 2000. [4] Institute of Electrical and Electronics Engineers, "Information Technology - Portable Operating System Interface (POSIX) - Part 1: System Application Program Interface (API) [C Language]", IEEE Standard 1003.2, 1996. [5] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Architecture", draft-ietf-secsh- - architecture-13 (work in progress), September 2002. + Lehtinen, "SSH Protocol Architecture", + draft-ietf-secsh-architecture-13 (work in progress), September + 2002. [6] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Protocol Transport Protocol", draft-ietf-secsh- - transport-15 (work in progress), September 2002. + Lehtinen, "SSH Protocol Transport Protocol", + draft-ietf-secsh-transport-15 (work in progress), September + 2002. [7] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. Lehtinen, "SSH Connection Protocol", draft-ietf-secsh-connect-16 (work in progress), September 2002. [8] Rinne, T., Ylonen, T., Kivinen, T., Saarinen, M. and S. - Lehtinen, "SSH Authentication Protocol", draft-ietf-secsh- - userauth-16 (work in progress), September 2002. + Lehtinen, "SSH Authentication Protocol", + draft-ietf-secsh-userauth-16 (work in progress), September 2002. Authors' Addresses Joseph Galbraith VanDyke Software 4848 Tramway Ridge Blvd Suite 101 Albuquerque, NM 87111 US @@ -1344,40 +1412,62 @@ EMail: ylo@ssh.com Sami Lehtinen SSH Communications Security Corp Fredrikinkatu 42 HELSINKI FIN-00100 Finland EMail: sjl@ssh.com +Intellectual Property Statement + + The IETF takes no position regarding the validity or scope of any + intellectual property or other rights that might be claimed to + pertain to the implementation or use of the technology described in + this document or the extent to which any license under such rights + might or might not be available; neither does it represent that it + has made any effort to identify any such rights. Information on the + IETF's procedures with respect to rights in standards-track and + standards-related documentation can be found in BCP-11. Copies of + claims of rights made available for publication and any assurances of + licenses to be made available, or the result of an attempt made to + obtain a general license or permission for the use of such + proprietary rights by implementors or users of this specification can + be obtained from the IETF Secretariat. + + The IETF invites any interested party to bring to its attention any + copyrights, patents or patent applications, or other proprietary + rights which may cover technology that may be required to practice + this standard. Please address the information to the IETF Executive + Director. + Full Copyright Statement Copyright (C) The Internet Society (2002). All Rights Reserved. This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way, such as by removing the copyright notice or references to the Internet Society or other Internet organizations, except as needed for the purpose of developing Internet standards in which case the procedures for copyrights defined in the Internet Standards process must be followed, or as required to translate it into languages other than English. The limited permissions granted above are perpetual and will not be - revoked by the Internet Society or its successors or assigns. + revoked by the Internet Society or its successors or assignees. This document and the information contained herein is provided on an "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Acknowledgement