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/ |