Annotation of src/usr.bin/ssh/PROTOCOL, Revision 1.3
1.1 djm 1: This documents OpenSSH's deviations and extensions to the published SSH
2: protocol.
3:
1.2 djm 4: Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
5: filexfer protocol described in:
1.1 djm 6:
7: http://www.openssh.com/txt/draft-ietf-secsh-filexfer-02.txt
8:
9: Features from newer versions of the draft are not supported, unless
10: explicitly implemented as extensions described below.
11:
12: 1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
13:
14: This is a new transport-layer MAC method using the UMAC algorithm
15: (rfc4418). This method is identical to the "umac-64" method documented
16: in:
17:
18: http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
19:
20: 2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
21:
22: This transport-layer compression method uses the zlib compression
23: algorithm (identical to the "zlib" method in rfc4253), but delays the
24: start of compression until after authentication has completed. This
1.2 djm 25: avoids exposing compression code to attacks from unauthenticated users.
1.1 djm 26:
27: The method is documented in:
28:
29: http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
30:
31: 3. connection: Channel write close extension "eow@openssh.com"
32:
33: The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
34: message to allow an endpoint to signal its peer that it will send no
35: more data over a channel. Unfortunately, there is no symmetric way for
36: an endpoint to request that its peer should cease sending data to it
37: while still keeping the channel open for the endpoint to send data to
38: the peer.
39:
1.2 djm 40: This is desirable, since it saves the transmission of data that would
1.1 djm 41: otherwise need to be discarded and it allows an endpoint to signal local
42: processes of the condition, e.g. by closing the corresponding file
43: descriptor.
44:
45: OpenSSH implements a channel extension message to perform this
46: signalling: "eow@openssh.com" (End Of Write). This message is sent by an
47: endpoint when the local output of a channel is closed or experiences a
48: write error. The message is formatted as follows:
49:
50: byte SSH_MSG_CHANNEL_REQUEST
51: uint32 recipient channel
52: string "eow@openssh.com"
53: boolean FALSE
54:
55: On receiving this message, the peer SHOULD cease sending data of
56: the channel and MAY signal the process from which the channel data
57: originates (e.g. by closing its read file descriptor).
58:
59: As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
60: remain open after a "eow@openssh.com" has been sent and more data may
61: still be sent in the other direction. This message does not consume
62: window space and may be sent even if no window space is available.
63:
64: 4. sftp: Reversal of arguments to SSH_FXP_SYMLINK
65:
66: When OpenSSH's sftp-server was implemented, the order of the arguments
67: to the SSH_FXP_SYMLINK method was inadvertendly reversed. Unfortunately,
68: the reversal was not noticed until the server was widely deployed. Since
69: fixing this to follow the specification would cause incompatibility, the
70: current order was retained. For correct operation, clients should send
71: SSH_FXP_SYMLINK as follows:
72:
73: uint32 id
74: string targetpath
75: string linkpath
76:
77: 5. sftp: Server extension announcement in SSH_FXP_VERSION
78:
79: OpenSSH's sftp-server lists the extensions it supports using the
80: standard extension announcement mechanism in the SSH_FXP_VERSION server
81: hello packet:
82:
83: uint32 3 /* protocol version */
84: string ext1-name
85: string ext1-version
86: string ext2-name
87: string ext2-version
88: ...
89: string extN-name
90: string extN-version
91:
92: Each extension reports its integer version number as an ASCII encoded
93: string, e.g. "1". The version will be incremented if the extension is
94: ever changed in an incompatible way. The server MAY advertise the same
95: extension with multiple versions (though this is unlikely). Clients MUST
96: check the version number before attemping to use the extension.
97:
98: 6. sftp: Extension request "posix-rename@openssh.com"
99:
100: This operation provides a rename operation with POSIX semantics, which
101: are different to those provided by the standard SSH_FXP_RENAME in
102: draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
103: SSH_FXP_EXTENDED request with the following format:
104:
105: uint32 id
106: string "posix-rename@openssh.com"
107: string oldpath
108: string newpath
109:
110: On receiving this request the server will perform the POSIX operation
111: rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
112: This extension is advertised in the SSH_FXP_VERSION hello with version
113: "1".
114:
115: 7. sftp: Extension requests "statvfs@openssh.com" and
1.2 djm 116: "fstatvfs@openssh.com"
1.1 djm 117:
118: These requests correspond to the statvfs and fstatvfs POSIX system
119: interfaces. The "statvfs@openssh.com" request operates on an explicit
120: pathname, and is formatted as follows:
121:
122: uint32 id
123: string "statvfs@openssh.com"
124: string path
125:
126: The "fstatvfs@openssh.com" operates on an open filehandle:
127:
128: uint32 id
1.2 djm 129: string "fstatvfs@openssh.com"
1.1 djm 130: string handle
131:
132: These requests return a SSH_FXP_STATUS reply on failure. On success they
133: return the following SSH_FXP_EXTENDED_REPLY reply:
134:
135: uint32 id
136: uint32 f_bsize /* file system block size */
137: uint32 f_frsize /* fundamental fs block size */
138: uint64 f_blocks /* number of blocks (unit f_frsize) */
139: uint64 f_bfree /* free blocks in file system */
140: uint64 f_bavail /* free blocks for non-root */
141: uint64 f_files /* total file inodes */
142: uint64 f_ffree /* free file inodes */
143: uint64 f_favail /* free file inodes for to non-root */
1.3 ! djm 144: uint64 f_fsid /* file system id */
1.1 djm 145: uint32 f_flag /* bit mask of f_flag values */
146: uint32 f_namemax /* maximum filename length */
147:
148: The values of the f_flag bitmask are as follows:
149:
150: #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
151: #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
152:
1.3 ! djm 153: This extension is advertised in the SSH_FXP_VERSION hello with version
! 154: "2".
! 155:
! 156: $Id: PROTOCOL,v 1.2 2008/05/17 01:31:56 djm Exp $
1.1 djm 157: