--- 1/draft-ietf-secsh-filexfer-12.txt 2006-07-18 22:12:26.000000000 +0200 +++ 2/draft-ietf-secsh-filexfer-13.txt 2006-07-18 22:12:26.000000000 +0200 @@ -1,19 +1,19 @@ Secure Shell Working Group J. Galbraith Internet-Draft VanDyke Software -Expires: July 29, 2006 O. Saarenmaa +Expires: January 11, 2007 O. Saarenmaa F-Secure - January 25, 2006 + July 10, 2006 SSH File Transfer Protocol - draft-ietf-secsh-filexfer-12.txt + draft-ietf-secsh-filexfer-13.txt Status of this Memo 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 becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that @@ -24,59 +24,59 @@ 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 July 29, 2006. + This Internet-Draft will expire on January 11, 2007. Copyright Notice Copyright (C) The Internet Society (2006). 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. + functionality over any reliable, bidirectional octect 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 . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4 3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5 4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 4.1. Request Synchronization and Reordering . . . . . . . . . . 6 4.2. New data types defined by this document . . . . . . . . . 7 4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9 5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9 5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9 5.3. Determining Server Newline Convention . . . . . . . . . . 10 5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10 - 5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 13 - 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14 + 5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 14 + 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 15 7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16 7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 17 7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 19 7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 19 7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 20 - 7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20 + 7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 24 7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 27 7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 27 7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 27 7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 28 7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 28 8. Requests From the Client to the Server . . . . . . . . . . . . 28 8.1. Opening and Closing Files and Directories . . . . . . . . 28 8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 29 @@ -85,71 +85,73 @@ 8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 36 8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 36 8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 37 8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 37 8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 38 8.4. Creating and Deleting Directories . . . . . . . . . . . . 39 8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 40 8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 41 8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 42 8.8. Byte-range locks . . . . . . . . . . . . . . . . . . . . . 43 - 8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 44 + 8.8.1. Obtaining a byte range lock . . . . . . . . . . . . . 43 + 8.8.2. Releasing a byte range lock . . . . . . . . . . . . . 44 + 8.9. Canonicalizing the Server-Side Path Name . . . . . . . . . 45 8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 46 9. Responses from the Server to the Client . . . . . . . . . . . 47 - 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 47 - 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 51 + 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 48 + 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 52 9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52 - 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 52 + 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 53 9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53 - 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 53 - 11. Implementation Considerations . . . . . . . . . . . . . . . . 54 + 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 54 + 11. Implementation Considerations . . . . . . . . . . . . . . . . 55 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 13. Security Considerations . . . . . . . . . . . . . . . . . . . 55 - 14. Changes from Previous Protocol Versions . . . . . . . . . . . 56 - 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 56 - 15.1. Normative References . . . . . . . . . . . . . . . . . . . 56 + 14. Changes from Previous Protocol Versions . . . . . . . . . . . 57 + 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57 + 15.1. Normative References . . . . . . . . . . . . . . . . . . . 57 15.2. Informative References . . . . . . . . . . . . . . . . . . 57 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 - Intellectual Property and Copyright Statements . . . . . . . . . . 59 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59 + Intellectual Property and Copyright Statements . . . . . . . . . . 60 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. + 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 [RFC4251], and that the server has already authenticated - the client, and that the identity of the client user is available to - the protocol. + channel in [RFC4251], that the server has already authenticated the + client, and that the identity of the client user is available to the + protocol. In general, this protocol follows a simple request-response model. Each request and response contains a sequence number and multiple requests may be pending simultaneously. There are a relatively large number of different request messages, but a small number of possible response messages. Each request has one or more response messages that may be returned in result (e.g., a read either returns data or reports error status). The packet format descriptions in this specification follow the notation presented in [RFC4251]. Even though this protocol is described in the context of the SSH2 protocol, this protocol is general and independent of the rest of the SSH2 protocol suite. It could be used in a number of different applications, such as secure file transfer over TLS [RFC2246] and transfer of management information in VPN applications. 2. Acknowledgements - This document owes it's initial creation and protocol design to Tatu + This document owes its initial creation and protocol design to Tatu Ylonen and Sami Lehtinen of SSH Communications Security Corp. We express our gratitude to them for their initial work on this protocol. 3. Use with the SSH Connection Protocol When used with the SSH2 Protocol suite, this protocol is intended to be used as a subsystem as described in [RFC4254] in the section "Starting a Shell or a Command". The subsystem name used with this @@ -214,21 +217,21 @@ field, but will not redefine it. 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. Additionally, when a packet has two or more optional fields, and an implementation wishes to use the i-th optional field, all fields from 1 to i MUST be present. In other words, only fields after the last - field the implementation wishes to send are actually options. + field the implementation wishes to send are actually optional. 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. @@ -360,21 +363,21 @@ the only such packets in the protocol. 5.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 discontinuous version + to interoperate with servers that support noncontiguous 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. 5.2. Server Initialization The SSH_FXP_VERSION packet (from server to client) has the following data: uint32 version @@ -420,83 +423,86 @@ 5.4. 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. 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. + include it as part of their version packet. string "supported2" string supported-structure uint32 supported-attribute-mask uint32 supported-attribute-bits uint32 supported-open-flags uint32 supported-access-mask uint32 max-read-size uint16 supported-open-block-vector uint16 supported-block-vector 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 7.1) to ensure that no unsupported attributes - are present during a operation which writes attributes. + This mask MAY be applied by the client to the 'File Attributes' + valid-attribute-flags field (Section 7.1) in order 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 7.9) to ensure that no unsupported attrib-bits are - present during a operation which writes attributes. + This mask MAY be applied by the client to the 'File Attributes' + attrib-bits field (Section 7.9) in order to ensure that no + unsupported attrib-bits are present during a operation which + writes attribute bits. supported-open-flags - The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN - (Section 8.1.1) flags field. + The supported-open-flags mask MAY be applied by the client to the + SSH_FXP_OPEN (Section 8.1.1) flags field. supported-access-mask - This mask may be applied to the ace-mask field of an ACL. + This mask may be applied by the client to the ace-mask field of an + ACL during a operation that writes the ACL. This mask SHOULD NOT be applied to the desired-access field of the SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result - in not requesting the access required by the client. In this - case, the server is responsible for translating the clients - requested access to a mode it supports that is sufficient to grant - all access requested by the client. + in not requesting the access required by the client. In the case + of open operations, the server is responsible for translating the + client's requested access to a mode it supports that is sufficient + to grant all access requested by the client. max-read-size This is the maximum read size that the server guarantees to complete. For example, certain embedded server implementations 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 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. 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 specified in Section 4. supported-open-block-vector supported-block-vector 16-bit masks specifying which combinations of blocking flags are supported. Each bit corresponds to one combination of the SSH_FXF_BLOCK_READ, SSH_FXF_BLOCK_WRITE, SSH_FXF_BLOCK_DELETE, and - SSH_FXF_BLOCK_ADVISORY bits from Section 7.1.1.3, with a set bit + SSH_FXF_BLOCK_ADVISORY bits from Section 8.1.1.3, with a set bit corresponding to a supported combination and a clear bit an unsupported combination. The index of a bit, bit zero being the least significant bit, viewed as a four-bit number, corresponds to a combination of flag bits, shifted right so that BLOCK_READ is the least significant bit. The combination `no blocking flags' MUST be supported, so the low bit will always be set. For example, a server supporting only the classic advisory read (shared) and write (exclusive) locks would set the bits corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, @@ -517,22 +523,22 @@ extension-count Count of extension names in the extension-names array. extension-names Names of extensions that can be used with the SSH_FXP_EXTEND (Section 10) 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. + either not mask the bit 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. The supported capabilities of the acl attribute are sent using the following extension. @@ -716,41 +722,41 @@ 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 - extended-pair extensions + extension-pair extensions 7.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 unless the client explicitly requests them. When writing attributes, the server SHOULD NOT modify attributes that are not present in the structure. However, if necessary, the server MAY use a default value for an absent attribute. In general, unless otherwise specified, if a server cannot support writing an attribute requested, it must fail the setstat operation. In this case, none of the attributes SHOULD be changed. - New fields can only be added by incrementing the protocol version + New fields can be added only by incrementing the protocol version number (or by using the extension mechanism described below). The following values are defined: SSH_FILEXFER_ATTR_SIZE 0x00000001 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 SSH_FILEXFER_ATTR_CREATETIME 0x00000010 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 SSH_FILEXFER_ATTR_ACL 0x00000040 @@ -787,48 +793,54 @@ of the stat structure. SPECIAL should be used for files that are of a known type which cannot be expressed in the protocol. UNKNOWN should be used if the type is not known. 7.3. Size The 'size' field specifies the number of bytes that can be read from the file, or in other words, the location of the end-of-file. If this field is present during file creation, it indicates the - number of bytes the client intends to transfer, but SHOULD NOT effect - the creation of the file. The server can use this information to + number of bytes the client intends to transfer, but SHOULD NOT affect + the creation of the file. If the file is a text-file, then the bytes + are 'as encoded on the wire.' The server can use this information to determine if the client sent all the intended data and the file was - transfered in it's entirity. + transfered in its entirity. If this field is present during a setstat operation, the file MUST be - extended or truncated to the specified size. + extended or truncated to the specified size. If the file is + extended, the semantics are to write the byte value 0x00 from the + previous end of file to the new offset. Files opened with the SSH_FXF_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_TEXT flag. 7.4. allocation-size The 'allocation-size' field specifies the number of bytes that the file consumes on disk. This field MAY be less than the 'size' field - if the file is 'sparse' (Section 7.9). + if the file is 'sparse' (Section 7.9). It will usually be larger + than the 'size' field, however, as most file-systems allocate space + to files in units that are larger than a single byte. When present during file creation, the file SHOULD be created and the specified number of bytes preallocated. If the preallocation 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, - the 'size' should be the minimum of the 'size' before the operation - and the new 'allocation-size'. + If this field is present during a setstat operation, the file + allocation SHOULD be changed to the specified size. If the + allocation size is increased, additional space is allocated to the + file, but the 'size' is not changed (the end-of-file marker is not + move.) If the new allocation size is smaller, than the operation is + effectively a truncation. 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. 7.5. Owner and Group @@ -1063,21 +1076,21 @@ To avoid conflict, these special identifiers are distinguish by an appended "@". For example: ANONYMOUS@. 7.9. attrib-bits and attrib-bits-valid 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 - communicate only the bits it knows about without inadvertently + communicate only the bits they knows about without inadvertently 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 @@ -1238,21 +1251,21 @@ 8. Requests From the Client to the Server Requests from the client to the server represent the various file system operations. 8.1. Opening and Closing Files and Directories Many operations in the protocol operate on open files. The SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is - an opaque, variable-length string) which may be used to access the + an opaque variable-length string) which may be used to access the file or directory later. The client MUST NOT send requests to the server with bogus or closed handles. However, the server MUST perform adequate checks on the handle in order to avoid security risks due to fabricated handles. This design allows either stateful and stateless server implementation, as well as an implementation which caches state between requests but may also flush it. The contents of the file handle string are entirely up to the server and its design. The client should not modify or attempt to interpret the file handle @@ -1356,21 +1369,21 @@ If the file exists, it is opened. If the file does not exist, it is created. SSH_FXF_TRUNCATE_EXISTING An existing file is opened and truncated. If the file does not exist, the server MUST return the same error codes as defined for SSH_FXF_OPEN_EXISTING. SSH_FXF_APPEND_DATA Data is always written at the end of the file. The offset field - of the SSH_FXP_WRITE requests are ignored. + of SSH_FXP_WRITE requests is ignored. Data is not required to be appended atomically. This means that if multiple writers attempt to append data simultaneously, data from the first may be lost. However, data MAY be appended atomically. SSH_FXF_APPEND_DATA_ATOMIC Data is always written at the end of the file. The offset field of the SSH_FXP_WRITE requests are ignored. @@ -1494,21 +1507,21 @@ SSH_FXF_BACKUP_STREAM This bit indicates that the client wishes to read or write a backup stream. A backup stream is a system dependent structured data stream that encodes all the information that must be preserved in order to restore the file from backup medium. The only well defined use for backup stream data read in this fashion is to write it to the same server to a file also opened using the BACKUP_STREAM flag. However, if the server has a well - defined backup stream format, their may be other uses for this + defined backup stream format, there may be other uses for this data outside the scope of this protocol. ACCESS_OVERRIDE_OWNER This bit indicates that the client wishes the server to enable any privileges or extra capabilities that the user may have in order to gain access to the file with WRITE_OWNER permission. This bit MUST always be specified in combination with ACE4_WRITE_OWNER. @@ -1614,22 +1628,23 @@ 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. If the server specified a non-zero 'max-read-size' in its - 'supported2' (Section 5.4) extension, then failure to return - 'length' bytes indicates that EOF or an error occurred. + 'supported2' (Section 5.4) extension and 'length' is <= 'max-read- + size', then failure to return 'length' bytes indicates that EOF or + an error occurred. 8.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 @@ -1712,33 +1727,40 @@ where 'request-id' is the request identifier, 'oldpath' is the name of an existing file or directory, and 'newpath' is the new name for the file or directory. 'flags' is 0 or a combination of: SSH_FXF_RENAME_OVERWRITE 0x00000001 SSH_FXF_RENAME_ATOMIC 0x00000002 SSH_FXF_RENAME_NATIVE 0x00000004 + If the server cannot support the requested mode of operation, it must + return SSH_FX_OP_UNSUPPORTED. + If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already exists a file with the name specified by newpath, the server MUST respond with SSH_FX_FILE_ALREADY_EXISTS. If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file already exists, it is replaced in an atomic fashion. I.e., there is no observable instant in time where the name does not refer to either the old or the new file. SSH_FXP_RENAME_ATOMIC implies SSH_FXP_RENAME_OVERWRITE. - If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace - the destination in an atomic fashion, then the server MUST respond - with SSH_FX_OP_UNSUPPORTED. + If 'SSH_FXP_RENAME_OVERWRITE' is not present, and the server does not + support this mode natively, it MAY emulate it by checking for the + existance of a file before executing the rename operation. + + If the 'SSH_FXF_RENAME_ATOMIC' is specified without the the + 'SSH_FXP_RENAME_OVERWRITE', then the server MUST be able to perform + the check and rename operation atomically. Because some servers cannot provide atomic rename, clients should only specify atomic rename if correct operation requires it. If SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an atomic rename even if it is not requested. If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the rename operation in whatever fashion it deems appropriate. Other flag values are considered hints as to desired behavior, but not requirements. @@ -1887,99 +1908,121 @@ 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. - existing-path - Specifies the path of an existing file system object to which the - new-link-path will refer. + target-path + Specifies the path of a target object to which the newly created + link will refer. In the case of a symbolic link, this path may + not exist. sym-link Specifies that the link should be a symbolic link, or a special file that redirects file system parsing to the resulting path. It 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 referring 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 servers may return SSH_FX_OP_UNSUPPORTED for either the hard-link, sym-link, or both operations. 8.8. Byte-range locks +8.8.1. Obtaining a byte range lock + SSH_FXP_BLOCK 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. + 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 a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. - Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the + Note that some servers MAY return SSH_FX_OP_UNSUPPORTED if the handle is a directory 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. + lock from 'offset' to the current end-of-file. (This operation is + equivalent to doing a SSH_FXP_STAT to retrive the 'size' and then + using that to calculate the length.) uLockMask A bit mask of SSH_FXF_BLOCK_* values; the meanings are described in Section 8.1.1.3. - SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the - specified handle. + The result is a SSH_FXP_STATUS packet. If the requested range + overlaps in any fashion with an already granted SSH_FXP_BLOCK request + (even if the request is from the same client in the same connection), + the result is SSH_FX_BYTE_RANGE_LOCK_REFUSED. - The result is a SSH_FXP_STATUS return. + It is permissible for 'offset' to be >= 'size', or for 'length' to + extend past 'size'. However, in no case does this operation effect + 'size'. Naturally, all of the same restrictions regarding + conflicting locks / access apply to such a lock. + + Take together the 'offset' and the 'length' can be considered to form + a unique key, which is then used to release the lock using the + SSH_FXP_UNBLOCK (below) request. + +8.8.2. Releasing a byte range lock + + SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the + specified handle. The 'offset' and 'length' MUST match exactly the + offset and length specified to the SSH_FXP_LOCK request. byte SSH_FXP_UNBLOCK uint32 request-id string handle uint64 offset uint64 length - handle 'handle' on which a SSH_FXP_BLOCK request has previously been issued. offset - Beginning of the byte-range to lock. + Beginning of the byte-range to unlock-- must match exactly the + 'offset' given to the SSH_FXP_BLOCK request. length - Number of bytes in the range to lock. The special value 0 means - lock from 'offset' to the end of the file. + Number of bytes in the range to unlock. The special value 0 means + unlock from 'offset' to the end of the file. This must match + exactly the 'length' give to the SSH_FXP_BLOCK request. + + The result is a SSH_FXP_STATUS packet. If the 'offset' and 'length' + do not exactly match a previously granted range, the server MUST + return SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK. 8.9. 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 @@ -2116,21 +2159,21 @@ 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. Implementations MUST be prepared to receive unexpected error codes and handle them sensibly (such as by treating them as equivalent - to SSH_FX_FAILURE). Future protocol revisions will add additional + to SSH_FX_FAILURE). Future protocol revisions may add additional error codes without changing the version number. error message Human readable description of the error. language tag 'language tag' specifies the language the error is in. error-specific data The error-specific data may be empty, or may contain additional @@ -2163,20 +2206,22 @@ 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 SSH_FX_DELETE_PENDING 27 SSH_FX_FILE_CORRUPT 28 SSH_FX_OWNER_INVALID 29 SSH_FX_GROUP_INVALID 30 + SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK 31 + SSH_FX_OK Indicates successful completion of the operation. SSH_FX_EOF An attempt to read past the end-of-file was made; or, there are no more directory entries to return. SSH_FX_NO_SUCH_FILE A reference was made to a file which does not exist. @@ -2222,22 +2267,22 @@ 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 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. + The requested operation cannot be completed because there is + insufficient free space on the filesystem. SSH_FX_QUOTA_EXCEEDED The operation cannot be completed because it would exceed the user's storage quota. 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: @@ -2253,62 +2298,68 @@ SSH_FX_DIR_NOT_EMPTY The directory is not empty. SSH_FX_NOT_A_DIRECTORY The specified file is not a directory. SSH_FX_INVALID_FILENAME The filename is not valid. SSH_FX_LINK_LOOP - Too many symbolic links encountered. + Too many symbolic links encountered or, an SSH_FXF_NOFOLLOW open + encountered a symbolic link as the final component SSH_FX_CANNOT_DELETE The file cannot be deleted. One possible reason is that the advisory READONLY attribute-bit is set. SSH_FX_INVALID_PARAMETER - On of the parameters was out of range, or the parameters specified - cannot be used together. + One of the parameters was out of range, or the parameters + specified cannot be used together. SSH_FX_FILE_IS_A_DIRECTORY The specified 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's + An read or write operation failed because another process's mandatory 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. SSH_FX_OWNER_INVALID The principal specified can not be assigned as an owner of a file. SSH_FX_GROUP_INVALID The principal specified can not be assigned as the primary group of a file. + SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK + The requested operation could not be completed because the + specifed byte range lock has not been granted. + 9.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. 9.3. Data Response The SSH_FXP_DATA response has the following format: @@ -2309,33 +2360,31 @@ the handle string MUST NOT exceed 256 data bytes. 9.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 8.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 (limited - server buffer for example.) + This field is optional, and if present and true 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 (limited server buffer for example.) 9.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] @@ -2350,21 +2399,22 @@ 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 If this field is present and true, there are no more entries to be - read. + read. This field should either be omitted or be true unless the + request is SSH_FXP_READDIR. 9.5. Attrs Response The SSH_FXP_ATTRS response has the following format: byte SSH_FXP_ATTRS uint32 request-id ATTRS attrs attrs @@ -2438,41 +2488,41 @@ Implementations MUST be aware that requests do not have to be satisfied in the order issued. (See Request Synchronization and Reordering (Section 4.1).) Implementations MUST also be aware that read requests may not return all the requested data, even if the data is available. 12. IANA Considerations - An IANA registry needs to be created containing: + IANA registrie needs to be created for each of the following: o The packet types define defined in Section 4.3 o The extension specified in this draft, which are: 'text-seek', 'supported2', 'acl-supported', 'newline', 'versions', 'version- select', 'filename-charset', 'filename-translation-control' 13. 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 + may be able to manipulate files on the server and thus wholly compromise the server. This protocol provides file system access to arbitrary files on 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 [RFC4252]. + protocol, typically using [RFC4252]). 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 permission field of the attrib structure (Section 7.6) may include the SUID, SGID, and SVTX (sticky) bits. Clients should use