draft-ietf-secsh-filexfer-12.txt   draft-ietf-secsh-filexfer-13.txt 
Secure Shell Working Group J. Galbraith Secure Shell Working Group J. Galbraith
Internet-Draft VanDyke Software Internet-Draft VanDyke Software
Expires: July 29, 2006 O. Saarenmaa Expires: January 11, 2007 O. Saarenmaa
F-Secure F-Secure
January 25, 2006 July 10, 2006
SSH File Transfer Protocol SSH File Transfer Protocol
draft-ietf-secsh-filexfer-12.txt draft-ietf-secsh-filexfer-13.txt
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware 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 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. aware will be disclosed, in accordance with Section 6 of BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
skipping to change at page 1, line 35 skipping to change at page 1, line 35
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. 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 Notice
Copyright (C) The Internet Society (2006). Copyright (C) The Internet Society (2006).
Abstract Abstract
The SSH File Transfer Protocol provides secure file transfer The SSH File Transfer Protocol provides secure file transfer
functionality over any reliable data stream. It is the standard file functionality over any reliable, bidirectional octect stream. It is
transfer protocol for use with the SSH2 protocol. This document the standard file transfer protocol for use with the SSH2 protocol.
describes the file transfer protocol and its interface to the SSH2 This document describes the file transfer protocol and its interface
protocol suite. to the SSH2 protocol suite.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4 2. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 4
3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 3. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4
3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5 3.1. The Use of 'stderr' in the server . . . . . . . . . . . . 5
4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 4. General Packet Format . . . . . . . . . . . . . . . . . . . . 5
4.1. Request Synchronization and Reordering . . . . . . . . . . 6 4.1. Request Synchronization and Reordering . . . . . . . . . . 6
4.2. New data types defined by this document . . . . . . . . . 7 4.2. New data types defined by this document . . . . . . . . . 7
4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 4.3. Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7
5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9 5. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9
5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9 5.1. Client Initialization . . . . . . . . . . . . . . . . . . 9
5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9 5.2. Server Initialization . . . . . . . . . . . . . . . . . . 9
5.3. Determining Server Newline Convention . . . . . . . . . . 10 5.3. Determining Server Newline Convention . . . . . . . . . . 10
5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10 5.4. Supported Features . . . . . . . . . . . . . . . . . . . . 10
5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 13 5.5. Version re-negotiation . . . . . . . . . . . . . . . . . . 14
6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14 6. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16 7. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16
7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 17 7.1. valid-attribute-flags . . . . . . . . . . . . . . . . . . 17
7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.2. Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 7.3. Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 19 7.4. allocation-size . . . . . . . . . . . . . . . . . . . . . 19
7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 19 7.5. Owner and Group . . . . . . . . . . . . . . . . . . . . . 19
7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 20 7.6. Permissions . . . . . . . . . . . . . . . . . . . . . . . 20
7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20 7.7. Times . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 7.8. ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 24 7.9. attrib-bits and attrib-bits-valid . . . . . . . . . . . . 24
7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 27 7.10. text-hint . . . . . . . . . . . . . . . . . . . . . . . . 27
7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 27 7.11. mime-type . . . . . . . . . . . . . . . . . . . . . . . . 27
7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 27 7.12. link-count . . . . . . . . . . . . . . . . . . . . . . . . 27
7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 28 7.13. untranslated-name . . . . . . . . . . . . . . . . . . . . 28
7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 28 7.14. Extended Attributes . . . . . . . . . . . . . . . . . . . 28
8. Requests From the Client to the Server . . . . . . . . . . . . 28 8. Requests From the Client to the Server . . . . . . . . . . . . 28
8.1. Opening and Closing Files and Directories . . . . . . . . 28 8.1. Opening and Closing Files and Directories . . . . . . . . 28
8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 29 8.1.1. Opening a File . . . . . . . . . . . . . . . . . . . . 29
skipping to change at page 2, line 52 skipping to change at page 2, line 52
8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 36 8.2. Reading and Writing . . . . . . . . . . . . . . . . . . . 36
8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 36 8.2.1. Reading Files . . . . . . . . . . . . . . . . . . . . 36
8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 37 8.2.2. Reading Directories . . . . . . . . . . . . . . . . . 37
8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 37 8.2.3. Writing Files . . . . . . . . . . . . . . . . . . . . 37
8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 38 8.3. Removing and Renaming Files . . . . . . . . . . . . . . . 38
8.4. Creating and Deleting Directories . . . . . . . . . . . . 39 8.4. Creating and Deleting Directories . . . . . . . . . . . . 39
8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 40 8.5. Retrieving File Attributes . . . . . . . . . . . . . . . . 40
8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 41 8.6. Setting File Attributes . . . . . . . . . . . . . . . . . 41
8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 42 8.7. Dealing with Links . . . . . . . . . . . . . . . . . . . . 42
8.8. Byte-range locks . . . . . . . . . . . . . . . . . . . . . 43 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 8.9.1. Best Practice for Dealing with Paths . . . . . . . . . 46
9. Responses from the Server to the Client . . . . . . . . . . . 47 9. Responses from the Server to the Client . . . . . . . . . . . 47
9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 47 9.1. Status Response . . . . . . . . . . . . . . . . . . . . . 48
9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 51 9.2. Handle Response . . . . . . . . . . . . . . . . . . . . . 52
9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52 9.3. Data Response . . . . . . . . . . . . . . . . . . . . . . 52
9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 52 9.4. Name Response . . . . . . . . . . . . . . . . . . . . . . 53
9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53 9.5. Attrs Response . . . . . . . . . . . . . . . . . . . . . . 53
10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 53 10. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 54
11. Implementation Considerations . . . . . . . . . . . . . . . . 54 11. Implementation Considerations . . . . . . . . . . . . . . . . 55
12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 55
13. Security Considerations . . . . . . . . . . . . . . . . . . . 55 13. Security Considerations . . . . . . . . . . . . . . . . . . . 55
14. Changes from Previous Protocol Versions . . . . . . . . . . . 56 14. Changes from Previous Protocol Versions . . . . . . . . . . . 57
15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 56 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 57
15.1. Normative References . . . . . . . . . . . . . . . . . . . 56 15.1. Normative References . . . . . . . . . . . . . . . . . . . 57
15.2. Informative References . . . . . . . . . . . . . . . . . . 57 15.2. Informative References . . . . . . . . . . . . . . . . . . 57
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 58 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 59
Intellectual Property and Copyright Statements . . . . . . . . . . 59 Intellectual Property and Copyright Statements . . . . . . . . . . 60
1. Introduction 1. Introduction
This protocol provides secure file transfer (and more generally file This protocol provides secure file transfer (and more generally file
system access.) It is designed so that it could be used to implement 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 a secure remote file system service as well as a secure file transfer
transfer service. service.
This protocol assumes that it runs over a secure channel, such as a This protocol assumes that it runs over a secure channel, such as a
channel in [RFC4251], and that the server has already authenticated channel in [RFC4251], that the server has already authenticated the
the client, and that the identity of the client user is available to client, and that the identity of the client user is available to the
the protocol. protocol.
In general, this protocol follows a simple request-response model. In general, this protocol follows a simple request-response model.
Each request and response contains a sequence number and multiple Each request and response contains a sequence number and multiple
requests may be pending simultaneously. There are a relatively large requests may be pending simultaneously. There are a relatively large
number of different request messages, but a small number of possible number of different request messages, but a small number of possible
response messages. Each request has one or more response messages response messages. Each request has one or more response messages
that may be returned in result (e.g., a read either returns data or that may be returned in result (e.g., a read either returns data or
reports error status). reports error status).
The packet format descriptions in this specification follow the The packet format descriptions in this specification follow the
notation presented in [RFC4251]. notation presented in [RFC4251].
Even though this protocol is described in the context of the SSH2 Even though this protocol is described in the context of the SSH2
protocol, this protocol is general and independent of the rest of the protocol, this protocol is general and independent of the rest of the
SSH2 protocol suite. It could be used in a number of different SSH2 protocol suite. It could be used in a number of different
applications, such as secure file transfer over TLS [RFC2246] and applications, such as secure file transfer over TLS [RFC2246] and
transfer of management information in VPN applications. transfer of management information in VPN applications.
2. Acknowledgements 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. Ylonen and Sami Lehtinen of SSH Communications Security Corp.
We express our gratitude to them for their initial work on this We express our gratitude to them for their initial work on this
protocol. protocol.
3. Use with the SSH Connection Protocol 3. Use with the SSH Connection Protocol
When used with the SSH2 Protocol suite, this protocol is intended to When used with the SSH2 Protocol suite, this protocol is intended to
be used as a subsystem as described in [RFC4254] in the section be used as a subsystem as described in [RFC4254] in the section
"Starting a Shell or a Command". The subsystem name used with this "Starting a Shell or a Command". The subsystem name used with this
skipping to change at page 6, line 26 skipping to change at page 6, line 27
field, but will not redefine it. field, but will not redefine it.
Implementations MUST ignore excess data at the end of an otherwise Implementations MUST ignore excess data at the end of an otherwise
valid packet. Implementations MUST respond to unrecognized packet valid packet. Implementations MUST respond to unrecognized packet
types with an SSH_FX_OP_UNSUPPORTED error. This will allow the types with an SSH_FX_OP_UNSUPPORTED error. This will allow the
protocol to be extended in a backwards compatible way as needed. protocol to be extended in a backwards compatible way as needed.
Additionally, when a packet has two or more optional fields, and an Additionally, when a packet has two or more optional fields, and an
implementation wishes to use the i-th optional field, all fields from 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 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) There is no limit on the number of outstanding (non-acknowledged)
requests that the client may send to the server. In practice this is 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 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 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 not read any more data from the stream, and flow control will prevent
the client from sending more requests. Note, however, that while the client from sending more requests. Note, however, that while
there is no restriction on the protocol level, the client's API may there is no restriction on the protocol level, the client's API may
provide a limit in order to prevent infinite queuing of outgoing provide a limit in order to prevent infinite queuing of outgoing
requests at the client. requests at the client.
skipping to change at page 9, line 36 skipping to change at page 9, line 36
the only such packets in the protocol. the only such packets in the protocol.
5.1. Client Initialization 5.1. Client Initialization
The SSH_FXP_INIT packet (from client to server) has the following The SSH_FXP_INIT packet (from client to server) has the following
data: data:
uint32 version uint32 version
'version' is the version number of the client. If the client wishes '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' numbers it SHOULD send '3', and then use the 'version-select'
extension (see below.) Otherwise, this value is '6' for this version extension (see below.) Otherwise, this value is '6' for this version
of the protocol. of the protocol.
5.2. Server Initialization 5.2. Server Initialization
The SSH_FXP_VERSION packet (from server to client) has the following The SSH_FXP_VERSION packet (from server to client) has the following
data: data:
uint32 version uint32 version
skipping to change at page 10, line 49 skipping to change at page 10, line 49
5.4. Supported Features 5.4. Supported Features
The sftp protocol has grown to be very rich, and now supports a The sftp protocol has grown to be very rich, and now supports a
number of features that may not be available on all servers. number of features that may not be available on all servers.
When a server receives a request for a feature it cannot support, it When a server receives a request for a feature it cannot support, it
MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise MUST return a SSH_FX_OP_UNSUPPORTED status code, unless otherwise
specified. The following extension facilitates clients being able to specified. The following extension facilitates clients being able to
use the maximum available feature set, and yet not be overly burdened use the maximum available feature set, and yet not be overly burdened
by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST 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 "supported2"
string supported-structure string supported-structure
uint32 supported-attribute-mask uint32 supported-attribute-mask
uint32 supported-attribute-bits uint32 supported-attribute-bits
uint32 supported-open-flags uint32 supported-open-flags
uint32 supported-access-mask uint32 supported-access-mask
uint32 max-read-size uint32 max-read-size
uint16 supported-open-block-vector uint16 supported-open-block-vector
uint16 supported-block-vector uint16 supported-block-vector
uint32 attrib-extension-count uint32 attrib-extension-count
string attrib-extension-names[attrib_extension-count] string attrib-extension-names[attrib_extension-count]
uint32 extension-count uint32 extension-count
string extension-names[extension-count] string extension-names[extension-count]
Note that the name "supported2" is used here to avoid conflict with Note that the name "supported2" is used here to avoid conflict with
the slightly different "supported" extension that was previously the slightly different "supported" extension that was previously
used. used.
supported-attribute-mask supported-attribute-mask
This mask MAY by applied to the 'File Attributes' valid-attribute- This mask MAY be applied by the client to the 'File Attributes'
flags field (Section 7.1) to ensure that no unsupported attributes valid-attribute-flags field (Section 7.1) in order to ensure that
are present during a operation which writes attributes. no unsupported attributes are present during a operation which
writes attributes.
supported-attribute-bits supported-attribute-bits
This mask MAY by applied to the 'File Attributes' attrib-bits This mask MAY be applied by the client to the 'File Attributes'
field (Section 7.9) to ensure that no unsupported attrib-bits are attrib-bits field (Section 7.9) in order to ensure that no
present during a operation which writes attributes. unsupported attrib-bits are present during a operation which
writes attribute bits.
supported-open-flags supported-open-flags
The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN The supported-open-flags mask MAY be applied by the client to the
(Section 8.1.1) flags field. SSH_FXP_OPEN (Section 8.1.1) flags field.
supported-access-mask 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 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 SSH_FXP_OPEN (Section 8.1.1) request. Doing so will simply result
in not requesting the access required by the client. In this in not requesting the access required by the client. In the case
case, the server is responsible for translating the clients of open operations, the server is responsible for translating the
requested access to a mode it supports that is sufficient to grant client's requested access to a mode it supports that is sufficient
all access requested by the client. to grant all access requested by the client.
max-read-size max-read-size
This is the maximum read size that the server guarantees to This is the maximum read size that the server guarantees to
complete. For example, certain embedded server implementations complete. For example, certain embedded server implementations
complete only 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. data to be read from the file.
If the server specifies a non-zero value for max-read-size, it 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 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. 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 The server MAY use this value to express that it is willing to
handle very large read requests, in excess of the standard 34000 handle very large read requests, in excess of the standard 34000
bytes specified in Section 4. bytes specified in Section 4.
supported-open-block-vector supported-open-block-vector
supported-block-vector supported-block-vector
16-bit masks specifying which combinations of blocking flags are 16-bit masks specifying which combinations of blocking flags are
supported. Each bit corresponds to one combination of the 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_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 corresponding to a supported combination and a clear bit an
unsupported combination. The index of a bit, bit zero being the unsupported combination. The index of a bit, bit zero being the
least significant bit, viewed as a four-bit number, corresponds to least significant bit, viewed as a four-bit number, corresponds to
a combination of flag bits, shifted right so that BLOCK_READ is a combination of flag bits, shifted right so that BLOCK_READ is
the least significant bit. The combination `no blocking flags' the least significant bit. The combination `no blocking flags'
MUST be supported, so the low bit will always be set. MUST be supported, so the low bit will always be set.
For example, a server supporting only the classic advisory read For example, a server supporting only the classic advisory read
(shared) and write (exclusive) locks would set the bits (shared) and write (exclusive) locks would set the bits
corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY,
skipping to change at page 13, line 5 skipping to change at page 13, line 14
extension-count extension-count
Count of extension names in the extension-names array. Count of extension names in the extension-names array.
extension-names extension-names
Names of extensions that can be used with the SSH_FXP_EXTEND Names of extensions that can be used with the SSH_FXP_EXTEND
(Section 10) packet. (Section 10) packet.
Naturally, if a given attribute field, attribute mask bit, open flag, Naturally, if a given attribute field, attribute mask bit, open flag,
or extension is required for correct operation, the client MUST or extension is required for correct operation, the client MUST
either not allow the bit to be masked off, or MUST fail the operation either not mask the bit off, or MUST fail the operation gracefully
gracefully without sending the request to the server. without sending the request to the server.
The client MAY send requests that are not supported by 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 however, it is not normally expected to be productive to do so. The
client SHOULD apply the mask even to attrib structures received from client SHOULD apply the mask even to attrib structures received from
the server. The server MAY include attributes or attrib-bits that the server. The server MAY include attributes or attrib-bits that
are not included in the mask. Such attributes or attrib-bits are are not included in the mask. Such attributes or attrib-bits are
effectively read-only. effectively read-only.
The supported capabilities of the acl attribute are sent using the The supported capabilities of the acl attribute are sent using the
following extension. following extension.
skipping to change at page 17, line 28 skipping to change at page 17, line 28
int64 ctime if flag CTIME int64 ctime if flag CTIME
uint32 ctime-nseconds if flag SUBSECOND_TIMES uint32 ctime-nseconds if flag SUBSECOND_TIMES
string acl if flag ACL string acl if flag ACL
uint32 attrib-bits if flag BITS uint32 attrib-bits if flag BITS
uint32 attrib-bits-valid if flag BITS uint32 attrib-bits-valid if flag BITS
byte text-hint if flag TEXT_HINT byte text-hint if flag TEXT_HINT
string mime-type if flag MIME_TYPE string mime-type if flag MIME_TYPE
uint32 link-count if flag LINK_COUNT uint32 link-count if flag LINK_COUNT
string untranslated-name if flag UNTRANSLATED_NAME string untranslated-name if flag UNTRANSLATED_NAME
uint32 extended-count if flag EXTENDED uint32 extended-count if flag EXTENDED
extended-pair extensions extension-pair extensions
7.1. valid-attribute-flags 7.1. valid-attribute-flags
The 'valid-attribute-flags' specifies which of the fields are The 'valid-attribute-flags' specifies which of the fields are
present. Those fields for which the corresponding flag is not set present. Those fields for which the corresponding flag is not set
are not present (not included in the packet). are not present (not included in the packet).
The server generally includes all attributes it knows about; however, The server generally includes all attributes it knows about; however,
it may exclude attributes that are overly expensive to retrieve it may exclude attributes that are overly expensive to retrieve
unless the client explicitly requests them. unless the client explicitly requests them.
When writing attributes, the server SHOULD NOT modify attributes that When writing attributes, the server SHOULD NOT modify attributes that
are not present in the structure. However, if necessary, the server are not present in the structure. However, if necessary, the server
MAY use a default value for an absent attribute. MAY use a default value for an absent attribute.
In general, unless otherwise specified, if a server cannot support In general, unless otherwise specified, if a server cannot support
writing an attribute requested, it must fail the setstat operation. writing an attribute requested, it must fail the setstat operation.
In this case, none of the attributes SHOULD be changed. 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). number (or by using the extension mechanism described below).
The following values are defined: The following values are defined:
SSH_FILEXFER_ATTR_SIZE 0x00000001 SSH_FILEXFER_ATTR_SIZE 0x00000001
SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004
SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008
SSH_FILEXFER_ATTR_CREATETIME 0x00000010 SSH_FILEXFER_ATTR_CREATETIME 0x00000010
SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020
SSH_FILEXFER_ATTR_ACL 0x00000040 SSH_FILEXFER_ATTR_ACL 0x00000040
skipping to change at page 18, line 51 skipping to change at page 18, line 51
of the stat structure. SPECIAL should be used for files that are of of the stat structure. SPECIAL should be used for files that are of
a known type which cannot be expressed in the protocol. UNKNOWN a known type which cannot be expressed in the protocol. UNKNOWN
should be used if the type is not known. should be used if the type is not known.
7.3. Size 7.3. Size
The 'size' field specifies the number of bytes that can be read from 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. the file, or in other words, the location of the end-of-file.
If this field is present during file creation, it indicates the If this field is present during file creation, it indicates the
number of bytes the client intends to transfer, but SHOULD NOT effect number of bytes the client intends to transfer, but SHOULD NOT affect
the creation of the file. The server can use this information to 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 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 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 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 greater or less than the value of the size field. The server MAY
fail setstat operations specifying size for files opened with the fail setstat operations specifying size for files opened with the
SSH_FXF_TEXT flag. SSH_FXF_TEXT flag.
7.4. allocation-size 7.4. allocation-size
The 'allocation-size' field specifies the number of bytes that the The 'allocation-size' field specifies the number of bytes that the
file consumes on disk. This field MAY be less than the 'size' field 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 When present during file creation, the file SHOULD be created and the
specified number of bytes preallocated. If the preallocation fails, specified number of bytes preallocated. If the preallocation fails,
the file should be removed (if it was created) and an error returned. 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 If this field is present during a setstat operation, the file
be extended or truncated to the specified size. The 'size' of the allocation SHOULD be changed to the specified size. If the
file may be affected by this operation. If the operation succeeds, allocation size is increased, additional space is allocated to the
the 'size' should be the minimum of the 'size' before the operation file, but the 'size' is not changed (the end-of-file marker is not
and the new 'allocation-size'. 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 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 that is greater-than or equal to the value set, but it MAY not return
the precise value set. the precise value set.
If both 'size' and 'allocation-size' are set during a setstat If both 'size' and 'allocation-size' are set during a setstat
operation, and 'allocation-size' is less than 'size', the server MUST operation, and 'allocation-size' is less than 'size', the server MUST
return SSH_FX_INVALID_PARAMETER. return SSH_FX_INVALID_PARAMETER.
7.5. Owner and Group 7.5. Owner and Group
skipping to change at page 25, line 4 skipping to change at page 25, line 7
To avoid conflict, these special identifiers are distinguish by an To avoid conflict, these special identifiers are distinguish by an
appended "@". For example: ANONYMOUS@. appended "@". For example: ANONYMOUS@.
7.9. attrib-bits and attrib-bits-valid 7.9. attrib-bits and attrib-bits-valid
These fields, taken together, reflect various attributes of the file These fields, taken together, reflect various attributes of the file
or directory, on the server. or directory, on the server.
Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib-
bits' field. This allows both the server and the client to 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. twiddling bits they don't understand.
The following attrib-bits are defined: The following attrib-bits are defined:
SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001
SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002
SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004
SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008
SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010
SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020
skipping to change at page 28, line 42 skipping to change at page 28, line 42
8. Requests From the Client to the Server 8. Requests From the Client to the Server
Requests from the client to the server represent the various file Requests from the client to the server represent the various file
system operations. system operations.
8.1. Opening and Closing Files and Directories 8.1. Opening and Closing Files and Directories
Many operations in the protocol operate on open files. The Many operations in the protocol operate on open files. The
SSH_FXP_OPEN and SSH_FXP_OPENDIR requests return a handle (which is 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 file or directory later. The client MUST NOT send requests to the
server with bogus or closed handles. However, the server MUST server with bogus or closed handles. However, the server MUST
perform adequate checks on the handle in order to avoid security perform adequate checks on the handle in order to avoid security
risks due to fabricated handles. risks due to fabricated handles.
This design allows either stateful and stateless server This design allows either stateful and stateless server
implementation, as well as an implementation which caches state implementation, as well as an implementation which caches state
between requests but may also flush it. The contents of the file between requests but may also flush it. The contents of the file
handle string are entirely up to the server and its design. The handle string are entirely up to the server and its design. The
client should not modify or attempt to interpret the file handle client should not modify or attempt to interpret the file handle
skipping to change at page 31, line 16 skipping to change at page 31, line 16
If the file exists, it is opened. If the file does not exist, If the file exists, it is opened. If the file does not exist,
it is created. it is created.
SSH_FXF_TRUNCATE_EXISTING SSH_FXF_TRUNCATE_EXISTING
An existing file is opened and truncated. If the file does not An existing file is opened and truncated. If the file does not
exist, the server MUST return the same error codes as defined exist, the server MUST return the same error codes as defined
for SSH_FXF_OPEN_EXISTING. for SSH_FXF_OPEN_EXISTING.
SSH_FXF_APPEND_DATA SSH_FXF_APPEND_DATA
Data is always written at the end of the file. The offset field 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 Data is not required to be appended atomically. This means that
if multiple writers attempt to append data simultaneously, data if multiple writers attempt to append data simultaneously, data
from the first may be lost. However, data MAY be appended from the first may be lost. However, data MAY be appended
atomically. atomically.
SSH_FXF_APPEND_DATA_ATOMIC SSH_FXF_APPEND_DATA_ATOMIC
Data is always written at the end of the file. The offset field Data is always written at the end of the file. The offset field
of the SSH_FXP_WRITE requests are ignored. of the SSH_FXP_WRITE requests are ignored.
skipping to change at page 34, line 19 skipping to change at page 34, line 19
SSH_FXF_BACKUP_STREAM SSH_FXF_BACKUP_STREAM
This bit indicates that the client wishes to read or write a This bit indicates that the client wishes to read or write a
backup stream. A backup stream is a system dependent structured backup stream. A backup stream is a system dependent structured
data stream that encodes all the information that must be data stream that encodes all the information that must be
preserved in order to restore the file from backup medium. preserved in order to restore the file from backup medium.
The only well defined use for backup stream data read in this 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 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 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. data outside the scope of this protocol.
ACCESS_OVERRIDE_OWNER ACCESS_OVERRIDE_OWNER
This bit indicates that the client wishes the server to enable any This bit indicates that the client wishes the server to enable any
privileges or extra capabilities that the user may have in order privileges or extra capabilities that the user may have in order
to gain access to the file with WRITE_OWNER permission. to gain access to the file with WRITE_OWNER permission.
This bit MUST always be specified in combination with This bit MUST always be specified in combination with
ACE4_WRITE_OWNER. ACE4_WRITE_OWNER.
skipping to change at page 36, line 49 skipping to change at page 36, line 49
length length
'length' is the maximum number of bytes to read. 'length' is the maximum number of bytes to read.
The server MUST not respond with more data than is specified by The server MUST not respond with more data than is specified by
the 'length' parameter. However, the server MAY respond with less the 'length' parameter. However, the server MAY respond with less
data if EOF is reached, an error is encountered, or the servers data if EOF is reached, an error is encountered, or the servers
internal buffers can not handle such a large request. internal buffers can not handle such a large request.
If the server specified a non-zero 'max-read-size' in its If the server specified a non-zero 'max-read-size' in its
'supported2' (Section 5.4) extension, then failure to return 'supported2' (Section 5.4) extension and 'length' is <= 'max-read-
'length' bytes indicates that EOF or an error occurred. size', then failure to return 'length' bytes indicates that EOF or
an error occurred.
8.2.2. Reading Directories 8.2.2. Reading Directories
In order to retrieve a directory listing, the client issues one or In order to retrieve a directory listing, the client issues one or
more SSH_FXP_READDIR requests. In order to obtain a complete more SSH_FXP_READDIR requests. In order to obtain a complete
directory listing, the client MUST issue repeated SSH_FXP_READDIR directory listing, the client MUST issue repeated SSH_FXP_READDIR
requests until the server responds with an SSH_FXP_STATUS message. requests until the server responds with an SSH_FXP_STATUS message.
byte SSH_FXP_READDIR byte SSH_FXP_READDIR
uint32 request-id uint32 request-id
skipping to change at page 39, line 9 skipping to change at page 39, line 9
where 'request-id' is the request identifier, 'oldpath' is the name where 'request-id' is the request identifier, 'oldpath' is the name
of an existing file or directory, and 'newpath' is the new name for of an existing file or directory, and 'newpath' is the new name for
the file or directory. the file or directory.
'flags' is 0 or a combination of: 'flags' is 0 or a combination of:
SSH_FXF_RENAME_OVERWRITE 0x00000001 SSH_FXF_RENAME_OVERWRITE 0x00000001
SSH_FXF_RENAME_ATOMIC 0x00000002 SSH_FXF_RENAME_ATOMIC 0x00000002
SSH_FXF_RENAME_NATIVE 0x00000004 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 If flags does not include SSH_FXP_RENAME_OVERWRITE, and there already
exists a file with the name specified by newpath, the server MUST exists a file with the name specified by newpath, the server MUST
respond with SSH_FX_FILE_ALREADY_EXISTS. respond with SSH_FX_FILE_ALREADY_EXISTS.
If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file If flags includes SSH_FXP_RENAME_ATOMIC, and the destination file
already exists, it is replaced in an atomic fashion. I.e., there is 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 no observable instant in time where the name does not refer to either
the old or the new file. SSH_FXP_RENAME_ATOMIC implies the old or the new file. SSH_FXP_RENAME_ATOMIC implies
SSH_FXP_RENAME_OVERWRITE. SSH_FXP_RENAME_OVERWRITE.
If flags includes SSH_FXP_RENAME_ATOMIC and the server cannot replace If 'SSH_FXP_RENAME_OVERWRITE' is not present, and the server does not
the destination in an atomic fashion, then the server MUST respond support this mode natively, it MAY emulate it by checking for the
with SSH_FX_OP_UNSUPPORTED. 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 Because some servers cannot provide atomic rename, clients should
only specify atomic rename if correct operation requires it. If only specify atomic rename if correct operation requires it. If
SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an SSH_FXP_RENAME_OVERWRITE is specified, the server MAY perform an
atomic rename even if it is not requested. atomic rename even if it is not requested.
If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the If flags includes SSH_FXP_RENAME_NATIVE, the server is free to do the
rename operation in whatever fashion it deems appropriate. Other rename operation in whatever fashion it deems appropriate. Other
flag values are considered hints as to desired behavior, but not flag values are considered hints as to desired behavior, but not
requirements. requirements.
skipping to change at page 42, line 45 skipping to change at page 43, line 5
byte SSH_FXP_LINK byte SSH_FXP_LINK
uint32 request-id uint32 request-id
string new-link-path [UTF-8] string new-link-path [UTF-8]
string existing-path [UTF-8] string existing-path [UTF-8]
bool sym-link bool sym-link
new-link-path new-link-path
Specifies the path name of the new link to create. Specifies the path name of the new link to create.
existing-path target-path
Specifies the path of an existing file system object to which the Specifies the path of a target object to which the newly created
new-link-path will refer. link will refer. In the case of a symbolic link, this path may
not exist.
sym-link sym-link
Specifies that the link should be a symbolic link, or a special Specifies that the link should be a symbolic link, or a special
file that redirects file system parsing to the resulting path. It file that redirects file system parsing to the resulting path. It
is generally possible to create symbolic links across device is generally possible to create symbolic links across device
boundaries; however, it is not required that a server support boundaries; however, it is not required that a server support
this. this.
If 'sym-link' is false, the link should be a hard link, or a If 'sym-link' is false, the link should be a hard link, or a
second directory entry referring to the same file or directory second directory entry referring to the same file or directory
object. It is generally not possible to create hard links across object. It is generally not possible to create hard links across
devices. devices.
The server shall respond with a SSH_FXP_STATUS. Clients should be The server shall respond with a SSH_FXP_STATUS. Clients should be
aware that some servers 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 hard-link, sym-link, or both operations.
8.8. Byte-range locks 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 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 handle. The lock can be either mandatory (meaning that the server
enforces that no other process or client can perform operations in enforces that no other process or client can perform operations in
violation of the lock) or advisory (meaning that no other process can violation of the lock) or advisory (meaning that no other process can
obtain a conflicting lock, but the server does not enforce that no 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 A server MAY implement an advisory lock in a mandatory fashion; in
other words, the server MAY enforce that no operation violates the other words, the server MAY enforce that no operation violates the
lock even when operating in advisory mode. lock even when operating in advisory mode.
The result is a SSH_FXP_STATUS return.
byte SSH_FXP_BLOCK byte SSH_FXP_BLOCK
uint32 request-id uint32 request-id
string handle string handle
uint64 offset uint64 offset
uint64 length uint64 length
uint32 uLockMask uint32 uLockMask
handle handle
'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. '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. handle is a directory handle.
offset offset
Beginning of the byte-range to lock. Beginning of the byte-range to lock.
length length
Number of bytes in the range to lock. The special value 0 means 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 uLockMask
A bit mask of SSH_FXF_BLOCK_* values; the meanings are described A bit mask of SSH_FXF_BLOCK_* values; the meanings are described
in Section 8.1.1.3. in Section 8.1.1.3.
SSH_FXP_UNBLOCK removes a previously acquired byte-range lock on the The result is a SSH_FXP_STATUS packet. If the requested range
specified handle. 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 byte SSH_FXP_UNBLOCK
uint32 request-id uint32 request-id
string handle string handle
uint64 offset uint64 offset
uint64 length uint64 length
handle handle
'handle' on which a SSH_FXP_BLOCK request has previously been 'handle' on which a SSH_FXP_BLOCK request has previously been
issued. issued.
offset 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 length
Number of bytes in the range to lock. The special value 0 means Number of bytes in the range to unlock. The special value 0 means
lock from 'offset' to the end of the file. 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 8.9. Canonicalizing the Server-Side Path Name
The SSH_FXP_REALPATH request can be used to have the server The SSH_FXP_REALPATH request can be used to have the server
canonicalize any given path name to an absolute path. This is useful canonicalize any given path name to an absolute path. This is useful
for converting path names containing ".." components or relative for converting path names containing ".." components or relative
pathnames without a leading slash into absolute paths. The format of pathnames without a leading slash into absolute paths. The format of
the request is as follows: the request is as follows:
byte SSH_FXP_REALPATH byte SSH_FXP_REALPATH
skipping to change at page 47, line 48 skipping to change at page 48, line 33
The 'request-id' specified by the client in the request the server The 'request-id' specified by the client in the request the server
is responding to. is responding to.
error/status code error/status code
Machine readable status code indicating the result of the request. Machine readable status code indicating the result of the request.
Error code values are defined below. The value SSH_FX_OK Error code values are defined below. The value SSH_FX_OK
indicates success, and all other values indicate failure. indicates success, and all other values indicate failure.
Implementations MUST be prepared to receive unexpected error codes Implementations MUST be prepared to receive unexpected error codes
and handle them sensibly (such as by treating them as equivalent 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 codes without changing the version number.
error message error message
Human readable description of the error. Human readable description of the error.
language tag language tag
'language tag' specifies the language the error is in. 'language tag' specifies the language the error is in.
error-specific data error-specific data
The error-specific data may be empty, or may contain additional The error-specific data may be empty, or may contain additional
skipping to change at page 49, line 4 skipping to change at page 49, line 36
SSH_FX_LINK_LOOP 21 SSH_FX_LINK_LOOP 21
SSH_FX_CANNOT_DELETE 22 SSH_FX_CANNOT_DELETE 22
SSH_FX_INVALID_PARAMETER 23 SSH_FX_INVALID_PARAMETER 23
SSH_FX_FILE_IS_A_DIRECTORY 24 SSH_FX_FILE_IS_A_DIRECTORY 24
SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25
SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 SSH_FX_BYTE_RANGE_LOCK_REFUSED 26
SSH_FX_DELETE_PENDING 27 SSH_FX_DELETE_PENDING 27
SSH_FX_FILE_CORRUPT 28 SSH_FX_FILE_CORRUPT 28
SSH_FX_OWNER_INVALID 29 SSH_FX_OWNER_INVALID 29
SSH_FX_GROUP_INVALID 30 SSH_FX_GROUP_INVALID 30
SSH_FX_NO_MATCHING_BYTE_RANGE_LOCK 31
SSH_FX_OK SSH_FX_OK
Indicates successful completion of the operation. Indicates successful completion of the operation.
SSH_FX_EOF SSH_FX_EOF
An attempt to read past the end-of-file was made; or, there are no An attempt to read past the end-of-file was made; or, there are no
more directory entries to return. more directory entries to return.
SSH_FX_NO_SUCH_FILE SSH_FX_NO_SUCH_FILE
A reference was made to a file which does not exist. A reference was made to a file which does not exist.
skipping to change at page 50, line 19 skipping to change at page 51, line 6
The file already exists. The file already exists.
SSH_FX_WRITE_PROTECT SSH_FX_WRITE_PROTECT
The file is on read-only media, or the media is write protected. The file is on read-only media, or the media is write protected.
SSH_FX_NO_MEDIA SSH_FX_NO_MEDIA
The requested operation cannot be completed because there is no The requested operation cannot be completed because there is no
media available in the drive. media available in the drive.
SSH_FX_NO_SPACE_ON_FILESYSTEM SSH_FX_NO_SPACE_ON_FILESYSTEM
The requested operation cannot be completed because there is no The requested operation cannot be completed because there is
free space on the filesystem. insufficient free space on the filesystem.
SSH_FX_QUOTA_EXCEEDED SSH_FX_QUOTA_EXCEEDED
The operation cannot be completed because it would exceed the The operation cannot be completed because it would exceed the
user's storage quota. user's storage quota.
SSH_FX_UNKNOWN_PRINCIPAL SSH_FX_UNKNOWN_PRINCIPAL
A principal referenced by the request (either the 'owner', A principal referenced by the request (either the 'owner',
'group', or 'who' field of an ACL), was unknown. The error 'group', or 'who' field of an ACL), was unknown. The error
specific data contains the problematic names. The format is one specific data contains the problematic names. The format is one
or more: or more:
skipping to change at page 51, line 6 skipping to change at page 51, line 37
SSH_FX_DIR_NOT_EMPTY SSH_FX_DIR_NOT_EMPTY
The directory is not empty. The directory is not empty.
SSH_FX_NOT_A_DIRECTORY SSH_FX_NOT_A_DIRECTORY
The specified file is not a directory. The specified file is not a directory.
SSH_FX_INVALID_FILENAME SSH_FX_INVALID_FILENAME
The filename is not valid. The filename is not valid.
SSH_FX_LINK_LOOP 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 SSH_FX_CANNOT_DELETE
The file cannot be deleted. One possible reason is that the The file cannot be deleted. One possible reason is that the
advisory READONLY attribute-bit is set. advisory READONLY attribute-bit is set.
SSH_FX_INVALID_PARAMETER SSH_FX_INVALID_PARAMETER
On of the parameters was out of range, or the parameters specified One of the parameters was out of range, or the parameters
cannot be used together. specified cannot be used together.
SSH_FX_FILE_IS_A_DIRECTORY SSH_FX_FILE_IS_A_DIRECTORY
The specified file was a directory in a context where a directory The specified file was a directory in a context where a directory
cannot be used. cannot be used.
SSH_FX_BYTE_RANGE_LOCK_CONFLICT 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. mandatory byte-range lock overlaps with the request.
SSH_FX_BYTE_RANGE_LOCK_REFUSED SSH_FX_BYTE_RANGE_LOCK_REFUSED
A request for a byte range lock was refused. A request for a byte range lock was refused.
SSH_FX_DELETE_PENDING SSH_FX_DELETE_PENDING
An operation was attempted on a file for which a delete operation An operation was attempted on a file for which a delete operation
is pending. is pending.
SSH_FX_FILE_CORRUPT SSH_FX_FILE_CORRUPT
The file is corrupt; an filesystem integrity check should be run. The file is corrupt; an filesystem integrity check should be run.
SSH_FX_OWNER_INVALID SSH_FX_OWNER_INVALID
The principal specified can not be assigned as an owner of a file. The principal specified can not be assigned as an owner of a file.
SSH_FX_GROUP_INVALID SSH_FX_GROUP_INVALID
The principal specified can not be assigned as the primary group The principal specified can not be assigned as the primary group
of a file. 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 9.2. Handle Response
The SSH_FXP_HANDLE response has the following format: The SSH_FXP_HANDLE response has the following format:
byte SSH_FXP_HANDLE byte SSH_FXP_HANDLE
uint32 request-id uint32 request-id
string handle string handle
'handle' 'handle'
An arbitrary string that identifies an open file or directory on An arbitrary string that identifies an open file or directory on
the server. The handle is opaque to the client; the client MUST 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 NOT attempt to interpret or modify it in any way. The length of
the handle string MUST NOT exceed 256 data bytes. the handle string MUST NOT exceed 256 data bytes.
9.3. Data Response 9.3. Data Response
The SSH_FXP_DATA response has the following format: The SSH_FXP_DATA response has the following format:
skipping to change at page 52, line 18 skipping to change at page 53, line 4
the handle string MUST NOT exceed 256 data bytes. the handle string MUST NOT exceed 256 data bytes.
9.3. Data Response 9.3. Data Response
The SSH_FXP_DATA response has the following format: The SSH_FXP_DATA response has the following format:
byte SSH_FXP_DATA byte SSH_FXP_DATA
uint32 request-id uint32 request-id
string data string data
bool end-of-file [optional] bool end-of-file [optional]
data data
'data' is an arbitrary byte string containing the requested 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 The data string may be at most the number of bytes requested in a
SSH_FXP_READ request, but may also be shorter. (See SSH_FXP_READ request, but may also be shorter. (See
Section 8.2.1.) Section 8.2.1.)
end-of-file end-of-file
This field is optional. If it is present in the packet, it MUST This field is optional, and if present and true it indicates that
be true, and it indicates that EOF was reached during this read. EOF was reached during this read. This can help the client avoid
This can help the client avoid a round trip to determine whether a a round trip to determine whether a short read was normal (due to
short read was normal (due to EOF) or some other problem (limited EOF) or some other problem (limited server buffer for example.)
server buffer for example.)
9.4. Name Response 9.4. Name Response
The SSH_FXP_NAME response has the following format: The SSH_FXP_NAME response has the following format:
byte SSH_FXP_NAME byte SSH_FXP_NAME
uint32 request-id uint32 request-id
uint32 count uint32 count
repeats count times: repeats count times:
string filename [UTF-8] string filename [UTF-8]
skipping to change at page 53, line 16 skipping to change at page 53, line 43
A file name being returned (for SSH_FXP_READDIR, it will be a A file name being returned (for SSH_FXP_READDIR, it will be a
relative name within the directory, without any path components; relative name within the directory, without any path components;
for SSH_FXP_REALPATH it will be an absolute path name.) for SSH_FXP_REALPATH it will be an absolute path name.)
attrs attrs
The attributes of the file as described in Section ''File The attributes of the file as described in Section ''File
Attributes''. Attributes''.
end-of-list end-of-list
If this field is present and true, there are no more entries to be 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 9.5. Attrs Response
The SSH_FXP_ATTRS response has the following format: The SSH_FXP_ATTRS response has the following format:
byte SSH_FXP_ATTRS byte SSH_FXP_ATTRS
uint32 request-id uint32 request-id
ATTRS attrs ATTRS attrs
attrs attrs
skipping to change at page 55, line 14 skipping to change at page 55, line 40
Implementations MUST be aware that requests do not have to be Implementations MUST be aware that requests do not have to be
satisfied in the order issued. (See Request Synchronization and satisfied in the order issued. (See Request Synchronization and
Reordering (Section 4.1).) Reordering (Section 4.1).)
Implementations 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. all the requested data, even if the data is available.
12. IANA Considerations 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 packet types define defined in Section 4.3
o The extension specified in this draft, which are: 'text-seek', o The extension specified in this draft, which are: 'text-seek',
'supported2', 'acl-supported', 'newline', 'versions', 'version- 'supported2', 'acl-supported', 'newline', 'versions', 'version-
select', 'filename-charset', 'filename-translation-control' select', 'filename-charset', 'filename-translation-control'
13. Security Considerations 13. Security Considerations
It is assumed that both ends of the connection have been It is assumed that both ends of the connection have been
authenticated and that the connection has privacy and integrity authenticated and that the connection has privacy and integrity
features. Such security issues are left to the underlying transport features. Such security issues are left to the underlying transport
protocol, except to note that if this is not the case, an attacker 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. compromise the server.
This protocol provides file system access to arbitrary files on the This protocol provides file system access to arbitrary files on the
server (constrained only 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 responsibility of the server implementation to enforce any access
controls that may be required to limit the access allowed for any controls that may be required to limit the access allowed for any
particular user (the user being authenticated externally to this 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 Extreme care must be used when interpreting file handle strings. In
particular, care must be taken that a file handle string is valid 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- 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 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 purposes, and the client must not be able to access these files by
specifying an arbitrary file handle string. specifying an arbitrary file handle string.
The permission field of the attrib structure (Section 7.6) may The permission field of the attrib structure (Section 7.6) may
include the SUID, SGID, and SVTX (sticky) bits. Clients should use include the SUID, SGID, and SVTX (sticky) bits. Clients should use
 End of changes. 66 change blocks. 
102 lines changed or deleted 150 lines changed or added

This html diff was produced by rfcdiff 1.32. The latest version is available from http://www.levkowetz.com/ietf/tools/rfcdiff/