--- 1/draft-ietf-secsh-filexfer-07.txt 2006-02-05 01:34:14.000000000 +0100 +++ 2/draft-ietf-secsh-filexfer-08.txt 2006-02-05 01:34:14.000000000 +0100 @@ -1,49 +1,49 @@ Secure Shell Working Group J. Galbraith Internet-Draft VanDyke Software -Expires: September 25, 2005 O. Saarenmaa +Expires: October 7, 2005 O. Saarenmaa F-Secure T. Ylonen S. Lehtinen SSH Communications Security Corp - March 24, 2005 + April 5, 2005 SSH File Transfer Protocol - draft-ietf-secsh-filexfer-07.txt + draft-ietf-secsh-filexfer-08.txt Status of this Memo This document is an Internet-Draft and is subject to all provisions of Section 3 of RFC 3667. By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she become aware will be disclosed, in accordance with RFC 3668. 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 September 25, 2005. + This Internet-Draft will expire on October 7, 2005. Copyright Notice Copyright (C) The Internet Society (2005). 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 @@ -54,77 +54,83 @@ 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 4 3. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 3.1 Request Synchronization and Reordering . . . . . . . . . . 6 3.2 New data types defined by this document . . . . . . . . . 6 3.3 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 4. Protocol Initialization . . . . . . . . . . . . . . . . . . . 8 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 - 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8 + 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 9 4.3 Determining Server Newline Convention . . . . . . . . . . 9 - 4.4 Supported Features . . . . . . . . . . . . . . . . . . . . 9 - 4.5 Version re-negotiation . . . . . . . . . . . . . . . . . . 11 - 5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 11 - 6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 13 - 6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 14 - 6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 - 6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 - 6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 16 - 6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 16 - 6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 17 - 6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 17 - 6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 - 6.9 attrib-bits . . . . . . . . . . . . . . . . . . . . . . . 19 - 6.10 Text Hint . . . . . . . . . . . . . . . . . . . . . . . . 22 - 6.11 Mime type . . . . . . . . . . . . . . . . . . . . . . . . 22 - 6.12 Link Count . . . . . . . . . . . . . . . . . . . . . . . . 22 - 6.13 Extended Attributes . . . . . . . . . . . . . . . . . . . 22 - 7. Requests From the Client to the Server . . . . . . . . . . . . 23 - 7.1 Opening and Closing Files and Directories . . . . . . . . 23 - 7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 23 - 7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 28 - 7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 29 - 7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 29 - 7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 29 - 7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 30 - 7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 30 - 7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 31 - 7.4 Creating and Deleting Directories . . . . . . . . . . . . 32 - 7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 33 - 7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 34 - 7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 35 - 7.8 Canonicalizing the Server-Side Path Name . . . . . . . . . 36 - 7.8.1 Best Practice for Dealing with Paths . . . . . . . . . 37 - 8. Responses from the Server to the Client . . . . . . . . . . . 38 - 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 44 - 9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 45 - 9.1.1 Checking File Contents: v5 extension . . . . . . . . . 46 - 9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 47 - 9.2 Querying Available Space . . . . . . . . . . . . . . . . . 48 - 9.3 Querying User Home Directory . . . . . . . . . . . . . . . 49 - 10. Implementation Considerations . . . . . . . . . . . . . . . 50 - 11. Security Considerations . . . . . . . . . . . . . . . . . . 50 - 12. Changes from Previous Protocol Versions . . . . . . . . . . 52 - 12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 52 - 12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 52 - 12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 53 - 12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 54 - 12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 54 - 12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 54 - 13. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 54 - 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 - 14.1 Normative References . . . . . . . . . . . . . . . . . . . 54 - 14.2 Informative References . . . . . . . . . . . . . . . . . . 55 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 55 - Intellectual Property and Copyright Statements . . . . . . . . 57 + 4.4 Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . 9 + 4.5 Supported Features . . . . . . . . . . . . . . . . . . . . 10 + 4.6 Version re-negotiation . . . . . . . . . . . . . . . . . . 12 + 5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 13 + 6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 15 + 6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 16 + 6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 + 6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 18 + 6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 18 + 6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 19 + 6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 6.9 attrib-bits and attrib-bits-valid . . . . . . . . . . . . 21 + 6.10 text-hint . . . . . . . . . . . . . . . . . . . . . . . . 24 + 6.11 mime-type . . . . . . . . . . . . . . . . . . . . . . . . 24 + 6.12 link-count . . . . . . . . . . . . . . . . . . . . . . . . 24 + 6.13 untranslated-name . . . . . . . . . . . . . . . . . . . . 25 + 6.14 Extended Attributes . . . . . . . . . . . . . . . . . . . 25 + 7. Requests From the Client to the Server . . . . . . . . . . . . 25 + 7.1 Opening and Closing Files and Directories . . . . . . . . 25 + 7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 26 + 7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 31 + 7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 32 + 7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 32 + 7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 32 + 7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 33 + 7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 33 + 7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 34 + 7.4 Creating and Deleting Directories . . . . . . . . . . . . 35 + 7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 36 + 7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 37 + 7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 38 + 7.8 Canonicalizing the Server-Side Path Name . . . . . . . . . 40 + 7.8.1 Best Practice for Dealing with Paths . . . . . . . . . 42 + 8. Responses from the Server to the Client . . . . . . . . . . . 42 + 8.1 Status Response . . . . . . . . . . . . . . . . . . . . . 43 + 8.2 Handle Response . . . . . . . . . . . . . . . . . . . . . 47 + 8.3 Data Response . . . . . . . . . . . . . . . . . . . . . . 47 + 8.4 Name Response . . . . . . . . . . . . . . . . . . . . . . 48 + 8.5 Attrs Response . . . . . . . . . . . . . . . . . . . . . . 49 + 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 49 + 9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 50 + 9.1.1 Checking File Contents: v5 extension . . . . . . . . . 51 + 9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 52 + 9.2 Querying Available Space . . . . . . . . . . . . . . . . . 54 + 9.3 Querying User Home Directory . . . . . . . . . . . . . . . 55 + 10. Implementation Considerations . . . . . . . . . . . . . . . 55 + 11. Security Considerations . . . . . . . . . . . . . . . . . . 56 + 12. Changes from Previous Protocol Versions . . . . . . . . . . 57 + 12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 57 + 12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 58 + 12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 59 + 12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 59 + 12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 59 + 12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 59 + 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 + 13.1 Normative References . . . . . . . . . . . . . . . . . . . 60 + 13.2 Informative References . . . . . . . . . . . . . . . . . . 61 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 61 + Intellectual Property and Copyright Statements . . . . . . . . 63 1. Introduction This protocol provides secure file transfer (and more generally file system access.) It is designed so that it could be used to implement a secure remote file system service, as well as a secure file transfer service. This protocol assumes that it runs over a secure channel, such as a channel in [I-D.ietf-secsh-architecture]. and that the server has @@ -206,24 +212,24 @@ request that the server is responding to. One possible implementation is for the client to us a monotonically increasing request sequence number (modulo 2^32). There is, however, no particular requirement the 'request-id' fields be unique. There are two packets, INIT and VERSION, which do not use the request-id. Packet descriptions in this document will contain the 'request-id' field, but will not redefine it. - Implementations MUST ignore excess data after an otherwise valid - packet. Implementation MUST respond to unrecognized packet types - with an SSH_FX_OP_UNSUPPORTED error. This will allow the protocol to - be extended in a backwards compatible way as needed. + Implementations MUST ignore excess data at the end of an otherwise + valid packet. Implementations MUST respond to unrecognized packet + types with an SSH_FX_OP_UNSUPPORTED error. This will allow the + protocol to be extended in a backwards compatible way as needed. There is no limit on the number of outstanding (non-acknowledged) requests that the client may send to the server. In practice this is limited by the buffering available on the data stream and the queuing performed by the server. If the server's queues are full, it should not read any more data from the stream, and flow control will prevent the client from sending more requests. Note, however, that while there is no restriction on the protocol level, the client's API may provide a limit in order to prevent infinite queuing of outgoing requests at the client. @@ -247,36 +253,36 @@ 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. A client MUST be prepared to recieve responses to multiple overlapped requests out of order. 3.2 New data types defined by this document - This document defines several data types in addition to those defined + This document defines these data types in addition to those defined in [I-D.ietf-secsh-architecture]. int64 Represents a 64-bit signed integer. Stored as eight bytes in the order of decreasing significance (network byte order). extension-pair string extension-name string extension-data 'extension-name' is the name of a protocol extension. Extensions - not defined by IETF consensus MUST follow the the DNS - extensibility naming convention outlined in - [I-D.ietf-secsh-architecture]. + not defined by IETF CONSENSUS MUST follow the the DNS + extensibility naming convention outlined in [I-D.ietf-secsh- + architecture]. 'extension-data' is any data specific to the extension, and MAY be zero length if the extension has no data. 3.3 Packet Types The following values are defined for packet types. SSH_FXP_INIT 1 SSH_FXP_VERSION 2 @@ -291,213 +297,295 @@ SSH_FXP_OPENDIR 11 SSH_FXP_READDIR 12 SSH_FXP_REMOVE 13 SSH_FXP_MKDIR 14 SSH_FXP_RMDIR 15 SSH_FXP_REALPATH 16 SSH_FXP_STAT 17 SSH_FXP_RENAME 18 SSH_FXP_READLINK 19 SSH_FXP_LINK 21 + SSH_FXP_BLOCK 22 + SSH_FXP_UNBLOCK 23 SSH_FXP_STATUS 101 SSH_FXP_HANDLE 102 SSH_FXP_DATA 103 SSH_FXP_NAME 104 SSH_FXP_ATTRS 105 SSH_FXP_EXTENDED 200 SSH_FXP_EXTENDED_REPLY 201 - 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 extensions, which can be vendor - specific. See Section ''Extensions'' for more details. + SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY packets can be used to + implement extensions, which can be vendor specific. See Section + ''Extensions'' for more details. + + Values 210-255 are reserved for use in conjunction with these + extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the + meaning of these reserved types. It is suggested that the actual + value to be used also be negotiated, since this will prevent + collision among multiple uncoordinated extensions. + + The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if + it receives a packet it does not recognize. The protocol version + (Section 4) MUST be incremented if the server is to send new packets + to the client (because the client has no way to respond indicating + that the packet isn't recognized.) 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. + should from then on adhere to that particular version of the + protocol. The version number of the protocol specified in this document is 6. The version number should be incremented for each incompatible revision of this protocol. Note that these two packets DO NOT contain a request id. These are the only such packets in the protocol. 4.1 Client Initialization The SSH_FXP_INIT packet (from client to server) has the following data: uint32 version 'version' is the version number of the client. If the client wishes - to interoperate with servers that support dis-contigous version + to interoperate with servers that support discontiguous version numbers it SHOULD send '3', and then use the 'version-select' extension (see below.) Otherwise, this value is '6' for this version of the protocol. 4.2 Server Initialization The SSH_FXP_VERSION packet (from server to client) has the following data: uint32 version extension-pair extensions[0..n] 'version' is the lower of the protocol version supported by the server and the version number received from the client. 'extensions' is 0 or more extension-pairs (Section 3.2). - Implementations MUST silently ignore any extensions whose name they + Implementations MUST silently ignore any extensions whose names they do not recognize. 4.3 Determining Server Newline Convention In order to correctly process text files in a cross platform compatible way, newline sequences must be converted between client and server conventions. The SSH_FXF_TEXT file open flag (Section 7.1.1) makes it possible to request that the server translate a file to a 'canonical' wire - format. This format uses \r\n as the line separator. + format. This format uses CRLF 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. + Servers for systems using other conventions MUST translate to and + from 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") + string new-canonical-separator (usually CR or LF or CRLF) 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 server's 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 + CRLF sequence, a lone CR or a lone LF SHOULD be written through without change. -4.4 Supported Features +4.4 Vendor Id + + It is often necessary to detect the version of a the server so that + bugs can be worked around. This extension allows the client to do + so. (It may also be sent by the client using an EXTENDED request. + + string "vendor-id" + string vendor-structure + string vendor-name + string product-name + string product-version + uint64 product-build-number + + vendor-name + Arbitrary name identifying the maker of the product. + + product-name + Arbitrary name identifying the product. + + product-name + Arbitrary string identifying the version of the product. + + product-build-number + A build-number for the product, such that if a bug is fixed in + build-number 'x', it can be assumed that (barring regression in + the product) it is fixed in all build-numbers > 'x'. + +4.5 Supported Features The sftp protocol has grown to be very rich, and now supports a number of features that may not be available on all servers. When a server receives a request for a feature it cannot support, it MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise - specified. In order to facilitate clients being able to use the - maximum available feature set, and yet not be overly burdened by - dealing with SSH_FX_OP_UNSUPPORTED status codes, the following - extension which all servers MUST include as part of their version - packet, is introduced. + specified. The following extension facilitates clients being able to + use the maximum available feature set, and yet not be overly burdened + by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST + include as part of their version packet. string "supported2" string supported-structure uint32 supported-attribute-mask uint32 supported-attribute-bits uint32 supported-open-flags uint32 max-read-size - string extension-names[0..n] + uint64 supported-open-block-masks + uint64 supported-block-masks + uint32 attrib-extension-count + string attrib-extension-names[attrib_extension-count] + uint32 extension-count + string extension-names[extension-count] + Note that the name "supported2" is used here to avoid conflict with + the slightly different "supported" extension that was previously + used. supported-attribute-mask - This mask MAY by applied to the 'File Attributes' - valid-attribute-flags field (Section 6.1) to ensure that no - unsupported attributes are present during a operation which writes - attributes. + This mask MAY by applied to the 'File Attributes' valid-attribute- + flags field (Section 6.1) to ensure that no unsupported attributes + are present during a operation which writes attributes. supported-attribute-bits This mask MAY by applied to the 'File Attributes' attrib-bits field (Section 6.9) to ensure that no unsupported attrib-bits are present during a operation which writes attributes. supported-open-flags The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN (Section 7.1.1) flags field. max-read-size - This is the maximum read size that the server gaurantees to + This is the maximum read size that the server guarantees to complete. For example, certain embedded server implementations - only complete the first 4K of a read, even if there is additional + complete only the first 4K of a read, even if there is additional data to be read from the file. - If the server specifies a non-zero value, it MUST return at least - the max-read-size number of bytes for any read requesting - max-read-size bytes. Failure to return max-read-size bytes in - such a case indicates either EOF or another error condition - occurred. + If the server specifies a non-zero value for max-read-size, it + MUST return the requested number of bytes for reads that are less + than or equal to the value, unless it encounters EOF or an ERROR. - extension names - The extension names may be empty (contains zero strings), or it - may contain any named extensions that the server wishes to - advertise. + The server MAY use this value to express that it is willing to + handle very large read requests, in excess of the standard 34000 + bytes specfied in Section 3. - The client must be able to differentiate between attribute - extensions (Section 6.13) and extended requests (Section 9) by the - extension name. + supported-open-block-masks + Series of four-bit fields representing the support combinations of + SSH_FXF_ACCESS_BLOCK_READ, SSH_FXF_ACCESS_BLOCK_WRITE, + SSH_FXF_ACCESS_BLOCK_DELETE, and SSH_FXF_ACCESS_BLOCK_ADVISORY + (Section 7.1.1.3.) + + The bits are interpreted in four-bit groups, beginning with the + least significant bit. The bit values are the values used in the + file open flags, shifted right so that BLOCK_READ is the least + significant bit. + + For example, a server that supported only the classic advisory + read lock (shared lock) and write lock (exclusive lock) would send + 0b1011 1010, or 0xba. + + supported-block-masks + Series of four-bit fields representing the supported combinations + of BLOCK_* flags for use with the SSH_FXF_BLOCK request, as + described above. + attrib-extension-count + Count of extension names in the attrib-extension array. + + attrib-extension-names + Names of extensions that can be used in an ATTRS (Section 6.14) + structure. + + extension-count + Count of extension names in the attrib-extension array. + + extension-names + Names of extensions that can be used with the SSH_FXP_EXTEND + (Section 9) packet. Naturally, if a given attribute field, attribute mask bit, open flag, or extension is required for correct operation, the client MUST either not allow the bit to be masked off, or MUST fail the operation gracefully without sending the request to the server. The client MAY send requests that are not supported by the server; however, it is not normally expected to be productive to do so. The client SHOULD apply the mask even to attrib structures received from the server. The server MAY include attributes or attrib-bits that are not included in the mask. Such attributes or attrib-bits are effectively read-only. -4.5 Version re-negotiation +4.6 Version re-negotiation - If the server supports a higher version than was negotiated, it may - wish to send the 'versions' extension to inform the client of this - fact. The client may then optionally choose to use one of the higher - versions supported. + If the server supports other versions than what was negotiated, it + may wish to send the 'versions' extension to inform the client of + this fact. The client may then optionally choose to use one of the + other versions supported. string "versions" - string comma-seperated-versions + string comma-separated-versions - 'comma-seperated-versions' is a string of comma seperated version - numbers, for example, "3,6,7. Versions defined by are: "2", "3", - "4", "5", "6". Any other version advertised by the server must - follow the DNS extensibility naming convention outlined in - [I-D.ietf-secsh-architecture]. + 'comma-separated-versions' is a string of comma separated version + numbers, for example, "3,6,7". Defined versions are: "2", "3", "4", + "5", "6". Any other version advertised by the server must follow the + DNS extensibility naming convention outlined in [I-D.ietf-secsh- + architecture]. - The client may select a new version to use from the list the server - provided using the following SSH_FXP_EXTENDED request. + If the client and server have negotiated any version higher than + version '3' (the version at which SSH_FXP_EXTENDED was introduced) in + the initial VERSION/INIT exchange, the client may select a new + version to use from the list the server provided using the following + SSH_FXP_EXTENDED request. string "version-select" uint32 version-from-list If the 'version-from-list' is one of the versions on the servers list, the server MUST respond with SSH_FX_OK. If the server did not send the "versions" extension, or the version-from-list was not included, the server MAY send a status response describing the failure, but MUST then close the channel without processing any further requests. + The 'version-select' MUST be the first request from the client to the + server; if it is not, the server MUST fail the request and close the + channel. + Although this request does take a full round trip, no client need wait for the response before continuing, because any valid request MUST succeed, and any invalid request results in a channel close. + Since the request is the first request, it is not possible for the + server to have already sent responses conforming to the old version. + + The client SHOULD NOT select a version lower than was initially + negotiated; however, it is not forbidden to do so. One reason a + client might do so is to work around a buggy implementation. 5. 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 @@ -553,60 +641,64 @@ If the server included the 'filename-charset' extension with its VERSION packet, a client MAY send the following extension to turn off server translation to UTF-8. string "filename-translation-control" bool do-translate If the client does not send this extension, the server MUST continue to attempt translation to UTF-8. When a client sends this extension, - the server MUST enable or disable filename translation according to - the value of 'do-translate' + the server MUST enable filename translation if 'do-translate' is + true, or disable filename translation if it is false. The server MUST respond with a STATUS response; if the server sent a 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, the status MUST be UNSUPPORTED. When UTF-8 is sent, 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. 6. 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. + A new compound data type, 'ATTRS', 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. uint32 valid-attribute-flags byte type always present uint64 size if flag SIZE uint64 allocation-size if flag ALLOCATION_SIZE string owner if flag OWNERGROUP string group if flag OWNERGROUP uint32 permissions if flag PERMISSIONS int64 atime if flag ACCESSTIME - uint32 atime_nseconds if flag SUBSECOND_TIMES + uint32 atime-nseconds if flag SUBSECOND_TIMES int64 createtime if flag CREATETIME - uint32 createtime_nseconds if flag SUBSECOND_TIMES + uint32 createtime-nseconds if flag SUBSECOND_TIMES int64 mtime if flag MODIFYTIME - uint32 mtime_nseconds if flag SUBSECOND_TIMES + uint32 mtime-nseconds if flag SUBSECOND_TIMES + int64 ctime if flag CTIME + uint32 ctime-nseconds if flag SUBSECOND_TIMES string acl if flag ACL uint32 attrib-bits if flag BITS + uint32 attrib-bits-valid if flag BITS byte text-hint if flag TEXT_HINT string mime-type if flag MIME_TYPE uint32 link-count if flag LINK_COUNT string untranslated-name if flag UNTRANSLATED_NAME - uint32 extended_count if flag EXTENDED + uint32 extended-count if flag EXTENDED extended-pair extensions 6.1 valid-attribute-flags The 'valid-attribute-flags' specifies which of the fields are present. Those fields for which the corresponding flag is not set are not present (not included in the packet). The server generally includes all attributes it knows about; however, it may exclude attributes that are overly expensive to retrieve @@ -632,20 +724,21 @@ SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 SSH_FILEXFER_ATTR_ACL 0x00000040 SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 SSH_FILEXFER_ATTR_BITS 0x00000200 SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 + SSH_FILEXFER_ATTR_CTIME 0x00008000 SSH_FILEXFER_ATTR_EXTENDED 0x80000000 0x00000002 was used in a previous version of this protocol. It is now a reserved value and MUST NOT appear in the mask. Some future version of this protocol may reuse this value. 6.2 Type The type field is always present. The following types are defined: @@ -674,72 +767,77 @@ extended or truncated to the specified size. Files opened with the SSH_FXF_ACCESS_TEXT flag may have a size that is greater or less than the value of the size field. The server MAY fail setstat operations specifying size for files opened with the SSH_FXF_ACCESS_TEXT flag. 6.4 allocation-size The 'allocation-size' field specifies the number of bytes that the - file consumes on disk. This is greater than or equal to the 'size' - field. + file consumes on disk. This field MAY be less than the 'size' field + if the file is 'sparse' (Section 6.9). When present during file creation, the file SHOULD be created and the specified number of bytes pre-allocated. If the pre-allocation - fails, the file should be removed and an error returned. + fails, the file should be removed (if it was created) and an error + returned. If this field is present during a setstat operation, the file SHOULD be extended or truncated to the specified size. The 'size' of the file may be affected by this operation. If the operation succeeds, - it should be the min of the 'size' before the operation and the new - 'allocation-size'. + the 'size' should be the minimum of the 'size' before the operation + and the new 'allocation-size'. Querying the 'allocation-size' after setting it MUST return a value that is greater-than or equal to the value set, but it MAY not return the precise value set. + If both 'size' and 'allocation-size' are set during a setstat + operation, and 'allocation-size' is less than 'size', the server MUST + return SSH_FX_INVALID_PARAMETER. + 6.5 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 [RFC3010]. 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". + 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 + special meaning on the attribute value. Even though the attribute value cannot be translated, it may still be useful. In the case of a client, the attribute string may be used for local display of ownership. user@localhost represents a user in the context of the server. If either the owner or group field is zero length, the field should be considered absent, and no change should be made to that specific - field. + field during a modification operation. 6.6 Permissions The 'permissions' field contains a bit mask specifying file permissions. These permissions correspond to the st_mode field of the stat structure defined by POSIX [IEEE.1003-1.1996]. This protocol uses the following values for the symbols declared in - the posix standard. + the POSIX standard. S_IRUSR 0000400 (octal) S_IWUSR 0000200 S_IXUSR 0000100 S_IRGRP 0000040 S_IWGRP 0000020 S_IXGRP 0000010 S_IROTH 0000004 S_IWOTH 0000002 S_IXOTH 0000001 @@ -748,31 +846,39 @@ S_ISVTX 0001000 Implementations MUST NOT send bits that are not defined. The server SHOULD NOT apply a 'umask' to the mode bits; but should set the mode bits as specified by the client. The client MUST apply an appropriate 'umask' to the mode bits before sending them. 6.7 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. + The 'atime' field contains the last access time of the file. Many + operating systems either don't have this field, only optionally + maintain it, or maintain it with less resolution than other fields. - A negative value indicates number of seconds before Jan 1, 1970. In + The 'mtime' contains the last time the file was written. + + 'createtime' contains the creation time of the file. + + 'ctime' contains the last time the file attrbutes were changed. The + exact meaning of this field depends on the server. + + All times 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 + 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. 6.8 ACL The 'ACL' field contains an ACL similar to that defined in section 5.9 of NFS version 4 Protocol [RFC3010]. uint32 ace-count repeated ace-count time: @@ -793,22 +899,23 @@ Version 4 Protocol [RFC3010] section 5.9.2: ACE4_FILE_INHERIT_ACE 0x00000001 ACE4_DIRECTORY_INHERIT_ACE 0x00000002 ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 ACE4_INHERIT_ONLY_ACE 0x00000008 ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 ACE4_IDENTIFIER_GROUP 0x00000040 - ace-mask is any combination of the following flags (taken from NFS - Version 4 Protocol [RFC3010] section 5.9.3: + ace-mask is any combination of the following flags (taken from + [RFC3010], section 5.9.3. The semantic meaning of these flags is + also given in [RFC3010]. ACE4_READ_DATA 0x00000001 ACE4_LIST_DIRECTORY 0x00000001 ACE4_WRITE_DATA 0x00000002 ACE4_ADD_FILE 0x00000002 ACE4_APPEND_DATA 0x00000004 ACE4_ADD_SUBDIRECTORY 0x00000004 ACE4_READ_NAMED_ATTRS 0x00000008 ACE4_WRITE_NAMED_ATTRS 0x00000010 ACE4_EXECUTE 0x00000020 @@ -837,24 +944,29 @@ 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 "@". For example: ANONYMOUS@. -6.9 attrib-bits +6.9 attrib-bits and attrib-bits-valid - These bits reflect various attributes of the file or directory on the - server. + These fields, taken together, reflect various attributes of the file + or directory, on the server. + + Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- + bits' field. This allows both the server and the client to + comminicute only the bits it knows about without inadvertantly + twiddling bits they don't understand. The following attrib-bits are defined: SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 @@ -863,30 +975,30 @@ SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 SSH_FILEXFER_ATTR_FLAGS_READONLY Advisory, read-only bit. This bit is not part of the access control information on the file, but is rather an advisory field indicating that the file should not be written. SSH_FILEXFER_ATTR_FLAGS_SYSTEM - The file is part of operating system. + The file is part of the operating system. SSH_FILEXFER_ATTR_FLAGS_HIDDEN File SHOULD NOT be shown to user unless specifically requested. For example, most UNIX systems SHOULD set this bit if the filename - begins with a 'period'. This bit may be read-only (Section 4.4). + begins with a 'period'. This bit may be read-only (Section 4.5). Most UNIX systems will not allow this to be changed. SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE - This attribute can only apply to directories. This attribute is + This attribute applies only to directories. This attribute is always read-only, and cannot be modified. This attribute means that files and directory names in this directory should be compared without regard to case. It is recommended that where possible, the server's filesystem be allowed to do comparisons. For example, if a client wished to prompt a user before overwriting a file, it should not compare the new name with the previously retrieved list of names in the directory. Rather, it should first try to create the new file by specifying SSH_FXF_CREATE_NEW flag. Then, if this fails and @@ -908,48 +1020,50 @@ The file is stored on disk using file-system level transparent compression. This flag does not affect the file data on the wire. SSH_FILEXFER_ATTR_FLAGS_SPARSE The file is a sparse file; this means that file blocks that have not been explicitly written are not stored on disk. For example, if a client writes a buffer at 10 M from the beginning of the file, the blocks between the previous EOF marker and the 10 M offset would not consume physical disk space. - Some server may store all files as sparse files, in which case + Some servers may store all files as sparse files, in which case this bit will be unconditionally set. Other servers may not have a mechanism for determining if the file is sparse, and so the file MAY be stored sparse even if this flag is not set. SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY - The file can only be opened for writing in append mode. + Opening the file without either the SSH_FXF_ACCESS_APPEND_DATA or + the SSH_FXF_ACCESS_APPEND_DATA_ATOMIC flag (Section 7.1.1.3) MUST + result in an SSH_FX_INVALID_PARAMETER error. SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE The file cannot be deleted or renamed, no hard link can be created - to this file and no data can be written to the file. + to this file, and no data can be written to the file. This bit implies a stronger level of protection than SSH_FILEXFER_ATTR_FLAGS_READONLY, the file permission mask or ACLs. Typically even the superuser cannot write to immutable files, and only the superuser can set or remove the bit. SSH_FILEXFER_ATTR_FLAGS_SYNC When the file is modified, the changes are written synchronously to the disk. SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR The server MAY include this bit in a directory listing or realpath response. It indicates there was a failure in the translation to UTF-8. If this flag is included, the server SHOULD also include the UNTRANSLATED_NAME attribute. -6.10 Text Hint +6.10 text-hint The value is one of the following enumerations, and indicates what the server knows about the content of the file. SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 SSH_FILEXFER_ATTR_KNOWN_TEXT @@ -962,50 +1076,51 @@ flag. SSH_FILEXFER_ATTR_KNOWN_BINARY The server knows the file has binary content. SSH_FILEXFER_ATTR_GUESSED_BINARY The server has applied a hueristic or other mechanism and believes has binary content, and should not be opened with the SSH_FXF_ACCESS_TEXT_MODE flag. - This flag MUST NOT be present during a setstat operation. If this - flag is present during an fsetstat operation, the file handle is - converted to a text-mode handle, as if it had been opened with - SSH_FXF_ACCESS_TEXT_MODE. + This flag MUST NOT be present during either a setstat or a fsetstat + operation. -6.11 Mime type +6.11 mime-type The 'mime-type' field contains the mime-type [RFC1521] string. Most servers will not know this information and should not set the bit in their supported-attribute-mask. -6.12 Link Count +6.12 link-count - The 'link-count' field contains the hard link count of the file. - This attribute MUST NOT be present during a setstat operation. + This field contains the hard link count of the file. This attribute + MUST NOT be present during a setstat operation. -6.13 Extended Attributes +6.13 untranslated-name + + This field contains the name before filename translation was attempt. + It MUST NOT be included unless the server also set the + SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR (Section 6.9) bit in the + attrib-bits field. + +6.14 Extended Attributes The SSH_FILEXFER_ATTR_EXTENDED flag provides a general extension mechanism for the attrib structure. 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. + 'extension-pair' items that follow. Each of these items specifies an + extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED + if there are any unrecognized extensions. Clients can avoid sending + unsupported extensions by examining the attrib-extension-names of the + "supported2" extension attrib-extension-names (Section 4.5). 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. @@ -1050,62 +1165,64 @@ 7.1.1.1 filename The 'filename' field specifies the file name. See Section ''File Names'' for more information. If 'filename' is a directory file, the server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. 7.1.1.2 desired-access The 'desired-access' field is a bitmask containing a combination of - values from the ace-mask flags from section 5.7. + values from the ace-mask flags (Section 6.8). Note that again, the + meaning of these flags is given in [RFC3010]. The server MUST be prepared to translate the SFTP access flags into - it's local equivilants. If the server can not grant the access + its local equivalents. If the server cannot grant the access desired, it MUST return SSH_FX_PERMISSION_DENIED. The server MAY open the file with greater access than requested if the user has such access and the server implementation requires it. For example, a server that does not distinguish between READ_ATTRIBUTE and READ_DATA will have to request full 'read' access to the file when the client only requested READ_ATTRIBUTE, resulting in greater access than the client originaly requested. In such cases, it is possible, and permissable in the protocol, that - the client could open a file requesting some limitted access, and - then access the file in a way not permitted by that limitted access - and the server would permit such action. However, the server MUST - NOT ever grant access to the file that the client does not actually - have the rights to. + the client could open a file requesting some limited access, and then + access the file in a way not permitted by that limited access and the + server would permit such action. However, the server MUST NOT ever + grant access to the file that the client does not actually have the + rights to. 7.1.1.3 flags The 'flags' field controls various aspects of the operation, including whether or not the file is created and the kind of locking desired. The following 'flags' are defined: SSH_FXF_ACCESS_DISPOSITION = 0x00000007 SSH_FXF_CREATE_NEW = 0x00000000 SSH_FXF_CREATE_TRUNCATE = 0x00000001 SSH_FXF_OPEN_EXISTING = 0x00000002 SSH_FXF_OPEN_OR_CREATE = 0x00000003 SSH_FXF_TRUNCATE_EXISTING = 0x00000004 SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 - SSH_FXF_ACCESS_READ_LOCK = 0x00000040 - SSH_FXF_ACCESS_WRITE_LOCK = 0x00000080 - SSH_FXF_ACCESS_DELETE_LOCK = 0x00000100 - SSH_FXF_ACCESS_NOFOLLOW = 0x00000200 - SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000400 + SSH_FXF_ACCESS_BLOCK_READ = 0x00000040 + SSH_FXF_ACCESS_BLOCK_WRITE = 0x00000080 + SSH_FXF_ACCESS_BLOCK_DELETE = 0x00000100 + SSH_FXF_ACCESS_BLOCK_ADVISORY = 0x00000200 + SSH_FXF_ACCESS_NOFOLLOW = 0x00000400 + SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000800 SSH_FXF_ACCESS_DISPOSITION Disposition is a 3 bit field that controls how the file is opened. The server MUST support these bits. Any one of the following enumeration is allowed: SSH_FXF_CREATE_NEW A new file is created; if the file already exists, the server MUST return status SSH_FX_FILE_ALREADY_EXISTS. @@ -1148,25 +1265,25 @@ If both append flags are specified, the server SHOULD use atomic append if it is available, but SHOULD use non-atomic appends otherwise. The server SHOULD NOT fail the request in this case. 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. + the read and write functions is 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. + Servers MUST process multiple, parallel reads and writes correctly + in this mode. Naturally, it is permissible for them to do this by + serializing the requests. Clients SHOULD use the SSH_FXF_ACCESS_APPEND_DATA flag to append data to a text file rather then using write with a calculated offset. To support seeks on text files the following SSH_FXP_EXTENDED packet is defined. string "text-seek" string file-handle @@ -1183,66 +1300,100 @@ 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. - SSH_FXF_ACCESS_READ_LOCK - The file should be opened with a read lock. The server MUST - gaurantee that the client will be the exclusive reader of the file - until the client closes the handle. If there is a conflicting - lock the server MUST return SSH_FX_LOCK_CONFlICT. If the server - cannot make the locking gaurantee, it MUST return - SSH_FX_OP_UNSUPPORTED. + SSH_FXF_ACCESS_BLOCK_READ + The server MUST guarantee that no other open has taken place which + blocked handle has been opened with ACE4_READ_DATA access, and + that no other handle will be opened with ACE4_READ_DATA access + until the client closes the handle. (This MUST apply both to + other clients and to other processes on the server.) - SSH_FXF_ACCESS_WRITE_LOCK - The file should be opened with a write lock. The server MUST - gaurantee that the client will be the exclusive writer of the file - until the client closes the handle. + If there is a conflicting lock the server MUST return + SSH_FX_LOCK_CONFLICT. If the server cannot make the locking + guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. - SSH_FXF_ACCESS_DELETE_LOCK - The file should be opened with a delete lock. The server MUST - gaurantee that the file will not be deleted until the client - closes the handle. + Other handles MAY be opened for ACE4_WRITE_DATA or any other + combinatation of accesses, as long as ACE4_READ_DATA is not + included in the mask. + + SSH_FXF_ACCESS_BLOCK_WRITE + The server MUST guarantee that no other lock has been opened with + ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other + handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA + access until the client closes the handle. (This MUST apply both + to other clients and to other processes on the server.) + If there is a conflicting lock the server MUST return + SSH_FX_LOCK_CONFLICT. If the server cannot make the locking + guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. + + Other handles MAY be opened for ACE4_READ_DATA or any other + combinatation of accesses, as long as neither ACE4_WRITE_DATA nor + ACE4_APPEND_DATA are included in the mask. + + SSH_FXF_ACCESS_BLOCK_DELETE + The server MUST guarantee that no other handle has been opened + with ACE4_DELETE access, opened with the + SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that no other handle + will be opened with ACE4_DELETE access or with the + SSH_FXF_ACCESS_DELETE_ON_CLOSE flag set, and that the file itself + is not deleted in any other way until the client closes the + handle. + + If there is a conflicting lock the server MUST return + SSH_FX_LOCK_CONFLICT. If the server cannot make the locking + guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. + + SSH_FXF_ACCESS_BLOCK_ADVISORY + If this bit is set, the above BLOCK modes are advisory. In + advisory mode, only other accesses that specify a BLOCK mode need + be considered when determining whether the BLOCK can be granted, + and the server need not prevent I/O operations that violate the + block mode. + + The server MAY perform mandatory locking even if the + BLOCK_ADVISORY bit is set. SSH_FXF_ACCESS_NOFOLLOW If the final component of the path is a symlink, then the open MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. SSH_FXF_ACCESS_DELETE_ON_CLOSE The file should be deleted when the last handle to it is closed. (The last handle may not be an sftp-handle.) This MAY be emulated by a server if the OS doesn't support it by deleting the file when this handle is closed. The 'attrs' field specifies the initial attributes for the file. Default values MUST be supplied by the server for those attributes that are not specified. See Section ''File Attributes'' for more information. - The 'attrs' field is ignored if an exiting file is opened. + The 'attrs' field is ignored if an existing file is opened. - The following table is provided to assist in mapping posix semantics + The following table is provided to assist in mapping POSIX semantics to equivalent SFTP file open parameters: O_RDONLY desired-access = READ_DATA|READ_ATTRIBUTES O_WRONLY desired-access = WRITE_DATA|WRITE_ATTRIBUTES O_RDWR - desired-access = - READ_DATA|READ_ATTRIBUTES|WRITE_DATA|WRITE_ATTRIBUTES + desired-access = READ_DATA|READ_ATTRIBUTES|WRITE_DATA| + WRITE_ATTRIBUTES O_APPEND desired-access = WRITE_DATA|WRITE_ATTRIBUTES|APPEND_DATA flags = SSH_FXF_ACCESS_APPEND_DATA and or SSH_FXF_ACCESS_APPEND_DATA_ATOMIC O_CREAT flags = SSH_FXF_OPEN_OR_CREATE O_TRUNC @@ -1283,20 +1434,28 @@ handle '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. Note that on some server platforms even a close can fail. For example, if the server operating system caches writes, and an error occurs while flushing cached writes, the close operation may fail. + Note that the handle is invalid regardless of the SSH_FXP_STATUS + result. There is no way for the client to recover a handle that + fails to close. The client MUST release all resources associated + with the handle regardless of the status. The server SHOULD take + whatever steps it can to recover from a close failure and to ensure + that all resources associated with the handle on the server are + correctly released. + 7.2 Reading and Writing 7.2.1 Reading Files The following request can be used to read file data: byte SSH_FXP_READ uint32 request-id string handle uint64 offset @@ -1313,40 +1472,38 @@ SSH_FXF_TEXT was specified during the open. length 'length' is the maximum number of bytes to read. The server MUST not respond with more data than is specified by the 'length' parameter. However, the server MAY respond with less data if EOF is reached, an error is encountered, or the servers internal buffers can not handle such a large request. - For normal disk files, it is normally guaranteed that this will - read the specified number of bytes, or up to end of file. - - If the server specified 'max-read-size' then failure to return + If the server specified a non-zero 'max-read-size' in it's + 'supported2' (Section 4.5) extension, then failure to return 'length' bytes indicates that EOF or an error occured. 7.2.2 Reading Directories In order to retrieve a directory listing, the client issues one or more SSH_FXP_READDIR requests. In order to obtain a complete directory listing, the client MUST issue repeated SSH_FXP_READDIR requests until the server responds with an SSH_FXP_STATUS message. byte SSH_FXP_READDIR uint32 request-id string handle handle 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is - an oridinary file handle returned by SSH_FXP_OPEN, the server MUST + an ordinary file handle returned by SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. 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. @@ -1365,24 +1522,24 @@ 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. offset 'offset' is the offset (in bytes) relative to the beginning of the file that the write MUST start at. 'offset' is ignored if SSH_FXF_TEXT was specified during the open. The write will extend the file if writing beyond the end of the file. It is legal to write to an offset that extends 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 create a sparse file. + end of the file; the semantics are to write the byte value 0x00 + 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 create a sparse file. data The data to write to the file. The server responds to a write request with a SSH_FXP_STATUS message. 7.3 Removing and Renaming Files The following request can be used to remove a file: @@ -1515,23 +1672,22 @@ SSH_FXP_FSTAT differs from the others in that it returns status information for an open file (identified by the file handle). byte SSH_FXP_FSTAT uint32 request-id string handle uint32 flags handle - 'handle' is an open file handle returned by SSH_FXP_OPEN. If - 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST - return SSH_FX_INVALID_HANDLE. + 'handle' is an open file handle from either SSH_FXP_OPEN or + SSH_FXP_OPENDIR. The server responds to this request with SSH_FXP_ATTRS or SSH_FXP_STATUS. 7.6 Setting File Attributes File attributes may be modified using the SSH_FXP_SETSTAT and SSH_FXP_FSETSTAT requests. byte SSH_FXP_SETSTAT @@ -1544,55 +1699,54 @@ string handle ATTRS attrs path The file system object (e.g. file or directory) whose attributes are to be modified. If this object does not exist, or the user does not have sufficient access to write the attributes, the request MUST fail. handle - 'handle' is an open file handle returned by SSH_FXP_OPEN. If - 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST - return SSH_FX_INVALID_HANDLE. If the handle was not opened with - sufficient access to write the requested attributes, the request - MUST fail. + 'handle' is an open file handle from either SSH_FXP_OPEN or + SSH_FXP_OPENDIR. If the handle was not opened with sufficient + access to write the requested attributes, the request MUST fail. attrs Specifies the modified attributes to be applied. Attributes are discussed in more detail in Section ''File Attributes''. The server will respond with a SSH_FXP_STATUS message. Because some systems must use separate system calls to set various attributes, it is possible that a failure response will be returned, but yet some of the attributes may be have been successfully modified. If possible, servers SHOULD avoid this situation; however, - client MUST be aware that this is possible. + clients MUST be aware that this is possible. 7.7 Dealing with Links The SSH_FXP_READLINK request reads the target of a symbolic link. byte SSH_FXP_READLINK uint32 request-id string path [UTF-8] where 'request-id' is the request identifier and 'path' specifies the path name of the symlink to be read. The server will respond with a SSH_FXP_NAME packet containing only one name and a dummy attributes value. The name in the returned packet contains the target of the link. If an error occurs, the server MAY respond with SSH_FXP_STATUS. - The SSH_FXP_LINK request creates a symbolic link on the server. + The SSH_FXP_LINK request creates a link (either hare or symbolic) on + the server. byte SSH_FXP_LINK uint32 request-id string new-link-path [UTF-8] string existing-path [UTF-8] bool sym-link new-link-path Specifies the path name of the new link to create. @@ -1606,23 +1760,79 @@ is generally possible to create symbolic links across device boundaries; however, it is not required that a server support this. If 'sym-link' is false, the link should be a hard link, or a second directory entry refering to the same file or directory object. It is generally not possible to create hard links across devices. The server shall respond with a SSH_FXP_STATUS. Clients should be - aware that some server may return SSH_FX_OP_UNSUPPORTED for either + aware that some servers may return SSH_FX_OP_UNSUPPORTED for either the hard-link, sym-link, or both operations. + The SSH_FXP_LOCK creates a byte-range lock on the file specified by + the handle. The lock can be either mandatory (meaning that the + server enforces that no other process or client can perform + operations in violation of the lock) or advisory (meaning that no + other process can obtain a conflicting lock, but the server does not + enforce that no operation violates the lock. + + A server MAY implement an advisory lock in a mandatory fashion; in + other words, the server MAY enforce that no operation violates the + lock even when operating in advisory mode. + + The result is a SSH_FXP_STATUS return. + + byte SSH_FXP_BLOCK + uint32 request-id + string handle + uint64 offset + uint64 length + uint32 uLockMask + + handle + 'handle' is an open file handle returned by SSH_FXP_OPEN. If + 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST + return SSH_FX_INVALID_HANDLE. + + offset + Beginning of the byte-range to lock. + length + Number of bytes in the range to lock. The special value 0 means + lock from 'offset' to the end of the file. + uLockMask + A bit mask of SSH_FXF_ACCESS_BLOCK_* values; the meanings are + described in Section 7.1.1.3. + + The SSH_FXP_UNLOCK removes a previously aquired byte-range lock on + the specified handle. + + The result is a SSH_FXP_STATUS return. + + byte SSH_FXP_UNBLOCK + uint32 request-id + string handle + uint64 offset + uint64 length + + handle + 'handle' is an open file handle returned by SSH_FXP_OPEN. If + 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST + return SSH_FX_INVALID_HANDLE. + + offset + Beginning of the byte-range to lock. + length + Number of bytes in the range to lock. The special value 0 means + lock from 'offset' to the end of the file. + 7.8 Canonicalizing the Server-Side Path Name The SSH_FXP_REALPATH request can be used to have the server canonicalize any given path name to an absolute path. This is useful for converting path names containing ".." components or relative pathnames without a leading slash into absolute paths. The format of the request is as follows: byte SSH_FXP_REALPATH uint32 request-id @@ -1647,66 +1857,64 @@ SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 This field is optional, and if it is not present in the packet, it is assumed to be SSH_FXP_REALPATH_NO_CHECK. If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT fail the request if the path does not exist, is hidden, or the user does not have access to the path or some component thereof. However, the path MAY NOT be completely resolved to it's component form. For example, symlinks may not be followed in this case. - - The server MAY fail the request if the path is not syntaticly + The server MAY fail the request if the path is not syntactically valid, or for other reasons. If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the path if it exists and is accessible to the client. However, if the path does not exist, isn't visible, or isn't accessible, the server MUST NOT fail the request. If the stat failed, the file type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to distinguish between files that are actually SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will have to issue a seperate stat command in this case. If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat the path. If the stat operation fails, the server MUST fail the request. The server MUST take the 'original-path' and apply the 'compose-path' - as a modification to it. 'compose-path' MAY be relative to - 'original-path' or may be an absolute path, in which case - 'original-path' will be discarded. The 'compose-path' may be zero - length. + as a modification to it. 'compose-path' MAY be relative to 'original- + path' or may be an absolute path, in which case 'original-path' will + be discarded. The 'compose-path' may be zero length. The server will respond with a SSH_FXP_NAME packet containing the canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK is specified, the attributes are dummy values. 7.8.1 Best Practice for Dealing with Paths BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING Previous to this version, clients typically composed new paths themselves and then called both realpath and stat on the resulting - path to get it's canonical name and see if it really existed and was - a directory. + path to get its canonical name and see if it really existed and was a + directory. This required clients to assume certain things about how a relative vs. realpath looked. The new realpath allows clients to no longer make those assumptions and to remove one round trip from the process and get deterministic behavior from all servers. END: RFCEDITOR REMOVE BEFORE PUBLISHING The client SHOULD treat the results of SSH_FXP_REALPATH as a canonical absolute path, even if the path does not appear to be - absolute. A client that use REALPATH(".", "") and treats the result + absolute. A client that uses REALPATH(".", "") and treats the result as absolute, even if there is no leading slash, will continue to function correctly, even when talking to a Windows NT or VMS style system, where absolute paths may not begin with a slash. The client SHOULD also use SSH_FXP_REALPATH call to compose paths so that it does not need to know when a path is absolute or relative. For example, if the client wishes to change directory up, and the server has returned "c:/x/y/z" from REALPATH, the client SHOULD use REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) @@ -1731,66 +1939,70 @@ match each response with the corresponding request. Note that it is legal to have several requests outstanding simultaneously, and the server is allowed to send responses to them in a different order from the order in which the requests were sent (the result of their execution, however, is guaranteed to be as if they had been processed one at a time in the order in which the requests were sent). Response packets are of the same general format as request packets. Each response packet begins with the request identifier. +8.1 Status Response + The format of the data portion of the SSH_FXP_STATUS response is as follows: byte SSH_FXP_STATUS uint32 request-id uint32 error/status code string error message (ISO-10646 UTF-8 [RFC-2279]) string language tag (as defined in [RFC-1766]) - + error-specific data + request-id The 'request-id' specified by the client in the request the server is responding to. error/status code Machine readable status code indicating the result of the request. Error code values are defined below. The value SSH_FX_OK indicates success, and all other values indicate failure. error message - Human readable description of the error. 'language tag' specifies - the language the error is in. + Human readable description of the error. + language tag + 'language tag' specifies the language the error is in. The error-specific data may be empty, or may contain additional - information about the error. For error codes that send - error-specific data, the format of the data is defined below. + information about the error. For error codes that send error- + specific data, the format of the data is defined below. Error codes: SSH_FX_OK 0 SSH_FX_EOF 1 SSH_FX_NO_SUCH_FILE 2 SSH_FX_PERMISSION_DENIED 3 SSH_FX_FAILURE 4 SSH_FX_BAD_MESSAGE 5 SSH_FX_NO_CONNECTION 6 SSH_FX_CONNECTION_LOST 7 SSH_FX_OP_UNSUPPORTED 8 SSH_FX_INVALID_HANDLE 9 SSH_FX_NO_SUCH_PATH 10 SSH_FX_FILE_ALREADY_EXISTS 11 SSH_FX_WRITE_PROTECT 12 SSH_FX_NO_MEDIA 13 SSH_FX_NO_SPACE_ON_FILESYSTEM 14 SSH_FX_QUOTA_EXCEEDED 15 - SSH_FX_UNKNOWN_PRINCIPLE 16 + SSH_FX_UNKNOWN_PRINCIPAL 16 SSH_FX_LOCK_CONFLICT 17 SSH_FX_DIR_NOT_EMPTY 18 SSH_FX_NOT_A_DIRECTORY 19 SSH_FX_INVALID_FILENAME 20 SSH_FX_LINK_LOOP 21 SSH_FX_CANNOT_DELETE 22 SSH_FX_INVALID_PARAMETER 23 SSH_FX_FILE_IS_A_DIRECTORY 24 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 @@ -1816,26 +2028,26 @@ the failure. This error message SHOULD always have meaningful text in the the 'error message' field. SSH_FX_BAD_MESSAGE A badly formatted packet or other SFTP protocol incompatibility was detected. SSH_FX_NO_CONNECTION - There is no connection to the server. This error can only be - generated locally, and MUST NOT be return by a server. + There is no connection to the server. This error MAY be used + locally, but MUST NOT be return by a server. SSH_FX_CONNECTION_LOST - The connection to the server was lost. This error can only be - generated locally, and MUST NOT be return by a server. + The connection to the server was lost. This error MAY be used + locally, but MUST NOT be return by a server. SSH_FX_OP_UNSUPPORTED An attempted operation could not be completed by the server because the server does not support the operation. This error MAY be generated locally by the client if e.g. the version number exchange indicates that a required feature is not supported by the server, or it may be returned by the server if the server does not implement an operation). @@ -1853,25 +2065,25 @@ SSH_FX_NO_MEDIA The requested operation cannot be completed because there is no media available in the drive. SSH_FX_NO_SPACE_ON_FILESYSTEM The requested operation cannot be completed because there is no free space on the filesystem. SSH_FX_QUOTA_EXCEEDED - The operation cannot be completed because the it would exceed the - users storage quota. + The operation cannot be completed because it would exceed the + user's storage quota. - SSH_FX_UNKNOWN_PRINCIPLE - A principle referenced by the request (either the 'owner', + SSH_FX_UNKNOWN_PRINCIPAL + A principal referenced by the request (either the 'owner', 'group', or 'who' field of an ACL), was unknown. The error specific data contains the problematic names. The format is one or more: string unknown-name Each string contains the name of a principle that was unknown. SSH_FX_LOCK_CONFLICT The file could not be opened because it is locked by another @@ -1895,101 +2107,116 @@ SSH_FX_INVALID_PARAMETER On of the parameters was out of range, or the parameters specified cannot be used together. SSH_FX_FILE_IS_A_DIRECTORY The specifed file was a directory in a context where a directory cannot be used. SSH_FX_BYTE_RANGE_LOCK_CONFLICT - A read or write operation failed because another process owns a - byte range lock that conflicts. + Some operating systems support locking a range of bytes within a + file. On such operating systems, it is possible for a SFTP + request to fail due to some other process owning a byte-range + lock, even though the SFTP protocol does not support byte-range + locks natively. + + A read or write operation failed because another process's byte- + range lock overlaps with the request. SSH_FX_BYTE_RANGE_LOCK_REFUSED A request for a byte range lock was refused. SSH_FX_DELETE_PENDING An operation was attempted on a file for which a delete operation is pending. SSH_FX_FILE_CORRUPT The file is corrupt; an filesystem integrity check should be run. +8.2 Handle Response + The SSH_FXP_HANDLE response has the following format: byte SSH_FXP_HANDLE uint32 request-id string handle 'handle' 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. +8.3 Data Response + The SSH_FXP_DATA response has the following format: byte SSH_FXP_DATA uint32 request-id string data bool end-of-file [optional] data 'data' is an arbitrary byte string containing the requested data. The data string may be at most the number of bytes requested in a SSH_FXP_READ request, but may also be shorter. (See Section 7.2.1.) end-of-file This field is optional. If it is present in the packet, it MUST be true, and it indicates that EOF was reached during this read. This can help the client avoid a round trip to determine whether a - short read was normal (due to EOF) or some other problem (limitted + short read was normal (due to EOF) or some other problem (limited server buffer for example.) +8.4 Name Response + The SSH_FXP_NAME response has the following format: byte SSH_FXP_NAME uint32 request-id uint32 count repeats count times: string filename [UTF-8] ATTRS attrs bool end-of-list [optional] count - The number of names returned in this response, and the remaining - fields repeat 'count' times. + The number of names returned in this response, and the 'filename' + and 'attrs' field repeat 'count' times. filename A file name being returned (for SSH_FXP_READDIR, it will be a relative name within the directory, without any path components; for SSH_FXP_REALPATH it will be an absolute path name.) attrs The attributes of the file as described in Section ''File Attributes''. end-of-list This field is optional. If present in the packet, it MUST be true, and indicates that there are no more entries to be read. This can save the client a round trip to determine if there are more entries to be read. +8.5 Attrs Response + The SSH_FXP_ATTRS response has the following format: byte SSH_FXP_ATTRS uint32 request-id ATTRS attrs - where 'request-id' is the request identifier, and 'attrs' is the - returned file attributes as described in Section ''File Attributes''. + attrs + The returned file attributes as described in Section ''File + Attributes''. 9. Extensions The SSH_FXP_EXTENDED request provides a generic extension mechanism for adding additional commands. byte SSH_FXP_EXTENDED uint32 request-id string extended-request ... any request-specific data ... @@ -1999,22 +2226,22 @@ extended-request A string naming the extension. Vendor-specific extensions have use the "name@domain" syntax, where domain is an internet domain name of the vendor defining the request. The IETF may also define extensions to the protocol. These extension names will not have an '@' in them. request-specific data - The rest of the request is defined by the extension, and servers - should only attempt to interpret it if they recognize the + The rest of the request is defined by the extension; servers + SHOULD NOT attempt to interpret it if they do not recognize the 'extended-request' name. The server may respond to such requests using any of the response packets defined in Section ''Responses from the Server to the Client''. Additionally, the server may also respond with a SSH_FXP_EXTENDED_REPLY packet, as defined below. If the server does not recognize the 'extended-request' name, then the server MUST respond with SSH_FXP_STATUS with error/status set to SSH_FX_OP_UNSUPPORTED. @@ -2026,21 +2253,21 @@ uint32 request-id ... any request-specific data ... There is a range of packet types reserved for use by extensions. In order to avoid collision, extensions that that use additional packet types should determine those numbers dynamically. The suggested way of doing this is have an extension request from the client to the server that enables the extension; the extension response from the server to the client would specify the actual type - values to use, in additional to any other data. + values to use, in addition to any other data. Extension authors should be mindful of the limited range of packet types available (there are only 45 values available) and avoid requiring a new packet type where possible. 9.1 File Hashing BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING After some discussion of this at connectathon, I know of two uses for @@ -2153,66 +2380,66 @@ 'handle' is an open file handle returned by SSH_FXP_OPEN. If 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. If ACE4_READ_DATA MUST was not included when the file was opened, the server MUST return STATUS_PERMISSION_DENIED. If this file handle was opened in TEXT mode, the check must be performed on the data as it would be sent on the wire. hash-algorithm-list - A comma seperated list of hash alogirthms the client is willing to + A comma separated list of hash alogirthms the client is willing to accept for this operation. The server MUST pick the first hash on the list that it supports. Currently supported algorithms are "md5", "sha1", "sha224", "sha256", "sha384", "sha512", and "crc32". Additional algorithms may be added by following the DNS extensibility naming convention outlined in [I-D.ietf-secsh-architecture]. MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384, and SHA-512 are decribed in [FIPS-180-2]. crc32 is described in [ISO.3309.1991], and is the same algorithm used in [RFC1510] start-offset The starting offset of the data to include in the hash. length The length of data to include in the hash. If length is zero, all the data from start-offset to the end-of-file should be included. block-size - An independant hash MUST be computed over ever block in the file. + An independant hash MUST be computed over every block in the file. The size of blocks is specified by block-size. The block-size MUST NOT be smaller than 256 bytes. If the block-size is 0, then - only one hash, over the entire range MUST be made. + only one hash, over the entire range, MUST be made. The response is either a SSH_FXP_STATUS packet, indicating an error, or the following extended reply packet: byte SSH_FXP_EXTENDED_REPLY uint32 request-id string "check-file" string hash-algo-used byte hash[n][block-count] hash-algo-used The hash algorithm that was actually used. hash The computed hashes. The hash algorithm used determines the size of n. The number of block-size chunks of data in the file determines block-count. The hashes are placed in the packet one after another, with no decoration. Note that if the length of the range is not an even multiple of - block-size, the last hash will have been computer over only the + block-size, the last hash will have been computed over only the remainder of the range instead of a full block. 9.2 Querying Available Space The following extension provides a way to discover the available space for an arbitrary path. byte SSH_FXP_EXTENDED uint32 request-id string "space-available" @@ -2231,38 +2458,38 @@ uint64 unused-bytes-on-device uint64 bytes-available-to-user uint64 unused-bytes-available-to-user uint32 bytes-per-allocation-unit bytes-on-device The total number of bytes on the device which stores 'path', both used and unused, or 0 if unknown. unused-bytes-on-device - The total number of unused bytes availabe on the device which + The total number of unused bytes available on the device which stores 'path', or 0 if unknown. bytes-available-to-user The total number of bytes, both used and unused, available to the authenticated user on the device which stores 'path', or 0 if unknown. unused-bytes-available-to-user The total number of unused bytes available to the authenticated user on the device which stores 'path', or 0 if unknown. bytes-per-allocation-unit The number of bytes in each allocation unit on the device, or in other words, the minimum number of bytes that a file allocation size can grow or shrink by. If the server does not know this information, or the file-system in use does not use allocation - block, this value MUST be 0. + blocks, this value MUST be 0. 9.3 Querying User Home Directory Many users are used to being able to type '~' as an alias for their home directory, or ~username as an alias for another user's home directory. To support this feature, a server MAY support following extension. byte SSH_FXP_EXTENDED uint32 request-id @@ -2275,64 +2502,65 @@ The reply to the request is either a SSH_FXP_STATUS packet or the following extended reply: byte SSH_FXP_EXTENDED_REPLY uint32 request-id string "home-directory" string absolute-pathname absolute-pathname - Absolute pathname of the specified user's home directory. + Absolute pathname of the specified user's home directory, suitable + for use in operations such as REALPATH or OPEN. 10. Implementation Considerations In order for this protocol to perform well, especially over high latency networks, multiple read and write requests should be queued to the server. The data size of requests should match the maximum packet size for the next layer up in the protocol chain. When implemented over ssh, the best performance should be achieved - when the data size matches the channels max packet, and the channel + when the data size matches the channel's max packet, and the channel window is a multiple of the channel packet size. Implementations MUST be aware that requests do not have to be satisfied in the order issued. (See Request Synchronization and Reordering (Section 3.1).) - Implemenations MUST also be aware that read requests may not return + Implementations MUST also be aware that read requests may not return all the requested data, even if the data is available. 11. Security Considerations It is assumed that both ends of the connection have been authenticated and that the connection has privacy and integrity features. Such security issues are left to the underlying transport protocol, except to note that if this is not the case, an attacker could manipulate files on the server at will and thus wholly compromise the server. This protocol provides file system access to arbitrary files on the - server (only constrained by the server implementation). It is the + server (constrained only by the server implementation). It is the responsibility of the server implementation to enforce any access controls that may be required to limit the access allowed for any particular user (the user being authenticated externally to this protocol, typically using [I-D.ietf-secsh-userauth]. Extreme care must be used when interpreting file handle strings. In particular, care must be taken that a file handle string is valid in - the context of a given 'file-share' session. For example, the - 'file-share' server daemon may have files which it has opened for its - own purposes, and the client must not be able to access these files - by specifying an arbitrary file handle string. + the context of a given 'file-share' session. For example, the 'file- + share' server daemon may have files which it has opened for its own + purposes, and the client must not be able to access these files by + specifying an arbitrary file handle string. The permission field of the attrib structure (Section 6.6) may include the SUID, SGID, and SVTX (sticky) bits. Clients should use extreme caution when setting these bits on either remote or local files. (I.e., just because a file was SUID on the remote system does not necessarily imply that it should be SUID on the local system.) Filesystems often contain entries for objects that are not files at all, but are rather devices. For example, it may be possible to access serial ports, tape devices, or named pipes using this @@ -2343,21 +2571,21 @@ time while I/O is performed to such a device. Servers should take care that file-system quotas are respected for users. In addition, implementations should be aware that attacks may be possible, or facilitated, by filling a filesystem. For example, filling the filesystem where event logging and auditing occurs may, at best, cause the system to crash, or at worst, allow the attacker to take untraceable actions in the future. Servers should take care that filenames are in their appropriate - canonical form, and to insure that filenames not in canonical form + canonical form, and to ensure that filenames not in canonical form cannot be used to bypass access checks or controls. If the server implementation limits access to certain parts of the file system, extra care must be taken in parsing file names which contain the '..' path element, and when following symbolic links, shortcuts, or other filesystem objects which might transpose the path to refer to an object outside of the restricted area. There have been numerous reported security bugs where a ".." in a path name has allowed access outside the intended area. @@ -2382,46 +2610,54 @@ o Added allocation-size, text-hint, link-count, mime-type, and untranslated-name fields to attrib structure. Add ATTR_FLAGS_TRANSLATION_ERR to the attrib-bits. o Add optional 'compose-path' and 'control-byte' to REALPATH; make realpath's behaviour truly deterministic (i.e., MUST instead of SHOULD.) Give clients the ability to compose path's without understanding what is relative and what is absolute. o Give SSH_FXP_DATA and SSH_FXP_NAME optional end-of-data-set flags, which can help the client avoid a round trip during normal operation. + o Changed the SYMLINK packet to be LINK and give it the ability to create hard links. Also change it's packet number because many implementation implemented SYMLINK with the arguments reversed. Hopefully the new argument names make it clear which way is which. - o Clarify who should apply umask to posix mode bits (the client, not + o Clarify who should apply umask to POSIX mode bits (the client, not the server.) o Specify behavior for otherwise valid packets with excess data and unrecognized packet types. o Add home directory extension. o Remove "#define" from symbol definitions to shorten line and help us pass idnits. + o Change "supported" extension to "supported2", remove desired- + access-bits, seperate attrib extension from SSH_FXP_EXTENDED + extensions. + o Add "vendor-id" extension. + o Add ctime and attrib-bits-valid to attrib structure. + o Unrecognized attrib extensions cause failure rather than ignored. + o Option 'end of data' flags on data ane names responses. 12.2 Changes Between Versions 5 and 4 Many of the changes between version 5 and version 4 are to better support the changes in version 4, and to better specify error conditions. o Add "supported" extension to communicate features supported. o Clarify error handling when client requests unsupported feature. (For example, attempts to write an unsupported attribute.) o Add attrib-bits field to the attribute structure, which specifies a number of boolean attributes related to files and directories, including advisory read-only and case-sensitivity bits. o Clarify the actual bit values to be used for the permissions field - (since posix doesn't define values) and correct the value of + (since POSIX doesn't define values) and correct the value of ATTR_PERMISSIONS flag. o Some reordering of sections to attempt to get a better grouping of related functionality. o Open request explicitly specifies the access desired for the file. o Add support for explicitly requesting file locking. o Add support for better control of the rename operation. o Add SSH_FX_NO_SPACE_ON_FILESYSTEM, SSH_FX_QUOTA_EXCEEDED, and SSH_FX_UNKNOWN_PRINCIPLE error codes. o Add support for error specific data. This is used by a new SSH_FX_UNKNOWN_PRINCIPLE error to communicate which principles are @@ -2466,86 +2701,84 @@ message' and 'language tag'. 12.5 Changes Between Versions 2 and 1 o The SSH_FXP_RENAME message was added. 12.6 Changes Between Versions 1 and 0 o Implementation changes, no actual protocol changes. -13. Trademark Issues - - "ssh" is a registered trademark of SSH Communications Security Corp - in the United States and/or other countries. - -14. References +13. References -14.1 Normative References +13.1 Normative References [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, April 1992. [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network Authentication Service (V5)", RFC 1510, September 1993. [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., - Beame, C., Eisler, M. and D. Noveck, "NFS version 4 + Beame, C., Eisler, M., and D. Noveck, "NFS version 4 Protocol", RFC 3010, December 2000. [I-D.ietf-secsh-architecture] Lonvick, C., "SSH Protocol Architecture", - Internet-Draft draft-ietf-secsh-architecture-22, March - 2005. + draft-ietf-secsh-architecture-22 (work in progress), + March 2005. [I-D.ietf-secsh-transport] Lonvick, C., "SSH Transport Layer Protocol", - Internet-Draft draft-ietf-secsh-transport-24, March 2005. + draft-ietf-secsh-transport-24 (work in progress), + March 2005. [I-D.ietf-secsh-connect] Lonvick, C., "SSH Connection Protocol", - Internet-Draft draft-ietf-secsh-connect-25, March 2005. + draft-ietf-secsh-connect-25 (work in progress), + March 2005. [IEEE.1003-1.1996] 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. [FIPS-180-2] National Institute of Standards and Technology, "Secure Hash Standard (SHS)", Federal Information Processing Standards Publication 180-2, August 2002. [ISO.3309.1991] International Organization for Standardization, "Information Technology - Telecommunications and information exchange between systems - High-level data link control (HDLC) procedures - Frame structure", ISO Standard 3309, June 1991. -14.2 Informative References +13.2 Informative References [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet Mail Extensions) Part One: Mechanisms for Specifying and Describing the Format of Internet Message Bodies", RFC 1521, September 1993. [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998. [I-D.ietf-secsh-userauth] Lonvick, C., "SSH Authentication Protocol", - Internet-Draft draft-ietf-secsh-userauth-27, March 2005. + draft-ietf-secsh-userauth-27 (work in progress), + March 2005. Authors' Addresses Joseph Galbraith VanDyke Software 4848 Tramway Ridge Blvd Suite 101 Albuquerque, NM 87111 US