Annotation of src/usr.bin/ssh/PROTOCOL, Revision 1.10
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:
1.9 djm 12: The protocol used by OpenSSH's ssh-agent is described in the file
13: PROTOCOL.agent
14:
1.1 djm 15: 1. transport: Protocol 2 MAC algorithm "umac-64@openssh.com"
16:
17: This is a new transport-layer MAC method using the UMAC algorithm
18: (rfc4418). This method is identical to the "umac-64" method documented
19: in:
20:
21: http://www.openssh.com/txt/draft-miller-secsh-umac-01.txt
22:
23: 2. transport: Protocol 2 compression algorithm "zlib@openssh.com"
24:
25: This transport-layer compression method uses the zlib compression
26: algorithm (identical to the "zlib" method in rfc4253), but delays the
27: start of compression until after authentication has completed. This
1.2 djm 28: avoids exposing compression code to attacks from unauthenticated users.
1.1 djm 29:
30: The method is documented in:
31:
32: http://www.openssh.com/txt/draft-miller-secsh-compression-delayed-00.txt
33:
34: 3. connection: Channel write close extension "eow@openssh.com"
35:
36: The SSH connection protocol (rfc4254) provides the SSH_MSG_CHANNEL_EOF
37: message to allow an endpoint to signal its peer that it will send no
38: more data over a channel. Unfortunately, there is no symmetric way for
39: an endpoint to request that its peer should cease sending data to it
40: while still keeping the channel open for the endpoint to send data to
41: the peer.
42:
1.2 djm 43: This is desirable, since it saves the transmission of data that would
1.1 djm 44: otherwise need to be discarded and it allows an endpoint to signal local
45: processes of the condition, e.g. by closing the corresponding file
46: descriptor.
47:
48: OpenSSH implements a channel extension message to perform this
1.10 ! djm 49: signalling: "eow@openssh.com" (End Of Write). This message is sent by
! 50: an endpoint when the local output of a session channel is closed or
! 51: experiences a write error. The message is formatted as follows:
1.1 djm 52:
53: byte SSH_MSG_CHANNEL_REQUEST
54: uint32 recipient channel
55: string "eow@openssh.com"
56: boolean FALSE
57:
58: On receiving this message, the peer SHOULD cease sending data of
59: the channel and MAY signal the process from which the channel data
60: originates (e.g. by closing its read file descriptor).
61:
62: As with the symmetric SSH_MSG_CHANNEL_EOF message, the channel does
63: remain open after a "eow@openssh.com" has been sent and more data may
64: still be sent in the other direction. This message does not consume
65: window space and may be sent even if no window space is available.
66:
1.6 djm 67: 4. connection: disallow additional sessions extension
68: "no-more-sessions@openssh.com"
69:
70: Most SSH connections will only ever request a single session, but a
71: attacker may abuse a running ssh client to surreptitiously open
72: additional sessions under their control. OpenSSH provides a global
73: request "no-more-sessions@openssh.com" to mitigate this attack.
74:
75: When an OpenSSH client expects that it will never open another session
76: (i.e. it has been started with connection multiplexing disabled), it
77: will send the following global request:
78:
79: byte SSH_MSG_GLOBAL_REQUEST
80: string "no-more-sessions@openssh.com"
81: char want-reply
82:
83: On receipt of such a message, an OpenSSH server will refuse to open
84: future channels of type "session" and instead immediately abort the
85: connection.
86:
87: Note that this is not a general defence against compromised clients
88: (that is impossible), but it thwarts a simple attack.
89:
1.7 djm 90: 5. connection: Tunnel forward extension "tun@openssh.com"
91:
1.8 djm 92: OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
1.7 djm 93: channel type. This channel type supports forwarding of network packets
1.8 djm 94: with datagram boundaries intact between endpoints equipped with
1.7 djm 95: interfaces like the BSD tun(4) device. Tunnel forwarding channels are
96: requested by the client with the following packet:
97:
98: byte SSH_MSG_CHANNEL_OPEN
99: string "tun@openssh.com"
100: uint32 sender channel
101: uint32 initial window size
102: uint32 maximum packet size
103: uint32 tunnel mode
104: uint32 remote unit number
105:
106: The "tunnel mode" parameter specifies whether the tunnel should forward
107: layer 2 frames or layer 3 packets. It may take one of the following values:
108:
109: SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */
110: SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */
111:
112: The "tunnel unit number" specifies the remote interface number, or may
113: be zero to allow the server to automatically chose an interface. A server
114: that is not willing to open a client-specified unit should refuse the
115: request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful open,
116: the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
117:
118: Once established the client and server may exchange packet or frames
119: over the tunnel channel by encapsulating them in SSH protocol strings
120: and sending them as channel data. This ensures that packet boundaries
121: are kept intact. Specifically, packets are transmitted using normal
122: SSH_MSG_CHANNEL_DATA packets:
123:
124: byte SSH_MSG_CHANNEL_DATA
125: uint32 recipient channel
126: string data
127:
128: The contents of the "data" field for layer 3 packets is:
129:
130: uint32 packet length
131: uint32 address family
132: byte[packet length - 4] packet data
133:
134: The "address family" field identifies the type of packet in the message.
135: It may be one of:
136:
137: SSH_TUN_AF_INET 2 /* IPv4 */
138: SSH_TUN_AF_INET6 24 /* IPv6 */
139:
140: The "packet data" field consists of the IPv4/IPv6 datagram itself
141: without any link layer header.
142:
143: The contents of the "data" field for layer 3 packets is:
144:
145: uint32 packet length
146: byte[packet length] frame
147:
1.8 djm 148: The "frame" field contains an IEEE 802.3 Ethernet frame, including
1.7 djm 149: header.
150:
151: 6. sftp: Reversal of arguments to SSH_FXP_SYMLINK
1.1 djm 152:
153: When OpenSSH's sftp-server was implemented, the order of the arguments
1.8 djm 154: to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
1.1 djm 155: the reversal was not noticed until the server was widely deployed. Since
156: fixing this to follow the specification would cause incompatibility, the
157: current order was retained. For correct operation, clients should send
158: SSH_FXP_SYMLINK as follows:
159:
160: uint32 id
161: string targetpath
162: string linkpath
163:
1.7 djm 164: 7. sftp: Server extension announcement in SSH_FXP_VERSION
1.1 djm 165:
166: OpenSSH's sftp-server lists the extensions it supports using the
167: standard extension announcement mechanism in the SSH_FXP_VERSION server
168: hello packet:
169:
170: uint32 3 /* protocol version */
171: string ext1-name
172: string ext1-version
173: string ext2-name
174: string ext2-version
175: ...
176: string extN-name
177: string extN-version
178:
179: Each extension reports its integer version number as an ASCII encoded
180: string, e.g. "1". The version will be incremented if the extension is
181: ever changed in an incompatible way. The server MAY advertise the same
182: extension with multiple versions (though this is unlikely). Clients MUST
1.8 djm 183: check the version number before attempting to use the extension.
1.1 djm 184:
1.7 djm 185: 8. sftp: Extension request "posix-rename@openssh.com"
1.1 djm 186:
187: This operation provides a rename operation with POSIX semantics, which
188: are different to those provided by the standard SSH_FXP_RENAME in
189: draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
190: SSH_FXP_EXTENDED request with the following format:
191:
192: uint32 id
193: string "posix-rename@openssh.com"
194: string oldpath
195: string newpath
196:
197: On receiving this request the server will perform the POSIX operation
198: rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
199: This extension is advertised in the SSH_FXP_VERSION hello with version
200: "1".
201:
1.7 djm 202: 9. sftp: Extension requests "statvfs@openssh.com" and
1.2 djm 203: "fstatvfs@openssh.com"
1.1 djm 204:
205: These requests correspond to the statvfs and fstatvfs POSIX system
206: interfaces. The "statvfs@openssh.com" request operates on an explicit
207: pathname, and is formatted as follows:
208:
209: uint32 id
210: string "statvfs@openssh.com"
211: string path
212:
1.8 djm 213: The "fstatvfs@openssh.com" operates on an open file handle:
1.1 djm 214:
215: uint32 id
1.2 djm 216: string "fstatvfs@openssh.com"
1.1 djm 217: string handle
218:
219: These requests return a SSH_FXP_STATUS reply on failure. On success they
220: return the following SSH_FXP_EXTENDED_REPLY reply:
221:
222: uint32 id
1.4 dtucker 223: uint64 f_bsize /* file system block size */
224: uint64 f_frsize /* fundamental fs block size */
1.1 djm 225: uint64 f_blocks /* number of blocks (unit f_frsize) */
226: uint64 f_bfree /* free blocks in file system */
227: uint64 f_bavail /* free blocks for non-root */
228: uint64 f_files /* total file inodes */
229: uint64 f_ffree /* free file inodes */
230: uint64 f_favail /* free file inodes for to non-root */
1.3 djm 231: uint64 f_fsid /* file system id */
1.4 dtucker 232: uint64 f_flag /* bit mask of f_flag values */
233: uint64 f_namemax /* maximum filename length */
1.1 djm 234:
235: The values of the f_flag bitmask are as follows:
236:
237: #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
238: #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
239:
1.3 djm 240: This extension is advertised in the SSH_FXP_VERSION hello with version
241: "2".
242:
1.10 ! djm 243: $OpenBSD: PROTOCOL,v 1.9 2008/06/28 14:08:30 djm Exp $
![[BACK]](/icons/back.gif){kind=icon}
Return to PROTOCOL CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh