draft-ietf-secsh-filexfer-08.txt | draft-ietf-secsh-filexfer-09.txt | |||
---|---|---|---|---|
Secure Shell Working Group J. Galbraith | Secure Shell Working Group J. Galbraith | |||
Internet-Draft VanDyke Software | Internet-Draft VanDyke Software | |||
Expires: October 7, 2005 O. Saarenmaa | Expires: December 12, 2005 O. Saarenmaa | |||
F-Secure | F-Secure | |||
T. Ylonen | T. Ylonen | |||
S. Lehtinen | S. Lehtinen | |||
SSH Communications Security Corp | SSH Communications Security Corp | |||
April 5, 2005 | June 10, 2005 | |||
SSH File Transfer Protocol | SSH File Transfer Protocol | |||
draft-ietf-secsh-filexfer-08.txt | draft-ietf-secsh-filexfer-09.txt | |||
Status of this Memo | Status of this Memo | |||
This document is an Internet-Draft and is subject to all provisions | By submitting this Internet-Draft, each author represents that any | |||
of Section 3 of RFC 3667. By submitting this Internet-Draft, each | applicable patent or other IPR claims of which he or she is aware | |||
author represents that any applicable patent or other IPR claims of | have been or will be disclosed, and any of which he or she becomes | |||
which he or she is aware have been or will be disclosed, and any of | aware will be disclosed, in accordance with Section 6 of BCP 79. | |||
which he or she become aware will be disclosed, in accordance with | ||||
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 Internet- | other groups may also distribute working documents as 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 October 7, 2005. | This Internet-Draft will expire on December 12, 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 17 | skipping to change at page 2, line 15 | |||
Table of Contents | Table of Contents | |||
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 . . . . . . . . . . . . . . . . . . . 9 | |||
4.1 Client Initialization . . . . . . . . . . . . . . . . . . 8 | 4.1 Client Initialization . . . . . . . . . . . . . . . . . . 9 | |||
4.2 Server Initialization . . . . . . . . . . . . . . . . . . 9 | 4.2 Server Initialization . . . . . . . . . . . . . . . . . . 9 | |||
4.3 Determining Server Newline Convention . . . . . . . . . . 9 | 4.3 Determining Server Newline Convention . . . . . . . . . . 10 | |||
4.4 Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . 9 | 4.4 Vendor Id . . . . . . . . . . . . . . . . . . . . . . . . 10 | |||
4.5 Supported Features . . . . . . . . . . . . . . . . . . . . 10 | 4.5 Supported Features . . . . . . . . . . . . . . . . . . . . 11 | |||
4.6 Version re-negotiation . . . . . . . . . . . . . . . . . . 12 | 4.6 Version re-negotiation . . . . . . . . . . . . . . . . . . 13 | |||
5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 13 | 5. File Names . . . . . . . . . . . . . . . . . . . . . . . . . . 14 | |||
6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 15 | 6. File Attributes . . . . . . . . . . . . . . . . . . . . . . . 16 | |||
6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 16 | 6.1 valid-attribute-flags . . . . . . . . . . . . . . . . . . 17 | |||
6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 6.2 Type . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 | 6.3 Size . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 | |||
6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 18 | 6.4 allocation-size . . . . . . . . . . . . . . . . . . . . . 19 | |||
6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 18 | 6.5 Owner and Group . . . . . . . . . . . . . . . . . . . . . 19 | |||
6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 19 | 6.6 Permissions . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 19 | 6.7 Times . . . . . . . . . . . . . . . . . . . . . . . . . . 20 | |||
6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 | 6.8 ACL . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 | |||
6.9 attrib-bits and attrib-bits-valid . . . . . . . . . . . . 21 | 6.9 attrib-bits and attrib-bits-valid . . . . . . . . . . . . 23 | |||
6.10 text-hint . . . . . . . . . . . . . . . . . . . . . . . . 24 | 6.10 text-hint . . . . . . . . . . . . . . . . . . . . . . . . 25 | |||
6.11 mime-type . . . . . . . . . . . . . . . . . . . . . . . . 24 | 6.11 mime-type . . . . . . . . . . . . . . . . . . . . . . . . 26 | |||
6.12 link-count . . . . . . . . . . . . . . . . . . . . . . . . 24 | 6.12 link-count . . . . . . . . . . . . . . . . . . . . . . . . 26 | |||
6.13 untranslated-name . . . . . . . . . . . . . . . . . . . . 25 | 6.13 untranslated-name . . . . . . . . . . . . . . . . . . . . 26 | |||
6.14 Extended Attributes . . . . . . . . . . . . . . . . . . . 25 | 6.14 Extended Attributes . . . . . . . . . . . . . . . . . . . 26 | |||
7. Requests From the Client to the Server . . . . . . . . . . . . 25 | 7. Requests From the Client to the Server . . . . . . . . . . . . 26 | |||
7.1 Opening and Closing Files and Directories . . . . . . . . 25 | 7.1 Opening and Closing Files and Directories . . . . . . . . 27 | |||
7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 26 | 7.1.1 Opening a File . . . . . . . . . . . . . . . . . . . . 27 | |||
7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 31 | 7.1.2 Opening a Directory . . . . . . . . . . . . . . . . . 32 | |||
7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 32 | 7.1.3 Closing Handles . . . . . . . . . . . . . . . . . . . 33 | |||
7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 32 | 7.2 Reading and Writing . . . . . . . . . . . . . . . . . . . 33 | |||
7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 32 | 7.2.1 Reading Files . . . . . . . . . . . . . . . . . . . . 33 | |||
7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 33 | 7.2.2 Reading Directories . . . . . . . . . . . . . . . . . 34 | |||
7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 33 | 7.2.3 Writing Files . . . . . . . . . . . . . . . . . . . . 35 | |||
7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 34 | 7.3 Removing and Renaming Files . . . . . . . . . . . . . . . 35 | |||
7.4 Creating and Deleting Directories . . . . . . . . . . . . 35 | 7.4 Creating and Deleting Directories . . . . . . . . . . . . 37 | |||
7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 36 | 7.5 Retrieving File Attributes . . . . . . . . . . . . . . . . 37 | |||
7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 37 | 7.6 Setting File Attributes . . . . . . . . . . . . . . . . . 38 | |||
7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 38 | 7.7 Dealing with Links . . . . . . . . . . . . . . . . . . . . 39 | |||
7.8 Canonicalizing the Server-Side Path Name . . . . . . . . . 40 | 7.8 Byte-range locks . . . . . . . . . . . . . . . . . . . . . 40 | |||
7.8.1 Best Practice for Dealing with Paths . . . . . . . . . 42 | 7.9 Canonicalizing the Server-Side Path Name . . . . . . . . . 42 | |||
8. Responses from the Server to the Client . . . . . . . . . . . 42 | 7.9.1 Best Practice for Dealing with Paths . . . . . . . . . 43 | |||
8.1 Status Response . . . . . . . . . . . . . . . . . . . . . 43 | 8. Responses from the Server to the Client . . . . . . . . . . . 44 | |||
8.2 Handle Response . . . . . . . . . . . . . . . . . . . . . 47 | 8.1 Status Response . . . . . . . . . . . . . . . . . . . . . 44 | |||
8.3 Data Response . . . . . . . . . . . . . . . . . . . . . . 47 | 8.2 Handle Response . . . . . . . . . . . . . . . . . . . . . 49 | |||
8.4 Name Response . . . . . . . . . . . . . . . . . . . . . . 48 | 8.3 Data Response . . . . . . . . . . . . . . . . . . . . . . 49 | |||
8.5 Attrs Response . . . . . . . . . . . . . . . . . . . . . . 49 | 8.4 Name Response . . . . . . . . . . . . . . . . . . . . . . 50 | |||
9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 49 | 8.5 Attrs Response . . . . . . . . . . . . . . . . . . . . . . 50 | |||
9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 50 | 9. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 51 | |||
9.1.1 Checking File Contents: v5 extension . . . . . . . . . 51 | 9.1 File Hashing . . . . . . . . . . . . . . . . . . . . . . . 52 | |||
9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 52 | 9.1.1 Checking File Contents: v5 extension . . . . . . . . . 53 | |||
9.2 Querying Available Space . . . . . . . . . . . . . . . . . 54 | 9.1.2 Checking File Contents . . . . . . . . . . . . . . . . 54 | |||
9.3 Querying User Home Directory . . . . . . . . . . . . . . . 55 | 9.2 Querying Available Space . . . . . . . . . . . . . . . . . 56 | |||
10. Implementation Considerations . . . . . . . . . . . . . . . 55 | 9.3 Querying User Home Directory . . . . . . . . . . . . . . . 57 | |||
11. Security Considerations . . . . . . . . . . . . . . . . . . 56 | 10. Implementation Considerations . . . . . . . . . . . . . . . 57 | |||
12. Changes from Previous Protocol Versions . . . . . . . . . . 57 | 11. Security Considerations . . . . . . . . . . . . . . . . . . 58 | |||
12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 57 | 12. Changes from Previous Protocol Versions . . . . . . . . . . 59 | |||
12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 58 | 12.1 Changes Between Versions 6 and 5 . . . . . . . . . . . . . 59 | |||
12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 59 | 12.2 Changes Between Versions 5 and 4 . . . . . . . . . . . . . 60 | |||
12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 59 | 12.3 Changes Between Versions 4 and 3 . . . . . . . . . . . . . 61 | |||
12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 59 | 12.4 Changes Between Versions 3 and 2 . . . . . . . . . . . . . 61 | |||
12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 59 | 12.5 Changes Between Versions 2 and 1 . . . . . . . . . . . . . 61 | |||
13. References . . . . . . . . . . . . . . . . . . . . . . . . . 60 | 12.6 Changes Between Versions 1 and 0 . . . . . . . . . . . . . 61 | |||
13.1 Normative References . . . . . . . . . . . . . . . . . . . 60 | 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 | |||
13.2 Informative References . . . . . . . . . . . . . . . . . . 61 | 13.1 Normative References . . . . . . . . . . . . . . . . . . . 62 | |||
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 61 | 13.2 Informative References . . . . . . . . . . . . . . . . . . 63 | |||
Intellectual Property and Copyright Statements . . . . . . . . 63 | Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . 63 | |||
Intellectual Property and Copyright Statements . . . . . . . . 65 | ||||
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 | |||
already authenticated the client, and that the identity of the client | already authenticated the client, and that the identity of the client | |||
user is available to the protocol. | user is available to the protocol. | |||
In general, this protocol follows a simple request-response model. | In general, this protocol follows a simple request-response model. | |||
Each request and response contains a sequence number and multiple | Each request and response contains a sequence number and multiple | |||
requests may be pending simultaneously. There are a relatively large | requests may be pending simultaneously. There are a relatively large | |||
number of different request messages, but a small number of possible | number of different request messages, but a small number of possible | |||
response messages. Each request has one or more response messages | response messages. Each request has one or more response messages | |||
that may be returned in result (e.g., a read either returns data or | that may be returned in result (e.g., a read either returns data or | |||
reports error status). | reports error status). | |||
skipping to change at page 6, line 47 | skipping to change at page 6, line 47 | |||
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 these 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 | uint16 | |||
Represents a 64-bit signed integer. Stored as eight bytes in the | Represents a 16-bit unsigned integer. Stored as 2 bytes in the | |||
order of decreasing significance (network byte order). | order of decreasing significance (network byte order). | |||
int64 | ||||
Represents a 64-bit signed integer. Stored using two's | ||||
complement, as eight bytes in the 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 [I-D.ietf-secsh- | extensibility naming convention outlined in [I-D.ietf-secsh- | |||
architecture]. | architecture]. | |||
skipping to change at page 8, line 17 | skipping to change at page 8, line 48 | |||
implement extensions, which can be vendor specific. See Section | implement extensions, which can be vendor specific. See Section | |||
''Extensions'' for more details. | ''Extensions'' for more details. | |||
Values 210-255 are reserved for use in conjunction with these | Values 210-255 are reserved for use in conjunction with these | |||
extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the | extensions. The SSH_FXP_EXTENDED packet can be used to negotiate the | |||
meaning of these reserved types. It is suggested that the actual | meaning of these reserved types. It is suggested that the actual | |||
value to be used also be negotiated, since this will prevent | value to be used also be negotiated, since this will prevent | |||
collision among multiple uncoordinated extensions. | collision among multiple uncoordinated extensions. | |||
The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if | The server MUST respond with SSH_FXP_STATUS(SSH_FX_OP_UNSUPPORTED) if | |||
it receives a packet it does not recognize. The protocol version | it receives a packet it does not recognize. | |||
(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 | The use of additional packet types in the non-extension range MUST be | |||
that the packet isn't recognized.) | introduced through IETF consensus. New packet types to be sent from | |||
the client to the server MAY be introduced without changing the | ||||
protocol version (Section 4). Because the client has no way to | ||||
respond to unrecognized packet types, new packet types to be sent | ||||
from the server to the client the client MUST not used unless the | ||||
protocol version is changed or the client has negotiated to received | ||||
them. This negotiation MAY be explicit, through the use of | ||||
extensions, or MAY be implicit, by the client itself using a packet | ||||
type not defined above. | ||||
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 that particular version of the | should from then on adhere to that particular version of the | |||
protocol. | protocol. | |||
skipping to change at page 9, line 26 | skipping to change at page 10, line 15 | |||
'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 names 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_ACCESS_TEXT_MODE file open flag (Section 7.1.1) makes it | |||
request that the server translate a file to a 'canonical' wire | possible to request that the server translate a file to a 'canonical' | |||
format. This format uses CRLF as the line separator. | wire format. This format uses CRLF as the line separator. | |||
Servers for systems using other conventions MUST translate to and | Servers for systems using other conventions MUST translate to and | |||
from the canonical form. | from 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 CR or LF or CRLF) | string new-canonical-separator (usually CR or LF or CRLF) | |||
skipping to change at page 9, line 52 | skipping to change at page 10, line 41 | |||
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 | |||
CRLF sequence, a lone CR or a lone LF SHOULD be written through | CRLF sequence, a lone CR or a lone LF SHOULD be written through | |||
without change. | without change. | |||
4.4 Vendor Id | 4.4 Vendor Id | |||
It is often necessary to detect the version of a the server so that | It is often necessary to detect the version of the server so that | |||
bugs can be worked around. This extension allows the client to do | 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. | so. (It may also be sent by the client using an EXTENDED request.) | |||
string "vendor-id" | string "vendor-id" | |||
string vendor-structure | string vendor-structure | |||
string vendor-name | string vendor-name | |||
string product-name | string product-name | |||
string product-version | string product-version | |||
uint64 product-build-number | uint64 product-build-number | |||
vendor-name | vendor-name | |||
Arbitrary name identifying the maker of the product. | Arbitrary name identifying the maker of the product. | |||
product-name | product-name | |||
Arbitrary name identifying the product. | Arbitrary name identifying the product. | |||
product-name | product-name | |||
Arbitrary string identifying the version of the product. | Arbitrary string identifying the version of the product. | |||
product-build-number | product-build-number | |||
skipping to change at page 10, line 45 | skipping to change at page 11, line 35 | |||
specified. The following extension facilitates clients being able to | specified. The following extension facilitates clients being able to | |||
use the maximum available feature set, and yet not be overly burdened | use the maximum available feature set, and yet not be overly burdened | |||
by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST | by dealing with SSH_FX_OP_UNSUPPORTED status codes. All servers MUST | |||
include as part of their version packet. | include as part of their version packet. | |||
string "supported2" | string "supported2" | |||
string supported-structure | string supported-structure | |||
uint32 supported-attribute-mask | uint32 supported-attribute-mask | |||
uint32 supported-attribute-bits | uint32 supported-attribute-bits | |||
uint32 supported-open-flags | uint32 supported-open-flags | |||
uint32 supported-access-mask | ||||
uint32 max-read-size | uint32 max-read-size | |||
uint64 supported-open-block-masks | uint16 supported-open-block-masks | |||
uint64 supported-block-masks | uint16 supported-block-masks | |||
uint32 attrib-extension-count | uint32 attrib-extension-count | |||
string attrib-extension-names[attrib_extension-count] | string attrib-extension-names[attrib_extension-count] | |||
uint32 extension-count | uint32 extension-count | |||
string extension-names[extension-count] | string extension-names[extension-count] | |||
Note that the name "supported2" is used here to avoid conflict with | Note that the name "supported2" is used here to avoid conflict with | |||
the slightly different "supported" extension that was previously | the slightly different "supported" extension that was previously | |||
used. | used. | |||
supported-attribute-mask | supported-attribute-mask | |||
This mask MAY by applied to the 'File Attributes' valid-attribute- | This mask MAY by applied to the 'File Attributes' valid-attribute- | |||
flags field (Section 6.1) to ensure that no unsupported attributes | flags field (Section 6.1) to ensure that no unsupported attributes | |||
are present during a operation which writes attributes. | are present during a operation which writes attributes. | |||
supported-attribute-bits | supported-attribute-bits | |||
This mask MAY by applied to the 'File Attributes' attrib-bits | This mask MAY 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. | |||
skipping to change at page 11, line 23 | skipping to change at page 12, line 19 | |||
supported-attribute-bits | supported-attribute-bits | |||
This mask MAY by applied to the 'File Attributes' attrib-bits | This mask MAY by applied to the 'File Attributes' attrib-bits | |||
field (Section 6.9) to ensure that no unsupported attrib-bits are | field (Section 6.9) to ensure that no unsupported attrib-bits are | |||
present during a operation which writes attributes. | present during a operation which writes attributes. | |||
supported-open-flags | supported-open-flags | |||
The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN | The supported-open-flags mask MAY be applied to the SSH_FXP_OPEN | |||
(Section 7.1.1) flags field. | (Section 7.1.1) flags field. | |||
supported-access-mask | ||||
This mask may be applied to the ace-mask field of an ACL. | ||||
This mask SHOULD NOT be applied to the desired-access field of the | ||||
SSH_FXP_OPEN (Section 7.1.1) request. Doing so will simply result | ||||
in not requesting the access required by the client. In this | ||||
case, the server is responible for translating the clients | ||||
requested access to a mode it supports that is sufficient to grant | ||||
all access requested by the client. | ||||
max-read-size | max-read-size | |||
This is the maximum read size that the server guarantees to | This is the maximum read size that the server guarantees to | |||
complete. For example, certain embedded server implementations | complete. For example, certain embedded server implementations | |||
complete only the first 4K of a read, even if there is additional | complete only the first 4K of a read, even if there is additional | |||
data to be read from the file. | data to be read from the file. | |||
If the server specifies a non-zero value for max-read-size, it | If the server specifies a non-zero value for max-read-size, it | |||
MUST return the requested number of bytes for reads that are less | MUST return the requested number of bytes for reads that are less | |||
than or equal to the value, unless it encounters EOF or an ERROR. | than or equal to the value, unless it encounters EOF or an ERROR. | |||
The server MAY use this value to express that it is willing to | The server MAY use this value to express that it is willing to | |||
handle very large read requests, in excess of the standard 34000 | handle very large read requests, in excess of the standard 34000 | |||
bytes specfied in Section 3. | bytes specfied in Section 3. | |||
supported-open-block-masks | supported-open-block-masks | |||
Series of four-bit fields representing the support combinations of | supported-block-masks | |||
16-bit masks specifying which combinations of blocking flags are | ||||
supported. Each bit corresponds to one combination of the | ||||
SSH_FXF_ACCESS_BLOCK_READ, SSH_FXF_ACCESS_BLOCK_WRITE, | SSH_FXF_ACCESS_BLOCK_READ, SSH_FXF_ACCESS_BLOCK_WRITE, | |||
SSH_FXF_ACCESS_BLOCK_DELETE, and SSH_FXF_ACCESS_BLOCK_ADVISORY | SSH_FXF_ACCESS_BLOCK_DELETE, and SSH_FXF_ACCESS_BLOCK_ADVISORY | |||
(Section 7.1.1.3.) | bits from Section 7.1.1.3, with a set bit corresponding to a | |||
supported combination and a clear bit an unsupported combination. | ||||
The index of a bit, bit zero being the least significant bit, | ||||
viewed as a four-bit number, corresponds to a combination of flag | ||||
bits, shifted right so that BLOCK_READ is the least significant | ||||
bit. The combination `no blocking flags' MUST be supported, so | ||||
the low bit will always be set. | ||||
The bits are interpreted in four-bit groups, beginning with the | For example, a server supporting only the classic advisory read | |||
least significant bit. The bit values are the values used in the | (shared) and write (exclusive) locks would set the bits | |||
file open flags, shifted right so that BLOCK_READ is the least | corresponding to READ+WRITE+ADVISORY, 0b1011, and WRITE+ADVISORY, | |||
significant bit. | 0b1010, plus the always-set bit 0b0000, giving a mask value of | |||
0b0000110000000001, or 0x0c01; a server supporting no locking at | ||||
all would set only bit zero, giving 0x0001. | ||||
For example, a server that supported only the classic advisory | 'supported-open-block-masks' applies to the SSH_FXP_OPEN | |||
read lock (shared lock) and write lock (exclusive lock) would send | (Section 7.1.1) flags field. 'supported-block-masks' applies to | |||
0b1011 1010, or 0xba. | the SSH_FXF_BLOCK request. | |||
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 | attrib-extension-count | |||
Count of extension names in the attrib-extension array. | Count of extension names in the attrib-extension array. | |||
attrib-extension-names | attrib-extension-names | |||
Names of extensions that can be used in an ATTRS (Section 6.14) | Names of extensions that can be used in an ATTRS (Section 6.14) | |||
structure. | structure. | |||
extension-count | extension-count | |||
Count of extension names in the attrib-extension array. | Count of extension names in the attrib-extension array. | |||
skipping to change at page 12, line 50 | skipping to change at page 14, line 9 | |||
If the server supports other versions than what was negotiated, it | If the server supports other versions than what was negotiated, it | |||
may wish to send the 'versions' extension to inform the client of | may wish to send the 'versions' extension to inform the client of | |||
this fact. The client may then optionally choose to use one of the | this fact. The client may then optionally choose to use one of the | |||
other versions supported. | other versions supported. | |||
string "versions" | string "versions" | |||
string comma-separated-versions | string comma-separated-versions | |||
'comma-separated-versions' is a string of comma separated version | 'comma-separated-versions' is a string of comma separated version | |||
numbers, for example, "3,6,7". Defined versions are: "2", "3", "4", | numbers. Defined versions are: "2", "3", "4", "5", "6". Any other | |||
"5", "6". Any other version advertised by the server must follow the | version advertised by the server must follow the DNS extensibility | |||
DNS extensibility naming convention outlined in [I-D.ietf-secsh- | naming convention outlined in [I-D.ietf-secsh-architecture]. | |||
architecture]. | ||||
If the client and server have negotiated any version higher than | For example: "2,3,6,private@example.com". | |||
version '3' (the version at which SSH_FXP_EXTENDED was introduced) in | ||||
the initial VERSION/INIT exchange, the client may select a new | If the client and server have negotiated a a version greater than or | |||
version to use from the list the server provided using the following | equal to version '3' (the version at which SSH_FXP_EXTENDED was | |||
SSH_FXP_EXTENDED request. | 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 | string 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 | 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 | server; if it is not, the server MUST fail the request and close the | |||
channel. | 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 | Since the request is the first request, it is not possible for the | |||
server to have already sent responses conforming to the old version. | server to have already sent responses conforming to the old version. | |||
The client SHOULD NOT select a version lower than was initially | Typically, the client SHOULD NOT down-grade the protocol version | |||
negotiated; however, it is not forbidden to do so. One reason a | using this extension; however, it is not forbidden to do so. One | |||
client might do so is to work around a buggy implementation. | 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 15, line 15 | skipping to change at page 16, line 22 | |||
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 filename translation if 'do-translate' is | the server MUST enable filename translation if 'do-translate' is | |||
true, or disable filename translation if it is false. | 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 SSH_FX_OP_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 | |||
skipping to change at page 20, line 21 | skipping to change at page 21, line 21 | |||
half second before 0 hour January 1, 1970, the seconds field would | half second before 0 hour January 1, 1970, the seconds field would | |||
have a value of negative one (-1) and the nseconds fields would have | have a value of negative one (-1) and the nseconds fields would 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]. | |||
bool acl-present | ||||
uint32 ace-count | uint32 ace-count | |||
repeated ace-count time: | repeated ace-count times: | |||
uint32 ace-type | uint32 ace-type | |||
uint32 ace-flag | uint32 ace-flag | |||
uint32 ace-mask | uint32 ace-mask | |||
string who [UTF-8] | string who [UTF-8] | |||
If the 'acl-present' flag is not set, it indicates that the file does | ||||
not have an ACL. In this case the 'ace-count' field is omitted and | ||||
implicitly zero. This condition indicates that the server both | ||||
supports ACLs and that it checked the file and found no ACL for this | ||||
file. This is distinct from the case of SSH_FILEXFER_ATTR_ACL not | ||||
being present in the attrib flags. If SSH_FILEXFER_ATTR_ACL is not | ||||
present, the client can not deduce whether the server does not | ||||
support ACLs, did not check the ACL (because doing so was expensive), | ||||
or had some other reason for omitting the data. | ||||
ace-type is one of the following four values (taken from NFS Version | ace-type is one of the following four values (taken from NFS Version | |||
4 Protocol [RFC3010]: | 4 Protocol [RFC3010]: | |||
ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 | ACE4_ACCESS_ALLOWED_ACE_TYPE 0x00000000 | |||
ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 | ACE4_ACCESS_DENIED_ACE_TYPE 0x00000001 | |||
ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 | ACE4_SYSTEM_AUDIT_ACE_TYPE 0x00000002 | |||
ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 | ACE4_SYSTEM_ALARM_ACE_TYPE 0x00000003 | |||
ace-flag is a combination of the following flag values. See NFS | ace-flag is a combination of the following flag values. See NFS | |||
Version 4 Protocol [RFC3010] section 5.9.2: | Version 4 Protocol [RFC3010] section 5.9.2: | |||
skipping to change at page 22, line 4 | skipping to change at page 23, line 19 | |||
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 and attrib-bits-valid | 6.9 attrib-bits and attrib-bits-valid | |||
These fields, taken together, reflect various attributes of the file | These fields, taken together, reflect various attributes of the file | |||
or directory, on the server. | or directory, on the server. | |||
Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- | Bits not set in 'attrib-bits-valid' MUST be ignored in the 'attrib- | |||
bits' field. This allows both the server and the client to | bits' field. This allows both the server and the client to | |||
comminicute only the bits it knows about without inadvertantly | communicate only the bits it knows about without inadvertantly | |||
twiddling bits they don't understand. | twiddling bits they don't understand. | |||
The following attrib-bits are defined: | The following attrib-bits are defined: | |||
SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 | SSH_FILEXFER_ATTR_FLAGS_READONLY 0x00000001 | |||
SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 | SSH_FILEXFER_ATTR_FLAGS_SYSTEM 0x00000002 | |||
SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 | SSH_FILEXFER_ATTR_FLAGS_HIDDEN 0x00000004 | |||
SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 | SSH_FILEXFER_ATTR_FLAGS_CASE_INSENSITIVE 0x00000008 | |||
SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 | SSH_FILEXFER_ATTR_FLAGS_ARCHIVE 0x00000010 | |||
SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 | SSH_FILEXFER_ATTR_FLAGS_ENCRYPTED 0x00000020 | |||
skipping to change at page 25, line 27 | skipping to change at page 26, line 41 | |||
'extension-pair' items that follow. Each of these items specifies an | 'extension-pair' items that follow. Each of these items specifies an | |||
extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED | extended attribute. Implementations MUST return SSH_FX_UNSUPPORTED | |||
if there are any unrecognized extensions. Clients can avoid sending | if there are any unrecognized extensions. Clients can avoid sending | |||
unsupported extensions by examining the attrib-extension-names of the | unsupported extensions by examining the attrib-extension-names of the | |||
"supported2" extension attrib-extension-names (Section 4.5). | "supported2" extension attrib-extension-names (Section 4.5). | |||
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 be defined only 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. | |||
7. Requests From the Client to the Server | 7. Requests From the Client to the Server | |||
Requests from the client to the server represent the various file | Requests from the client to the server represent the various file | |||
system operations. | system operations. | |||
skipping to change at page 28, line 34 | skipping to change at page 29, line 45 | |||
Data is always written at the end of the file. The offset field | Data is always written at the end of the file. The offset field | |||
of the SSH_FXP_WRITE requests are ignored. | of the SSH_FXP_WRITE requests are ignored. | |||
Data MUST be written atomically so that there is no chance that | Data MUST be written atomically so that there is no chance that | |||
multiple appenders can collide and result in data being lost. | multiple appenders can collide and result in data being lost. | |||
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_ACCESS_TEXT_MODE | |||
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 this flag, the offset field in the read | ||||
When a file is opened with the FXF_TEXT flag, the offset field in | and write functions is ignored. | |||
the read and write functions is ignored. | ||||
Servers MUST process multiple, parallel reads and writes correctly | Servers MUST process multiple, parallel reads and writes correctly | |||
in this mode. Naturally, it is permissible for them to do this by | in this mode. Naturally, it is permissible for them to 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 | |||
skipping to change at page 29, line 27 | skipping to change at page 30, line 37 | |||
message. | message. | |||
An attempt to seek past the end-of-file should result in a | An attempt to seek past the end-of-file should result in a | |||
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 | ||||
for read or write operations that are not sequential. | ||||
SSH_FXF_ACCESS_BLOCK_READ | SSH_FXF_ACCESS_BLOCK_READ | |||
The server MUST guarantee that no other open has taken place which | The server MUST guarantee that no other handle has been opened | |||
blocked handle has been opened with ACE4_READ_DATA access, and | with ACE4_READ_DATA access, and that no other handle will be | |||
that no other handle will be opened with ACE4_READ_DATA access | opened with ACE4_READ_DATA access until the client closes the | |||
until the client closes the handle. (This MUST apply both to | handle. (This MUST apply both to other clients and to other | |||
other clients and to other processes on the server.) | processes on the server.) | |||
If there is a conflicting lock the server MUST return | If there is a conflicting lock the server MUST return | |||
SSH_FX_LOCK_CONFLICT. If the server cannot make the locking | SSH_FX_LOCK_CONFLICT. If the server cannot make the locking | |||
guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. | guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. | |||
Other handles MAY be opened for ACE4_WRITE_DATA or any other | Other handles MAY be opened for ACE4_WRITE_DATA or any other | |||
combinatation of accesses, as long as ACE4_READ_DATA is not | combinatation of accesses, as long as ACE4_READ_DATA is not | |||
included in the mask. | included in the mask. | |||
SSH_FXF_ACCESS_BLOCK_WRITE | SSH_FXF_ACCESS_BLOCK_WRITE | |||
The server MUST guarantee that no other lock has been opened with | The server MUST guarantee that no other handle has been opened | |||
ACE4_WRITE_DATA or ACE4_APPEND_DATA access, and that no other | 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 | handle will be opened with ACE4_WRITE_DATA or ACE4_APPEND_DATA | |||
access until the client closes the handle. (This MUST apply both | access until the client closes the handle. (This MUST apply both | |||
to other clients and to other processes on the server.) | to other clients and to other processes on the server.) | |||
If there is a conflicting lock the server MUST return | If there is a conflicting lock the server MUST return | |||
SSH_FX_LOCK_CONFLICT. If the server cannot make the locking | SSH_FX_LOCK_CONFLICT. If the server cannot make the locking | |||
guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. | guarantee, it MUST return SSH_FX_OP_UNSUPPORTED. | |||
Other handles MAY be opened for ACE4_READ_DATA or any other | Other handles MAY be opened for ACE4_READ_DATA or any other | |||
combinatation of accesses, as long as neither ACE4_WRITE_DATA nor | combinatation of accesses, as long as neither ACE4_WRITE_DATA nor | |||
ACE4_APPEND_DATA are included in the mask. | ACE4_APPEND_DATA are included in the mask. | |||
SSH_FXF_ACCESS_BLOCK_DELETE | SSH_FXF_ACCESS_BLOCK_DELETE | |||
The server MUST guarantee that no other handle has been opened | The server MUST guarantee that no other handle has been opened | |||
skipping to change at page 30, line 45 | skipping to change at page 32, line 11 | |||
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. | |||
It is implementation specific whether the directory entry is | ||||
removed immediately or when the 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 existing 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 | |||
skipping to change at page 33, line 6 | skipping to change at page 34, line 17 | |||
string handle | string handle | |||
uint64 offset | uint64 offset | |||
uint32 length | uint32 length | |||
handle | handle | |||
'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. | return SSH_FX_INVALID_HANDLE. | |||
offset | offset | |||
'offset' is the offset (in bytes) relative to the beginning of the | The offset (in bytes) relative to the beginning of the file that | |||
file that the read MUST start at. 'offset' is ignored if | the read MUST start at. This field is ignored if | |||
SSH_FXF_TEXT was specified during the open. | SSH_FXF_ACCESS_TEXT_MODE 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. | |||
If the server specified a non-zero 'max-read-size' in it's | If the server specified a non-zero 'max-read-size' in its | |||
'supported2' (Section 4.5) extension, then failure to return | 'supported2' (Section 4.5) extension, 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. | |||
skipping to change at page 34, line 17 | skipping to change at page 35, line 27 | |||
string handle | string handle | |||
uint64 offset | uint64 offset | |||
string data | string data | |||
handle | handle | |||
'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. | return SSH_FX_INVALID_HANDLE. | |||
offset | offset | |||
'offset' is the offset (in bytes) relative to the beginning of the | The offset (in bytes) relative to the beginning of the file that | |||
file that the write MUST start at. 'offset' is ignored if | the write MUST start at. This field is ignored if | |||
SSH_FXF_TEXT was specified during the open. | SSH_FXF_ACCESS_TEXT_MODE 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 the byte value 0x00 | end of the file; the semantics are to write the byte value 0x00 | |||
from the end of the file to the specified offset and then the | from the end of the file to the specified offset and then the | |||
data. On most operating systems, such writes do not allocate disk | data. On most operating systems, such writes do not allocate disk | |||
space but 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. | |||
skipping to change at page 38, line 48 | skipping to change at page 40, line 6 | |||
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 link (either hare or symbolic) on | The SSH_FXP_LINK request creates a link (either hard or symbolic) on | |||
the server. | 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 39, line 34 | skipping to change at page 40, line 38 | |||
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 servers may return SSH_FX_OP_UNSUPPORTED for either | aware that some servers may return SSH_FX_OP_UNSUPPORTED for either | |||
the hard-link, sym-link, or both operations. | the hard-link, sym-link, or both operations. | |||
The SSH_FXP_LOCK creates a byte-range lock on the file specified by | 7.8 Byte-range locks | |||
the handle. The lock can be either mandatory (meaning that the | ||||
server enforces that no other process or client can perform | SSH_FXP_BLOCK creates a byte-range lock on the file specified by the | |||
operations in violation of the lock) or advisory (meaning that no | handle. The lock can be either mandatory (meaning that the server | |||
other process can obtain a conflicting lock, but the server does not | enforces that no other process or client can perform operations in | |||
enforce that no operation violates the lock. | 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 | A server MAY implement an advisory lock in a mandatory fashion; in | |||
other words, the server MAY enforce that no operation violates the | other words, the server MAY enforce that no operation violates the | |||
lock even when operating in advisory mode. | lock even when operating in advisory mode. | |||
The result is a SSH_FXP_STATUS return. | The result is a SSH_FXP_STATUS return. | |||
byte SSH_FXP_BLOCK | byte SSH_FXP_BLOCK | |||
uint32 request-id | uint32 request-id | |||
string handle | string handle | |||
uint64 offset | uint64 offset | |||
uint64 length | uint64 length | |||
uint32 uLockMask | uint32 uLockMask | |||
handle | handle | |||
'handle' is an open file handle returned by SSH_FXP_OPEN. If | 'handle' is a handle returned by SSH_FXP_OPEN or SSH_FXP_OPENDIR. | |||
'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | Note that some server MAY return SSH_FX_OP_UNSUPPORTED if the | |||
return SSH_FX_INVALID_HANDLE. | handle is a directory handle. | |||
offset | offset | |||
Beginning of the byte-range to lock. | Beginning of the byte-range to lock. | |||
length | length | |||
Number of bytes in the range to lock. The special value 0 means | Number of bytes in the range to lock. The special value 0 means | |||
lock from 'offset' to the end of the file. | lock from 'offset' to the end of the file. | |||
uLockMask | uLockMask | |||
A bit mask of SSH_FXF_ACCESS_BLOCK_* values; the meanings are | A bit mask of SSH_FXF_ACCESS_BLOCK_* values; the meanings are | |||
described in Section 7.1.1.3. | described in Section 7.1.1.3. | |||
The SSH_FXP_UNLOCK removes a previously aquired byte-range lock on | SSH_FXP_UNBLOCK removes a previously aquired byte-range lock on the | |||
the specified handle. | specified handle. | |||
The result is a SSH_FXP_STATUS return. | The result is a SSH_FXP_STATUS return. | |||
byte SSH_FXP_UNBLOCK | byte SSH_FXP_UNBLOCK | |||
uint32 request-id | uint32 request-id | |||
string handle | string handle | |||
uint64 offset | uint64 offset | |||
uint64 length | uint64 length | |||
handle | handle | |||
'handle' is an open file handle returned by SSH_FXP_OPEN. If | 'handle' on which a SSH_FXP_BLOCK request has previously been | |||
'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | issued. | |||
return SSH_FX_INVALID_HANDLE. | ||||
offset | offset | |||
Beginning of the byte-range to lock. | Beginning of the byte-range to lock. | |||
length | length | |||
Number of bytes in the range to lock. The special value 0 means | Number of bytes in the range to lock. The special value 0 means | |||
lock from 'offset' to the end of the file. | lock from 'offset' to the end of the file. | |||
7.8 Canonicalizing the Server-Side Path Name | 7.9 Canonicalizing the Server-Side Path Name | |||
The SSH_FXP_REALPATH request can be used to have the server | The SSH_FXP_REALPATH request can be used to have the server | |||
canonicalize any given path name to an absolute path. This is useful | canonicalize any given path name to an absolute path. This is useful | |||
for converting path names containing ".." components or relative | for converting path names containing ".." components or relative | |||
pathnames without a leading slash into absolute paths. The format of | pathnames without a leading slash into absolute paths. The format of | |||
the request is as follows: | the request is as follows: | |||
byte SSH_FXP_REALPATH | byte SSH_FXP_REALPATH | |||
uint32 request-id | uint32 request-id | |||
string original-path [UTF-8] | string original-path [UTF-8] | |||
string compose-path [optional] | ||||
byte control-byte [optional] | byte control-byte [optional] | |||
string compose-path[0..n] [optional] | ||||
original-path | original-path | |||
The first component of the path which the client wishes resolved | The first component of the path which the client wishes resolved | |||
into a absolute canonical path. This may be the entire path. | into a absolute canonical path. This may be the entire path. | |||
compose-path | ||||
A path which the client wishs the server to compose with the | ||||
original path to form the new path. This field is optional, and | ||||
if it is not present in the packet, it is assumed to be a zero | ||||
length string. | ||||
control-byte | control-byte | |||
SSH_FXP_REALPATH_NO_CHECK 0x00000001 | SSH_FXP_REALPATH_NO_CHECK 0x00000001 | |||
SSH_FXP_REALPATH_STAT_IF 0x00000002 | SSH_FXP_REALPATH_STAT_IF 0x00000002 | |||
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 | |||
skipping to change at page 41, line 51 | skipping to change at page 43, line 9 | |||
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. | |||
compose-path | ||||
A path which the client wishs the server to compose with the | ||||
original path to form the new path. This field is optional, and | ||||
if it is not present in the packet, it is assumed to be a zero | ||||
length string. | ||||
The client may specify multiple 'compose-path' elements, in which | ||||
case the server should build the resultant path up by applying | ||||
each compose path to the accumulated result until all 'compose- | ||||
path' elements have been applied. | ||||
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 'original- | as a modification to it. 'compose-path' MAY be relative to 'original- | |||
path' or may be an absolute path, in which case 'original-path' will | path' or may be an absolute path, in which case 'original-path' will | |||
be discarded. The 'compose-path' may be zero length. | be discarded. The 'compose-path' MAY be zero 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.9.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 its canonical name and see if it really existed and was a | path to get its canonical name and see if it really existed and was 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 | |||
skipping to change at page 43, line 47 | skipping to change at page 45, line 18 | |||
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. | Human readable description of the error. | |||
language tag | language tag | |||
'language tag' specifies the language the error is in. | 'language tag' specifies the language the error is in. | |||
<error-specific data> | ||||
error-specific data | ||||
The error-specific data may be empty, or may contain additional | The error-specific data may be empty, or may contain additional | |||
information about the error. For error codes that send error- | information about the error. For error codes that send 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 | |||
skipping to change at page 45, line 31 | skipping to change at page 47, line 31 | |||
The connection to the server was lost. This error MAY be used | The connection to the server was lost. This error MAY be used | |||
locally, but 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. | |||
SSH_FX_INVALID_HANDLE | SSH_FX_INVALID_HANDLE | |||
The handle value was invalid. | The handle value was invalid. | |||
SSH_FX_NO_SUCH_PATH | SSH_FX_NO_SUCH_PATH | |||
The file path does not exist or is invalid. | The file path does not exist or is invalid. | |||
SSH_FX_FILE_ALREADY_EXISTS | SSH_FX_FILE_ALREADY_EXISTS | |||
The file already exists. | The file already exists. | |||
skipping to change at page 46, line 21 | skipping to change at page 48, line 21 | |||
user's storage quota. | user's storage quota. | |||
SSH_FX_UNKNOWN_PRINCIPAL | SSH_FX_UNKNOWN_PRINCIPAL | |||
A principal referenced by the request (either the 'owner', | A principal referenced by the request (either the 'owner', | |||
'group', or 'who' field of an ACL), was unknown. The error | 'group', or 'who' field of an ACL), was unknown. The error | |||
specific data contains the problematic names. The format is one | specific data contains the problematic names. The format is one | |||
or more: | or more: | |||
string unknown-name | string unknown-name | |||
Each string contains the name of a principle that was unknown. | Each string contains the name of a principal 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 | |||
process. | process. | |||
SSH_FX_DIR_NOT_EMPTY | SSH_FX_DIR_NOT_EMPTY | |||
The directory is not empty. | The directory is not empty. | |||
SSH_FX_NOT_A_DIRECTORY | SSH_FX_NOT_A_DIRECTORY | |||
The specified file is not a directory. | The specified file is not a directory. | |||
skipping to change at page 47, line 6 | skipping to change at page 49, 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 | |||
Some operating systems support locking a range of bytes within a | A read or write operation failed because another process's | |||
file. On such operating systems, it is possible for a SFTP | mandatory byte-range lock overlaps with the request. | |||
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. | |||
skipping to change at page 49, line 31 | skipping to change at page 51, line 22 | |||
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 ... | |||
request-id | request-id | |||
Identifier to be returned from the server with the response. | Identifier to be returned from the server with the response. | |||
extended-request | extended-request | |||
A string naming the extension. Vendor-specific extensions have | A string naming the extension, following the the DNS extensibility | |||
use the "name@domain" syntax, where domain is an internet domain | naming convention outlined in [I-D.ietf-secsh-architecture], or | |||
name of the vendor defining the request. | defined by IETF consensus. | |||
The IETF may also define extensions to the protocol. These | ||||
extension names will not have an '@' in them. | ||||
request-specific data | request-specific data | |||
The rest of the request is defined by the extension; servers | The rest of the request is defined by the extension; servers | |||
SHOULD NOT attempt to interpret it if they do not 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 | |||
skipping to change at page 51, line 39 | skipping to change at page 53, line 29 | |||
Used if "md5-hash" is specified; indicates the name of the file to | Used if "md5-hash" is specified; indicates the name of the file to | |||
use. The hash will be of the file contents as it would appear on | use. The hash will be of the file contents as it would appear on | |||
the wire if the file were opened with no special flags. | the wire if the file were opened with no special flags. | |||
file-handle | file-handle | |||
Used if "md5-hash-handle" is specified; specifies a file handle to | Used if "md5-hash-handle" is specified; specifies a file handle to | |||
read the data from. The handle MUST be a file handle, and | read the data from. The handle MUST be a file handle, and | |||
ACE4_READ_DATA MUST have been included in the desired-access when | ACE4_READ_DATA MUST have been included in the desired-access when | |||
the file was opened. | the file was opened. | |||
If this file handle was opened in TEXT mode, the md5-hash must be | If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode, | |||
made of the data as it would be sent on the wire. | the md5-hash must be made of the data as it would be sent on the | |||
wire. | ||||
start-offset | start-offset | |||
The starting offset of the data to hash. | The starting offset of the data to hash. | |||
length | length | |||
The length of data to include in the hash. If both start-offset | The length of data to include in the hash. If both start-offset | |||
and length are zero, the entire file should be included. | and length are zero, the entire file should be included. | |||
quick-check-hash | quick-check-hash | |||
The hash over the first 2048 bytes of the data range as the client | The hash over the first 2048 bytes of the data range as the client | |||
skipping to change at page 52, line 36 | skipping to change at page 54, line 23 | |||
hash of the entire data range (including the first 2048 bytes that | hash of the entire data range (including the first 2048 bytes that | |||
were included in the 'quick-check-hash'.) | were included in the 'quick-check-hash'.) | |||
9.1.2 Checking File Contents | 9.1.2 Checking File Contents | |||
This extension allows a client to easily check if a file (or portion | This extension allows a client to easily check if a file (or portion | |||
thereof) that it already has matches what is on the server. | thereof) that it already has matches what is on the server. | |||
byte SSH_FXP_EXTENDED | byte SSH_FXP_EXTENDED | |||
uint32 request-id | uint32 request-id | |||
string "check-file" | string "check-file-handle" / "check-file-name" | |||
string handle | string handle / name | |||
string hash-algorithm-list | string hash-algorithm-list | |||
uint64 start-offset | uint64 start-offset | |||
uint64 length | uint64 length | |||
uint32 block-size | uint32 block-size | |||
handle | handle | |||
'handle' is an open file handle returned by SSH_FXP_OPEN. If | For "check-file-handle", 'handle' is an open file handle returned | |||
'handle' is not a handle returned by SSH_FXP_OPEN, the server MUST | by SSH_FXP_OPEN. If 'handle' is not a handle returned by | |||
return SSH_FX_INVALID_HANDLE. If ACE4_READ_DATA MUST was not | SSH_FXP_OPEN, the server MUST return SSH_FX_INVALID_HANDLE. If | |||
included when the file was opened, the server MUST return | ACE4_READ_DATA was not included when the file was opened, the | |||
STATUS_PERMISSION_DENIED. | server MUST return STATUS_PERMISSION_DENIED. | |||
If this file handle was opened in TEXT mode, the check must be | If this file handle was opened in SSH_FXF_ACCESS_TEXT_MODE mode, | |||
performed on the data as it would be sent on the wire. | the check must be performed on the data as it would be sent on the | |||
wire. | ||||
name | ||||
For "check-file-name", 'name' is the path to the file to check. | ||||
If 'check-file-name' is a directory, SSH_FX_FILE_IS_A_DIRECTORY | ||||
SHOULD be returned. If 'check-file-name' refers to a | ||||
SSH_FILEXFER_TYPE_SYMLINK, the target should be opened. The | ||||
results are undefined file types other than | ||||
SSH_FILEXFER_TYPE_REGULAR. | ||||
The file MUST be opened without the SSH_FXF_ACCESS_TEXT_MODE | ||||
access flag (in binary mode.) | ||||
hash-algorithm-list | hash-algorithm-list | |||
A comma separated list of hash alogirthms the client is willing to | A comma separated list of hash algorithms 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 defined 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]. [ISO.3309.1991] | |||
[ISO.3309.1991], and is the same algorithm used in [RFC1510] | describes crc32, 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 every block in the file. | An independant hash MUST be computed over every block in the file. | |||
skipping to change at page 55, line 38 | skipping to change at page 57, line 38 | |||
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, suitable | Absolute pathname of the specified user's home directory, suitable | |||
for use in operations such as REALPATH or OPEN. | for use in operations such as REALPATH or OPENDIR. | |||
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. | |||
skipping to change at page 58, line 22 | skipping to change at page 60, line 22 | |||
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- | o Change "supported" extension to "supported2", remove desired- | |||
access-bits, seperate attrib extension from SSH_FXP_EXTENDED | access-bits, seperate attrib extension from SSH_FXP_EXTENDED | |||
extensions. | extensions. | |||
o Add "vendor-id" extension. | o Add "vendor-id" extension. | |||
o Add ctime and attrib-bits-valid to attrib structure. | o Add ctime and attrib-bits-valid to attrib structure. | |||
o Unrecognized attrib extensions cause failure rather than ignored. | o Unrecognized attrib extensions cause failure rather than ignored. | |||
o Option 'end of data' flags on data ane names responses. | o Optional 'end of data' flags on data and names responses. | |||
o Add valid-access-mask back into supported2 | ||||
o Add acl-present flag to acl. | ||||
12.2 Changes Between Versions 5 and 4 | 12.2 Changes Between Versions 5 and 4 | |||
Many of the changes between version 5 and version 4 are to better | Many of the changes between version 5 and version 4 are to better | |||
support the changes in version 4, and to better specify error | support the changes in version 4, and to better specify error | |||
conditions. | conditions. | |||
o Add "supported" extension to communicate features supported. | o Add "supported" extension to communicate features supported. | |||
o Clarify error handling when client requests unsupported feature. | o Clarify error handling when client requests unsupported feature. | |||
(For example, attempts to write an unsupported attribute.) | (For example, attempts to write an unsupported attribute.) | |||
skipping to change at page 60, line 18 | skipping to change at page 62, line 18 | |||
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", | Ylonen, T. and C. Lonvick, "SSH Protocol Architecture", | |||
draft-ietf-secsh-architecture-22 (work in progress), | draft-ietf-secsh-architecture-22 (work in progress), | |||
March 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", | |||
draft-ietf-secsh-transport-24 (work in progress), | draft-ietf-secsh-transport-24 (work in progress), | |||
March 2005. | March 2005. | |||
[I-D.ietf-secsh-connect] | [I-D.ietf-secsh-connect] | |||
Lonvick, C., "SSH Connection Protocol", | Lonvick, C. and T. Ylonen, "SSH Connection Protocol", | |||
draft-ietf-secsh-connect-25 (work in progress), | draft-ietf-secsh-connect-25 (work in progress), | |||
March 2005. | 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] | |||
skipping to change at page 61, line 19 | skipping to change at page 63, line 19 | |||
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. and T. Ylonen, "SSH Authentication Protocol", | |||
draft-ietf-secsh-userauth-27 (work in progress), | draft-ietf-secsh-userauth-27 (work in progress), | |||
March 2005. | 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 | |||
End of changes. | ||||
This html diff was produced by rfcdiff 1.23, available from http://www.levkowetz.com/ietf/tools/rfcdiff/ |