draft-ietf-secsh-filexfer-06.txt | draft-ietf-secsh-filexfer-07.txt | |||
---|---|---|---|---|
Secure Shell Working Group J. Galbraith | Secure Shell Working Group J. Galbraith | |||
Internet-Draft VanDyke Software | Internet-Draft VanDyke Software | |||
Expires: April 26, 2005 October 26, 2004 | Expires: September 25, 2005 O. Saarenmaa | |||
F-Secure | ||||
T. Ylonen | ||||
S. Lehtinen | ||||
SSH Communications Security Corp | ||||
March 24, 2005 | ||||
SSH File Transfer Protocol | SSH File Transfer Protocol | |||
draft-ietf-secsh-filexfer-06.txt | draft-ietf-secsh-filexfer-07.txt | |||
Status of this Memo | Status of this Memo | |||
This document is an Internet-Draft and is subject to all provisions | This document is an Internet-Draft and is subject to all provisions | |||
of section 3 of RFC 3667. By submitting this Internet-Draft, each | of Section 3 of RFC 3667. By submitting this Internet-Draft, each | |||
author represents that any applicable patent or other IPR claims of | author represents that any applicable patent or other IPR claims of | |||
which he or she is aware have been or will be disclosed, and any of | which he or she is aware have been or will be disclosed, and any of | |||
which he or she become aware will be disclosed, in accordance with | which he or she become aware will be disclosed, in accordance with | |||
RFC 3668. | RFC 3668. | |||
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 | |||
other groups may also distribute working documents as | other groups may also distribute working documents as | |||
Internet-Drafts. | Internet-Drafts. | |||
skipping to change at page 1, line 34 | skipping to change at page 1, line 40 | |||
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 April 26, 2005. | This Internet-Draft will expire on September 25, 2005. | |||
Copyright Notice | Copyright Notice | |||
Copyright (C) The Internet Society (2004). | Copyright (C) The Internet Society (2005). | |||
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 data stream. It is the standard file | |||
transfer protocol for use with the SSH2 protocol. This document | transfer protocol for use with the SSH2 protocol. This document | |||
describes the file transfer protocol and its interface to the SSH2 | describes the file transfer protocol and its interface to the SSH2 | |||
protocol suite. | protocol suite. | |||
Table of Contents | Table of Contents | |||
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 | 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 | |||
2. Use with the SSH Connection Protocol . . . . . . . . . . . . . 5 | 2. Use with the SSH Connection Protocol . . . . . . . . . . . . . 4 | |||
2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 5 | 2.1 The Use of 'stderr' in the server . . . . . . . . . . . . 4 | |||
3. General Packet Format . . . . . . . . . . . . . . . . . . . . 6 | 3. General Packet Format . . . . . . . . . . . . . . . . . . . . 5 | |||
3.1 Request Synchronization and Reordering . . . . . . . . . . 6 | 3.1 Request Synchronization and Reordering . . . . . . . . . . 6 | |||
3.2 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 | 3.2 New data types defined by this document . . . . . . . . . 6 | |||
4. Protocol Initialization . . . . . . . . . . . . . . . . . . . 9 | 3.3 Packet Types . . . . . . . . . . . . . . . . . . . . . . . 7 | |||
4.1 Client Initialization . . . . . . . . . . . . . . . . . . 9 | 4. Protocol Initialization . . . . . . . . . . . . . . . . . . . 8 | |||
4.2 Server Initialization . . . . . . . . . . . . . . . . . . 9 | 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 | |||
4.3 Determining Server Newline Convention . . . . . . . . . . 10 | 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 8 | |||
4.4 Supported Features . . . . . . . . . . . . . . . . . . . . 11 | 4.3 Determining Server Newline Convention . . . . . . . . . . 9 | |||
4.5 Version re-negotiation . . . . . . . . . . . . . . . . . . 12 | 4.4 Supported Features . . . . . . . . . . . . . . . . . . . . 9 | |||
5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14 | 4.5 Version re-negotiation . . . . . . . . . . . . . . . . . . 11 | |||
6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16 | 5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 11 | |||
6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 16 | 6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 13 | |||
6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 14 | |||
6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 | 6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
6.4 AllocationSize . . . . . . . . . . . . . . . . . . . . . . 18 | 6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 | |||
6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 19 | 6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 16 | |||
6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 19 | 6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 16 | |||
6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20 | 6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 | 6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | |||
6.9 attrib-bits . . . . . . . . . . . . . . . . . . . . . . . 21 | 6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
6.10 Text Hint . . . . . . . . . . . . . . . . . . . . . . . . 24 | 6.9 attrib-bits . . . . . . . . . . . . . . . . . . . . . . . 19 | |||
6.11 Mime type . . . . . . . . . . . . . . . . . . . . . . . . 24 | 6.10 Text Hint . . . . . . . . . . . . . . . . . . . . . . . . 22 | |||
6.12 Link Count . . . . . . . . . . . . . . . . . . . . . . . . 24 | 6.11 Mime type . . . . . . . . . . . . . . . . . . . . . . . . 22 | |||
6.13 Extended Attributes . . . . . . . . . . . . . . . . . . . 24 | 6.12 Link Count . . . . . . . . . . . . . . . . . . . . . . . . 22 | |||
7. Requests From the Client to the Server . . . . . . . . . . . . 26 | 6.13 Extended Attributes . . . . . . . . . . . . . . . . . . . 22 | |||
7.1 Opening and Closing Files and Directories . . . . . . . . 26 | 7. Requests From the Client to the Server . . . . . . . . . . . . 23 | |||
7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 26 | 7.1 Opening and Closing Files and Directories . . . . . . . . 23 | |||
7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 30 | 7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 23 | |||
7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 30 | 7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 28 | |||
7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 31 | 7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 29 | |||
7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 31 | 7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 29 | |||
7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 31 | 7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 29 | |||
7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 32 | 7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 30 | |||
7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 32 | 7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 30 | |||
7.4 Creating and Deleting Directories . . . . . . . . . . . . 34 | 7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 31 | |||
7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 34 | 7.4 Creating and Deleting Directories . . . . . . . . . . . . 32 | |||
7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 35 | 7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 33 | |||
7.7 Dealing with Symbolic Links . . . . . . . . . . . . . . . 36 | 7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 34 | |||
7.8 Canonicalizing the Server-Side Path Name . . . . . . . . . 37 | 7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 35 | |||
7.8 Canonicalizing the Server-Side Path Name . . . . . . . . . 36 | ||||
7.8.1 Best Practice for Dealing with Paths . . . . . . . . . 37 | 7.8.1 Best Practice for Dealing with Paths . . . . . . . . . 37 | |||
8. Responses from the Server to the Client . . . . . . . . . . . 39 | 8. Responses from the Server to the Client . . . . . . . . . . . 38 | |||
9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 44 | 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 44 | |||
9.1 Checking File Contents . . . . . . . . . . . . . . . . . . 45 | 9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 45 | |||
9.2 Querying Available Space . . . . . . . . . . . . . . . . . 46 | 9.1.1 Checking File Contents: v5 extension . . . . . . . . . 46 | |||
10. Implementation Considerations . . . . . . . . . . . . . . . 48 | 9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 47 | |||
11. Security Considerations . . . . . . . . . . . . . . . . . . 49 | 9.2 Querying Available Space . . . . . . . . . . . . . . . . . 48 | |||
12. Changes from Previous Protocol Versions . . . . . . . . . . 51 | 9.3 Querying User Home Directory . . . . . . . . . . . . . . . 49 | |||
12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 51 | 10. Implementation Considerations . . . . . . . . . . . . . . . 50 | |||
12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 51 | 11. Security Considerations . . . . . . . . . . . . . . . . . . 50 | |||
12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 52 | 12. Changes from Previous Protocol Versions . . . . . . . . . . 52 | |||
12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 52 | 12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 52 | |||
12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 52 | 12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 52 | |||
12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 53 | 12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 53 | |||
12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 54 | ||||
12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 54 | ||||
12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 54 | ||||
13. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 54 | 13. Trademark Issues . . . . . . . . . . . . . . . . . . . . . . 54 | |||
14. References . . . . . . . . . . . . . . . . . . . . . . . . . 55 | 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 | |||
14.1 Normative References . . . . . . . . . . . . . . . . . . . . 55 | 14.1 Normative References . . . . . . . . . . . . . . . . . . . 54 | |||
14.2 Informative References . . . . . . . . . . . . . . . . . . . 55 | 14.2 Informative References . . . . . . . . . . . . . . . . . . 55 | |||
Author's Address . . . . . . . . . . . . . . . . . . . . . . . 56 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 55 | |||
Intellectual Property and Copyright Statements . . . . . . . . 57 | Intellectual Property and Copyright Statements . . . . . . . . 57 | |||
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 service. | transfer 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 the SSH2 protocol [1]. and that the server has already | channel in [I-D.ietf-secsh-architecture]. and that the server has | |||
authenticated the client, and that the identity of the client user is | already authenticated the client, and that the identity of the client | |||
available to the protocol. | user is available to the 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 the secsh architecture draft. [1] | notation presented in [I-D.ietf-secsh-architecture]. | |||
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 RFC 2246 [7] 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. Use with the SSH Connection Protocol | 2. 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 from the SSH Connection Protocol [3] as a subsystem, as | be used as a subsystem as described in [I-D.ietf-secsh-connect] in | |||
described in section ''Starting a Shell or a Command''. The | the section "Starting a Shell or a Command". The subsystem name used | |||
subsystem name used with this protocol is "sftp". | with this protocol is "sftp". | |||
2.1 The Use of 'stderr' in the server | 2.1 The Use of 'stderr' in the server | |||
This protocol uses stdout and stdin to transmit binary protocol data. | This protocol uses stdout and stdin to transmit binary protocol data. | |||
The "session" channel SSH Connection Protocol [3], which is used by | The "session" channel ([I-D.ietf-secsh-connect]), which is used by | |||
the subsystem, also supports the use of stderr. | the subsystem, also supports the use of stderr. | |||
Data sent on stderr by the server SHOULD be considered free format | Data sent on stderr by the server SHOULD be considered free format | |||
debug or supplemental error information, and MAY be displayed to the | debug or supplemental error information, and MAY be displayed to the | |||
user. | user. | |||
For example, during initialization, there is no client request | For example, during initialization, there is no client request | |||
active, so errors or warning information cannot be sent to the client | active, so errors or warning information cannot be sent to the client | |||
as part of the SFTP protocol at this early stage. However, the | as part of the SFTP protocol at this early stage. However, the | |||
errors or warnings MAY be sent as stderr text. | errors or warnings MAY be sent as stderr text. | |||
3. General Packet Format | 3. General Packet Format | |||
All packets transmitted over the secure connection are of the | All packets transmitted over the secure connection are of the | |||
following format: | following format: | |||
uint32 length | uint32 length | |||
byte type | byte type | |||
uint32 request-id | uint32 request-id | |||
... type specific fields... | ... type specific fields... | |||
byte[length] data payload | ||||
'length' is the length of the entire packet, excluding the length | 'length' | |||
field itself, such that, for example, for a packet type containing no | The length of the entire packet, excluding the length field | |||
itself, such that, for example, for a packet type containing no | ||||
type specific fields, the length field would be 5, and 9 bytes of | type specific fields, the length field would be 5, and 9 bytes of | |||
data would be sent on the wire. (This is the packet format used in | data would be sent on the wire. (This is the packet format used | |||
the secsh transport. [2] | in [I-D.ietf-secsh-transport].) | |||
All packet descriptions in this document omit the length field for | All packet descriptions in this document omit the length field for | |||
brevity; the length field MUST be included in any case. | brevity; the length field MUST be included in any case. | |||
The maximum size of a packet is in practice determined by the | ||||
client (the maximum size of read or write requests that it sends, | ||||
plus a few bytes of packet overhead). All servers SHOULD support | ||||
packets of at least 34000 bytes (where the packet size refers to | ||||
the full length, including the header above). This should allow | ||||
for reads and writes of at most 32768 bytes. | ||||
'type' | ||||
The type code for the packet. | ||||
'request-id' | ||||
Each request from the client contains a 'request-id' field. Each | Each request from the client contains a 'request-id' field. Each | |||
response from the server includes that same 'request-id' from the | response from the server includes that same 'request-id' from the | |||
request that the server is responding to. One possible | request that the server is responding to. One possible | |||
implementation is for the client to us a monotonically increasing | implementation is for the client to us a monotonically increasing | |||
request sequence number (modulo 2^32). There is, however, no | request sequence number (modulo 2^32). There is, however, no | |||
particular requirement the 'request-id' fields be unique. | particular requirement the 'request-id' fields be unique. | |||
There are two packets, INIT and VERSION, which do not use the | ||||
request-id. | ||||
Packet descriptions in this document will contain the 'request-id' | ||||
field, but will not redefine it. | ||||
Implementations MUST ignore excess data after an otherwise valid | ||||
packet. Implementation MUST respond to unrecognized packet types | ||||
with an SSH_FX_OP_UNSUPPORTED error. This will allow the protocol to | ||||
be extended in a backwards compatible way as needed. | ||||
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 7, line 17 | skipping to change at page 6, line 42 | |||
There are no restrictions on the order in which responses to | There are no restrictions on the order in which responses to | |||
outstanding requests are delivered to the client, except that the | outstanding requests are delivered to the client, except that the | |||
server must ensure fairness in the sense that processing of no | server must ensure fairness in the sense that processing of no | |||
request will be indefinitely delayed even if the client is sending | request will be indefinitely delayed even if the client is sending | |||
other requests so that there are multiple outstanding requests all | other requests so that there are multiple outstanding requests all | |||
the time. | the time. | |||
A client MUST be prepared to recieve responses to multiple overlapped | A client MUST be prepared to recieve responses to multiple overlapped | |||
requests out of order. | requests out of order. | |||
This document defines one data type in addition to those defined in | 3.2 New data types defined by this document | |||
secsh architecture draft. [1] | ||||
This document defines several data types in addition to those defined | ||||
in [I-D.ietf-secsh-architecture]. | ||||
int64 | int64 | |||
Represents a 64-bit signed integer. Stored as eight bytes in the | Represents a 64-bit signed integer. Stored as eight bytes in the | |||
order of decreasing significance (network byte order). | order of decreasing significance (network byte order). | |||
The maximum size of a packet is in practice determined by the client | extension-pair | |||
(the maximum size of read or write requests that it sends, plus a few | ||||
bytes of packet overhead). All servers SHOULD support packets of at | ||||
least 34000 bytes (where the packet size refers to the full length, | ||||
including the header above). This should allow for reads and writes | ||||
of at most 32768 bytes. | ||||
3.2 Packet Types | string extension-name | |||
string extension-data | ||||
The following values are defined for packet types. | 'extension-name' is the name of a protocol extension. Extensions | |||
not defined by IETF consensus MUST follow the the DNS | ||||
extensibility naming convention outlined in | ||||
[I-D.ietf-secsh-architecture]. | ||||
#define SSH_FXP_INIT 1 | 'extension-data' is any data specific to the extension, and MAY be | |||
#define SSH_FXP_VERSION 2 | zero length if the extension has no data. | |||
#define SSH_FXP_OPEN 3 | ||||
#define SSH_FXP_CLOSE 4 | ||||
#define SSH_FXP_READ 5 | ||||
#define SSH_FXP_WRITE 6 | ||||
#define SSH_FXP_LSTAT 7 | ||||
#define SSH_FXP_FSTAT 8 | ||||
#define SSH_FXP_SETSTAT 9 | ||||
#define SSH_FXP_FSETSTAT 10 | ||||
#define SSH_FXP_OPENDIR 11 | ||||
#define SSH_FXP_READDIR 12 | ||||
#define SSH_FXP_REMOVE 13 | ||||
#define SSH_FXP_MKDIR 14 | ||||
#define SSH_FXP_RMDIR 15 | ||||
#define SSH_FXP_REALPATH 16 | ||||
#define SSH_FXP_STAT 17 | ||||
#define SSH_FXP_RENAME 18 | ||||
#define SSH_FXP_READLINK 19 | ||||
#define SSH_FXP_SYMLINK 20 | ||||
#define SSH_FXP_STATUS 101 | 3.3 Packet Types | |||
#define SSH_FXP_HANDLE 102 | ||||
#define SSH_FXP_DATA 103 | ||||
#define SSH_FXP_NAME 104 | ||||
#define SSH_FXP_ATTRS 105 | ||||
#define SSH_FXP_EXTENDED 200 | The following values are defined for packet types. | |||
#define SSH_FXP_EXTENDED_REPLY 201 | ||||
SSH_FXP_INIT 1 | ||||
SSH_FXP_VERSION 2 | ||||
SSH_FXP_OPEN 3 | ||||
SSH_FXP_CLOSE 4 | ||||
SSH_FXP_READ 5 | ||||
SSH_FXP_WRITE 6 | ||||
SSH_FXP_LSTAT 7 | ||||
SSH_FXP_FSTAT 8 | ||||
SSH_FXP_SETSTAT 9 | ||||
SSH_FXP_FSETSTAT 10 | ||||
SSH_FXP_OPENDIR 11 | ||||
SSH_FXP_READDIR 12 | ||||
SSH_FXP_REMOVE 13 | ||||
SSH_FXP_MKDIR 14 | ||||
SSH_FXP_RMDIR 15 | ||||
SSH_FXP_REALPATH 16 | ||||
SSH_FXP_STAT 17 | ||||
SSH_FXP_RENAME 18 | ||||
SSH_FXP_READLINK 19 | ||||
SSH_FXP_LINK 21 | ||||
SSH_FXP_STATUS 101 | ||||
SSH_FXP_HANDLE 102 | ||||
SSH_FXP_DATA 103 | ||||
SSH_FXP_NAME 104 | ||||
SSH_FXP_ATTRS 105 | ||||
SSH_FXP_EXTENDED 200 | ||||
SSH_FXP_EXTENDED_REPLY 201 | ||||
RESERVED_FOR_EXTENSIONS 210-255 | RESERVED_FOR_EXTENSIONS 210-255 | |||
Additional packet types should only be defined if the protocol | Additional packet types should only be defined if the protocol | |||
version number (see Section ''Protocol Initialization'') is | version number (see Section ''Protocol Initialization'') is | |||
incremented, and their use MUST be negotiated using the version | incremented, and their use MUST be negotiated using the version | |||
number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY | number. However, the SSH_FXP_EXTENDED and SSH_FXP_EXTENDED_REPLY | |||
packets can be used to implement extensions, which can be vendor | packets can be used to implement extensions, which can be vendor | |||
specific. See Section ''Extensions'' for more details. | specific. See Section ''Extensions'' for more details. | |||
4. Protocol Initialization | 4. Protocol Initialization | |||
skipping to change at page 9, line 17 | skipping to change at page 8, line 25 | |||
When the file transfer protocol starts, the client first sends a | When the file transfer protocol starts, the client first sends a | |||
SSH_FXP_INIT (including its version number) packet to the server. | SSH_FXP_INIT (including its version number) packet to the server. | |||
The server responds with a SSH_FXP_VERSION packet, supplying the | The server responds with a SSH_FXP_VERSION packet, supplying the | |||
lowest of its own and the client's version number. Both parties | lowest of its own and the client's version number. Both parties | |||
should from then on adhere to particular version of the protocol. | should from then on adhere to particular version of the protocol. | |||
The version number of the protocol specified in this document is 6. | The version number of the protocol specified in this document is 6. | |||
The version number should be incremented for each incompatible | The version number should be incremented for each incompatible | |||
revision of this protocol. | revision of this protocol. | |||
********************* DO NOT IMPLEMENT *********************** | Note that these two packets DO NOT contain a request id. These are | |||
********************* DO NOT IMPLEMENT *********************** | the only such packets in the protocol. | |||
***** ***** | ||||
***** There will be more edits after IETF 61. ***** | ||||
***** ***** | ||||
********************* DO NOT IMPLEMENT *********************** | ||||
********************* DO NOT IMPLEMENT *********************** | ||||
4.1 Client Initialization | 4.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 3 of this protocol allowed clients to include extensions in | 'version' is the version number of the client. If the client wishes | |||
the SSH_FXP_INIT packet; however, this can cause interoperability | to interoperate with servers that support dis-contigous version | |||
problems with version 1 and version 2 servers because the client must | numbers it SHOULD send '3', and then use the 'version-select' | |||
send this packet before knowing the servers version. | extension (see below.) Otherwise, this value is '6' for this version | |||
of the protocol. | ||||
In this version of the protocol, clients MUST use the | ||||
SSH_FXP_EXTENDED packet to send extensions to the server after | ||||
version exchange has completed. Clients MUST NOT include extensions | ||||
in the version packet. This will prevent interoperability problems | ||||
with older servers | ||||
4.2 Server Initialization | 4.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 | |||
<extension data> | extension-pair extensions[0..n] | |||
'version' is the lower of the protocol version supported by the | 'version' is the lower of the protocol version supported by the | |||
server and the version number received from the client. | server and the version number received from the client. | |||
The extension data may be empty, or may be a sequence of | 'extensions' is 0 or more extension-pairs (Section 3.2). | |||
string extension_name | ||||
string extension_data | ||||
pairs (both strings MUST always be present if one is, but the | ||||
'extension_data' string may be of zero length). If present, these | ||||
strings indicate extensions to the baseline protocol. The | ||||
'extension_name' field(s) identify the name of the extension. The | ||||
name should be of the form "name@domain", where the domain is the DNS | ||||
domain name of the organization defining the extension. Additional | ||||
names that are not of this format may be defined later by the IETF. | ||||
Implementations MUST silently ignore any extensions whose name they | Implementations MUST silently ignore any extensions whose name they | |||
do not recognize. | do not recognize. | |||
4.3 Determining Server Newline Convention | 4.3 Determining Server Newline Convention | |||
In order to correctly process text files in a cross platform | In order to correctly process text files in a cross platform | |||
compatible way, newline sequences must be converted between client | compatible way, newline sequences must be converted between client | |||
and server conventions. | and server conventions. | |||
The SSH_FXF_TEXT file open flag (Section 7.1.1) makes it possible to | The SSH_FXF_TEXT file open flag (Section 7.1.1) makes it possible to | |||
request that the server translate a file to a 'canonical' wire | request that the server translate a file to a 'canonical' wire | |||
format. This format uses \r\n as the line separator. | format. This format uses \r\n as the line separator. | |||
Servers for systems using multiple newline characters (for example, | Servers for systems using multiple newline characters (for example, | |||
Mac OS X or VMS) or systems using counted records, MUST translate to | Mac OS X or VMS) or systems using counted records, MUST translate to | |||
the canonical form. | the canonical form. | |||
However, to ease the burden of implementation on servers that use a | However, to ease the burden of implementation on servers that use a | |||
single, simple separator sequence, the following extension allows the | single, simple, separator sequence the following extension allows the | |||
canonical format to be changed. | canonical format to be changed. | |||
string "newline" | string "newline" | |||
string new-canonical-separator (usually "\r" or "\n" or "\r\n") | string new-canonical-separator (usually "\r" or "\n" or "\r\n") | |||
All clients MUST support this extension. | All clients MUST support this extension. | |||
When processing text files, clients SHOULD NOT translate any | When processing text files, clients SHOULD NOT translate any | |||
character or sequence that is not an exact match of the server's | character or sequence that is not an exact match of the server's | |||
newline separator. | newline separator. | |||
skipping to change at page 11, line 15 | skipping to change at page 9, line 50 | |||
4.4 Supported Features | 4.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. In order to facilitate clients being able to use the | specified. In order to facilitate clients being able to use the | |||
maximum available feature set, and yet not be overly burdened by | maximum available feature set, and yet not be overly burdened by | |||
dealing with SSH_FX_OP_UNSUPPORTED status codes, the following | dealing with SSH_FX_OP_UNSUPPORTED status codes, the following | |||
extension is introduced. | extension which all servers MUST include as part of their version | |||
packet, is introduced. | ||||
string "supported" | 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 max-read-size | uint32 max-read-size | |||
string extension-names[0..n] | string extension-names[0..n] | |||
supported-attribute-mask | supported-attribute-mask | |||
This mask MAY by applied to the 'File Attributes' | This mask MAY by applied to the 'File Attributes' | |||
valid-attribute-flags field (Section 6.1) to ensure that no | valid-attribute-flags field (Section 6.1) to ensure that no | |||
unsupported attributes are present during a operation which writes | unsupported attributes are present during a operation which writes | |||
attributes. | attributes. | |||
supported-attribute-bits | supported-attribute-bits | |||
This mask MAY by applied to the 'File Attributes' attrib-bits | This mask MAY by applied to the 'File Attributes' attrib-bits | |||
field (Section 6.9) to ensure that no unsupported attrib-bits are | field (Section 6.9) to ensure that no unsupported attrib-bits are | |||
present during a operation which writes attributes. | present during a operation which writes attributes. | |||
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 to the SSH_FXP_OPEN | |||
(Section 7.1.1) flags field. | (Section 7.1.1) flags field. | |||
supported-access-mask | ||||
The supported-access-mask mask MAY be applied to the SSH_FXP_OPEN | ||||
(Section 7.1.1) desired-access field or the ace-mask field of an | ||||
ACL. | ||||
max-read-size | max-read-size | |||
This is the maximum read size that the server gaurantees to | This is the maximum read size that the server gaurantees to | |||
complete. For example, certain embedded server implementations | complete. For example, certain embedded server implementations | |||
only complete the first 4K of a read, even if there is additional | only complete 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, it MUST return at least | If the server specifies a non-zero value, it MUST return at least | |||
the max-read-size number of bytes for any read requesting | the max-read-size number of bytes for any read requesting | |||
max-read-size bytes. Failure to return max-read-size bytes in | max-read-size bytes. Failure to return max-read-size bytes in | |||
such a case indicates either EOF or another error condition | such a case indicates either EOF or another error condition | |||
skipping to change at page 12, line 34 | skipping to change at page 11, line 15 | |||
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. | |||
4.5 Version re-negotiation | 4.5 Version re-negotiation | |||
The version exchange during protocol startup forces an implementation | If the server supports a higher version than was negotiated, it may | |||
to support all versions up to it's highest supported version; | wish to send the 'versions' extension to inform the client of this | |||
however, there have been a number of SFTP protocol versions deployed, | fact. The client may then optionally choose to use one of the higher | |||
and it is supposed that more implementations will support the final | versions supported. | |||
version of this protocol if they don't have to support all versions | ||||
between their currently deployed version and the final version. | ||||
Furthermore, only the current version of this protocol is documented, | ||||
so supporting earlier versions becomes problematic. | ||||
Therefore, the server SHOULD send the following extension as part of | ||||
it's INIT packet to inform the client of the versions it supports. | ||||
string "versions" | string "versions" | |||
string comma-seperated-versions | string comma-seperated-versions | |||
'comma-seperated-versions' is a string of comma seperated version | 'comma-seperated-versions' is a string of comma seperated version | |||
numbers, for example, "3,6,7" | numbers, for example, "3,6,7. Versions defined by are: "2", "3", | |||
A client wishing to support two non-continigous version of the | "4", "5", "6". Any other version advertised by the server must | |||
protocol must negotiate the lowest version for which it supports all | follow the DNS extensibility naming convention outlined in | |||
previous versions. When the client recieves the servers INIT packet, | [I-D.ietf-secsh-architecture]. | |||
if it includes the "versions" extension, it MAY send the following | ||||
extended request: | ||||
byte SSH_FXP_EXTENDED | The client may select a new version to use from the list the server | |||
uint32 request-id | provided using the following SSH_FXP_EXTENDED request. | |||
string "version" | ||||
string "version-select" | ||||
uint32 version-from-list | uint32 version-from-list | |||
If the 'version-from-list' is one of the versions on the servers | If the 'version-from-list' is one of the versions on the servers | |||
list, the server MUST respond with SSH_FX_OK. If the server did not | list, the server MUST respond with SSH_FX_OK. If the server did not | |||
send the "versions" extension, or the version-from-list was not | send the "versions" extension, or the version-from-list was not | |||
included, the server MAY send a status response describing the | included, the server MAY send a status response describing the | |||
failure, but MUST then close the channel. | failure, but MUST then close the channel without processing any | |||
further requests. | ||||
Although this request does take a full round trip, no client need | Although this request does take a full round trip, no client need | |||
wait for the response before continuing, because any valid request | wait for the response before continuing, because any valid request | |||
MUST succeed. | MUST succeed, and any invalid request results in a channel close. | |||
5. File Names | 5. File Names | |||
This protocol represents file names as strings. File names are | This protocol represents file names as strings. File names are | |||
assumed to use the slash ('/') character as a directory separator. | assumed to use the slash ('/') character as a directory separator. | |||
File names starting with a slash are "absolute", and are relative to | File names starting with a slash are "absolute", and are relative to | |||
the root of the file system. Names starting with any other character | the root of the file system. Names starting with any other character | |||
are relative to the user's default directory (home directory). Note | are relative to the user's default directory (home directory). Note | |||
that identifying the user is assumed to take place outside of this | that identifying the user is assumed to take place outside of this | |||
skipping to change at page 14, line 36 | skipping to change at page 12, line 29 | |||
using a slash ('/') as the separator, and that will work as expected. | using a slash ('/') as the separator, and that will work as expected. | |||
It is understood that the lack of well-defined semantics for file | It is understood that the lack of well-defined semantics for file | |||
names may cause interoperability problems between clients and servers | names may cause interoperability problems between clients and servers | |||
using radically different operating systems. However, this approach | using radically different operating systems. However, this approach | |||
is known to work acceptably with most systems, and alternative | is known to work acceptably with most systems, and alternative | |||
approaches that e.g. treat file names as sequences of structured | approaches that e.g. treat file names as sequences of structured | |||
components are quite complicated. | components are quite complicated. | |||
The prefered encoding for filenames is UTF-8. This is consistant | The prefered encoding for filenames is UTF-8. This is consistant | |||
with IETF Policy on Character Sets and Languages [8] and it is | with IETF Policy on Character Sets and Languages [RFC2277] and it is | |||
further supposed that the server is more likely to support any local | further supposed that the server is more likely to support any local | |||
character set and be able to convert it to UTF-8. | character set and be able to convert it to UTF-8. | |||
The shortest valid UTF-8 encoding of the UNICODE data MUST be used. | ||||
The server is responsible for converting the UNICODE data to whatever | ||||
canonical form it requires. For example, if the server requires that | ||||
precomposed characters always be used, the server MUST NOT assume the | ||||
filename as sent by the client has this attribute, but must do this | ||||
normalization itself. | ||||
However, because the server does not always know the encoding of | However, because the server does not always know the encoding of | |||
filenames, it is not always possible for the server to preform a | filenames, it is not always possible for the server to preform a | |||
valid translation to UTF-8. When an invalid translation to UTF-8 is | valid translation to UTF-8. When an invalid translation to UTF-8 is | |||
preformed, it becomes impossible to manipulate the file, because the | preformed, it becomes impossible to manipulate the file, because the | |||
translation is not reversable. Therefore, the following extensions | translation is not reversable. Therefore, the following extensions | |||
are provided in order to make it possible for the server to | are provided in order to make it possible for the server to | |||
communicate it's abilities to the client, and to allow the client to | communicate it's abilities to the client, and to allow the client to | |||
control whether the server attempts the conversion. | control whether the server attempts the conversion. | |||
A server MAY include the following extension with it's version | A server MAY include the following extension with it's version | |||
packet. | packet. | |||
string "filename-charset" | string "filename-charset" | |||
string charset-name | string charset-name | |||
A server that can always provide a valid UTF-8 translation for | A server that can always provide a valid UTF-8 translation for | |||
filenames SHOULD NOT send this extension. Otherwise, the server | filenames SHOULD NOT send this extension. Otherwise, the server | |||
SHOULD this extension and include the encoding most likely to be used | SHOULD send this extension and include the encoding most likely to be | |||
for filenames. This value will most likely be derived from the | used for filenames. This value will most likely be derived from the | |||
LC_CTYPE on most unix-like systems. | LC_CTYPE on most unix-like systems. | |||
A server that does not send this extension MUST send all filenames | A server that does not send this extension MUST send all filenames | |||
encoded in UTF-8. All clients MUST support UTF-8 filenames. | encoded in UTF-8. All clients MUST support UTF-8 filenames. | |||
If the server included the 'filename-charset' extension with its | If the server included the 'filename-charset' extension with its | |||
VERSION packet, a client MAY send the following extension to turn off | VERSION packet, a client MAY send the following extension to turn off | |||
server translation to UTF-8. | server translation to UTF-8. | |||
string "filename-translation-control" | string "filename-translation-control" | |||
skipping to change at page 16, line 5 | skipping to change at page 13, line 25 | |||
If the client does not send this extension, the server MUST continue | If the client does not send this extension, the server MUST continue | |||
to attempt translation to UTF-8. When a client sends this extension, | to attempt translation to UTF-8. When a client sends this extension, | |||
the server MUST enable or disable filename translation according to | the server MUST enable or disable filename translation according to | |||
the value of 'do-translate' | the value of 'do-translate' | |||
The server MUST respond with a STATUS response; if the server sent a | The server MUST respond with a STATUS response; if the server sent a | |||
'filename-charset' extension, the status MUST be SUCCESS. Otherwise, | 'filename-charset' extension, the status MUST be SUCCESS. Otherwise, | |||
the status MUST be UNSUPPORTED. | the status MUST be UNSUPPORTED. | |||
When UTF-8 is sent, the shortest valid UTF-8 encoding of the UNICODE | ||||
data MUST be used. The server is responsible for converting the | ||||
UNICODE data to whatever canonical form it requires. For example, if | ||||
the server requires that precomposed characters always be used, the | ||||
server MUST NOT assume the filename as sent by the client has this | ||||
attribute, but must do this normalization itself. | ||||
6. File Attributes | 6. File Attributes | |||
A new compound data type is defined for encoding file attributes. | A new compound data type is defined for encoding file attributes. | |||
The same encoding is used both when returning file attributes from | The same encoding is used both when returning file attributes from | |||
the server and when sending file attributes to the server. | the server and when sending file attributes to the server. | |||
uint32 valid-attribute-flags | uint32 valid-attribute-flags | |||
byte type always present | byte type always present | |||
uint64 size present only if flag SIZE | uint64 size if flag SIZE | |||
uint64 allocation-size present only if flag ALLOCATION_SIZE | uint64 allocation-size if flag ALLOCATION_SIZE | |||
string owner present only if flag OWNERGROUP | string owner if flag OWNERGROUP | |||
string group present only if flag OWNERGROUP | string group if flag OWNERGROUP | |||
uint32 permissions present only if flag PERMISSIONS | uint32 permissions if flag PERMISSIONS | |||
int64 atime present only if flag ACCESSTIME | int64 atime if flag ACCESSTIME | |||
uint32 atime_nseconds present only if flag SUBSECOND_TIMES | uint32 atime_nseconds if flag SUBSECOND_TIMES | |||
int64 createtime present only if flag CREATETIME | int64 createtime if flag CREATETIME | |||
uint32 createtime_nseconds present only if flag SUBSECOND_TIMES | uint32 createtime_nseconds if flag SUBSECOND_TIMES | |||
int64 mtime present only if flag MODIFYTIME | int64 mtime if flag MODIFYTIME | |||
uint32 mtime_nseconds present only if flag SUBSECOND_TIMES | uint32 mtime_nseconds if flag SUBSECOND_TIMES | |||
string acl present only if flag ACL | string acl if flag ACL | |||
uint32 attrib-bits present only if flag BITS | uint32 attrib-bits if flag BITS | |||
byte text-hint present only if flag TEXT_HINT | byte text-hint if flag TEXT_HINT | |||
string mime-type present only if flag MIME_TYPE | string mime-type if flag MIME_TYPE | |||
uint32 link-count present only if flag LINK_COUNT | uint32 link-count if flag LINK_COUNT | |||
string untranslated-name present only if flag UNTRANSLATED_NAME | string untranslated-name if flag UNTRANSLATED_NAME | |||
uint32 extended_count present only if flag EXTENDED | uint32 extended_count if flag EXTENDED | |||
string extended_type | extended-pair extensions | |||
string extended_data | ||||
... more extended data (extended_type - extended_data pairs), | ||||
so that number of pairs equals extended_count | ||||
6.1 valid-attribute-flags | 6.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. | |||
skipping to change at page 17, line 4 | skipping to change at page 14, line 43 | |||
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 only be added 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: | |||
#define SSH_FILEXFER_ATTR_SIZE 0x00000001 | SSH_FILEXFER_ATTR_SIZE 0x00000001 | |||
#define SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 | SSH_FILEXFER_ATTR_PERMISSIONS 0x00000004 | |||
#define SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 | SSH_FILEXFER_ATTR_ACCESSTIME 0x00000008 | |||
#define SSH_FILEXFER_ATTR_CREATETIME 0x00000010 | SSH_FILEXFER_ATTR_CREATETIME 0x00000010 | |||
#define SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 | SSH_FILEXFER_ATTR_MODIFYTIME 0x00000020 | |||
#define SSH_FILEXFER_ATTR_ACL 0x00000040 | SSH_FILEXFER_ATTR_ACL 0x00000040 | |||
#define SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 | SSH_FILEXFER_ATTR_OWNERGROUP 0x00000080 | |||
#define SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 | SSH_FILEXFER_ATTR_SUBSECOND_TIMES 0x00000100 | |||
#define SSH_FILEXFER_ATTR_BITS 0x00000200 | SSH_FILEXFER_ATTR_BITS 0x00000200 | |||
#define SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 | SSH_FILEXFER_ATTR_ALLOCATION_SIZE 0x00000400 | |||
#define SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 | SSH_FILEXFER_ATTR_TEXT_HINT 0x00000800 | |||
#define SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 | SSH_FILEXFER_ATTR_MIME_TYPE 0x00001000 | |||
#define SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 | SSH_FILEXFER_ATTR_LINK_COUNT 0x00002000 | |||
#define SSH_FILEXFER_ATTR_UNTRANLATED_NAME 0x00004000 | SSH_FILEXFER_ATTR_UNTRANSLATED_NAME 0x00004000 | |||
#define SSH_FILEXFER_ATTR_EXTENDED 0x80000000 | SSH_FILEXFER_ATTR_EXTENDED 0x80000000 | |||
0x00000002 was used in a previous version of this protocol. It is | 0x00000002 was used in a previous version of this protocol. It is | |||
now a reserved value and MUST NOT appear in the mask. Some future | now a reserved value and MUST NOT appear in the mask. Some future | |||
version of this protocol may reuse this value. | version of this protocol may reuse this value. | |||
6.2 Type | 6.2 Type | |||
The type field is always present. The following types are defined: | The type field is always present. The following types are defined: | |||
#define SSH_FILEXFER_TYPE_REGULAR 1 | SSH_FILEXFER_TYPE_REGULAR 1 | |||
#define SSH_FILEXFER_TYPE_DIRECTORY 2 | SSH_FILEXFER_TYPE_DIRECTORY 2 | |||
#define SSH_FILEXFER_TYPE_SYMLINK 3 | SSH_FILEXFER_TYPE_SYMLINK 3 | |||
#define SSH_FILEXFER_TYPE_SPECIAL 4 | SSH_FILEXFER_TYPE_SPECIAL 4 | |||
#define SSH_FILEXFER_TYPE_UNKNOWN 5 | SSH_FILEXFER_TYPE_UNKNOWN 5 | |||
#define SSH_FILEXFER_TYPE_SOCKET 6 | SSH_FILEXFER_TYPE_SOCKET 6 | |||
#define SSH_FILEXFER_TYPE_CHAR_DEVICE 7 | SSH_FILEXFER_TYPE_CHAR_DEVICE 7 | |||
#define SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 | SSH_FILEXFER_TYPE_BLOCK_DEVICE 8 | |||
#define SSH_FILEXFER_TYPE_FIFO 9 | SSH_FILEXFER_TYPE_FIFO 9 | |||
On a POSIX system, these values would be derived from the mode field | On a POSIX system, these values would be derived from the mode field | |||
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. | |||
6.3 Size | 6.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. If it | the file, or in other words, the location of the end-of-file. This | |||
is present during file creation, the file MUST be created and then | attribute MUST NOT be present during file creation. | |||
the EOF set to 'size'. A read from such a file SHOULD return nul | ||||
bytes, but this is not required if the underlying filesystem has | ||||
different characteristics. | ||||
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. Clients SHOULD | extended or truncated to the specified size. | |||
therefore be careful specifying size during a setstat operation. | ||||
Files opened with the SSH_FXF_TEXT flag may have a size that is | Files opened with the SSH_FXF_ACCESS_TEXT flag may have a size that | |||
greater or less than the value of the size field. | is greater or less than the value of the size field. The server MAY | |||
fail setstat operations specifying size for files opened with the | ||||
SSH_FXF_ACCESS_TEXT flag. | ||||
6.4 AllocationSize | 6.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 is normally greater than or equal to the | file consumes on disk. This is greater than or equal to the 'size' | |||
'size' field. If it is present during file creation, it should be | field. | |||
treated as a hint as to the eventual file size. The server MAY | ||||
choose to preallocate the disk space to save the overhead of repeated | ||||
extends. However, the file size MUST NOT be set to this value. In | ||||
other words, a read from such a file MUST fail with an EOF error. | ||||
(Unless 'size' was also set.) | ||||
If the server is unable to honor this hint during create, the create | When present during file creation, the file SHOULD be created and the | |||
should succeed regardless. Because this field is a hint, the field | specified number of bytes pre-allocated. If the pre-allocation | |||
may be specified even if the server doesn't set the bit in it's | fails, the file should be removed and an error returned. | |||
supported-attribute-mask. | ||||
If this field is present during a setstat operation, the file SHOULD | If this field is present during a setstat operation, the file SHOULD | |||
be extended or truncated to the specified size. Clients SHOULD | be extended or truncated to the specified size. The 'size' of the | |||
therefore be careful specifying size during a setstat operation. | file may be affected by this operation. If the operation succeeds, | |||
it should be the min of the 'size' before the operation and the new | ||||
If the file is extended by this operation, 'size' MUST not be | 'allocation-size'. | |||
affected. If the file is truncated by this operation, 'size' will be | ||||
changed ot match the new file allocation. | ||||
If a server can not honor the setstat operation, it MUST NOT set | Querying the 'allocation-size' after setting it MUST return a value | |||
allocation-size in it's supported-attribute-mask, though it MAY still | that is greater-than or equal to the value set, but it MAY not return | |||
send the allocation-size data if it can retrieve it. In addition, | the precise value set. | |||
such a server MUST fail a setstat operaiton that has the | ||||
allocation-size field present. | ||||
6.5 Owner and Group | 6.5 Owner and Group | |||
The 'owner' and 'group' fields are represented as UTF-8 strings; this | The 'owner' and 'group' fields are represented as UTF-8 strings; this | |||
is the form used by NFS v4. See NFS version 4 Protocol [4]. The | is the form used by NFS v4. See NFS version 4 Protocol [RFC3010]. | |||
following text is selected quotations from section 5.6. | The following text is selected quotations from section 5.6. | |||
To avoid a representation that is tied to a particular underlying | To avoid a representation that is tied to a particular underlying | |||
implementation at the client or server, the use of UTF-8 strings has | implementation at the client or server, the use of UTF-8 strings has | |||
been chosen. The string should be of the form user@dns_domain". | been chosen. The string should be of the form user@dns_domain". | |||
This will allow for a client and server that do not use the same | This will allow for a client and server that do not use the same | |||
local representation the ability to translate to a common syntax that | local representation the ability to translate to a common syntax that | |||
can be interpreted by both. In the case where there is no | can be interpreted by both. In the case where there is no | |||
translation available to the client or server, the attribute value | translation available to the client or server, the attribute value | |||
must be constructed without the "@". Therefore, the absence of the @ | must be constructed without the "@". Therefore, the absence of the @ | |||
from the owner or owner_group attribute signifies that no translation | from the owner or owner_group attribute signifies that no translation | |||
skipping to change at page 19, line 36 | skipping to change at page 17, line 13 | |||
user@localhost represents a user in the context of the server. | user@localhost represents a user in the context of the server. | |||
If either the owner or group field is zero length, the field should | If either the owner or group field is zero length, the field should | |||
be considered absent, and no change should be made to that specific | be considered absent, and no change should be made to that specific | |||
field. | field. | |||
6.6 Permissions | 6.6 Permissions | |||
The 'permissions' field contains a bit mask specifying file | The 'permissions' field contains a bit mask specifying file | |||
permissions. These permissions correspond to the st_mode field of | permissions. These permissions correspond to the st_mode field of | |||
the stat structure defined by POSIX [5]. | the stat structure defined by POSIX [IEEE.1003-1.1996]. | |||
This protocol uses the following values for the symbols declared in | This protocol uses the following values for the symbols declared in | |||
the posix standard. | the posix standard. | |||
#define S_IRUSR 0000400 (octal) | S_IRUSR 0000400 (octal) | |||
#define S_IWUSR 0000200 | S_IWUSR 0000200 | |||
#define S_IXUSR 0000100 | S_IXUSR 0000100 | |||
#define S_IRGRP 0000040 | S_IRGRP 0000040 | |||
#define S_IWGRP 0000020 | S_IWGRP 0000020 | |||
#define S_IXGRP 0000010 | S_IXGRP 0000010 | |||
#define S_IROTH 0000004 | S_IROTH 0000004 | |||
#define S_IWOTH 0000002 | S_IWOTH 0000002 | |||
#define S_IXOTH 0000001 | S_IXOTH 0000001 | |||
#define S_ISUID 0004000 | S_ISUID 0004000 | |||
#define S_ISGID 0002000 | S_ISGID 0002000 | |||
#define S_ISVTX 0001000 | S_ISVTX 0001000 | |||
Implementations MUST NOT send bits that are not defined. | Implementations MUST NOT send bits that are not defined. | |||
The server SHOULD NOT apply a 'umask' to the mode bits; but should | ||||
set the mode bits as specified by the client. The client MUST apply | ||||
an appropriate 'umask' to the mode bits before sending them. | ||||
6.7 Times | 6.7 Times | |||
The 'atime', 'createtime', and 'mtime' contain the accesses, | The 'atime', 'createtime', and 'mtime' contain the access, creation, | |||
creation, and modification times of the files, respectively. They | and modification times of the files, respectively. They are | |||
are represented as seconds from Jan 1, 1970 in UTC. | represented as seconds from Jan 1, 1970 in UTC. | |||
A negative value indicates number of seconds before Jan 1, 1970. In | A negative value indicates number of seconds before Jan 1, 1970. In | |||
both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the | both cases, if the SSH_FILEXFER_ATTR_SUBSECOND_TIMES flag is set, the | |||
nseconds field is to be added to the seconds field for the final time | nseconds field is to be added to the seconds field for the final time | |||
representation. For example, if the time to be represented is | representation. For example, if the time to be represented is | |||
one-half second before 0 hour January 1, 1970, the seconds field | one-half second before 0 hour January 1, 1970, the seconds field | |||
would have a value of negative one (-1) and the nseconds fields would | would have a value of negative one (-1) and the nseconds fields would | |||
have a value of one-half second (500000000). Values greater than | have a value of one-half second (500000000). Values greater than | |||
999,999,999 for nseconds are considered invalid. | 999,999,999 for nseconds are considered invalid. | |||
6.8 ACL | 6.8 ACL | |||
The 'ACL' field contains an ACL similar to that defined in section | The 'ACL' field contains an ACL similar to that defined in section | |||
5.9 of NFS version 4 Protocol [4]. | 5.9 of NFS version 4 Protocol [RFC3010]. | |||
uint32 ace-count | uint32 ace-count | |||
repeated ace-count time: | repeated ace-count time: | |||
uint32 ace-type | uint32 ace-type | |||
uint32 ace-flag | uint32 ace-flag | |||
uint32 ace-mask | uint32 ace-mask | |||
string who [UTF-8] | string who [UTF-8] | |||
ace-type is one of the following four values (taken from NFS Version | ace-type is one of the following four values (taken from NFS Version | |||
4 Protocol [4]: | 4 Protocol [RFC3010]: | |||
#define ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000; | ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 | |||
#define ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001; | ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 | |||
#define ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002; | ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 | |||
#define ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003; | ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 | |||
ace-flag is a combination of the following flag values. See NFS | ace-flag is a combination of the following flag values. See NFS | |||
Version 4 Protocol [4] section 5.9.2: | Version 4 Protocol [RFC3010] section 5.9.2: | |||
ACE4_FILE_INHERIT_ACE 0x00000001 | ||||
ACE4_DIRECTORY_INHERIT_ACE 0x00000002 | ||||
ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004 | ||||
ACE4_INHERIT_ONLY_ACE 0x00000008 | ||||
ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010 | ||||
ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020 | ||||
ACE4_IDENTIFIER_GROUP 0x00000040 | ||||
#define ACE4_FILE_INHERIT_ACE 0x00000001; | ||||
#define ACE4_DIRECTORY_INHERIT_ACE 0x00000002; | ||||
#define ACE4_NO_PROPAGATE_INHERIT_ACE 0x00000004; | ||||
#define ACE4_INHERIT_ONLY_ACE 0x00000008; | ||||
#define ACE4_SUCCESSFUL_ACCESS_ACE_FLAG 0x00000010; | ||||
#define ACE4_FAILED_ACCESS_ACE_FLAG 0x00000020; | ||||
#define ACE4_IDENTIFIER_GROUP 0x00000040; | ||||
ace-mask is any combination of the following flags (taken from NFS | ace-mask is any combination of the following flags (taken from NFS | |||
Version 4 Protocol [4] section 5.9.3: | Version 4 Protocol [RFC3010] section 5.9.3: | |||
#define ACE4_READ_DATA 0x00000001; | ACE4_READ_DATA 0x00000001 | |||
#define ACE4_LIST_DIRECTORY 0x00000001; | ACE4_LIST_DIRECTORY 0x00000001 | |||
#define ACE4_WRITE_DATA 0x00000002; | ACE4_WRITE_DATA 0x00000002 | |||
#define ACE4_ADD_FILE 0x00000002; | ACE4_ADD_FILE 0x00000002 | |||
#define ACE4_APPEND_DATA 0x00000004; | ACE4_APPEND_DATA 0x00000004 | |||
#define ACE4_ADD_SUBDIRECTORY 0x00000004; | ACE4_ADD_SUBDIRECTORY 0x00000004 | |||
#define ACE4_READ_NAMED_ATTRS 0x00000008; | ACE4_READ_NAMED_ATTRS 0x00000008 | |||
#define ACE4_WRITE_NAMED_ATTRS 0x00000010; | ACE4_WRITE_NAMED_ATTRS 0x00000010 | |||
#define ACE4_EXECUTE 0x00000020; | ACE4_EXECUTE 0x00000020 | |||
#define ACE4_DELETE_CHILD 0x00000040; | ACE4_DELETE_CHILD 0x00000040 | |||
#define ACE4_READ_ATTRIBUTES 0x00000080; | ACE4_READ_ATTRIBUTES 0x00000080 | |||
#define ACE4_WRITE_ATTRIBUTES 0x00000100; | ACE4_WRITE_ATTRIBUTES 0x00000100 | |||
#define ACE4_DELETE 0x00010000; | ACE4_DELETE 0x00010000 | |||
#define ACE4_READ_ACL 0x00020000; | ACE4_READ_ACL 0x00020000 | |||
#define ACE4_WRITE_ACL 0x00040000; | ACE4_WRITE_ACL 0x00040000 | |||
#define ACE4_WRITE_OWNER 0x00080000; | ACE4_WRITE_OWNER 0x00080000 | |||
#define ACE4_SYNCHRONIZE 0x00100000; | ACE4_SYNCHRONIZE 0x00100000 | |||
who is a UTF-8 string of the form described in 'Owner and Group' | who is a UTF-8 string of the form described in 'Owner and Group' | |||
(Section 6.5) | (Section 6.5) | |||
Also, as per '5.9.4 ACE who' [4] there are several identifiers that | Also, as per '5.9.4 ACE who' [RFC3010] there are several identifiers | |||
need to be understood universally. Some of these identifiers cannot | that need to be understood universally. Some of these identifiers | |||
be understood when an client access the server, but have meaning when | cannot be understood when an client access the server, but have | |||
a local process accesses the file. The ability to display and modify | meaning when a local process accesses the file. The ability to | |||
these permissions is permitted over SFTP. | display and modify these permissions is permitted over SFTP. | |||
OWNER The owner of the file. | OWNER The owner of the file. | |||
GROUP The group associated with the file. | GROUP The group associated with the file. | |||
EVERYONE The world. | EVERYONE The world. | |||
INTERACTIVE Accessed from an interactive terminal. | INTERACTIVE Accessed from an interactive terminal. | |||
NETWORK Accessed via the network. | NETWORK Accessed via the network. | |||
DIALUP Accessed as a dialup user to the server. | DIALUP Accessed as a dialup user to the server. | |||
BATCH Accessed from a batch job. | BATCH Accessed from a batch job. | |||
ANONYMOUS Accessed without any authentication. | ANONYMOUS Accessed without any authentication. | |||
AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). | AUTHENTICATED Any authenticated user (opposite of ANONYMOUS). | |||
skipping to change at page 22, line 7 | skipping to change at page 20, line 5 | |||
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@. | |||
6.9 attrib-bits | 6.9 attrib-bits | |||
These bits reflect various attributes of the file or directory on the | These bits reflect various attributes of the file or directory on the | |||
server. | server. | |||
The following attrib-bits are defined: | The following attrib-bits are defined: | |||
#define SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 | SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 | |||
#define SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 | SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 | |||
#define SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 | SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 | |||
#define SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 | SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 | |||
#define SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 | SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 | |||
#define SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 | SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 | |||
#define SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 | SSH_FILEXFER_ATTR_FLAGS_COMPRESSED 0x00000040 | |||
#define SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 | SSH_FILEXFER_ATTR_FLAGS_SPARSE 0x00000080 | |||
#define SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 | SSH_FILEXFER_ATTR_FLAGS_APPEND_ONLY 0x00000100 | |||
#define SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 | SSH_FILEXFER_ATTR_FLAGS_IMMUTABLE 0x00000200 | |||
#define SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 | SSH_FILEXFER_ATTR_FLAGS_SYNC 0x00000400 | |||
#define SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 | SSH_FILEXFER_ATTR_FLAGS_TRANSLATION_ERR 0x00000800 | |||
SSH_FILEXFER_ATTR_FLAGS_READONLY | SSH_FILEXFER_ATTR_FLAGS_READONLY | |||
Advisory, read-only bit. This bit is not part of the access | Advisory, read-only bit. This bit is not part of the access | |||
control information on the file, but is rather an advisory field | control information on the file, but is rather an advisory field | |||
indicating that the file should not be written. | indicating that the file should not be written. | |||
SSH_FILEXFER_ATTR_FLAGS_SYSTEM | SSH_FILEXFER_ATTR_FLAGS_SYSTEM | |||
The file is part of operating system. | The file is part of operating system. | |||
SSH_FILEXFER_ATTR_FLAGS_HIDDEN | SSH_FILEXFER_ATTR_FLAGS_HIDDEN | |||
skipping to change at page 24, line 10 | skipping to change at page 22, line 10 | |||
The server MAY include this bit in a directory listing or realpath | The server MAY include this bit in a directory listing or realpath | |||
response. It indicates there was a failure in the translation to | response. It indicates there was a failure in the translation to | |||
UTF-8. If this flag is included, the server SHOULD also include | UTF-8. If this flag is included, the server SHOULD also include | |||
the UNTRANSLATED_NAME attribute. | the UNTRANSLATED_NAME attribute. | |||
6.10 Text Hint | 6.10 Text Hint | |||
The value is one of the following enumerations, and indicates what | The value is one of the following enumerations, and indicates what | |||
the server knows about the content of the file. | the server knows about the content of the file. | |||
#define SSH_FILEXFER_ATTR_KNOWN_TEXT 0x01 | SSH_FILEXFER_ATTR_KNOWN_TEXT 0x00 | |||
#define SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 | SSH_FILEXFER_ATTR_GUESSED_TEXT 0x01 | |||
#define SSH_FILEXFER_ATTR_KNOWN_BINARY 0x01 | SSH_FILEXFER_ATTR_KNOWN_BINARY 0x02 | |||
#define SSH_FILEXFER_ATTR_GUESSED_BINARY 0x01 | SSH_FILEXFER_ATTR_GUESSED_BINARY 0x03 | |||
SSH_FILEXFER_ATTR_KNOWN_TEXT | SSH_FILEXFER_ATTR_KNOWN_TEXT | |||
The server knows the file is a text file, and should be opened | The server knows the file is a text file, and should be opened | |||
using the SSH_FXF_ACCESS_TEXT_MODE flag. | using the SSH_FXF_ACCESS_TEXT_MODE flag. | |||
SSH_FILEXFER_ATTR_GUESSED_TEXT | SSH_FILEXFER_ATTR_GUESSED_TEXT | |||
The server has applied a hueristic or other mechanism and believes | The server has applied a hueristic or other mechanism and believes | |||
that the file should be opened with the SSH_FXF_ACCESS_TEXT_MODE | that the file should be opened with the SSH_FXF_ACCESS_TEXT_MODE | |||
flag. | flag. | |||
skipping to change at page 24, line 39 | skipping to change at page 22, line 39 | |||
has binary content, and should not be opened with the | has binary content, and should not be opened with the | |||
SSH_FXF_ACCESS_TEXT_MODE flag. | SSH_FXF_ACCESS_TEXT_MODE flag. | |||
This flag MUST NOT be present during a setstat operation. If this | This flag MUST NOT be present during a setstat operation. If this | |||
flag is present during an fsetstat operation, the file handle is | flag is present during an fsetstat operation, the file handle is | |||
converted to a text-mode handle, as if it had been opened with | converted to a text-mode handle, as if it had been opened with | |||
SSH_FXF_ACCESS_TEXT_MODE. | SSH_FXF_ACCESS_TEXT_MODE. | |||
6.11 Mime type | 6.11 Mime type | |||
The 'mime-type' field contains the mime-type [9] string. Most | The 'mime-type' field contains the mime-type [RFC1521] string. Most | |||
servers will not know this information and should not set the bit in | servers will not know this information and should not set the bit in | |||
their supported-attribute-mask. | their supported-attribute-mask. | |||
6.12 Link Count | 6.12 Link Count | |||
The 'link-count' field contains the hard link count of the file. | The 'link-count' field contains the hard link count of the file. | |||
This attribute MUST NOT be present during a setstat operation. | This attribute MUST NOT be present during a setstat operation. | |||
6.13 Extended Attributes | 6.13 Extended Attributes | |||
skipping to change at page 26, line 31 | skipping to change at page 23, line 51 | |||
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 | |||
strings. | strings. | |||
The file handle strings MUST NOT be longer than 256 bytes. | The file handle strings MUST NOT be longer than 256 bytes. | |||
7.1.1 Opening a File | 7.1.1 Opening a File | |||
Files are opened and created using the SSH_FXP_OPEN message: | Files are opened and created using the SSH_FXP_OPEN message. | |||
byte SSH_FXP_OPEN | byte SSH_FXP_OPEN | |||
uint32 request-id | uint32 request-id | |||
string filename [UTF-8] | string filename [UTF-8] | |||
uint32 desired-access | uint32 desired-access | |||
uint32 flags | uint32 flags | |||
ATTRS attrs | ATTRS attrs | |||
The response to this message will be either SSH_FXP_HANDLE (if the | The response to this message will be either SSH_FXP_HANDLE (if the | |||
operation is successful) or SSH_FXP_STATUS (if the operation fails). | operation is successful) or SSH_FXP_STATUS (if the operation fails.) | |||
The 'request-id' field is the request identifier as for all requests. | 7.1.1.1 filename | |||
The 'filename' field specifies the file name. See Section ''File | The 'filename' field specifies the file name. See Section ''File | |||
Names'' for more information. | Names'' for more information. If 'filename' is a directory file, the | |||
server MUST return an SSH_FX_FILE_IS_A_DIRECTORY error. | ||||
7.1.1.2 desired-access | ||||
The 'desired-access' field is a bitmask containing a combination of | The 'desired-access' field is a bitmask containing a combination of | |||
values from the ace-mask flags from section 5.7. | values from the ace-mask flags from section 5.7. | |||
The server MUST be prepared to translate the SFTP access flags into | ||||
it's local equivilants. If the server can not grant the access | ||||
desired, it MUST return SSH_FX_PERMISSION_DENIED. | ||||
The server MAY open the file with greater access than requested if | ||||
the user has such access and the server implementation requires it. | ||||
For example, a server that does not distinguish between | ||||
READ_ATTRIBUTE and READ_DATA will have to request full 'read' access | ||||
to the file when the client only requested READ_ATTRIBUTE, resulting | ||||
in greater access than the client originaly requested. | ||||
In such cases, it is possible, and permissable in the protocol, that | ||||
the client could open a file requesting some limitted access, and | ||||
then access the file in a way not permitted by that limitted access | ||||
and the server would permit such action. However, the server MUST | ||||
NOT ever grant access to the file that the client does not actually | ||||
have the rights to. | ||||
7.1.1.3 flags | ||||
The 'flags' field controls various aspects of the operation, | The 'flags' field controls various aspects of the operation, | |||
including whether or not the file is created and the kind of locking | including whether or not the file is created and the kind of locking | |||
desired. | desired. | |||
The following 'flags' are defined: | The following 'flags' are defined: | |||
SSH_FXF_ACCESS_DISPOSITION = 0x00000007 | SSH_FXF_ACCESS_DISPOSITION = 0x00000007 | |||
SSH_FXF_CREATE_NEW = 0x00000000 | SSH_FXF_CREATE_NEW = 0x00000000 | |||
SSH_FXF_CREATE_TRUNCATE = 0x00000001 | SSH_FXF_CREATE_TRUNCATE = 0x00000001 | |||
SSH_FXF_OPEN_EXISTING = 0x00000002 | SSH_FXF_OPEN_EXISTING = 0x00000002 | |||
SSH_FXF_OPEN_OR_CREATE = 0x00000003 | SSH_FXF_OPEN_OR_CREATE = 0x00000003 | |||
SSH_FXF_TRUNCATE_EXISTING = 0x00000004 | SSH_FXF_TRUNCATE_EXISTING = 0x00000004 | |||
SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 | SSH_FXF_ACCESS_APPEND_DATA = 0x00000008 | |||
SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 | SSH_FXF_ACCESS_APPEND_DATA_ATOMIC = 0x00000010 | |||
SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 | SSH_FXF_ACCESS_TEXT_MODE = 0x00000020 | |||
SSH_FXF_ACCESS_READ_LOCK = 0x00000040 | SSH_FXF_ACCESS_READ_LOCK = 0x00000040 | |||
SSH_FXF_ACCESS_WRITE_LOCK = 0x00000080 | SSH_FXF_ACCESS_WRITE_LOCK = 0x00000080 | |||
SSH_FXF_ACCESS_DELETE_LOCK = 0x00000100 | SSH_FXF_ACCESS_DELETE_LOCK = 0x00000100 | |||
SSH_FXF_NOFOLLOW = 0x00000200 | SSH_FXF_ACCESS_NOFOLLOW = 0x00000200 | |||
SSH_FXF_ACCESS_DELETE_ON_CLOSE = 0x00000400 | ||||
SSH_FXF_ACCESS_DISPOSITION | SSH_FXF_ACCESS_DISPOSITION | |||
Disposition is a 3 bit field that controls how the file is opened. | Disposition is a 3 bit field that controls how the file is opened. | |||
The server MUST support these bits. Any one of the following | The server MUST support these bits. Any one of the following | |||
enumeration is allowed: | enumeration is allowed: | |||
SSH_FXF_CREATE_NEW | SSH_FXF_CREATE_NEW | |||
A new file is created; if the file already exists, the server | A new file is created; if the file already exists, the server | |||
MUST return status SSH_FX_FILE_ALREADY_EXISTS. | MUST return status SSH_FX_FILE_ALREADY_EXISTS. | |||
SSH_FXF_CREATE_TRUNCATE | SSH_FXF_CREATE_TRUNCATE | |||
A new file is created; if the file already exists, it is | A new file is created; if the file already exists, it is opened | |||
truncated. | and truncated. | |||
SSH_FXF_OPEN_EXISTING | SSH_FXF_OPEN_EXISTING | |||
An existing file is opened. If the file does not exist, the | An existing file is opened. If the file does not exist, the | |||
server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the | server MUST return SSH_FX_NO_SUCH_FILE. If a directory in the | |||
path does not exist, the server SHOULD return | path does not exist, the server SHOULD return | |||
SSH_FX_NO_SUCH_PATH. It is also acceptable if the server | SSH_FX_NO_SUCH_PATH. It is also acceptable if the server | |||
returns SSH_FX_NO_SUCH_FILE in this case. | returns SSH_FX_NO_SUCH_FILE in this case. | |||
SSH_FXF_OPEN_OR_CREATE | SSH_FXF_OPEN_OR_CREATE | |||
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, | |||
skipping to change at page 29, line 37 | skipping to change at page 27, line 34 | |||
SSH_FXF_ACCESS_WRITE_LOCK | SSH_FXF_ACCESS_WRITE_LOCK | |||
The file should be opened with a write lock. The server MUST | The file should be opened with a write lock. The server MUST | |||
gaurantee that the client will be the exclusive writer of the file | gaurantee that the client will be the exclusive writer of the file | |||
until the client closes the handle. | until the client closes the handle. | |||
SSH_FXF_ACCESS_DELETE_LOCK | SSH_FXF_ACCESS_DELETE_LOCK | |||
The file should be opened with a delete lock. The server MUST | The file should be opened with a delete lock. The server MUST | |||
gaurantee that the file will not be deleted until the client | gaurantee that the file will not be deleted until the client | |||
closes the handle. | closes the handle. | |||
SSH_FXF_NOFOLLOW | SSH_FXF_ACCESS_NOFOLLOW | |||
If the final component of the path is a symlink, then the open | If the final component of the path is a symlink, then the open | |||
MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. | MUST fail, and the error SSH_FX_LINK_LOOP MUST be returned. | |||
SSH_FXF_ACCESS_DELETE_ON_CLOSE | ||||
The file should be deleted when the last handle to it is closed. | ||||
(The last handle may not be an sftp-handle.) This MAY be emulated | ||||
by a server if the OS doesn't support it by deleting the file when | ||||
this handle is closed. | ||||
The 'attrs' field specifies the initial attributes for the file. | The 'attrs' field specifies the initial attributes for the file. | |||
Default values MUST be supplied by the server for those attributes | Default values MUST be supplied by the server for those attributes | |||
that are not specified. See Section ''File Attributes'' for more | that are not specified. See Section ''File Attributes'' for more | |||
information. | information. | |||
The 'attrs' field is ignored if an exiting file is opened. | The 'attrs' field is ignored if an exiting file is opened. | |||
The following table is provided to assist in mapping posix semantics | The following table is provided to assist in mapping posix semantics | |||
to equivalent SFTP file open parameters: | to equivalent SFTP file open parameters: | |||
O_RDONLY | O_RDONLY | |||
desired-access = READ_DATA|READ_ATTRIBUTES | desired-access = READ_DATA|READ_ATTRIBUTES | |||
O_WRONLY | O_WRONLY | |||
desired-access = WRITE_DATA|WRITE_ATTRIBUTES | desired-access = WRITE_DATA|WRITE_ATTRIBUTES | |||
O_RDWR | O_RDWR | |||
desired-access = | desired-access = | |||
READ_DATA|READ_ATTRIBUTES|WRITE_DATA|WRITE_ATTRIBUTES | READ_DATA|READ_ATTRIBUTES|WRITE_DATA|WRITE_ATTRIBUTES | |||
skipping to change at page 30, line 39 | skipping to change at page 28, line 39 | |||
7.1.2 Opening a Directory | 7.1.2 Opening a Directory | |||
To enumerate a directory, the client first obtains a handle and then | To enumerate a directory, the client first obtains a handle and then | |||
issues directory read requests. When enumeration is complete, the | issues directory read requests. When enumeration is complete, the | |||
handle MUST be closed. | handle MUST be closed. | |||
byte SSH_FXP_OPENDIR | byte SSH_FXP_OPENDIR | |||
uint32 request-id | uint32 request-id | |||
string path [UTF-8] | string path [UTF-8] | |||
'request-id' is the request identifier. | path | |||
The 'path' field is the path name of the directory to be listed | ||||
(without any trailing slash). See Section 'File Names' for more | ||||
information on file names. | ||||
'path' is the path name of the directory to be listed (without any | If 'path' does not refer to a directory, the server MUST return | |||
trailing slash). See Section 'File Names' for more information on | SSH_FX_NOT_A_DIRECTORY. | |||
file names. | ||||
The response to this message will be either SSH_FXP_HANDLE (if the | The response to this message will be either SSH_FXP_HANDLE (if the | |||
operation is successful) or SSH_FXP_STATUS (if the operation fails). | operation is successful) or SSH_FXP_STATUS (if the operation fails). | |||
7.1.3 Closing Handles | 7.1.3 Closing Handles | |||
A handle is closed using the following request. | A handle is closed using the following request. | |||
byte SSH_FXP_CLOSE | byte SSH_FXP_CLOSE | |||
uint32 request-id | uint32 request-id | |||
string handle | string handle | |||
'request-id' is the request identifier, and 'handle' is a handle | handle | |||
previously returned in the response to SSH_FXP_OPEN or | 'handle' is a handle previously returned in the response to | |||
SSH_FXP_OPENDIR. The handle becomes invalid immediately after this | SSH_FXP_OPEN or SSH_FXP_OPENDIR. The handle becomes invalid | |||
request has been sent. | immediately after this request has been sent. | |||
The response to this request will be a SSH_FXP_STATUS message. Note | The response to this request will be a SSH_FXP_STATUS message. Note | |||
that on some server platforms even a close can fail. For example, if | that on some server platforms even a close can fail. For example, if | |||
the server operating system caches writes, and an error occurs while | the server operating system caches writes, and an error occurs while | |||
flushing cached writes, the close operation may fail. | flushing cached writes, the close operation may fail. | |||
7.2 Reading and Writing | 7.2 Reading and Writing | |||
7.2.1 Reading Files | 7.2.1 Reading Files | |||
The following request can be used to read file data: | The following request can be used to read file data: | |||
byte SSH_FXP_READ | byte SSH_FXP_READ | |||
uint32 request-id | uint32 request-id | |||
string handle | string handle | |||
uint64 offset | uint64 offset | |||
uint32 length | uint32 length | |||
where 'request-id' is the request identifier, 'handle' is an open | handle | |||
file handle returned by SSH_FXP_OPEN, 'offset' is the offset (in | 'handle' is an open file handle returned by SSH_FXP_OPEN. If | |||
bytes) relative to the beginning of the file from where to start | 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | |||
reading, and 'length' is the maximum number of bytes to read. | return SSH_FX_INVALID_HANDLE. | |||
In response to this request, the server will read as many bytes as it | offset | |||
can from the file (up to 'length'), and return them in a SSH_FXP_DATA | 'offset' is the offset (in bytes) relative to the beginning of the | |||
message. If an error occurs or EOF is encountered before reading any | file that the read MUST start at. 'offset' is ignored if | |||
data, the server will respond with SSH_FXP_STATUS. | SSH_FXF_TEXT was specified during the open. | |||
For normal disk files, it is normally guaranteed that this will read | length | |||
the specified number of bytes, or up to end of file. However, if the | 'length' is the maximum number of bytes to read. | |||
read length is very long, the server may truncate it if it doesn't | ||||
support packets of that length. See General Packet Format (Section | The server MUST not respond with more data than is specified by | |||
3). | the 'length' parameter. However, the server MAY respond with less | |||
data if EOF is reached, an error is encountered, or the servers | ||||
internal buffers can not handle such a large request. | ||||
For normal disk files, it is normally guaranteed that this will | ||||
read the specified number of bytes, or up to end of file. | ||||
If the server specified 'max-read-size' then failure to return | ||||
'length' bytes indicates that EOF or an error occured. | ||||
7.2.2 Reading Directories | 7.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 | |||
string handle | string handle | |||
where 'request-id' is the request identifier, and 'handle' is a | handle | |||
handle returned by SSH_FXP_OPENDIR. (It is a protocol error to | 'handle' is a handle returned by SSH_FXP_OPENDIR. If 'handle' is | |||
attempt to use an ordinary file handle returned by SSH_FXP_OPEN.) | an oridinary file handle returned by SSH_FXP_OPEN, the server MUST | |||
return SSH_FX_INVALID_HANDLE. | ||||
The server responds to this request with either a SSH_FXP_NAME or a | The server responds to this request with either a SSH_FXP_NAME or a | |||
SSH_FXP_STATUS message. One or more names may be returned at a time. | SSH_FXP_STATUS message. One or more names may be returned at a time. | |||
Full status information is returned for each name in order to speed | Full status information is returned for each name in order to speed | |||
up typical directory listings. | up typical directory listings. | |||
If there are no more names available to be read, the server MUST | If there are no more names available to be read, the server MUST | |||
respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. | respond with a SSH_FXP_STATUS message with error code of SSH_FX_EOF. | |||
7.2.3 Writing Files | 7.2.3 Writing Files | |||
Writing to a file is achieved using the following message: | Writing to a file is achieved using the following message: | |||
byte SSH_FXP_WRITE | byte SSH_FXP_WRITE | |||
uint32 request-id | uint32 request-id | |||
string handle | string handle | |||
uint64 offset | uint64 offset | |||
string data | string data | |||
where 'request-id' is a request identifier, 'handle' is a file handle | handle | |||
returned by SSH_FXP_OPEN, 'offset' is the offset (in bytes) from the | 'handle' is an open file handle returned by SSH_FXP_OPEN. If | |||
beginning of the file where to start writing, and 'data' is the data | 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | |||
to be written. | return SSH_FX_INVALID_HANDLE. | |||
The write will extend the file if writing beyond the end of the file. | offset | |||
It is legal to write to an offset that extends beyond the end of the | 'offset' is the offset (in bytes) relative to the beginning of the | |||
file; the semantics are to write zeroes from the end of the file to | file that the write MUST start at. 'offset' is ignored if | |||
the specified offset and then the data. On most operating systems, | SSH_FXF_TEXT was specified during the open. | |||
such writes do not allocate disk space but instead create a sparse | ||||
file. | The write will extend the file if writing beyond the end of the | |||
file. It is legal to write to an offset that extends beyond the | ||||
end of the file; the semantics are to write zeroes from the end of | ||||
the file to the specified offset and then the data. On most | ||||
operating systems, such writes do not allocate disk space but | ||||
instead create a sparse file. | ||||
data | ||||
The data to write to the file. | ||||
The server responds to a write request with a SSH_FXP_STATUS message. | The server responds to a write request with a SSH_FXP_STATUS message. | |||
7.3 Removing and Renaming Files | 7.3 Removing and Renaming Files | |||
The following request can be used to remove a file: | The following request can be used to remove a file: | |||
byte SSH_FXP_REMOVE | byte SSH_FXP_REMOVE | |||
uint32 request-id | uint32 request-id | |||
string filename [UTF-8] | string filename [UTF-8] | |||
where 'request-id' is the request identifier and 'filename' is the | ||||
name of the file to be removed. See Section ''File Names'' for more | filename | |||
information. This request cannot be used to remove directories. | 'filename' is the name of the file to be removed. See Section | |||
'File Names' for more information. | ||||
This request cannot be used to remove directories. The server | ||||
MUST return SSH_FX_FILE_IS_A_DIRECTORY in this case. | ||||
The server will respond to this request with a SSH_FXP_STATUS | The server will respond to this request with a SSH_FXP_STATUS | |||
message. | message. | |||
Files (and directories) can be renamed using the SSH_FXP_RENAME | Files (and directories) can be renamed using the SSH_FXP_RENAME | |||
message. | message. | |||
byte SSH_FXP_RENAME | byte SSH_FXP_RENAME | |||
uint32 request-id | uint32 request-id | |||
string oldpath [UTF-8] | string oldpath [UTF-8] | |||
skipping to change at page 35, line 37 | skipping to change at page 34, line 16 | |||
that it has expressed an interest in. | that it has expressed an interest in. | |||
SSH_FXP_FSTAT differs from the others in that it returns status | SSH_FXP_FSTAT differs from the others in that it returns status | |||
information for an open file (identified by the file handle). | information for an open file (identified by the file handle). | |||
byte SSH_FXP_FSTAT | byte SSH_FXP_FSTAT | |||
uint32 request-id | uint32 request-id | |||
string handle | string handle | |||
uint32 flags | uint32 flags | |||
where 'request-id' is the request identifier and 'handle' is a file | handle | |||
handle returned by SSH_FXP_OPEN. The server responds to this request | 'handle' is an open file handle returned by SSH_FXP_OPEN. If | |||
with SSH_FXP_ATTRS or SSH_FXP_STATUS. | 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | |||
return SSH_FX_INVALID_HANDLE. | ||||
The server responds to this request with SSH_FXP_ATTRS or | ||||
SSH_FXP_STATUS. | ||||
7.6 Setting File Attributes | 7.6 Setting File Attributes | |||
File attributes may be modified using the SSH_FXP_SETSTAT and | File attributes may be modified using the SSH_FXP_SETSTAT and | |||
SSH_FXP_FSETSTAT requests. | SSH_FXP_FSETSTAT requests. | |||
byte SSH_FXP_SETSTAT | byte SSH_FXP_SETSTAT | |||
uint32 request-id | uint32 request-id | |||
string path [UTF-8] | string path [UTF-8] | |||
ATTRS attrs | ATTRS attrs | |||
skipping to change at page 36, line 4 | skipping to change at page 34, line 33 | |||
7.6 Setting File Attributes | 7.6 Setting File Attributes | |||
File attributes may be modified using the SSH_FXP_SETSTAT and | File attributes may be modified using the SSH_FXP_SETSTAT and | |||
SSH_FXP_FSETSTAT requests. | SSH_FXP_FSETSTAT requests. | |||
byte SSH_FXP_SETSTAT | byte SSH_FXP_SETSTAT | |||
uint32 request-id | uint32 request-id | |||
string path [UTF-8] | string path [UTF-8] | |||
ATTRS attrs | ATTRS attrs | |||
byte SSH_FXP_FSETSTAT | byte SSH_FXP_FSETSTAT | |||
uint32 request-id | uint32 request-id | |||
string handle | string handle | |||
ATTRS attrs | ATTRS attrs | |||
request-id | ||||
The request identifier to be returned as part of the response. | ||||
path | path | |||
The file system object (e.g. file or directory) whose attributes | The file system object (e.g. file or directory) whose attributes | |||
are to be modified. If this object does not exist, or the user | are to be modified. If this object does not exist, or the user | |||
does not have sufficient access to write the attributes, the | does not have sufficient access to write the attributes, the | |||
request MUST fail. | request MUST fail. | |||
handle | handle | |||
The handle is a handle previously returned from a SSH_FXP_OPEN | 'handle' is an open file handle returned by SSH_FXP_OPEN. If | |||
request which identifies the file whose attributes are to be | 'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | |||
modified. If the handle was not opened with sufficient access to | return SSH_FX_INVALID_HANDLE. If the handle was not opened with | |||
write the requested attributes, the request MUST fail. | sufficient access to write the requested attributes, the request | |||
MUST fail. | ||||
attrs | attrs | |||
Specifies the modified attributes to be applied. Attributes are | Specifies the modified attributes to be applied. Attributes are | |||
discussed in more detail in Section ''File Attributes''. | discussed in more detail in Section ''File Attributes''. | |||
The server will respond with a SSH_FXP_STATUS message. | The server will respond with a SSH_FXP_STATUS message. | |||
Because some systems must use separate system calls to set various | Because some systems must use separate system calls to set various | |||
attributes, it is possible that a failure response will be returned, | attributes, it is possible that a failure response will be returned, | |||
but yet some of the attributes may be have been successfully | but yet some of the attributes may be have been successfully | |||
modified. If possible, servers SHOULD avoid this situation; however, | modified. If possible, servers SHOULD avoid this situation; however, | |||
client MUST be aware that this is possible. | client MUST be aware that this is possible. | |||
7.7 Dealing with Symbolic Links | 7.7 Dealing with Links | |||
The SSH_FXP_READLINK request reads the target of a symbolic link. | The SSH_FXP_READLINK request reads the target of a symbolic link. | |||
byte SSH_FXP_READLINK | byte SSH_FXP_READLINK | |||
uint32 request-id | uint32 request-id | |||
string path [UTF-8] | string path [UTF-8] | |||
where 'request-id' is the request identifier and 'path' specifies the | where 'request-id' is the request identifier and 'path' specifies the | |||
path name of the symlink to be read. | path name of the symlink to be read. | |||
The server will respond with a SSH_FXP_NAME packet containing only | The server will respond with a SSH_FXP_NAME packet containing only | |||
one name and a dummy attributes value. The name in the returned | one name and a dummy attributes value. The name in the returned | |||
packet contains the target of the link. If an error occurs, the | packet contains the target of the link. If an error occurs, the | |||
server MAY respond with SSH_FXP_STATUS. | server MAY respond with SSH_FXP_STATUS. | |||
The SSH_FXP_SYMLINK request creates a symbolic link on the server. | The SSH_FXP_LINK request creates a symbolic link on the server. | |||
byte SSH_FXP_SYMLINK | byte SSH_FXP_LINK | |||
uint32 request-id | uint32 request-id | |||
string linkpath [UTF-8] | string new-link-path [UTF-8] | |||
string targetpath [UTF-8] | string existing-path [UTF-8] | |||
bool sym-link | ||||
where 'request-id' is the request identifier, 'linkpath' specifies | new-link-path | |||
the path name of the symlink to be created and 'targetpath' specifies | Specifies the path name of the new link to create. | |||
the target of the symlink. The server shall respond with a | ||||
SSH_FXP_STATUS. | existing-path | |||
Specifies the path of an existing file system object to which the | ||||
new-link-path will refer. | ||||
sym-link | ||||
Specifies that the link should be a symbolic link, or a special | ||||
file that redirects file system parsing to the resulting path. It | ||||
is generally possible to create symbolic links across device | ||||
boundaries; however, it is not required that a server support | ||||
this. | ||||
If 'sym-link' is false, the link should be a hard link, or a | ||||
second directory entry refering to the same file or directory | ||||
object. It is generally not possible to create hard links across | ||||
devices. | ||||
The server shall respond with a SSH_FXP_STATUS. Clients should be | ||||
aware that some server may return SSH_FX_OP_UNSUPPORTED for either | ||||
the hard-link, sym-link, or both operations. | ||||
7.8 Canonicalizing the Server-Side Path Name | 7.8 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 | |||
uint32 request-id | uint32 request-id | |||
string path [UTF-8] | string original-path [UTF-8] | |||
string compose-path [optional] | ||||
byte control-byte [optional] | ||||
where 'request-id' is the request identifier and 'path' specifies the | original-path | |||
path name to be canonicalized. The server will respond with a | The first component of the path which the client wishes resolved | |||
SSH_FXP_NAME packet containing the name in canonical form and a dummy | into a absolute canonical path. This may be the entire path. | |||
attributes value. If an error occurs, the server may also respond | ||||
with SSH_FXP_STATUS. | ||||
The server SHOULD fail the request if the path is not present on the | compose-path | |||
server. | A path which the client wishs the server to compose with the | |||
original path to form the new path. This field is optional, and | ||||
if it is not present in the packet, it is assumed to be a zero | ||||
length string. | ||||
control-byte | ||||
SSH_FXP_REALPATH_NO_CHECK 0x00000001 | ||||
SSH_FXP_REALPATH_STAT_IF 0x00000002 | ||||
SSH_FXP_REALPATH_STAT_ALWAYS 0x00000003 | ||||
This field is optional, and if it is not present in the packet, it | ||||
is assumed to be SSH_FXP_REALPATH_NO_CHECK. | ||||
If SSH_FXP_REALPATH_NO_CHECK is specified, the server MUST NOT | ||||
fail the request if the path does not exist, is hidden, or the | ||||
user does not have access to the path or some component thereof. | ||||
However, the path MAY NOT be completely resolved to it's component | ||||
form. For example, symlinks may not be followed in this case. | ||||
The server MAY fail the request if the path is not syntaticly | ||||
valid, or for other reasons. | ||||
If SSH_FXP_REALPATH_STAT_IF is specified, the server MUST stat the | ||||
path if it exists and is accessible to the client. However, if | ||||
the path does not exist, isn't visible, or isn't accessible, the | ||||
server MUST NOT fail the request. If the stat failed, the file | ||||
type will be SSH_FILEXFER_TYPE_UNKNOWN. If the client needs to | ||||
distinguish between files that are actually | ||||
SSH_FILEXFER_TYPE_UNKNOWN and paths that don't exist, it will | ||||
have to issue a seperate stat command in this case. | ||||
If SSH_FXP_REALPATH_STAT_ALWAYS is specified the server MUST stat | ||||
the path. If the stat operation fails, the server MUST fail the | ||||
request. | ||||
The server MUST take the 'original-path' and apply the 'compose-path' | ||||
as a modification to it. 'compose-path' MAY be relative to | ||||
'original-path' or may be an absolute path, in which case | ||||
'original-path' will be discarded. The 'compose-path' may be zero | ||||
length. | ||||
The server will respond with a SSH_FXP_NAME packet containing the | ||||
canonical form of the composite path. If SSH_FXP_REALPATH_NO_CHECK | ||||
is specified, the attributes are dummy values. | ||||
7.8.1 Best Practice for Dealing with Paths | 7.8.1 Best Practice for Dealing with Paths | |||
BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING | ||||
Previous to this version, clients typically composed new paths | ||||
themselves and then called both realpath and stat on the resulting | ||||
path to get it's canonical name and see if it really existed and was | ||||
a directory. | ||||
This required clients to assume certain things about how a relative | ||||
vs. realpath looked. The new realpath allows clients to no longer | ||||
make those assumptions and to remove one round trip from the process | ||||
and get deterministic behavior from all servers. | ||||
END: RFCEDITOR REMOVE BEFORE PUBLISHING | ||||
The client SHOULD treat the results of SSH_FXP_REALPATH as a | The client SHOULD treat the results of SSH_FXP_REALPATH as a | |||
canonical absolute path, even if the path does not appear to be | canonical absolute path, even if the path does not appear to be | |||
absolute. A client that use REALPATH(".") and treats the result as | absolute. A client that use REALPATH(".", "") and treats the result | |||
absolute, even if there is no leading slash, will continue to | as absolute, even if there is no leading slash, will continue to | |||
function correctly, even when talking to a Windows NT or VMS style | function correctly, even when talking to a Windows NT or VMS style | |||
system, where absolute paths may not begin with a slash. | system, where absolute paths may not begin with a slash. | |||
The client SHOULD also use SSH_FXP_REALPATH call to compose paths so | ||||
that it does not need to know when a path is absolute or relative. | ||||
For example, if the client wishes to change directory up, and the | For example, if the client wishes to change directory up, and the | |||
server has returned "c:/x/y/z" from REALPATH, the client SHOULD use | server has returned "c:/x/y/z" from REALPATH, the client SHOULD use | |||
"c:/x/y/z/..". | REALPATH("c:/x/y/z", "..", SSH_FXP_REALPATH_STAT_ALWAYS) | |||
As a second example, if the client wishes to open the file "x.txt" in | As a second example, if the client wishes transfer local file "a" to | |||
the current directory, and server has returned "dka100:/x/y/z" as the | remote file "/b/d/e", and server has returned "dka100:/x/y/z" as the | |||
canonical path of the directory, the client SHOULD open | canonical path of the current directory, the client SHOULD send | |||
"dka100:/x/y/z/x.txt" | REALPATH("dka100:/x/y/z", "/b/d/e", SSH_FXP_REALPATH_STAT_IF). This | |||
call will determine the correct path to use for the open request and | ||||
whether the /b/d/e represents a directory. | ||||
8. Responses from the Server to the Client | 8. Responses from the Server to the Client | |||
The server responds to the client using one of a few response | The server responds to the client using one of a few response | |||
packets. All requests can return a SSH_FXP_STATUS response upon | packets. All requests can return a SSH_FXP_STATUS response upon | |||
failure. When the operation is successful, and no data needs to be | failure. When the operation is successful, and no data needs to be | |||
returned, the SSH_FXP_STATUS response with SSH_FX_OK status is | returned, the SSH_FXP_STATUS response with SSH_FX_OK status is | |||
appropriate. | appropriate. | |||
Exactly one response will be returned for each request. Each | Exactly one response will be returned for each request. Each | |||
skipping to change at page 40, line 7 | skipping to change at page 39, line 24 | |||
Human readable description of the error. 'language tag' specifies | Human readable description of the error. 'language tag' specifies | |||
the language the error is in. | 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 | |||
information about the error. For error codes that send | information about the error. For error codes that send | |||
error-specific data, the format of the data is defined below. | error-specific data, the format of the data is defined below. | |||
Error codes: | Error codes: | |||
#define SSH_FX_OK 0 | SSH_FX_OK 0 | |||
#define SSH_FX_EOF 1 | SSH_FX_EOF 1 | |||
#define SSH_FX_NO_SUCH_FILE 2 | SSH_FX_NO_SUCH_FILE 2 | |||
#define SSH_FX_PERMISSION_DENIED 3 | SSH_FX_PERMISSION_DENIED 3 | |||
#define SSH_FX_FAILURE 4 | SSH_FX_FAILURE 4 | |||
#define SSH_FX_BAD_MESSAGE 5 | SSH_FX_BAD_MESSAGE 5 | |||
#define SSH_FX_NO_CONNECTION 6 | SSH_FX_NO_CONNECTION 6 | |||
#define SSH_FX_CONNECTION_LOST 7 | SSH_FX_CONNECTION_LOST 7 | |||
#define SSH_FX_OP_UNSUPPORTED 8 | SSH_FX_OP_UNSUPPORTED 8 | |||
#define SSH_FX_INVALID_HANDLE 9 | SSH_FX_INVALID_HANDLE 9 | |||
#define SSH_FX_NO_SUCH_PATH 10 | SSH_FX_NO_SUCH_PATH 10 | |||
#define SSH_FX_FILE_ALREADY_EXISTS 11 | SSH_FX_FILE_ALREADY_EXISTS 11 | |||
#define SSH_FX_WRITE_PROTECT 12 | SSH_FX_WRITE_PROTECT 12 | |||
#define SSH_FX_NO_MEDIA 13 | SSH_FX_NO_MEDIA 13 | |||
#define SSH_FX_NO_SPACE_ON_FILESYSTEM 14 | SSH_FX_NO_SPACE_ON_FILESYSTEM 14 | |||
#define SSH_FX_QUOTA_EXCEEDED 15 | SSH_FX_QUOTA_EXCEEDED 15 | |||
#define SSH_FX_UNKNOWN_PRINCIPLE 16 | SSH_FX_UNKNOWN_PRINCIPLE 16 | |||
#define SSH_FX_LOCK_CONFlICT 17 | SSH_FX_LOCK_CONFLICT 17 | |||
#define SSH_FX_DIR_NOT_EMPTY 18 | SSH_FX_DIR_NOT_EMPTY 18 | |||
#define SSH_FX_NOT_A_DIRECTORY 19 | SSH_FX_NOT_A_DIRECTORY 19 | |||
#define SSH_FX_INVALID_FILENAME 20 | SSH_FX_INVALID_FILENAME 20 | |||
#define SSH_FX_LINK_LOOP 21 | SSH_FX_LINK_LOOP 21 | |||
SSH_FX_CANNOT_DELETE 22 | ||||
SSH_FX_INVALID_PARAMETER 23 | ||||
SSH_FX_FILE_IS_A_DIRECTORY 24 | ||||
SSH_FX_BYTE_RANGE_LOCK_CONFLICT 25 | ||||
SSH_FX_BYTE_RANGE_LOCK_REFUSED 26 | ||||
SSH_FX_DELETE_PENDING 27 | ||||
SSH_FX_FILE_CORRUPT 28 | ||||
SSH_FX_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 42, line 31 | skipping to change at page 42, line 5 | |||
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. | |||
SSH_FX_CANNOT_DELETE | ||||
The file cannot be deleted. One possible reason is that the | ||||
advisory READONLY attribute-bit is set. | ||||
SSH_FX_INVALID_PARAMETER | ||||
On of the parameters was out of range, or the parameters specified | ||||
cannot be used together. | ||||
SSH_FX_FILE_IS_A_DIRECTORY | ||||
The specifed file was a directory in a context where a directory | ||||
cannot be used. | ||||
SSH_FX_BYTE_RANGE_LOCK_CONFLICT | ||||
A read or write operation failed because another process owns a | ||||
byte range lock that conflicts. | ||||
SSH_FX_BYTE_RANGE_LOCK_REFUSED | ||||
A request for a byte range lock was refused. | ||||
SSH_FX_DELETE_PENDING | ||||
An operation was attempted on a file for which a delete operation | ||||
is pending. | ||||
SSH_FX_FILE_CORRUPT | ||||
The file is corrupt; an filesystem integrity check should be run. | ||||
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 | |||
where 'request-id' is the request identifier, and 'handle' is an | 'handle' | |||
arbitrary string that identifies an open file or directory on the | An arbitrary string that identifies an open file or directory on | |||
server. The handle is opaque to the client; the client MUST NOT | the server. The handle is opaque to the client; the client MUST | |||
attempt to interpret or modify it in any way. The length of the | NOT attempt to interpret or modify it in any way. The length of | |||
handle string MUST NOT exceed 256 data bytes. | the handle string MUST NOT exceed 256 data bytes. | |||
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] | ||||
data | ||||
'data' is an arbitrary byte string containing the requested data. | ||||
The data string may be at most the number of bytes requested in a | ||||
SSH_FXP_READ request, but may also be shorter. (See | ||||
Section 7.2.1.) | ||||
where 'request-id' is the request identifier, and 'data' is an | end-of-file | |||
arbitrary byte string containing the requested data. The data string | This field is optional. If it is present in the packet, it MUST | |||
may be at most the number of bytes requested in a SSH_FXP_READ | be true, and it indicates that EOF was reached during this read. | |||
request, but may also be shorter if end of file is reached or if the | This can help the client avoid a round trip to determine whether a | |||
read is from something other than a regular file. | short read was normal (due to EOF) or some other problem (limitted | |||
server buffer for example.) | ||||
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] | |||
ATTRS attrs | ATTRS attrs | |||
bool end-of-list [optional] | ||||
where 'request-id' is the request identifier, 'count' is the number | count | |||
of names returned in this response, and the remaining fields repeat | The number of names returned in this response, and the remaining | |||
'count' times. In the repeated part, 'filename' is a file name being | fields repeat 'count' times. | |||
returned (for SSH_FXP_READDIR, it will be a relative name within the | ||||
directory, without any path components; for SSH_FXP_REALPATH it will | filename | |||
be an absolute path name), and 'attrs' is the attributes of the file | A file name being returned (for SSH_FXP_READDIR, it will be a | |||
as described in Section ''File Attributes''. | relative name within the directory, without any path components; | |||
for SSH_FXP_REALPATH it will be an absolute path name.) | ||||
attrs | ||||
The attributes of the file as described in Section ''File | ||||
Attributes''. | ||||
end-of-list | ||||
This field is optional. If present in the packet, it MUST be | ||||
true, and indicates that there are no more entries to be read. | ||||
This can save the client a round trip to determine if there are | ||||
more entries to be read. | ||||
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 | |||
where 'request-id' is the request identifier, and 'attrs' is the | where 'request-id' is the request identifier, and 'attrs' is the | |||
returned file attributes as described in Section ''File Attributes''. | returned file attributes as described in Section ''File Attributes''. | |||
skipping to change at page 45, line 11 | skipping to change at page 45, line 18 | |||
The suggested way of doing this is have an extension request from the | The suggested way of doing this is have an extension request from the | |||
client to the server that enables the extension; the extension | client to the server that enables the extension; the extension | |||
response from the server to the client would specify the actual type | response from the server to the client would specify the actual type | |||
values to use, in additional to any other data. | values to use, in additional to any other data. | |||
Extension authors should be mindful of the limited range of packet | Extension authors should be mindful of the limited range of packet | |||
types available (there are only 45 values available) and avoid | types available (there are only 45 values available) and avoid | |||
requiring a new packet type where possible. | requiring a new packet type where possible. | |||
9.1 Checking File Contents | 9.1 File Hashing | |||
BEGIN: RFCEDITOR REMOVE BEFORE PUBLISHING | ||||
After some discussion of this at connectathon, I know of two uses for | ||||
this feature, neither one of which the feature is entirely suited | ||||
for: | ||||
o Checking that a file has been uploaded to the server correctly; | ||||
some portion of the customers wanting this feature want it in a | ||||
security sense, as part of proof the server has the file. | ||||
o Optimizing upload or download of the file; multiple hashes are | ||||
performed on small pieces of the file and the results are used to | ||||
determine what chunks of the file, if any, need to be transfered. | ||||
This is similar to the way rsync works. | ||||
I've seen both of these implemented. | ||||
For the first case, the extension has several drawbacks, including: | ||||
o A FIPS implementation can't ship md5. | ||||
o MD5's security is potential weaker than other options. | ||||
o Being hard-coded to MD5 makes in impossible to adapt to future | ||||
developments in the arena of MD5 compromises. | ||||
For the second case, the extension has these drawbacks: | ||||
o MD5 is expensive (relative to other options.) | ||||
o The extension must be sent potentially thousands of times to | ||||
retrieve the desired granularity of hashes. | ||||
Therefore, for this draft, this section is marked experimental; I've | ||||
included a second proposed extension. Please post your thoughts on | ||||
the mailing list. (I did it this way just so I could get a draft out | ||||
that I and my active co-author are happy with. | ||||
In addition, implemenation experience has shown the quick check hash | ||||
to not be useful. | ||||
END: RFCEDITOR REMOVE BEFORE PUBLISHING | ||||
9.1.1 Checking File Contents: v5 extension | ||||
This extension allows a client to easily check if a file (or portion | This extension allows a client to easily check if a file (or portion | |||
thereof) that it already has matches what is on the server. | thereof) that it already has matches what is on the server. | |||
byte SSH_FXP_EXTENDED | byte SSH_FXP_EXTENDED | |||
uint32 request-id | uint32 request-id | |||
string "md5-hash" / "md5-hash-handle" | string "md5-hash" / "md5-hash-handle" | |||
string filename / file-handle | string filename [UTF-8] / file-handle | |||
uint64 start-offset | uint64 start-offset | |||
uint64 length | uint64 length | |||
string quick-check-hash | string quick-check-hash | |||
filename | filename | |||
Used if "md5-hash" is specified; indicates the name of the file to | Used if "md5-hash" is specified; indicates the name of the file to | |||
use. The has will be of the file contents as it would appear on | use. The hash will be of the file contents as it would appear on | |||
the wire if the file were opened with no special flags. | the wire if the file were opened with no special flags. | |||
file-handle | file-handle | |||
Used if "md5-hash-handle" is specified; specifies a file handle to | Used if "md5-hash-handle" is specified; specifies a file handle to | |||
read the data from. The handle MUST be a file handle, and | read the data from. The handle MUST be a file handle, and | |||
ACE4_READ_DATA MUST have been included in the desired-access when | ACE4_READ_DATA MUST have been included in the desired-access when | |||
the file was opened. | the file was opened. | |||
If this file handle was opened in TEXT mode, the md5-hash must be | If this file handle was opened in TEXT mode, the md5-hash must be | |||
made of the data as it would be sent on the wire. | made of the data as it would be sent on the wire. | |||
skipping to change at page 46, line 23 | skipping to change at page 47, line 18 | |||
byte SSH_FXP_EXTENDED_REPLY | byte SSH_FXP_EXTENDED_REPLY | |||
uint32 request-id | uint32 request-id | |||
string "md5-hash" | string "md5-hash" | |||
string hash | string hash | |||
If 'hash' is zero length, then the 'quick-check-hash' did not match, | If 'hash' is zero length, then the 'quick-check-hash' did not match, | |||
and no hash operation was preformed. Otherwise, 'hash' contains the | and no hash operation was preformed. Otherwise, 'hash' contains the | |||
hash of the entire data range (including the first 2048 bytes that | hash of the entire data range (including the first 2048 bytes that | |||
were included in the 'quick-check-hash'.) | were included in the 'quick-check-hash'.) | |||
9.1.2 Checking File Contents | ||||
This extension allows a client to easily check if a file (or portion | ||||
thereof) that it already has matches what is on the server. | ||||
byte SSH_FXP_EXTENDED | ||||
uint32 request-id | ||||
string "check-file" | ||||
string handle | ||||
string hash-algorithm-list | ||||
uint64 start-offset | ||||
uint64 length | ||||
uint32 block-size | ||||
handle | ||||
'handle' is an open file handle returned by SSH_FXP_OPEN. If | ||||
'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | ||||
return SSH_FX_INVALID_HANDLE. If ACE4_READ_DATA MUST was not | ||||
included when the file was opened, the server MUST return | ||||
STATUS_PERMISSION_DENIED. | ||||
If this file handle was opened in TEXT mode, the check must be | ||||
performed on the data as it would be sent on the wire. | ||||
hash-algorithm-list | ||||
A comma seperated list of hash alogirthms the client is willing to | ||||
accept for this operation. The server MUST pick the first hash on | ||||
the list that it supports. | ||||
Currently supported algorithms are "md5", "sha1", "sha224", | ||||
"sha256", "sha384", "sha512", and "crc32". Additional algorithms | ||||
may be added by following the DNS extensibility naming convention | ||||
outlined in [I-D.ietf-secsh-architecture]. | ||||
MD5 is described in [RFC1321]. SHA-1, SHA-224, SHA-256, SHA-384, | ||||
and SHA-512 are decribed in [FIPS-180-2]. crc32 is described in | ||||
[ISO.3309.1991], and is the same algorithm used in [RFC1510] | ||||
start-offset | ||||
The starting offset of the data to include in the hash. | ||||
length | ||||
The length of data to include in the hash. If length is zero, all | ||||
the data from start-offset to the end-of-file should be included. | ||||
block-size | ||||
An independant hash MUST be computed over ever block in the file. | ||||
The size of blocks is specified by block-size. The block-size | ||||
MUST NOT be smaller than 256 bytes. If the block-size is 0, then | ||||
only one hash, over the entire range MUST be made. | ||||
The response is either a SSH_FXP_STATUS packet, indicating an error, | ||||
or the following extended reply packet: | ||||
byte SSH_FXP_EXTENDED_REPLY | ||||
uint32 request-id | ||||
string "check-file" | ||||
string hash-algo-used | ||||
byte hash[n][block-count] | ||||
hash-algo-used | ||||
The hash algorithm that was actually used. | ||||
hash | ||||
The computed hashes. The hash algorithm used determines the size | ||||
of n. The number of block-size chunks of data in the file | ||||
determines block-count. The hashes are placed in the packet one | ||||
after another, with no decoration. | ||||
Note that if the length of the range is not an even multiple of | ||||
block-size, the last hash will have been computer over only the | ||||
remainder of the range instead of a full block. | ||||
9.2 Querying Available Space | 9.2 Querying Available Space | |||
The following extension provides a way to discover the available | The following extension provides a way to discover the available | |||
space for an arbitrary path. | space for an arbitrary path. | |||
byte SSH_FXP_EXTENDED | byte SSH_FXP_EXTENDED | |||
uint32 request-id | uint32 request-id | |||
string "space-available" | string "space-available" | |||
string path [UTF-8] | string path [UTF-8] | |||
path | path | |||
'path' for which the available space should be reported. This | 'path' for which the available space should be reported. This | |||
'path' is not required to be the mount point path, but MAY be a | 'path' is not required to be the mount point path, but MAY be a | |||
directory or file contained within the mount. | directory or file contained within the mount. | |||
The reply to the request is as follows: | ||||
byte SSH_FXP_EXTENDED_REPLY | byte SSH_FXP_EXTENDED_REPLY | |||
uint32 request-id | uint32 request-id | |||
uint64 total-space-on-device | uint64 bytes-on-device | |||
uint64 unused-on-device | uint64 unused-bytes-on-device | |||
uint64 total-space-available-to-user | uint64 bytes-available-to-user | |||
uint64 unused-space-available-to-user | uint64 unused-bytes-available-to-user | |||
uint32 bytes-per-allocation-unit | ||||
total-space-on-device | bytes-on-device | |||
The total amount of storage space on the device which stores | The total number of bytes on the device which stores 'path', both | |||
'path', both used and unused, or 0 if unknown. | used and unused, or 0 if unknown. | |||
unused-space-on-device | unused-bytes-on-device | |||
The total amount of unused storage availabe on the device which | The total number of unused bytes availabe on the device which | |||
stores 'path', or 0 if unknown. | stores 'path', or 0 if unknown. | |||
total-space-available-to-user | bytes-available-to-user | |||
The total amount of storage space, both used and unused, available | The total number of bytes, both used and unused, available to the | |||
to the authenticated user on the device which stores 'path', or 0 | authenticated user on the device which stores 'path', or 0 if | |||
if unknown. | unknown. | |||
unused-space-on-device | unused-bytes-available-to-user | |||
The total amount of unused storage available to the authenticated | The total number of unused bytes available to the authenticated | |||
user on the device which stores 'path', or 0 if unknown. | user on the device which stores 'path', or 0 if unknown. | |||
bytes-per-allocation-unit | ||||
The number of bytes in each allocation unit on the device, or in | ||||
other words, the minimum number of bytes that a file allocation | ||||
size can grow or shrink by. If the server does not know this | ||||
information, or the file-system in use does not use allocation | ||||
block, this value MUST be 0. | ||||
9.3 Querying User Home Directory | ||||
Many users are used to being able to type '~' as an alias for their | ||||
home directory, or ~username as an alias for another user's home | ||||
directory. To support this feature, a server MAY support following | ||||
extension. | ||||
byte SSH_FXP_EXTENDED | ||||
uint32 request-id | ||||
string "home-directory" | ||||
string username [UTF-8] | ||||
username | ||||
Username whose home directory path is being requested. An empty | ||||
string implies the current user. | ||||
The reply to the request is either a SSH_FXP_STATUS packet or the | ||||
following extended reply: | ||||
byte SSH_FXP_EXTENDED_REPLY | ||||
uint32 request-id | ||||
string "home-directory" | ||||
string absolute-pathname | ||||
absolute-pathname | ||||
Absolute pathname of the specified user's home directory. | ||||
10. Implementation Considerations | 10. Implementation Considerations | |||
In order for this protocol to perform well, especially over high | In order for this protocol to perform well, especially over high | |||
latency networks, multiple read and write requests should be queued | latency networks, multiple read and write requests should be queued | |||
to the server. | to the server. | |||
The data size of requests should match the maximum packet size for | The data size of requests should match the maximum packet size for | |||
the next layer up in the protocol chain. | the next layer up in the protocol chain. | |||
When implemented over ssh, the best performance should be achieved | When implemented over ssh, the best performance should be achieved | |||
skipping to change at page 49, line 19 | skipping to change at page 51, line 11 | |||
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 | could manipulate files on the server at will 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 (only constrained by the server implementation). It is the | server (only constrained 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 the SSH User Authentication Protocol [6]. | protocol, typically using [I-D.ietf-secsh-userauth]. | |||
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 SFTP session. For example, the sftp server | the context of a given 'file-share' session. For example, the | |||
daemon may have files which it has opened for its own purposes, and | 'file-share' server daemon may have files which it has opened for its | |||
the client must not be able to access these files by specifying an | own purposes, and the client must not be able to access these files | |||
arbitrary file handle string. | by specifying an arbitrary file handle string. | |||
The permission field of the attrib structure (Section 6.6) may | The permission field of the attrib structure (Section 6.6) may | |||
include the SUID, SGID, and SVTX (sticky) bits. Clients should use | include the SUID, SGID, and SVTX (sticky) bits. Clients should use | |||
extreme caution when setting these bits on either remote or local | extreme caution when setting these bits on either remote or local | |||
files. (I.e., just because a file was SUID on the remote system does | files. (I.e., just because a file was SUID on the remote system does | |||
not necessarily imply that it should be SUID on the local system.) | not necessarily imply that it should be SUID on the local system.) | |||
Filesystems often contain entries for objects that are not files at | Filesystems often contain entries for objects that are not files at | |||
all, but are rather devices. For example, it may be possible to | all, but are rather devices. For example, it may be possible to | |||
access serial ports, tape devices, or named pipes using this | access serial ports, tape devices, or named pipes using this | |||
skipping to change at page 51, line 12 | skipping to change at page 52, line 13 | |||
been numerous reported security bugs where a ".." in a path name has | been numerous reported security bugs where a ".." in a path name has | |||
allowed access outside the intended area. | allowed access outside the intended area. | |||
12. Changes from Previous Protocol Versions | 12. Changes from Previous Protocol Versions | |||
The SSH File Transfer Protocol has changed over time, before its | The SSH File Transfer Protocol has changed over time, before its | |||
standardization. The following is a description of the incompatible | standardization. The following is a description of the incompatible | |||
changes between different versions. | changes between different versions. | |||
12.1 Changes Between Versions 6 and 5 | 12.1 Changes Between Versions 6 and 5 | |||
********************* DO NOT IMPLEMENT *********************** | ||||
********************* DO NOT IMPLEMENT *********************** | ||||
***** ***** | ||||
***** There will be more edits after IETF 61. ***** | ||||
***** ***** | ||||
********************* DO NOT IMPLEMENT *********************** | ||||
********************* DO NOT IMPLEMENT *********************** | ||||
o Add ability to negotiate version when client supports discontigous | o Add ability to negotiate version when client supports discontigous | |||
ranges of protocol version. | ranges of protocol version. | |||
o Add 'filename-charset' and the 'filename-translation-control' | o Add 'filename-charset' and the 'filename-translation-control' | |||
extensions to allow better support of servers that can't reliably | extensions to allow better support of servers that can't reliably | |||
translate to UTF-8. | translate to UTF-8. | |||
o Add DIR_NOT_EMPTY, NOT_A_DIRECTORY, INVALID_FILENAME and LINK_LOOP | o Add DIR_NOT_EMPTY, NOT_A_DIRECTORY, INVALID_FILENAME LINK_LOOP, | |||
error codes. | CANNOT_DELETE, INVALID_PARAMETER, FILE_IS_A_DIRECTORY, | |||
BYTE_RANGE_LOCK_CONFLICT, BYTE_RANGE_LOCK_REFUSED, DELETE_PENDING, | ||||
and FILE_CORRUPT error codes. | ||||
o Added space-available extension. | o Added space-available extension. | |||
o Added NOFOLLOW flag to open flags. | o Added NOFOLLOW and DELETE_ON_CLOSE flag to open flags. | |||
o Added allocation-size, text-hint, link-count, mime-type, and | o Added allocation-size, text-hint, link-count, mime-type, and | |||
untranslated-name fields to attrib structure. Add | untranslated-name fields to attrib structure. Add | |||
ATTR_FLAGS_TRANSLATION_ERR to the attrib-bits. | ATTR_FLAGS_TRANSLATION_ERR to the attrib-bits. | |||
o Add optional 'compose-path' and 'control-byte' to REALPATH; make | ||||
realpath's behaviour truly deterministic (i.e., MUST instead of | ||||
SHOULD.) Give clients the ability to compose path's without | ||||
understanding what is relative and what is absolute. | ||||
o Give SSH_FXP_DATA and SSH_FXP_NAME optional end-of-data-set flags, | ||||
which can help the client avoid a round trip during normal | ||||
operation. | ||||
o Changed the SYMLINK packet to be LINK and give it the ability to | ||||
create hard links. Also change it's packet number because many | ||||
implementation implemented SYMLINK with the arguments reversed. | ||||
Hopefully the new argument names make it clear which way is which. | ||||
o Clarify who should apply umask to posix mode bits (the client, not | ||||
the server.) | ||||
o Specify behavior for otherwise valid packets with excess data and | ||||
unrecognized packet types. | ||||
o Add home directory extension. | ||||
o Remove "#define" from symbol definitions to shorten line and help | ||||
us pass idnits. | ||||
12.2 Changes Between Versions 5 and 4 | 12.2 Changes Between Versions 5 and 4 | |||
Many of the changes between version 5 and version 4 are to better | Many of the changes between version 5 and version 4 are to better | |||
support the changes in version 4, and to better specify error | support the changes in version 4, and to better specify error | |||
conditions. | conditions. | |||
o Add "supported" extension to communicate features supported. | o Add "supported" extension to communicate features supported. | |||
o Clarify error handling when client requests unsupported feature. | o Clarify error handling when client requests unsupported feature. | |||
(For example, attempts to write an unsupported attribute.) | (For example, attempts to write an unsupported attribute.) | |||
skipping to change at page 55, line 9 | skipping to change at page 54, line 32 | |||
13. Trademark Issues | 13. Trademark Issues | |||
"ssh" is a registered trademark of SSH Communications Security Corp | "ssh" is a registered trademark of SSH Communications Security Corp | |||
in the United States and/or other countries. | in the United States and/or other countries. | |||
14. References | 14. References | |||
14.1 Normative References | 14.1 Normative References | |||
[1] Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", | [RFC1321] Rivest, R., "The MD5 Message-Digest Algorithm", RFC 1321, | |||
draft-ietf-secsh-architecture-16 (work in progress), June 2004. | April 1992. | |||
[2] Ylonen, T. and C. Lonvick, "SSH Transport Layer Protocol", | [RFC1510] Kohl, J. and B. Neuman, "The Kerberos Network | |||
draft-ietf-secsh-transport-18 (work in progress), June 2004. | Authentication Service (V5)", RFC 1510, September 1993. | |||
[3] Ylonen, T., Kivinen, T., Rinne, T. and S. Lehtinen, "SSH | [RFC3010] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., | |||
Connection Protocol", draft-ietf-secsh-connect-19 (work in | Beame, C., Eisler, M. and D. Noveck, "NFS version 4 | |||
progress), June 2004. | Protocol", RFC 3010, December 2000. | |||
[4] Shepler, S., Callaghan, B., Robinson, D., Thurlow, R., Beame, | [I-D.ietf-secsh-architecture] | |||
C., Eisler, M. and D. Noveck, "NFS version 4 Protocol", RFC | Lonvick, C., "SSH Protocol Architecture", | |||
3010, December 2000. | Internet-Draft draft-ietf-secsh-architecture-22, March | |||
2005. | ||||
[5] Institute of Electrical and Electronics Engineers, "Information | [I-D.ietf-secsh-transport] | |||
Technology - Portable Operating System Interface (POSIX) - Part | Lonvick, C., "SSH Transport Layer Protocol", | |||
1: System Application Program Interface (API) [C Language]", | Internet-Draft draft-ietf-secsh-transport-24, March 2005. | |||
IEEE Standard 1003.2, 1996. | ||||
[I-D.ietf-secsh-connect] | ||||
Lonvick, C., "SSH Connection Protocol", | ||||
Internet-Draft draft-ietf-secsh-connect-25, March 2005. | ||||
[IEEE.1003-1.1996] | ||||
Institute of Electrical and Electronics Engineers, | ||||
"Information Technology - Portable Operating System | ||||
Interface (POSIX) - Part 1: System Application Program | ||||
Interface (API) [C Language]", IEEE Standard 1003.2, 1996. | ||||
[FIPS-180-2] | ||||
National Institute of Standards and Technology, "Secure | ||||
Hash Standard (SHS)", Federal Information Processing | ||||
Standards Publication 180-2, August 2002. | ||||
[ISO.3309.1991] | ||||
International Organization for Standardization, | ||||
"Information Technology - Telecommunications and | ||||
information exchange between systems - High-level data | ||||
link control (HDLC) procedures - Frame structure", | ||||
ISO Standard 3309, June 1991. | ||||
14.2 Informative References | 14.2 Informative References | |||
[6] Ylonen, T. and C. Lonvick, "SSH Authentication Protocol", | [RFC1521] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet | |||
draft-ietf-secsh-userauth-21 (work in progress), June 2004. | Mail Extensions) Part One: Mechanisms for Specifying and | |||
Describing the Format of Internet Message Bodies", | ||||
RFC 1521, September 1993. | ||||
[7] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC | [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", | |||
2246, January 1999. | RFC 2246, January 1999. | |||
[8] Alvestrand, H., "IETF Policy on Character Sets and Languages", | [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and | |||
BCP 18, RFC 2277, January 1998. | Languages", BCP 18, RFC 2277, January 1998. | |||
[9] Borenstein, N. and N. Freed, "MIME (Multipurpose Internet Mail | [I-D.ietf-secsh-userauth] | |||
Extensions) Part One: Mechanisms for Specifying and Describing | Lonvick, C., "SSH Authentication Protocol", | |||
the Format of Internet Message Bodies", RFC 1521, September | Internet-Draft draft-ietf-secsh-userauth-27, March 2005. | |||
1993. | ||||
Author's Address | Authors' Addresses | |||
Joseph Galbraith | Joseph Galbraith | |||
VanDyke Software | VanDyke Software | |||
4848 Tramway Ridge Blvd | 4848 Tramway Ridge Blvd | |||
Suite 101 | Suite 101 | |||
Albuquerque, NM 87111 | Albuquerque, NM 87111 | |||
US | US | |||
Phone: +1 505 332 5700 | Phone: +1 505 332 5700 | |||
EMail: galb-list@vandyke.com | Email: galb-list@vandyke.com | |||
Oskari Saarenmaa | ||||
F-Secure | ||||
Tammasaarenkatu 7 | ||||
Helsinki 00180 | ||||
FI | ||||
Email: oskari.saarenmaa@f-secure.com | ||||
Tatu Ylonen | ||||
SSH Communications Security Corp | ||||
Fredrikinkatu 42 | ||||
HELSINKI FIN-00100 | ||||
Finland | ||||
Email: ylo@ssh.com | ||||
Sami Lehtinen | ||||
SSH Communications Security Corp | ||||
Fredrikinkatu 42 | ||||
HELSINKI FIN-00100 | ||||
Finland | ||||
Email: sjl@ssh.com | ||||
Trademark notice | ||||
"ssh" is a registered trademark in the United States and/or other | ||||
countries. | ||||
Intellectual Property Statement | Intellectual Property Statement | |||
The IETF takes no position regarding the validity or scope of any | The IETF takes no position regarding the validity or scope of any | |||
Intellectual Property Rights or other rights that might be claimed to | Intellectual Property Rights or other rights that might be claimed to | |||
pertain to the implementation or use of the technology described in | pertain to the implementation or use of the technology described in | |||
this document or the extent to which any license under such rights | this document or the extent to which any license under such rights | |||
might or might not be available; nor does it represent that it has | might or might not be available; nor does it represent that it has | |||
made any independent effort to identify any such rights. Information | made any independent effort to identify any such rights. Information | |||
on the procedures with respect to rights in RFC documents can be | on the procedures with respect to rights in RFC documents can be | |||
skipping to change at page 57, line 41 | skipping to change at page 57, line 41 | |||
This document and the information contained herein are provided on an | This document and the information contained herein are provided on an | |||
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS | "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS | |||
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET | OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET | |||
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, | ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, | |||
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE | INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE | |||
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED | INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED | |||
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. | WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. | |||
Copyright Statement | Copyright Statement | |||
Copyright (C) The Internet Society (2004). This document is subject | Copyright (C) The Internet Society (2005). This document is subject | |||
to the rights, licenses and restrictions contained in BCP 78, and | to the rights, licenses and restrictions contained in BCP 78, and | |||
except as set forth therein, the authors retain all their rights. | except as set forth therein, the authors retain all their rights. | |||
Acknowledgment | Acknowledgment | |||
Funding for the RFC Editor function is currently provided by the | Funding for the RFC Editor function is currently provided by the | |||
Internet Society. | Internet Society. | |||
End of changes. | ||||
This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/ |