Annotation of src/crypto/external/bsd/openssh/dist/PROTOCOL, Revision 1.1.1.1
1.1 christos 1: This documents OpenSSH's deviations and extensions to the published SSH
2: protocol.
3:
4: Note that OpenSSH's sftp and sftp-server implement revision 3 of the SSH
5: filexfer protocol described in:
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: The protocol used by OpenSSH's ssh-agent is described in the file
13: PROTOCOL.agent
14:
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
28: avoids exposing compression code to attacks from unauthenticated users.
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:
43: This is desirable, since it saves the transmission of data that would
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
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:
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:
67: NB. due to certain broken SSH implementations aborting upon receipt
68: of this message (in contravention of RFC4254 section 5.4), this
69: message is only sent to OpenSSH peers (identified by banner).
70: Other SSH implementations may be whitelisted to receive this message
71: upon request.
72:
73: 4. connection: disallow additional sessions extension
74: "no-more-sessions@openssh.com"
75:
76: Most SSH connections will only ever request a single session, but a
77: attacker may abuse a running ssh client to surreptitiously open
78: additional sessions under their control. OpenSSH provides a global
79: request "no-more-sessions@openssh.com" to mitigate this attack.
80:
81: When an OpenSSH client expects that it will never open another session
82: (i.e. it has been started with connection multiplexing disabled), it
83: will send the following global request:
84:
85: byte SSH_MSG_GLOBAL_REQUEST
86: string "no-more-sessions@openssh.com"
87: char want-reply
88:
89: On receipt of such a message, an OpenSSH server will refuse to open
90: future channels of type "session" and instead immediately abort the
91: connection.
92:
93: Note that this is not a general defence against compromised clients
94: (that is impossible), but it thwarts a simple attack.
95:
96: NB. due to certain broken SSH implementations aborting upon receipt
97: of this message, the no-more-sessions request is only sent to OpenSSH
98: servers (identified by banner). Other SSH implementations may be
99: whitelisted to receive this message upon request.
100:
101: 5. connection: Tunnel forward extension "tun@openssh.com"
102:
103: OpenSSH supports layer 2 and layer 3 tunnelling via the "tun@openssh.com"
104: channel type. This channel type supports forwarding of network packets
105: with datagram boundaries intact between endpoints equipped with
106: interfaces like the BSD tun(4) device. Tunnel forwarding channels are
107: requested by the client with the following packet:
108:
109: byte SSH_MSG_CHANNEL_OPEN
110: string "tun@openssh.com"
111: uint32 sender channel
112: uint32 initial window size
113: uint32 maximum packet size
114: uint32 tunnel mode
115: uint32 remote unit number
116:
117: The "tunnel mode" parameter specifies whether the tunnel should forward
118: layer 2 frames or layer 3 packets. It may take one of the following values:
119:
120: SSH_TUNMODE_POINTOPOINT 1 /* layer 3 packets */
121: SSH_TUNMODE_ETHERNET 2 /* layer 2 frames */
122:
123: The "tunnel unit number" specifies the remote interface number, or may
124: be zero to allow the server to automatically chose an interface. A server
125: that is not willing to open a client-specified unit should refuse the
126: request with a SSH_MSG_CHANNEL_OPEN_FAILURE error. On successful open,
127: the server should reply with SSH_MSG_CHANNEL_OPEN_SUCCESS.
128:
129: Once established the client and server may exchange packet or frames
130: over the tunnel channel by encapsulating them in SSH protocol strings
131: and sending them as channel data. This ensures that packet boundaries
132: are kept intact. Specifically, packets are transmitted using normal
133: SSH_MSG_CHANNEL_DATA packets:
134:
135: byte SSH_MSG_CHANNEL_DATA
136: uint32 recipient channel
137: string data
138:
139: The contents of the "data" field for layer 3 packets is:
140:
141: uint32 packet length
142: uint32 address family
143: byte[packet length - 4] packet data
144:
145: The "address family" field identifies the type of packet in the message.
146: It may be one of:
147:
148: SSH_TUN_AF_INET 2 /* IPv4 */
149: SSH_TUN_AF_INET6 24 /* IPv6 */
150:
151: The "packet data" field consists of the IPv4/IPv6 datagram itself
152: without any link layer header.
153:
154: The contents of the "data" field for layer 3 packets is:
155:
156: uint32 packet length
157: byte[packet length] frame
158:
159: The "frame" field contains an IEEE 802.3 Ethernet frame, including
160: header.
161:
162: 6. sftp: Reversal of arguments to SSH_FXP_SYMLINK
163:
164: When OpenSSH's sftp-server was implemented, the order of the arguments
165: to the SSH_FXP_SYMLINK method was inadvertently reversed. Unfortunately,
166: the reversal was not noticed until the server was widely deployed. Since
167: fixing this to follow the specification would cause incompatibility, the
168: current order was retained. For correct operation, clients should send
169: SSH_FXP_SYMLINK as follows:
170:
171: uint32 id
172: string targetpath
173: string linkpath
174:
175: 7. sftp: Server extension announcement in SSH_FXP_VERSION
176:
177: OpenSSH's sftp-server lists the extensions it supports using the
178: standard extension announcement mechanism in the SSH_FXP_VERSION server
179: hello packet:
180:
181: uint32 3 /* protocol version */
182: string ext1-name
183: string ext1-version
184: string ext2-name
185: string ext2-version
186: ...
187: string extN-name
188: string extN-version
189:
190: Each extension reports its integer version number as an ASCII encoded
191: string, e.g. "1". The version will be incremented if the extension is
192: ever changed in an incompatible way. The server MAY advertise the same
193: extension with multiple versions (though this is unlikely). Clients MUST
194: check the version number before attempting to use the extension.
195:
196: 8. sftp: Extension request "posix-rename@openssh.com"
197:
198: This operation provides a rename operation with POSIX semantics, which
199: are different to those provided by the standard SSH_FXP_RENAME in
200: draft-ietf-secsh-filexfer-02.txt. This request is implemented as a
201: SSH_FXP_EXTENDED request with the following format:
202:
203: uint32 id
204: string "posix-rename@openssh.com"
205: string oldpath
206: string newpath
207:
208: On receiving this request the server will perform the POSIX operation
209: rename(oldpath, newpath) and will respond with a SSH_FXP_STATUS message.
210: This extension is advertised in the SSH_FXP_VERSION hello with version
211: "1".
212:
213: 9. sftp: Extension requests "statvfs@openssh.com" and
214: "fstatvfs@openssh.com"
215:
216: These requests correspond to the statvfs and fstatvfs POSIX system
217: interfaces. The "statvfs@openssh.com" request operates on an explicit
218: pathname, and is formatted as follows:
219:
220: uint32 id
221: string "statvfs@openssh.com"
222: string path
223:
224: The "fstatvfs@openssh.com" operates on an open file handle:
225:
226: uint32 id
227: string "fstatvfs@openssh.com"
228: string handle
229:
230: These requests return a SSH_FXP_STATUS reply on failure. On success they
231: return the following SSH_FXP_EXTENDED_REPLY reply:
232:
233: uint32 id
234: uint64 f_bsize /* file system block size */
235: uint64 f_frsize /* fundamental fs block size */
236: uint64 f_blocks /* number of blocks (unit f_frsize) */
237: uint64 f_bfree /* free blocks in file system */
238: uint64 f_bavail /* free blocks for non-root */
239: uint64 f_files /* total file inodes */
240: uint64 f_ffree /* free file inodes */
241: uint64 f_favail /* free file inodes for to non-root */
242: uint64 f_fsid /* file system id */
243: uint64 f_flag /* bit mask of f_flag values */
244: uint64 f_namemax /* maximum filename length */
245:
246: The values of the f_flag bitmask are as follows:
247:
248: #define SSH_FXE_STATVFS_ST_RDONLY 0x1 /* read-only */
249: #define SSH_FXE_STATVFS_ST_NOSUID 0x2 /* no setuid */
250:
251: Both the "statvfs@openssh.com" and "fstatvfs@openssh.com" extensions are
252: advertised in the SSH_FXP_VERSION hello with version "2".
253:
254: $OpenBSD: PROTOCOL,v 1.12 2009/02/14 06:35:49 djm Exp $
CVSweb <webmaster@jp.NetBSD.org>
![[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 [cvs.NetBSD.org] / src / crypto / external / bsd / openssh / dist