Annotation of src/usr.bin/ssh/PROTOCOL, Revision 1.6
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:
1.6 ! djm 64: 4. connection: disallow additional sessions extension
! 65: "no-more-sessions@openssh.com"
! 66:
! 67: Most SSH connections will only ever request a single session, but a
! 68: attacker may abuse a running ssh client to surreptitiously open
! 69: additional sessions under their control. OpenSSH provides a global
! 70: request "no-more-sessions@openssh.com" to mitigate this attack.
! 71:
! 72: When an OpenSSH client expects that it will never open another session
! 73: (i.e. it has been started with connection multiplexing disabled), it
! 74: will send the following global request:
! 75:
! 76: byte SSH_MSG_GLOBAL_REQUEST
! 77: string "no-more-sessions@openssh.com"
! 78: char want-reply
! 79:
! 80: On receipt of such a message, an OpenSSH server will refuse to open
! 81: future channels of type "session" and instead immediately abort the
! 82: connection.
! 83:
! 84: Note that this is not a general defence against compromised clients
! 85: (that is impossible), but it thwarts a simple attack.
! 86:
! 87: 5. sftp: Reversal of arguments to SSH_FXP_SYMLINK
1.1 djm 88:
89: When OpenSSH's sftp-server was implemented, the order of the arguments
90: to the SSH_FXP_SYMLINK method was inadvertendly reversed. Unfortunately,
91: the reversal was not noticed until the server was widely deployed. Since
92: fixing this to follow the specification would cause incompatibility, the
93: current order was retained. For correct operation, clients should send
94: SSH_FXP_SYMLINK as follows:
95:
96: uint32 id
97: string targetpath
98: string linkpath
99:
1.6 ! djm 100: 6. sftp: Server extension announcement in SSH_FXP_VERSION
1.1 djm 101:
102: OpenSSH's sftp-server lists the extensions it supports using the
103: standard extension announcement mechanism in the SSH_FXP_VERSION server
104: hello packet:
105:
106: uint32 3 /* protocol version */
107: string ext1-name
108: string ext1-version
109: string ext2-name
110: string ext2-version
111: ...
112: string extN-name
113: string extN-version
114:
115: Each extension reports its integer version number as an ASCII encoded
116: string, e.g. "1". The version will be incremented if the extension is
117: ever changed in an incompatible way. The server MAY advertise the same
118: extension with multiple versions (though this is unlikely). Clients MUST
119: check the version number before attemping to use the extension.
120:
1.6 ! djm 121: 7. sftp: Extension request "posix-rename@openssh.com"
1.1 djm 122:
123: This operation provides a rename operation with POSIX semantics, which
124: are different to those provided by the standard SSH_FXP_RENAME in
125: draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
126: SSH_FXP_EXTENDED request with the following format:
127:
128: uint32 id
129: string "posix-rename@openssh.com"
130: string oldpath
131: string newpath
132:
133: On receiving this request the server will perform the POSIX operation
134: rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
135: This extension is advertised in the SSH_FXP_VERSION hello with version
136: "1".
137:
1.6 ! djm 138: 8. sftp: Extension requests "statvfs@openssh.com" and
1.2 djm 139: "fstatvfs@openssh.com"
1.1 djm 140:
141: These requests correspond to the statvfs and fstatvfs POSIX system
142: interfaces. The "statvfs@openssh.com" request operates on an explicit
143: pathname, and is formatted as follows:
144:
145: uint32 id
146: string "statvfs@openssh.com"
147: string path
148:
149: The "fstatvfs@openssh.com" operates on an open filehandle:
150:
151: uint32 id
1.2 djm 152: string "fstatvfs@openssh.com"
1.1 djm 153: string handle
154:
155: These requests return a SSH_FXP_STATUS reply on failure. On success they
156: return the following SSH_FXP_EXTENDED_REPLY reply:
157:
158: uint32 id
1.4 dtucker 159: uint64 f_bsize /* file system block size */
160: uint64 f_frsize /* fundamental fs block size */
1.1 djm 161: uint64 f_blocks /* number of blocks (unit f_frsize) */
162: uint64 f_bfree /* free blocks in file system */
163: uint64 f_bavail /* free blocks for non-root */
164: uint64 f_files /* total file inodes */
165: uint64 f_ffree /* free file inodes */
166: uint64 f_favail /* free file inodes for to non-root */
1.3 djm 167: uint64 f_fsid /* file system id */
1.4 dtucker 168: uint64 f_flag /* bit mask of f_flag values */
169: uint64 f_namemax /* maximum filename length */
1.1 djm 170:
171: The values of the f_flag bitmask are as follows:
172:
173: #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
174: #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
175:
1.3 djm 176: This extension is advertised in the SSH_FXP_VERSION hello with version
177: "2".
178:
1.6 ! djm 179: $OpenBSD: PROTOCOL,v 1.5 2008/06/09 13:38:46 dtucker Exp $
1.1 djm 180: