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