]>
Commit | Line | Data |
---|---|---|
3c0ef626 | 1 | .\" -*- nroff -*- |
2 | .\" | |
3 | .\" $OpenBSD: RFC.nroff,v 1.2 2000/10/16 09:38:44 djm Exp $ | |
4 | .\" | |
5 | .pl 10.0i | |
6 | .po 0 | |
7 | .ll 7.2i | |
8 | .lt 7.2i | |
9 | .nr LL 7.2i | |
10 | .nr LT 7.2i | |
11 | .ds LF Ylonen | |
12 | .ds RF FORMFEED[Page %] | |
13 | .ds CF | |
14 | .ds LH Internet-Draft | |
15 | .ds RH 15 November 1995 | |
16 | .ds CH SSH (Secure Shell) Remote Login Protocol | |
17 | .na | |
18 | .hy 0 | |
19 | .in 0 | |
20 | Network Working Group T. Ylonen | |
21 | Internet-Draft Helsinki University of Technology | |
22 | draft-ylonen-ssh-protocol-00.txt 15 November 1995 | |
23 | Expires: 15 May 1996 | |
24 | ||
25 | .in 3 | |
26 | ||
27 | .ce | |
28 | The SSH (Secure Shell) Remote Login Protocol | |
29 | ||
30 | .ti 0 | |
31 | Status of This Memo | |
32 | ||
33 | This document is an Internet-Draft. Internet-Drafts are working | |
34 | documents of the Internet Engineering Task Force (IETF), its areas, | |
35 | and its working groups. Note that other groups may also distribute | |
36 | working documents as Internet-Drafts. | |
37 | ||
38 | Internet-Drafts are draft documents valid for a maximum of six | |
39 | months and may be updated, replaced, or obsoleted by other docu- | |
40 | ments at any time. It is inappropriate to use Internet-Drafts as | |
41 | reference material or to cite them other than as ``work in pro- | |
42 | gress.'' | |
43 | ||
44 | To learn the current status of any Internet-Draft, please check the | |
45 | ``1id-abstracts.txt'' listing contained in the Internet- Drafts Shadow | |
46 | Directories on ftp.is.co.za (Africa), nic.nordu.net (Europe), | |
47 | munnari.oz.au (Pacific Rim), ds.internic.net (US East Coast), or | |
48 | ftp.isi.edu (US West Coast). | |
49 | ||
50 | The distribution of this memo is unlimited. | |
51 | ||
52 | .ti 0 | |
53 | Introduction | |
54 | ||
55 | SSH (Secure Shell) is a program to log into another computer over a | |
56 | network, to execute commands in a remote machine, and to move files | |
57 | from one machine to another. It provides strong authentication and | |
58 | secure communications over insecure networks. Its features include | |
59 | the following: | |
60 | .IP o | |
61 | Closes several security holes (e.g., IP, routing, and DNS spoofing). | |
62 | New authentication methods: .rhosts together with RSA [RSA] based host | |
63 | authentication, and pure RSA authentication. | |
64 | .IP o | |
65 | All communications are automatically and transparently encrypted. | |
66 | Encryption is also used to protect integrity. | |
67 | .IP o | |
68 | X11 connection forwarding provides secure X11 sessions. | |
69 | .IP o | |
70 | Arbitrary TCP/IP ports can be redirected over the encrypted channel | |
71 | in both directions. | |
72 | .IP o | |
73 | Client RSA-authenticates the server machine in the beginning of every | |
74 | connection to prevent trojan horses (by routing or DNS spoofing) and | |
75 | man-in-the-middle attacks, and the server RSA-authenticates the client | |
76 | machine before accepting .rhosts or /etc/hosts.equiv authentication | |
77 | (to prevent DNS, routing, or IP spoofing). | |
78 | .IP o | |
79 | An authentication agent, running in the user's local workstation or | |
80 | laptop, can be used to hold the user's RSA authentication keys. | |
81 | .RT | |
82 | ||
83 | The goal has been to make the software as easy to use as possible for | |
84 | ordinary users. The protocol has been designed to be as secure as | |
85 | possible while making it possible to create implementations that | |
86 | are easy to use and install. The sample implementation has a number | |
87 | of convenient features that are not described in this document as they | |
88 | are not relevant for the protocol. | |
89 | ||
90 | ||
91 | .ti 0 | |
92 | Overview of the Protocol | |
93 | ||
94 | The software consists of a server program running on a server machine, | |
95 | and a client program running on a client machine (plus a few auxiliary | |
96 | programs). The machines are connected by an insecure IP [RFC0791] | |
97 | network (that can be monitored, tampered with, and spoofed by hostile | |
98 | parties). | |
99 | ||
100 | A connection is always initiated by the client side. The server | |
101 | listens on a specific port waiting for connections. Many clients may | |
102 | connect to the same server machine. | |
103 | ||
104 | The client and the server are connected via a TCP/IP [RFC0793] socket | |
105 | that is used for bidirectional communication. Other types of | |
106 | transport can be used but are currently not defined. | |
107 | ||
108 | When the client connects the server, the server accepts the connection | |
109 | and responds by sending back its version identification string. The | |
110 | client parses the server's identification, and sends its own | |
111 | identification. The purpose of the identification strings is to | |
112 | validate that the connection was to the correct port, declare the | |
113 | protocol version number used, and to declare the software version used | |
114 | on each side (for debugging purposes). The identification strings are | |
115 | human-readable. If either side fails to understand or support the | |
116 | other side's version, it closes the connection. | |
117 | ||
118 | After the protocol identification phase, both sides switch to a packet | |
119 | based binary protocol. The server starts by sending its host key | |
120 | (every host has an RSA key used to authenticate the host), server key | |
121 | (an RSA key regenerated every hour), and other information to the | |
122 | client. The client then generates a 256 bit session key, encrypts it | |
123 | using both RSA keys (see below for details), and sends the encrypted | |
124 | session key and selected cipher type to the server. Both sides then | |
125 | turn on encryption using the selected algorithm and key. The server | |
126 | sends an encrypted confirmation message to the client. | |
127 | ||
128 | The client then authenticates itself using any of a number of | |
129 | authentication methods. The currently supported authentication | |
130 | methods are .rhosts or /etc/hosts.equiv authentication (disabled by | |
131 | default), the same with RSA-based host authentication, RSA | |
132 | authentication, and password authentication. | |
133 | ||
134 | After successful authentication, the client makes a number of requests | |
135 | to prepare for the session. Typical requests include allocating a | |
136 | pseudo tty, starting X11 [X11] or TCP/IP port forwarding, starting | |
137 | authentication agent forwarding, and executing the shell or a command. | |
138 | ||
139 | When a shell or command is executed, the connection enters interactive | |
140 | session mode. In this mode, data is passed in both directions, | |
141 | new forwarded connections may be opened, etc. The interactive session | |
142 | normally terminates when the server sends the exit status of the | |
143 | program to the client. | |
144 | ||
145 | ||
146 | The protocol makes several reservations for future extensibility. | |
147 | First of all, the initial protocol identification messages include the | |
148 | protocol version number. Second, the first packet by both sides | |
149 | includes a protocol flags field, which can be used to agree on | |
150 | extensions in a compatible manner. Third, the authentication and | |
151 | session preparation phases work so that the client sends requests to | |
152 | the server, and the server responds with success or failure. If the | |
153 | client sends a request that the server does not support, the server | |
154 | simply returns failure for it. This permits compatible addition of | |
155 | new authentication methods and preparation operations. The | |
156 | interactive session phase, on the other hand, works asynchronously and | |
157 | does not permit the use of any extensions (because there is no easy | |
158 | and reliable way to signal rejection to the other side and problems | |
159 | would be hard to debug). Any compatible extensions to this phase must | |
160 | be agreed upon during any of the earlier phases. | |
161 | ||
162 | .ti 0 | |
163 | The Binary Packet Protocol | |
164 | ||
165 | After the protocol identification strings, both sides only send | |
166 | specially formatted packets. The packet layout is as follows: | |
167 | .IP o | |
168 | Packet length: 32 bit unsigned integer, coded as four 8-bit bytes, msb | |
169 | first. Gives the length of the packet, not including the length field | |
170 | and padding. The maximum length of a packet (not including the length | |
171 | field and padding) is 262144 bytes. | |
172 | .IP o | |
173 | Padding: 1-8 bytes of random data (or zeroes if not encrypting). The | |
174 | amount of padding is (8 - (length % 8)) bytes (where % stands for the | |
175 | modulo operator). The rationale for always having some random padding | |
176 | at the beginning of each packet is to make known plaintext attacks | |
177 | more difficult. | |
178 | .IP o | |
179 | Packet type: 8-bit unsigned byte. The value 255 is reserved for | |
180 | future extension. | |
181 | .IP o | |
182 | Data: binary data bytes, depending on the packet type. The number of | |
183 | data bytes is the "length" field minus 5. | |
184 | .IP o | |
185 | Check bytes: 32-bit crc, four 8-bit bytes, msb first. The crc is the | |
186 | Cyclic Redundancy Check, with the polynomial 0xedb88320, of the | |
187 | Padding, Packet type, and Data fields. The crc is computed before | |
188 | any encryption. | |
189 | .RT | |
190 | ||
191 | The packet, except for the length field, may be encrypted using any of | |
192 | a number of algorithms. The length of the encrypted part (Padding + | |
193 | Type + Data + Check) is always a multiple of 8 bytes. Typically the | |
194 | cipher is used in a chained mode, with all packets chained together as | |
195 | if it was a single data stream (the length field is never included in | |
196 | the encryption process). Details of encryption are described below. | |
197 | ||
198 | When the session starts, encryption is turned off. Encryption is | |
199 | enabled after the client has sent the session key. The encryption | |
200 | algorithm to use is selected by the client. | |
201 | ||
202 | ||
203 | .ti 0 | |
204 | Packet Compression | |
205 | ||
206 | If compression is supported (it is an optional feature, see | |
207 | SSH_CMSG_REQUEST_COMPRESSION below), the packet type and data fields | |
208 | of the packet are compressed using the gzip deflate algorithm [GZIP]. | |
209 | If compression is in effect, the packet length field indicates the | |
210 | length of the compressed data, plus 4 for the crc. The amount of | |
211 | padding is computed from the compressed data, so that the amount of | |
212 | data to be encrypted becomes a multiple of 8 bytes. | |
213 | ||
214 | When compressing, the packets (type + data portions) in each direction | |
215 | are compressed as if they formed a continuous data stream, with only the | |
216 | current compression block flushed between packets. This corresponds | |
217 | to the GNU ZLIB library Z_PARTIAL_FLUSH option. The compression | |
218 | dictionary is not flushed between packets. The two directions are | |
219 | compressed independently of each other. | |
220 | ||
221 | ||
222 | .ti 0 | |
223 | Packet Encryption | |
224 | ||
225 | The protocol supports several encryption methods. During session | |
226 | initialization, the server sends a bitmask of all encryption methods | |
227 | that it supports, and the client selects one of these methods. The | |
228 | client also generates a 256-bit random session key (32 8-bit bytes) and | |
229 | sends it to the server. | |
230 | ||
231 | The encryption methods supported by the current implementation, and | |
232 | their codes are: | |
233 | .TS | |
234 | center; | |
235 | l r l. | |
236 | SSH_CIPHER_NONE 0 No encryption | |
237 | SSH_CIPHER_IDEA 1 IDEA in CFB mode | |
238 | SSH_CIPHER_DES 2 DES in CBC mode | |
239 | SSH_CIPHER_3DES 3 Triple-DES in CBC mode | |
240 | SSH_CIPHER_TSS 4 An experimental stream cipher | |
241 | SSH_CIPHER_RC4 5 RC4 | |
242 | .TE | |
243 | ||
244 | All implementations are required to support SSH_CIPHER_DES and | |
245 | SSH_CIPHER_3DES. Supporting SSH_CIPHER_IDEA, SSH_CIPHER_RC4, and | |
246 | SSH_CIPHER_NONE is recommended. Support for SSH_CIPHER_TSS is | |
247 | optional (and it is not described in this document). Other ciphers | |
248 | may be added at a later time; support for them is optional. | |
249 | ||
250 | For encryption, the encrypted portion of the packet is considered a | |
251 | linear byte stream. The length of the stream is always a multiple of | |
252 | 8. The encrypted portions of consecutive packets (in the same | |
253 | direction) are encrypted as if they were a continuous buffer (that is, | |
254 | any initialization vectors are passed from the previous packet to the | |
255 | next packet). Data in each direction is encrypted independently. | |
256 | .IP SSH_CIPHER_DES | |
257 | The key is taken from the first 8 bytes of the session key. The least | |
258 | significant bit of each byte is ignored. This results in 56 bits of | |
259 | key data. DES [DES] is used in CBC mode. The iv (initialization vector) is | |
260 | initialized to all zeroes. | |
261 | .IP SSH_CIPHER_3DES | |
262 | The variant of triple-DES used here works as follows: there are three | |
263 | independent DES-CBC ciphers, with independent initialization vectors. | |
264 | The data (the whole encrypted data stream) is first encrypted with the | |
265 | first cipher, then decrypted with the second cipher, and finally | |
266 | encrypted with the third cipher. All these operations are performed | |
267 | in CBC mode. | |
268 | ||
269 | The key for the first cipher is taken from the first 8 bytes of the | |
270 | session key; the key for the next cipher from the next 8 bytes, and | |
271 | the key for the third cipher from the following 8 bytes. All three | |
272 | initialization vectors are initialized to zero. | |
273 | ||
274 | (Note: the variant of 3DES used here differs from some other | |
275 | descriptions.) | |
276 | .IP SSH_CIPHER_IDEA | |
277 | The key is taken from the first 16 bytes of the session key. IDEA | |
278 | [IDEA] is used in CFB mode. The initialization vector is initialized | |
279 | to all zeroes. | |
280 | .IP SSH_CIPHER_TSS | |
281 | All 32 bytes of the session key are used as the key. | |
282 | ||
283 | There is no reference available for the TSS algorithm; it is currently | |
284 | only documented in the sample implementation source code. The | |
285 | security of this cipher is unknown (but it is quite fast). The cipher | |
286 | is basically a stream cipher that uses MD5 as a random number | |
287 | generator and takes feedback from the data. | |
288 | .IP SSH_CIPHER_RC4 | |
289 | The first 16 bytes of the session key are used as the key for the | |
290 | server to client direction. The remaining 16 bytes are used as the | |
291 | key for the client to server direction. This gives independent | |
292 | 128-bit keys for each direction. | |
293 | ||
294 | This algorithm is the alleged RC4 cipher posted to the Usenet in 1995. | |
295 | It is widely believed to be equivalent with the original RSADSI RC4 | |
296 | cipher. This is a very fast algorithm. | |
297 | .RT | |
298 | ||
299 | ||
300 | .ti 0 | |
301 | Data Type Encodings | |
302 | ||
303 | The Data field of each packet contains data encoded as described in | |
304 | this section. There may be several data items; each item is coded as | |
305 | described here, and their representations are concatenated together | |
306 | (without any alignment or padding). | |
307 | ||
308 | Each data type is stored as follows: | |
309 | .IP "8-bit byte" | |
310 | The byte is stored directly as a single byte. | |
311 | .IP "32-bit unsigned integer" | |
312 | Stored in 4 bytes, msb first. | |
313 | .IP "Arbitrary length binary string" | |
314 | First 4 bytes are the length of the string, msb first (not including | |
315 | the length itself). The following "length" bytes are the string | |
316 | value. There are no terminating null characters. | |
317 | .IP "Multiple-precision integer" | |
318 | First 2 bytes are the number of bits in the integer, msb first (for | |
319 | example, the value 0x00012345 would have 17 bits). The value zero has | |
320 | zero bits. It is permissible that the number of bits be larger than the | |
321 | real number of bits. | |
322 | ||
323 | The number of bits is followed by (bits + 7) / 8 bytes of binary data, | |
324 | msb first, giving the value of the integer. | |
325 | .RT | |
326 | ||
327 | ||
328 | .ti 0 | |
329 | TCP/IP Port Number and Other Options | |
330 | ||
331 | The server listens for connections on TCP/IP port 22. | |
332 | ||
333 | The client may connect the server from any port. However, if the | |
334 | client wishes to use any form of .rhosts or /etc/hosts.equiv | |
335 | authentication, it must connect from a privileged port (less than | |
336 | 1024). | |
337 | ||
338 | For the IP Type of Service field [RFC0791], it is recommended that | |
339 | interactive sessions (those having a user terminal or forwarding X11 | |
340 | connections) use the IPTOS_LOWDELAY, and non-interactive connections | |
341 | use IPTOS_THROUGHPUT. | |
342 | ||
343 | It is recommended that keepalives are used, because otherwise programs | |
344 | on the server may never notice if the other end of the connection is | |
345 | rebooted. | |
346 | ||
347 | ||
348 | .ti 0 | |
349 | Protocol Version Identification | |
350 | ||
351 | After the socket is opened, the server sends an identification string, | |
352 | which is of the form | |
353 | "SSH-<protocolmajor>.<protocolminor>-<version>\\n", where | |
354 | <protocolmajor> and <protocolminor> are integers and specify the | |
355 | protocol version number (not software distribution version). | |
356 | <version> is server side software version string (max 40 characters); | |
357 | it is not interpreted by the remote side but may be useful for | |
358 | debugging. | |
359 | ||
360 | The client parses the server's string, and sends a corresponding | |
361 | string with its own information in response. If the server has lower | |
362 | version number, and the client contains special code to emulate it, | |
363 | the client responds with the lower number; otherwise it responds with | |
364 | its own number. The server then compares the version number the | |
365 | client sent with its own, and determines whether they can work | |
366 | together. The server either disconnects, or sends the first packet | |
367 | using the binary packet protocol and both sides start working | |
368 | according to the lower of the protocol versions. | |
369 | ||
370 | By convention, changes which keep the protocol compatible with | |
371 | previous versions keep the same major protocol version; changes that | |
372 | are not compatible increment the major version (which will hopefully | |
373 | never happen). The version described in this document is 1.3. | |
374 | ||
375 | The client will | |
376 | ||
377 | .ti 0 | |
378 | Key Exchange and Server Host Authentication | |
379 | ||
380 | The first message sent by the server using the packet protocol is | |
381 | SSH_SMSG_PUBLIC_KEY. It declares the server's host key, server public | |
382 | key, supported ciphers, supported authentication methods, and flags | |
383 | for protocol extensions. It also contains a 64-bit random number | |
384 | (cookie) that must be returned in the client's reply (to make IP | |
385 | spoofing more difficult). No encryption is used for this message. | |
386 | ||
387 | Both sides compute a session id as follows. The modulus of the server | |
388 | key is interpreted as a byte string (without explicit length field, | |
389 | with minimum length able to hold the whole value), most significant | |
390 | byte first. This string is concatenated with the server host key | |
391 | interpreted the same way. Additionally, the cookie is concatenated | |
392 | with this. Both sides compute MD5 of the resulting string. The | |
393 | resulting 16 bytes (128 bits) are stored by both parties and are | |
394 | called the session id. | |
395 | ||
396 | The client responds with a SSH_CMSG_SESSION_KEY message, which | |
397 | contains the selected cipher type, a copy of the 64-bit cookie sent by | |
398 | the server, client's protocol flags, and a session key encrypted | |
399 | with both the server's host key and server key. No encryption is used | |
400 | for this message. | |
401 | ||
402 | The session key is 32 8-bit bytes (a total of 256 random bits | |
403 | generated by the client). The client first xors the 16 bytes of the | |
404 | session id with the first 16 bytes of the session key. The resulting | |
405 | string is then encrypted using the smaller key (one with smaller | |
406 | modulus), and the result is then encrypted using the other key. The | |
407 | number of bits in the public modulus of the two keys must differ by at | |
408 | least 128 bits. | |
409 | ||
410 | At each encryption step, a multiple-precision integer is constructed | |
411 | from the data to be encrypted as follows (the integer is here | |
412 | interpreted as a sequence of bytes, msb first; the number of bytes is | |
413 | the number of bytes needed to represent the modulus). | |
414 | ||
415 | The most significant byte (which is only partial as the value must be | |
416 | less than the public modulus, which is never a power of two) is zero. | |
417 | ||
418 | The next byte contains the value 2 (which stands for public-key | |
419 | encrypted data in the PKCS standard [PKCS#1]). Then, there are | |
420 | non-zero random bytes to fill any unused space, a zero byte, and the | |
421 | data to be encrypted in the least significant bytes, the last byte of | |
422 | the data in the least significant byte. | |
423 | ||
424 | This algorithm is used twice. First, it is used to encrypt the 32 | |
425 | random bytes generated by the client to be used as the session key | |
426 | (xored by the session id). This value is converted to an integer as | |
427 | described above, and encrypted with RSA using the key with the smaller | |
428 | modulus. The resulting integer is converted to a byte stream, msb | |
429 | first. This byte stream is padded and encrypted identically using the | |
430 | key with the larger modulus. | |
431 | ||
432 | After the client has sent the session key, it starts to use the | |
433 | selected algorithm and key for decrypting any received packets, and | |
434 | for encrypting any sent packets. Separate ciphers are used for | |
435 | different directions (that is, both directions have separate | |
436 | initialization vectors or other state for the ciphers). | |
437 | ||
438 | When the server has received the session key message, and has turned | |
439 | on encryption, it sends a SSH_SMSG_SUCCESS message to the client. | |
440 | ||
441 | The recommended size of the host key is 1024 bits, and 768 bits for | |
442 | the server key. The minimum size is 512 bits for the smaller key. | |
443 | ||
444 | ||
445 | .ti 0 | |
446 | Declaring the User Name | |
447 | ||
448 | The client then sends a SSH_CMSG_USER message to the server. This | |
449 | message specifies the user name to log in as. | |
450 | ||
451 | The server validates that such a user exists, checks whether | |
452 | authentication is needed, and responds with either SSH_SMSG_SUCCESS or | |
453 | SSH_SMSG_FAILURE. SSH_SMSG_SUCCESS indicates that no authentication | |
454 | is needed for this user (no password), and authentication phase has | |
455 | now been completed. SSH_SMSG_FAILURE indicates that authentication is | |
456 | needed (or the user does not exist). | |
457 | ||
458 | If the user does not exist, it is recommended that this returns | |
459 | failure, but the server keeps reading messages from the client, and | |
460 | responds to any messages (except SSH_MSG_DISCONNECT, SSH_MSG_IGNORE, | |
461 | and SSH_MSG_DEBUG) with SSH_SMSG_FAILURE. This way the client cannot | |
462 | be certain whether the user exists. | |
463 | ||
464 | ||
465 | .ti 0 | |
466 | Authentication Phase | |
467 | ||
468 | Provided the server didn't immediately accept the login, an | |
469 | authentication exchange begins. The client sends messages to the | |
470 | server requesting different types of authentication in arbitrary order as | |
471 | many times as desired (however, the server may close the connection | |
472 | after a timeout). The server always responds with SSH_SMSG_SUCCESS if | |
473 | it has accepted the authentication, and with SSH_SMSG_FAILURE if it has | |
474 | denied authentication with the requested method or it does not | |
475 | recognize the message. Some authentication methods cause an exchange | |
476 | of further messages before the final result is sent. The | |
477 | authentication phase ends when the server responds with success. | |
478 | ||
479 | The recommended value for the authentication timeout (timeout before | |
480 | disconnecting if no successful authentication has been made) is 5 | |
481 | minutes. | |
482 | ||
483 | The following authentication methods are currently supported: | |
484 | .TS | |
485 | center; | |
486 | l r l. | |
487 | SSH_AUTH_RHOSTS 1 .rhosts or /etc/hosts.equiv | |
488 | SSH_AUTH_RSA 2 pure RSA authentication | |
489 | SSH_AUTH_PASSWORD 3 password authentication | |
490 | SSH_AUTH_RHOSTS_RSA 4 .rhosts with RSA host authentication | |
491 | .TE | |
492 | .IP SSH_AUTH_RHOSTS | |
493 | ||
494 | This is the authentication method used by rlogin and rsh [RFC1282]. | |
495 | ||
496 | The client sends SSH_CMSG_AUTH_RHOSTS with the client-side user name | |
497 | as an argument. | |
498 | ||
499 | The server checks whether to permit authentication. On UNIX systems, | |
500 | this is usually done by checking /etc/hosts.equiv, and .rhosts in the | |
501 | user's home directory. The connection must come from a privileged | |
502 | port. | |
503 | ||
504 | It is recommended that the server checks that there are no IP options | |
505 | (such as source routing) specified for the socket before accepting | |
506 | this type of authentication. The client host name should be | |
507 | reverse-mapped and then forward mapped to ensure that it has the | |
508 | proper IP-address. | |
509 | ||
510 | This authentication method trusts the remote host (root on the remote | |
511 | host can pretend to be any other user on that host), the name | |
512 | services, and partially the network: anyone who can see packets coming | |
513 | out from the server machine can do IP-spoofing and pretend to be any | |
514 | machine; however, the protocol prevents blind IP-spoofing (which used | |
515 | to be possible with rlogin). | |
516 | ||
517 | Many sites probably want to disable this authentication method because | |
518 | of the fundamental insecurity of conventional .rhosts or | |
519 | /etc/hosts.equiv authentication when faced with spoofing. It is | |
520 | recommended that this method not be supported by the server by | |
521 | default. | |
522 | .IP SSH_AUTH_RHOSTS_RSA | |
523 | ||
524 | In addition to conventional .rhosts and hosts.equiv authentication, | |
525 | this method additionally requires that the client host be | |
526 | authenticated using RSA. | |
527 | ||
528 | The client sends SSH_CMSG_AUTH_RHOSTS_RSA specifying the client-side | |
529 | user name, and the public host key of the client host. | |
530 | ||
531 | The server first checks if normal .rhosts or /etc/hosts.equiv | |
532 | authentication would be accepted, and if not, responds with | |
533 | SSH_SMSG_FAILURE. Otherwise, it checks whether it knows the host key | |
534 | for the client machine (using the same name for the host that was used | |
535 | for checking the .rhosts and /etc/hosts.equiv files). If it does not | |
536 | know the RSA key for the client, access is denied and SSH_SMSG_FAILURE | |
537 | is sent. | |
538 | ||
539 | If the server knows the host key of the client machine, it verifies | |
540 | that the given host key matches that known for the client. If not, | |
541 | access is denied and SSH_SMSG_FAILURE is sent. | |
542 | ||
543 | The server then sends a SSH_SMSG_AUTH_RSA_CHALLENGE message containing | |
544 | an encrypted challenge for the client. The challenge is 32 8-bit | |
545 | random bytes (256 bits). When encrypted, the highest (partial) byte | |
546 | is left as zero, the next byte contains the value 2, the following are | |
547 | non-zero random bytes, followed by a zero byte, and the challenge put | |
548 | in the remaining bytes. This is then encrypted using RSA with the | |
549 | client host's public key. (The padding and encryption algorithm is | |
550 | the same as that used for the session key.) | |
551 | ||
552 | The client decrypts the challenge using its private host key, | |
553 | concatenates this with the session id, and computes an MD5 checksum | |
554 | of the resulting 48 bytes. The MD5 output is returned as 16 bytes in | |
555 | a SSH_CMSG_AUTH_RSA_RESPONSE message. (MD5 is used to deter chosen | |
556 | plaintext attacks against RSA; the session id binds it to a specific | |
557 | session). | |
558 | ||
559 | The server verifies that the MD5 of the decrypted challenge returned by | |
560 | the client matches that of the original value, and sends SSH_SMSG_SUCCESS if | |
561 | so. Otherwise it sends SSH_SMSG_FAILURE and refuses the | |
562 | authentication attempt. | |
563 | ||
564 | This authentication method trusts the client side machine in that root | |
565 | on that machine can pretend to be any user on that machine. | |
566 | Additionally, it trusts the client host key. The name and/or IP | |
567 | address of the client host is only used to select the public host key. | |
568 | The same host name is used when scanning .rhosts or /etc/hosts.equiv | |
569 | and when selecting the host key. It would in principle be possible to | |
570 | eliminate the host name entirely and substitute it directly by the | |
571 | host key. IP and/or DNS [RFC1034] spoofing can only be used | |
572 | to pretend to be a host for which the attacker has the private host | |
573 | key. | |
574 | .IP SSH_AUTH_RSA | |
575 | ||
576 | The idea behind RSA authentication is that the server recognizes the | |
577 | public key offered by the client, generates a random challenge, and | |
578 | encrypts the challenge with the public key. The client must then | |
579 | prove that it has the corresponding private key by decrypting the | |
580 | challenge. | |
581 | ||
582 | The client sends SSH_CMSG_AUTH_RSA with public key modulus (n) as an | |
583 | argument. | |
584 | ||
585 | The server may respond immediately with SSH_SMSG_FAILURE if it does | |
586 | not permit authentication with this key. Otherwise it generates a | |
587 | challenge, encrypts it using the user's public key (stored on the | |
588 | server and identified using the modulus), and sends | |
589 | SSH_SMSG_AUTH_RSA_CHALLENGE with the challenge (mp-int) as an | |
590 | argument. | |
591 | ||
592 | The challenge is 32 8-bit random bytes (256 bits). When encrypted, | |
593 | the highest (partial) byte is left as zero, the next byte contains the | |
594 | value 2, the following are non-zero random bytes, followed by a zero | |
595 | byte, and the challenge put in the remaining bytes. This is then | |
596 | encrypted with the public key. (The padding and encryption algorithm | |
597 | is the same as that used for the session key.) | |
598 | ||
599 | The client decrypts the challenge using its private key, concatenates | |
600 | it with the session id, and computes an MD5 checksum of the resulting | |
601 | 48 bytes. The MD5 output is returned as 16 bytes in a | |
602 | SSH_CMSG_AUTH_RSA_RESPONSE message. (Note that the MD5 is necessary | |
603 | to avoid chosen plaintext attacks against RSA; the session id binds it | |
604 | to a specific session.) | |
605 | ||
606 | The server verifies that the MD5 of the decrypted challenge returned | |
607 | by the client matches that of the original value, and sends | |
608 | SSH_SMSG_SUCCESS if so. Otherwise it sends SSH_SMSG_FAILURE and | |
609 | refuses the authentication attempt. | |
610 | ||
611 | This authentication method does not trust the remote host, the | |
612 | network, name services, or anything else. Authentication is based | |
613 | solely on the possession of the private identification keys. Anyone | |
614 | in possession of the private keys can log in, but nobody else. | |
615 | ||
616 | The server may have additional requirements for a successful | |
617 | authentiation. For example, to limit damage due to a compromised RSA | |
618 | key, a server might restrict access to a limited set of hosts. | |
619 | .IP SSH_AUTH_PASSWORD | |
620 | ||
621 | The client sends a SSH_CMSG_AUTH_PASSWORD message with the plain text | |
622 | password. (Note that even though the password is plain text inside | |
623 | the message, it is normally encrypted by the packet mechanism.) | |
624 | ||
625 | The server verifies the password, and sends SSH_SMSG_SUCCESS if | |
626 | authentication was accepted and SSH_SMSG_FAILURE otherwise. | |
627 | ||
628 | Note that the password is read from the user by the client; the user | |
629 | never interacts with a login program. | |
630 | ||
631 | This authentication method does not trust the remote host, the | |
632 | network, name services or anything else. Authentication is based | |
633 | solely on the possession of the password. Anyone in possession of the | |
634 | password can log in, but nobody else. | |
635 | .RT | |
636 | ||
637 | .ti 0 | |
638 | Preparatory Operations | |
639 | ||
640 | After successful authentication, the server waits for a request from | |
641 | the client, processes the request, and responds with SSH_SMSG_SUCCESS | |
642 | whenever a request has been successfully processed. If it receives a | |
643 | message that it does not recognize or it fails to honor a request, it | |
644 | returns SSH_SMSG_FAILURE. It is expected that new message types might | |
645 | be added to this phase in future. | |
646 | ||
647 | The following messages are currently defined for this phase. | |
648 | .IP SSH_CMSG_REQUEST_COMPRESSION | |
649 | Requests that compression be enabled for this session. A | |
650 | gzip-compatible compression level (1-9) is passed as an argument. | |
651 | .IP SSH_CMSG_REQUEST_PTY | |
652 | Requests that a pseudo terminal device be allocated for this session. | |
653 | The user terminal type and terminal modes are supplied as arguments. | |
654 | .IP SSH_CMSG_X11_REQUEST_FORWARDING | |
655 | Requests forwarding of X11 connections from the remote machine to the | |
656 | local machine over the secure channel. Causes an internet-domain | |
657 | socket to be allocated and the DISPLAY variable to be set on the server. | |
658 | X11 authentication data is automatically passed to the server, and the | |
659 | client may implement spoofing of authentication data for added | |
660 | security. The authentication data is passed as arguments. | |
661 | .IP SSH_CMSG_PORT_FORWARD_REQUEST | |
662 | Requests forwarding of a TCP/IP port on the server host over the | |
663 | secure channel. What happens is that whenever a connection is made to | |
664 | the port on the server, a connection will be made from the client end | |
665 | to the specified host/port. Any user can forward unprivileged ports; | |
666 | only the root can forward privileged ports (as determined by | |
667 | authentication done earlier). | |
668 | .IP SSH_CMSG_AGENT_REQUEST_FORWARDING | |
669 | Requests forwarding of the connection to the authentication agent. | |
670 | .IP SSH_CMSG_EXEC_SHELL | |
671 | Starts a shell (command interpreter) for the user, and moves into | |
672 | interactive session mode. | |
673 | .IP SSH_CMSG_EXEC_CMD | |
674 | Executes the given command (actually "<shell> -c <command>" or | |
675 | equivalent) for the user, and moves into interactive session mode. | |
676 | .RT | |
677 | ||
678 | ||
679 | .ti 0 | |
680 | Interactive Session and Exchange of Data | |
681 | ||
682 | During the interactive session, any data written by the shell or | |
683 | command running on the server machine is forwarded to stdin or | |
684 | stderr on the client machine, and any input available from stdin on | |
685 | the client machine is forwarded to the program on the server machine. | |
686 | ||
687 | All exchange is asynchronous; either side can send at any time, and | |
688 | there are no acknowledgements (TCP/IP already provides reliable | |
689 | transport, and the packet protocol protects against tampering or IP | |
690 | spoofing). | |
691 | ||
692 | When the client receives EOF from its standard input, it will send | |
693 | SSH_CMSG_EOF; however, this in no way terminates the exchange. The | |
694 | exchange terminates and interactive mode is left when the server sends | |
695 | SSH_SMSG_EXITSTATUS to indicate that the client program has | |
696 | terminated. Alternatively, either side may disconnect at any time by | |
697 | sending SSH_MSG_DISCONNECT or closing the connection. | |
698 | ||
699 | The server may send any of the following messages: | |
700 | .IP SSH_SMSG_STDOUT_DATA | |
701 | Data written to stdout by the program running on the server. The data | |
702 | is passed as a string argument. The client writes this data to | |
703 | stdout. | |
704 | .IP SSH_SMSG_STDERR_DATA | |
705 | Data written to stderr by the program running on the server. The data | |
706 | is passed as a string argument. The client writes this data to | |
707 | stderr. (Note that if the program is running on a tty, it is not | |
708 | possible to separate stdout and stderr data, and all data will be sent | |
709 | as stdout data.) | |
710 | .IP SSH_SMSG_EXITSTATUS | |
711 | Indicates that the shell or command has exited. Exit status is passed | |
712 | as an integer argument. This message causes termination of the | |
713 | interactive session. | |
714 | .IP SSH_SMSG_AGENT_OPEN | |
715 | Indicates that someone on the server side is requesting a connection | |
716 | to the authentication agent. The server-side channel number is passed | |
717 | as an argument. The client must respond with either | |
718 | SSH_CHANNEL_OPEN_CONFIRMATION or SSH_CHANNEL_OPEN_FAILURE. | |
719 | .IP SSH_SMSG_X11_OPEN | |
720 | Indicates that a connection has been made to the X11 socket on the | |
721 | server side and should be forwarded to the real X server. An integer | |
722 | argument indicates the channel number allocated for this connection on | |
723 | the server side. The client should send back either | |
724 | SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with | |
725 | the same server side channel number. | |
726 | .IP SSH_MSG_PORT_OPEN | |
727 | Indicates that a connection has been made to a port on the server side | |
728 | for which forwarding has been requested. Arguments are server side | |
729 | channel number, host name to connect to, and port to connect to. The | |
730 | client should send back either | |
731 | SSH_MSG_CHANNEL_OPEN_CONFIRMATION or SSH_MSG_CHANNEL_OPEN_FAILURE with | |
732 | the same server side channel number. | |
733 | .IP SSH_MSG_CHANNEL_OPEN_CONFIRMATION | |
734 | This is sent by the server to indicate that it has opened a connection | |
735 | as requested in a previous message. The first argument indicates the | |
736 | client side channel number, and the second argument is the channel number | |
737 | that the server has allocated for this connection. | |
738 | .IP SSH_MSG_CHANNEL_OPEN_FAILURE | |
739 | This is sent by the server to indicate that it failed to open a | |
740 | connection as requested in a previous message. The client-side | |
741 | channel number is passed as an argument. The client will close the | |
742 | descriptor associated with the channel and free the channel. | |
743 | .IP SSH_MSG_CHANNEL_DATA | |
744 | This packet contains data for a channel from the server. The first | |
745 | argument is the client-side channel number, and the second argument (a | |
746 | string) is the data. | |
747 | .IP SSH_MSG_CHANNEL_CLOSE | |
748 | This is sent by the server to indicate that whoever was in the other | |
749 | end of the channel has closed it. The argument is the client side channel | |
750 | number. The client will let all buffered data in the channel to | |
751 | drain, and when ready, will close the socket, free the channel, and | |
752 | send the server a SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message for the | |
753 | channel. | |
754 | .IP SSH_MSG_CHANNEL_CLOSE_CONFIRMATION | |
755 | This is send by the server to indicate that a channel previously | |
756 | closed by the client has now been closed on the server side as well. | |
757 | The argument indicates the client channel number. The client frees | |
758 | the channel. | |
759 | .RT | |
760 | ||
761 | The client may send any of the following messages: | |
762 | .IP SSH_CMSG_STDIN_DATA | |
763 | This is data to be sent as input to the program running on the server. | |
764 | The data is passed as a string. | |
765 | .IP SSH_CMSG_EOF | |
766 | Indicates that the client has encountered EOF while reading standard | |
767 | input. The server will allow any buffered input data to drain, and | |
768 | will then close the input to the program. | |
769 | .IP SSH_CMSG_WINDOW_SIZE | |
770 | Indicates that window size on the client has been changed. The server | |
771 | updates the window size of the tty and causes SIGWINCH to be sent to | |
772 | the program. The new window size is passed as four integer arguments: | |
773 | row, col, xpixel, ypixel. | |
774 | .IP SSH_MSG_PORT_OPEN | |
775 | Indicates that a connection has been made to a port on the client side | |
776 | for which forwarding has been requested. Arguments are client side | |
777 | channel number, host name to connect to, and port to connect to. The | |
778 | server should send back either SSH_MSG_CHANNEL_OPEN_CONFIRMATION or | |
779 | SSH_MSG_CHANNEL_OPEN_FAILURE with the same client side channel number. | |
780 | .IP SSH_MSG_CHANNEL_OPEN_CONFIRMATION | |
781 | This is sent by the client to indicate that it has opened a connection | |
782 | as requested in a previous message. The first argument indicates the | |
783 | server side channel number, and the second argument is the channel | |
784 | number that the client has allocated for this connection. | |
785 | .IP SSH_MSG_CHANNEL_OPEN_FAILURE | |
786 | This is sent by the client to indicate that it failed to open a | |
787 | connection as requested in a previous message. The server side | |
788 | channel number is passed as an argument. The server will close the | |
789 | descriptor associated with the channel and free the channel. | |
790 | .IP SSH_MSG_CHANNEL_DATA | |
791 | This packet contains data for a channel from the client. The first | |
792 | argument is the server side channel number, and the second argument (a | |
793 | string) is the data. | |
794 | .IP SSH_MSG_CHANNEL_CLOSE | |
795 | This is sent by the client to indicate that whoever was in the other | |
796 | end of the channel has closed it. The argument is the server channel | |
797 | number. The server will allow buffered data to drain, and when ready, | |
798 | will close the socket, free the channel, and send the client a | |
799 | SSH_MSG_CHANNEL_CLOSE_CONFIRMATION message for the channel. | |
800 | .IP SSH_MSG_CHANNEL_CLOSE_CONFIRMATION | |
801 | This is send by the client to indicate that a channel previously | |
802 | closed by the server has now been closed on the client side as well. | |
803 | The argument indicates the server channel number. The server frees | |
804 | the channel. | |
805 | .RT | |
806 | ||
807 | Any unsupported messages during interactive mode cause the connection | |
808 | to be terminated with SSH_MSG_DISCONNECT and an error message. | |
809 | Compatible protocol upgrades should agree about any extensions during | |
810 | the preparation phase or earlier. | |
811 | ||
812 | ||
813 | .ti 0 | |
814 | Termination of the Connection | |
815 | ||
816 | Normal termination of the connection is always initiated by the server | |
817 | by sending SSH_SMSG_EXITSTATUS after the program has exited. The | |
818 | client responds to this message by sending SSH_CMSG_EXIT_CONFIRMATION | |
819 | and closes the socket; the server then closes the socket. There are | |
820 | two purposes for the confirmation: some systems may lose previously | |
821 | sent data when the socket is closed, and closing the client side first | |
822 | causes any TCP/IP TIME_WAIT [RFC0793] waits to occur on the client side, not | |
823 | consuming server resources. | |
824 | ||
825 | If the program terminates due to a signal, the server will send | |
826 | SSH_MSG_DISCONNECT with an appropriate message. If the connection is | |
827 | closed, all file descriptors to the program will be closed and the | |
828 | server will exit. If the program runs on a tty, the kernel sends it | |
829 | the SIGHUP signal when the pty master side is closed. | |
830 | ||
831 | .ti 0 | |
832 | Protocol Flags | |
833 | ||
834 | Both the server and the client pass 32 bits of protocol flags to the | |
835 | other side. The flags are intended for compatible protocol extension; | |
836 | the server first announces which added capabilities it supports, and | |
837 | the client then sends the capabilities that it supports. | |
838 | ||
839 | The following flags are currently defined (the values are bit masks): | |
840 | .IP "1 SSH_PROTOFLAG_SCREEN_NUMBER" | |
841 | This flag can only be sent by the client. It indicates that the X11 | |
842 | forwarding requests it sends will include the screen number. | |
843 | .IP "2 SSH_PROTOFLAG_HOST_IN_FWD_OPEN" | |
844 | If both sides specify this flag, SSH_SMSG_X11_OPEN and | |
845 | SSH_MSG_PORT_OPEN messages will contain an additional field containing | |
846 | a description of the host at the other end of the connection. | |
847 | .RT | |
848 | ||
849 | .ti 0 | |
850 | Detailed Description of Packet Types and Formats | |
851 | ||
852 | The supported packet types and the corresponding message numbers are | |
853 | given in the following table. Messages with _MSG_ in their name may | |
854 | be sent by either side. Messages with _CMSG_ are only sent by the | |
855 | client, and messages with _SMSG_ only by the server. | |
856 | ||
857 | A packet may contain additional data after the arguments specified | |
858 | below. Any such data should be ignored by the receiver. However, it | |
859 | is recommended that no such data be stored without good reason. (This | |
860 | helps build compatible extensions.) | |
861 | .IP "0 SSH_MSG_NONE" | |
862 | This code is reserved. This message type is never sent. | |
863 | .IP "1 SSH_MSG_DISCONNECT" | |
864 | .TS | |
865 | ; | |
866 | l l. | |
867 | string Cause of disconnection | |
868 | .TE | |
869 | This message may be sent by either party at any time. It causes the | |
870 | immediate disconnection of the connection. The message is intended to | |
871 | be displayed to a human, and describes the reason for disconnection. | |
872 | .IP "2 SSH_SMSG_PUBLIC_KEY" | |
873 | .TS | |
874 | ; | |
875 | l l. | |
876 | 8 bytes anti_spoofing_cookie | |
877 | 32-bit int server_key_bits | |
878 | mp-int server_key_public_exponent | |
879 | mp-int server_key_public_modulus | |
880 | 32-bit int host_key_bits | |
881 | mp-int host_key_public_exponent | |
882 | mp-int host_key_public_modulus | |
883 | 32-bit int protocol_flags | |
884 | 32-bit int supported_ciphers_mask | |
885 | 32-bit int supported_authentications_mask | |
886 | .TE | |
887 | Sent as the first message by the server. This message gives the | |
888 | server's host key, server key, protocol flags (intended for compatible | |
889 | protocol extension), supported_ciphers_mask (which is the | |
890 | bitwise or of (1 << cipher_number), where << is the left shift | |
891 | operator, for all supported ciphers), and | |
892 | supported_authentications_mask (which is the bitwise or of (1 << | |
893 | authentication_type) for all supported authentication types). The | |
894 | anti_spoofing_cookie is 64 random bytes, and must be sent back | |
895 | verbatim by the client in its reply. It is used to make IP-spoofing | |
896 | more difficult (encryption and host keys are the real defense against | |
897 | spoofing). | |
898 | .IP "3 SSH_CMSG_SESSION_KEY" | |
899 | .TS | |
900 | ; | |
901 | l l. | |
902 | 1 byte cipher_type (must be one of the supported values) | |
903 | 8 bytes anti_spoofing_cookie (must match data sent by the server) | |
904 | mp-int double-encrypted session key | |
905 | 32-bit int protocol_flags | |
906 | .TE | |
907 | Sent by the client as the first message in the session. Selects the | |
908 | cipher to use, and sends the encrypted session key to the server. The | |
909 | anti_spoofing_cookie must be the same bytes that were sent by the | |
910 | server. Protocol_flags is intended for negotiating compatible | |
911 | protocol extensions. | |
912 | .IP "4 SSH_CMSG_USER" | |
913 | .TS | |
914 | ; | |
915 | l l. | |
916 | string user login name on server | |
917 | .TE | |
918 | Sent by the client to begin authentication. Specifies the user name | |
919 | on the server to log in as. The server responds with SSH_SMSG_SUCCESS | |
920 | if no authentication is needed for this user, or SSH_SMSG_FAILURE if | |
921 | authentication is needed (or the user does not exist). [Note to the | |
922 | implementator: the user name is of arbitrary size. The implementation | |
923 | must be careful not to overflow internal buffers.] | |
924 | .IP "5 SSH_CMSG_AUTH_RHOSTS" | |
925 | .TS | |
926 | ; | |
927 | l l. | |
928 | string client-side user name | |
929 | .TE | |
930 | Requests authentication using /etc/hosts.equiv and .rhosts (or | |
931 | equivalent mechanisms). This authentication method is normally | |
932 | disabled in the server because it is not secure (but this is the | |
933 | method used by rsh and rlogin). The server responds with | |
934 | SSH_SMSG_SUCCESS if authentication was successful, and | |
935 | SSH_SMSG_FAILURE if access was not granted. The server should check | |
936 | that the client side port number is less than 1024 (a privileged | |
937 | port), and immediately reject authentication if it is not. Supporting | |
938 | this authentication method is optional. This method should normally | |
939 | not be enabled in the server because it is not safe. (However, not | |
940 | enabling this only helps if rlogind and rshd are disabled.) | |
941 | .IP "6 SSH_CMSG_AUTH_RSA" | |
942 | .TS | |
943 | ; | |
944 | l l. | |
945 | mp-int identity_public_modulus | |
946 | .TE | |
947 | Requests authentication using pure RSA authentication. The server | |
948 | checks if the given key is permitted to log in, and if so, responds | |
949 | with SSH_SMSG_AUTH_RSA_CHALLENGE. Otherwise, it responds with | |
950 | SSH_SMSG_FAILURE. The client often tries several different keys in | |
951 | sequence until one supported by the server is found. Authentication | |
952 | is accepted if the client gives the correct response to the challenge. | |
953 | The server is free to add other criteria for authentication, such as a | |
954 | requirement that the connection must come from a certain host. Such | |
955 | additions are not visible at the protocol level. Supporting this | |
956 | authentication method is optional but recommended. | |
957 | .IP "7 SSH_SMSG_AUTH_RSA_CHALLENGE" | |
958 | .TS | |
959 | ; | |
960 | l l. | |
961 | mp-int encrypted challenge | |
962 | .TE | |
963 | Presents an RSA authentication challenge to the client. The challenge | |
964 | is a 256-bit random value encrypted as described elsewhere in this | |
965 | document. The client must decrypt the challenge using the RSA private | |
966 | key, compute MD5 of the challenge plus session id, and send back the | |
967 | resulting 16 bytes using SSH_CMSG_AUTH_RSA_RESPONSE. | |
968 | .IP "8 SSH_CMSG_AUTH_RSA_RESPONSE" | |
969 | .TS | |
970 | ; | |
971 | l l. | |
972 | 16 bytes MD5 of decrypted challenge | |
973 | .TE | |
974 | This message is sent by the client in response to an RSA challenge. | |
975 | The MD5 checksum is returned instead of the decrypted challenge to | |
976 | deter known-plaintext attacks against the RSA key. The server | |
977 | responds to this message with either SSH_SMSG_SUCCESS or | |
978 | SSH_SMSG_FAILURE. | |
979 | .IP "9 SSH_CMSG_AUTH_PASSWORD" | |
980 | .TS | |
981 | ; | |
982 | l l. | |
983 | string plain text password | |
984 | .TE | |
985 | Requests password authentication using the given password. Note that | |
986 | even though the password is plain text inside the packet, the whole | |
987 | packet is normally encrypted by the packet layer. It would not be | |
988 | possible for the client to perform password encryption/hashing, | |
989 | because it cannot know which kind of encryption/hashing, if any, the | |
990 | server uses. The server responds to this message with | |
991 | SSH_SMSG_SUCCESS or SSH_SMSG_FAILURE. | |
992 | .IP "10 SSH_CMSG_REQUEST_PTY" | |
993 | .TS | |
994 | ; | |
995 | l l. | |
996 | string TERM environment variable value (e.g. vt100) | |
997 | 32-bit int terminal height, rows (e.g., 24) | |
998 | 32-bit int terminal width, columns (e.g., 80) | |
999 | 32-bit int terminal width, pixels (0 if no graphics) (e.g., 480) | |
1000 | 32-bit int terminal height, pixels (0 if no graphics) (e.g., 640) | |
1001 | n bytes tty modes encoded in binary | |
1002 | .TE | |
1003 | Requests a pseudo-terminal to be allocated for this command. This | |
1004 | message can be used regardless of whether the session will later | |
1005 | execute the shell or a command. If a pty has been requested with this | |
1006 | message, the shell or command will run on a pty. Otherwise it will | |
1007 | communicate with the server using pipes, sockets or some other similar | |
1008 | mechanism. | |
1009 | ||
1010 | The terminal type gives the type of the user's terminal. In the UNIX | |
1011 | environment it is passed to the shell or command in the TERM | |
1012 | environment variable. | |
1013 | ||
1014 | The width and height values give the initial size of the user's | |
1015 | terminal or window. All values can be zero if not supported by the | |
1016 | operating system. The server will pass these values to the kernel if | |
1017 | supported. | |
1018 | ||
1019 | Terminal modes are encoded into a byte stream in a portable format. | |
1020 | The exact format is described later in this document. | |
1021 | ||
1022 | The server responds to the request with either SSH_SMSG_SUCCESS or | |
1023 | SSH_SMSG_FAILURE. If the server does not have the concept of pseudo | |
1024 | terminals, it should return success if it is possible to execute a | |
1025 | shell or a command so that it looks to the client as if it was running | |
1026 | on a pseudo terminal. | |
1027 | .IP "11 SSH_CMSG_WINDOW_SIZE" | |
1028 | .TS | |
1029 | ; | |
1030 | l l. | |
1031 | 32-bit int terminal height, rows | |
1032 | 32-bit int terminal width, columns | |
1033 | 32-bit int terminal width, pixels | |
1034 | 32-bit int terminal height, pixels | |
1035 | .TE | |
1036 | This message can only be sent by the client during the interactive | |
1037 | session. This indicates that the size of the user's window has | |
1038 | changed, and provides the new size. The server will update the | |
1039 | kernel's notion of the window size, and a SIGWINCH signal or | |
1040 | equivalent will be sent to the shell or command (if supported by the | |
1041 | operating system). | |
1042 | .IP "12 SSH_CMSG_EXEC_SHELL" | |
1043 | ||
1044 | (no arguments) | |
1045 | ||
1046 | Starts a shell (command interpreter), and enters interactive session | |
1047 | mode. | |
1048 | .IP "13 SSH_CMSG_EXEC_CMD" | |
1049 | .TS | |
1050 | ; | |
1051 | l l. | |
1052 | string command to execute | |
1053 | .TE | |
1054 | Starts executing the given command, and enters interactive session | |
1055 | mode. On UNIX, the command is run as "<shell> -c <command>", where | |
1056 | <shell> is the user's login shell. | |
1057 | .IP "14 SSH_SMSG_SUCCESS" | |
1058 | ||
1059 | (no arguments) | |
1060 | ||
1061 | This message is sent by the server in response to the session key, a | |
1062 | successful authentication request, and a successfully completed | |
1063 | preparatory operation. | |
1064 | .IP "15 SSH_SMSG_FAILURE" | |
1065 | ||
1066 | (no arguments) | |
1067 | ||
1068 | This message is sent by the server in response to a failed | |
1069 | authentication operation to indicate that the user has not yet been | |
1070 | successfully authenticated, and in response to a failed preparatory | |
1071 | operation. This is also sent in response to an authentication or | |
1072 | preparatory operation request that is not recognized or supported. | |
1073 | .IP "16 SSH_CMSG_STDIN_DATA" | |
1074 | .TS | |
1075 | ; | |
1076 | l l. | |
1077 | string data | |
1078 | .TE | |
1079 | Delivers data from the client to be supplied as input to the shell or | |
1080 | program running on the server side. This message can only be used in | |
1081 | the interactive session mode. No acknowledgement is sent for this | |
1082 | message. | |
1083 | .IP "17 SSH_SMSG_STDOUT_DATA" | |
1084 | .TS | |
1085 | ; | |
1086 | l l. | |
1087 | string data | |
1088 | .TE | |
1089 | Delivers data from the server that was read from the standard output of | |
1090 | the shell or program running on the server side. This message can | |
1091 | only be used in the interactive session mode. No acknowledgement is | |
1092 | sent for this message. | |
1093 | .IP "18 SSH_SMSG_STDERR_DATA" | |
1094 | .TS | |
1095 | ; | |
1096 | l l. | |
1097 | string data | |
1098 | .TE | |
1099 | Delivers data from the server that was read from the standard error of | |
1100 | the shell or program running on the server side. This message can | |
1101 | only be used in the interactive session mode. No acknowledgement is | |
1102 | sent for this message. | |
1103 | .IP "19 SSH_CMSG_EOF" | |
1104 | ||
1105 | (no arguments) | |
1106 | ||
1107 | This message is sent by the client to indicate that EOF has been | |
1108 | reached on the input. Upon receiving this message, and after all | |
1109 | buffered input data has been sent to the shell or program, the server | |
1110 | will close the input file descriptor to the program. This message can | |
1111 | only be used in the interactive session mode. No acknowledgement is | |
1112 | sent for this message. | |
1113 | .IP "20 SSH_SMSG_EXITSTATUS" | |
1114 | .TS | |
1115 | ; | |
1116 | l l. | |
1117 | 32-bit int exit status of the command | |
1118 | .TE | |
1119 | Returns the exit status of the shell or program after it has exited. | |
1120 | The client should respond with SSH_CMSG_EXIT_CONFIRMATION when it has | |
1121 | received this message. This will be the last message sent by the | |
1122 | server. If the program being executed dies with a signal instead of | |
1123 | exiting normally, the server should terminate the session with | |
1124 | SSH_MSG_DISCONNECT (which can be used to pass a human-readable string | |
1125 | indicating that the program died due to a signal) instead of using | |
1126 | this message. | |
1127 | .IP "21 SSH_MSG_CHANNEL_OPEN_CONFIRMATION" | |
1128 | .TS | |
1129 | ; | |
1130 | l l. | |
1131 | 32-bit int remote_channel | |
1132 | 32-bit int local_channel | |
1133 | .TE | |
1134 | This is sent in response to any channel open request if the channel | |
1135 | has been successfully opened. Remote_channel is the channel number | |
1136 | received in the initial open request; local_channel is the channel | |
1137 | number the side sending this message has allocated for the channel. | |
1138 | Data can be transmitted on the channel after this message. | |
1139 | .IP "22 SSH_MSG_CHANNEL_OPEN_FAILURE" | |
1140 | .TS | |
1141 | ; | |
1142 | l l. | |
1143 | 32-bit int remote_channel | |
1144 | .TE | |
1145 | This message indicates that an earlier channel open request by the | |
1146 | other side has failed or has been denied. Remote_channel is the | |
1147 | channel number given in the original request. | |
1148 | .IP "23 SSH_MSG_CHANNEL_DATA" | |
1149 | .TS | |
1150 | ; | |
1151 | l l. | |
1152 | 32-bit int remote_channel | |
1153 | string data | |
1154 | .TE | |
1155 | Data is transmitted in a channel in these messages. A channel is | |
1156 | bidirectional, and both sides can send these messages. There is no | |
1157 | acknowledgement for these messages. It is possible that either side | |
1158 | receives these messages after it has sent SSH_MSG_CHANNEL_CLOSE for | |
1159 | the channel. These messages cannot be received after the party has | |
1160 | sent or received SSH_MSG_CHANNEL_CLOSE_CONFIRMATION. | |
1161 | .IP "24 SSH_MSG_CHANNEL_CLOSE" | |
1162 | .TS | |
1163 | ; | |
1164 | l l. | |
1165 | 32-bit int remote_channel | |
1166 | .TE | |
1167 | When a channel is closed at one end of the connection, that side sends | |
1168 | this message. Upon receiving this message, the channel should be | |
1169 | closed. When this message is received, if the channel is already | |
1170 | closed (the receiving side has sent this message for the same channel | |
1171 | earlier), the channel is freed and no further action is taken; | |
1172 | otherwise the channel is freed and SSH_MSG_CHANNEL_CLOSE_CONFIRMATION | |
1173 | is sent in response. (It is possible that the channel is closed | |
1174 | simultaneously at both ends.) | |
1175 | .IP "25 SSH_MSG_CHANNEL_CLOSE_CONFIRMATION" | |
1176 | .TS | |
1177 | ; | |
1178 | l l. | |
1179 | 32-bit int remote_channel | |
1180 | .TE | |
1181 | This message is sent in response to SSH_MSG_CHANNEL_CLOSE unless the | |
1182 | channel was already closed. When this message is sent or received, | |
1183 | the channel is freed. | |
1184 | .IP "26 (OBSOLETED; was unix-domain X11 forwarding) | |
1185 | .IP "27 SSH_SMSG_X11_OPEN" | |
1186 | .TS | |
1187 | ; | |
1188 | l l. | |
1189 | 32-bit int local_channel | |
1190 | string originator_string (see below) | |
1191 | .TE | |
1192 | This message can be sent by the server during the interactive session | |
1193 | mode to indicate that a client has connected the fake X server. | |
1194 | Local_channel is the channel number that the server has allocated for | |
1195 | the connection. The client should try to open a connection to the | |
1196 | real X server, and respond with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or | |
1197 | SSH_MSG_CHANNEL_OPEN_FAILURE. | |
1198 | ||
1199 | The field originator_string is present if both sides | |
1200 | specified SSH_PROTOFLAG_HOST_IN_FWD_OPEN in the protocol flags. It | |
1201 | contains a description of the host originating the connection. | |
1202 | .IP "28 SSH_CMSG_PORT_FORWARD_REQUEST" | |
1203 | .TS | |
1204 | ; | |
1205 | l l. | |
1206 | 32-bit int server_port | |
1207 | string host_to_connect | |
1208 | 32-bit int port_to_connect | |
1209 | .TE | |
1210 | Sent by the client in the preparatory phase, this message requests | |
1211 | that server_port on the server machine be forwarded over the secure | |
1212 | channel to the client machine, and from there to the specified host | |
1213 | and port. The server should start listening on the port, and send | |
1214 | SSH_MSG_PORT_OPEN whenever a connection is made to it. Supporting | |
1215 | this message is optional, and the server is free to reject any forward | |
1216 | request. For example, it is highly recommended that unless the user | |
1217 | has been authenticated as root, forwarding any privileged port numbers | |
1218 | (below 1024) is denied. | |
1219 | .IP "29 SSH_MSG_PORT_OPEN" | |
1220 | .TS | |
1221 | ; | |
1222 | l l. | |
1223 | 32-bit int local_channel | |
1224 | string host_name | |
1225 | 32-bit int port | |
1226 | string originator_string (see below) | |
1227 | .TE | |
1228 | Sent by either party in interactive session mode, this message | |
1229 | indicates that a connection has been opened to a forwarded TCP/IP | |
1230 | port. Local_channel is the channel number that the sending party has | |
1231 | allocated for the connection. Host_name is the host the connection | |
1232 | should be be forwarded to, and the port is the port on that host to | |
1233 | connect. The receiving party should open the connection, and respond | |
1234 | with SSH_MSG_CHANNEL_OPEN_CONFIRMATION or | |
1235 | SSH_MSG_CHANNEL_OPEN_FAILURE. It is recommended that the receiving | |
1236 | side check the host_name and port for validity to avoid compromising | |
1237 | local security by compromised remote side software. Particularly, it | |
1238 | is recommended that the client permit connections only to those ports | |
1239 | for which it has requested forwarding with SSH_CMSG_PORT_FORWARD_REQUEST. | |
1240 | ||
1241 | The field originator_string is present if both sides | |
1242 | specified SSH_PROTOFLAG_HOST_IN_FWD_OPEN in the protocol flags. It | |
1243 | contains a description of the host originating the connection. | |
1244 | .IP "30 SSH_CMSG_AGENT_REQUEST_FORWARDING" | |
1245 | ||
1246 | (no arguments) | |
1247 | ||
1248 | Requests that the connection to the authentication agent be forwarded | |
1249 | over the secure channel. The method used by clients to contact the | |
1250 | authentication agent within each machine is implementation and machine | |
1251 | dependent. If the server accepts this request, it should arrange that | |
1252 | any clients run from this session will actually contact the server | |
1253 | program when they try to contact the authentication agent. The server | |
1254 | should then send a SSH_SMSG_AGENT_OPEN to open a channel to the agent, | |
1255 | and the client should forward the connection to the real | |
1256 | authentication agent. Supporting this message is optional. | |
1257 | .IP "31 SSH_SMSG_AGENT_OPEN" | |
1258 | .TS | |
1259 | ; | |
1260 | l l. | |
1261 | 32-bit int local_channel | |
1262 | .TE | |
1263 | Sent by the server in interactive session mode, this message requests | |
1264 | opening a channel to the authentication agent. The client should open | |
1265 | a channel, and respond with either SSH_MSG_CHANNEL_OPEN_CONFIRMATION | |
1266 | or SSH_MSG_CHANNEL_OPEN_FAILURE. | |
1267 | .IP "32 SSH_MSG_IGNORE" | |
1268 | .TS | |
1269 | ; | |
1270 | l l. | |
1271 | string data | |
1272 | .TE | |
1273 | Either party may send this message at any time. This message, and the | |
1274 | argument string, is silently ignored. This message might be used in | |
1275 | some implementations to make traffic analysis more difficult. This | |
1276 | message is not currently sent by the implementation, but all | |
1277 | implementations are required to recognize and ignore it. | |
1278 | .IP "33 SSH_CMSG_EXIT_CONFIRMATION" | |
1279 | ||
1280 | (no arguments) | |
1281 | ||
1282 | Sent by the client in response to SSH_SMSG_EXITSTATUS. This is the | |
1283 | last message sent by the client. | |
1284 | .IP "34 SSH_CMSG_X11_REQUEST_FORWARDING" | |
1285 | .TS | |
1286 | ; | |
1287 | l l. | |
1288 | string x11_authentication_protocol | |
1289 | string x11_authentication_data | |
1290 | 32-bit int screen number (if SSH_PROTOFLAG_SCREEN_NUMBER) | |
1291 | .TE | |
1292 | Sent by the client during the preparatory phase, this message requests | |
1293 | that the server create a fake X11 display and set the DISPLAY | |
1294 | environment variable accordingly. An internet-domain display is | |
1295 | preferable. The given authentication protocol and the associated data | |
1296 | should be recorded by the server so that it is used as authentication | |
1297 | on connections (e.g., in .Xauthority). The authentication protocol | |
1298 | must be one of the supported X11 authentication protocols, e.g., | |
1299 | "MIT-MAGIC-COOKIE-1". Authentication data must be a lowercase hex | |
1300 | string of even length. Its interpretation is protocol dependent. | |
1301 | The data is in a format that can be used with e.g. the xauth program. | |
1302 | Supporting this message is optional. | |
1303 | ||
1304 | The client is permitted (and recommended) to generate fake | |
1305 | authentication information and send fake information to the server. | |
1306 | This way, a corrupt server will not have access to the user's terminal | |
1307 | after the connection has terminated. The correct authorization codes | |
1308 | will also not be left hanging around in files on the server (many | |
1309 | users keep the same X session for months, thus protecting the | |
1310 | authorization data becomes important). | |
1311 | ||
1312 | X11 authentication spoofing works by initially sending fake (random) | |
1313 | authentication data to the server, and interpreting the first packet | |
1314 | sent by the X11 client after the connection has been opened. The | |
1315 | first packet contains the client's authentication. If the packet | |
1316 | contains the correct fake data, it is replaced by the client by the | |
1317 | correct authentication data, and then sent to the X server. | |
1318 | .IP "35 SSH_CMSG_AUTH_RHOSTS_RSA" | |
1319 | .TS | |
1320 | ; | |
1321 | l l. | |
1322 | string clint-side user name | |
1323 | 32-bit int client_host_key_bits | |
1324 | mp-int client_host_key_public_exponent | |
1325 | mp-int client_host_key_public_modulus | |
1326 | .TE | |
1327 | Requests authentication using /etc/hosts.equiv and .rhosts (or | |
1328 | equivalent) together with RSA host authentication. The server should | |
1329 | check that the client side port number is less than 1024 (a privileged | |
1330 | port), and immediately reject authentication if it is not. The server | |
1331 | responds with SSH_SMSG_FAILURE or SSH_SMSG_AUTH_RSA_CHALLENGE. The | |
1332 | client must respond to the challenge with the proper | |
1333 | SSH_CMSG_AUTH_RSA_RESPONSE. The server then responds with success if | |
1334 | access was granted, or failure if the client gave a wrong response. | |
1335 | Supporting this authentication method is optional but recommended in | |
1336 | most environments. | |
1337 | .IP "36 SSH_MSG_DEBUG" | |
1338 | .TS | |
1339 | ; | |
1340 | l l. | |
1341 | string debugging message sent to the other side | |
1342 | .TE | |
1343 | This message may be sent by either party at any time. It is used to | |
1344 | send debugging messages that may be informative to the user in | |
1345 | solving various problems. For example, if authentication fails | |
1346 | because of some configuration error (e.g., incorrect permissions for | |
1347 | some file), it can be very helpful for the user to make the cause of | |
1348 | failure available. On the other hand, one should not make too much | |
1349 | information available for security reasons. It is recommended that | |
1350 | the client provides an option to display the debugging information | |
1351 | sent by the sender (the user probably does not want to see it by default). | |
1352 | The server can log debugging data sent by the client (if any). Either | |
1353 | party is free to ignore any received debugging data. Every | |
1354 | implementation must be able to receive this message, but no | |
1355 | implementation is required to send these. | |
1356 | .IP "37 SSH_CMSG_REQUEST_COMPRESSION" | |
1357 | .TS | |
1358 | ; | |
1359 | l l. | |
1360 | 32-bit int gzip compression level (1-9) | |
1361 | .TE | |
1362 | This message can be sent by the client in the preparatory operations | |
1363 | phase. The server responds with SSH_SMSG_FAILURE if it does not | |
1364 | support compression or does not want to compress; it responds with | |
1365 | SSH_SMSG_SUCCESS if it accepted the compression request. In the | |
1366 | latter case the response to this packet will still be uncompressed, | |
1367 | but all further packets in either direction will be compressed by gzip. | |
1368 | .RT | |
1369 | ||
1370 | ||
1371 | .ti 0 | |
1372 | Encoding of Terminal Modes | |
1373 | ||
1374 | Terminal modes (as passed in SSH_CMSG_REQUEST_PTY) are encoded into a | |
1375 | byte stream. It is intended that the coding be portable across | |
1376 | different environments. | |
1377 | ||
1378 | The tty mode description is a stream of bytes. The stream consists of | |
1379 | opcode-argument pairs. It is terminated by opcode TTY_OP_END (0). | |
1380 | Opcodes 1-127 have one-byte arguments. Opcodes 128-159 have 32-bit | |
1381 | integer arguments (stored msb first). Opcodes 160-255 are not yet | |
1382 | defined, and cause parsing to stop (they should only be used after any | |
1383 | other data). | |
1384 | ||
1385 | The client puts in the stream any modes it knows about, and the server | |
1386 | ignores any modes it does not know about. This allows some degree of | |
1387 | machine-independence, at least between systems that use a POSIX-like | |
1388 | [POSIX] tty interface. The protocol can support other systems as | |
1389 | well, but the client may need to fill reasonable values for a number | |
1390 | of parameters so the server pty gets set to a reasonable mode (the | |
1391 | server leaves all unspecified mode bits in their default values, and | |
1392 | only some combinations make sense). | |
1393 | ||
1394 | The following opcodes have been defined. The naming of opcodes mostly | |
1395 | follows the POSIX terminal mode flags. | |
1396 | .IP "0 TTY_OP_END" | |
1397 | Indicates end of options. | |
1398 | .IP "1 VINTR" | |
1399 | Interrupt character; 255 if none. Similarly for the other characters. | |
1400 | Not all of these characters are supported on all systems. | |
1401 | .IP "2 VQUIT" | |
1402 | The quit character (sends SIGQUIT signal on UNIX systems). | |
1403 | .IP "3 VERASE" | |
1404 | Erase the character to left of the cursor. | |
1405 | .IP "4 VKILL" | |
1406 | Kill the current input line. | |
1407 | .IP "5 VEOF " | |
1408 | End-of-file character (sends EOF from the terminal). | |
1409 | .IP "6 VEOL " | |
1410 | End-of-line character in addition to carriage return and/or linefeed. | |
1411 | .IP "7 VEOL2" | |
1412 | Additional end-of-line character. | |
1413 | .IP "8 VSTART" | |
1414 | Continues paused output (normally ^Q). | |
1415 | .IP "9 VSTOP" | |
1416 | Pauses output (^S). | |
1417 | .IP "10 VSUSP" | |
1418 | Suspends the current program. | |
1419 | .IP "11 VDSUSP" | |
1420 | Another suspend character. | |
1421 | .IP "12 VREPRINT" | |
1422 | Reprints the current input line. | |
1423 | .IP "13 VWERASE" | |
1424 | Erases a word left of cursor. | |
1425 | .IP "14 VLNEXT" | |
1426 | More special input characters; these are probably not supported on | |
1427 | most systems. | |
1428 | .IP "15 VFLUSH" | |
1429 | .IP "16 VSWTCH" | |
1430 | .IP "17 VSTATUS" | |
1431 | .IP "18 VDISCARD" | |
1432 | ||
1433 | .IP "30 IGNPAR" | |
1434 | The ignore parity flag. The next byte should be 0 if this flag is not | |
1435 | set, and 1 if it is set. | |
1436 | .IP "31 PARMRK" | |
1437 | More flags. The exact definitions can be found in the POSIX standard. | |
1438 | .IP "32 INPCK" | |
1439 | .IP "33 ISTRIP" | |
1440 | .IP "34 INLCR" | |
1441 | .IP "35 IGNCR" | |
1442 | .IP "36 ICRNL" | |
1443 | .IP "37 IUCLC" | |
1444 | .IP "38 IXON" | |
1445 | .IP "39 IXANY" | |
1446 | .IP "40 IXOFF" | |
1447 | .IP "41 IMAXBEL" | |
1448 | ||
1449 | .IP "50 ISIG" | |
1450 | .IP "51 ICANON" | |
1451 | .IP "52 XCASE" | |
1452 | .IP "53 ECHO" | |
1453 | .IP "54 ECHOE" | |
1454 | .IP "55 ECHOK" | |
1455 | .IP "56 ECHONL" | |
1456 | .IP "57 NOFLSH" | |
1457 | .IP "58 TOSTOP" | |
1458 | .IP "59 IEXTEN" | |
1459 | .IP "60 ECHOCTL" | |
1460 | .IP "61 ECHOKE" | |
1461 | .IP "62 PENDIN" | |
1462 | ||
1463 | .IP "70 OPOST" | |
1464 | .IP "71 OLCUC" | |
1465 | .IP "72 ONLCR" | |
1466 | .IP "73 OCRNL" | |
1467 | .IP "74 ONOCR" | |
1468 | .IP "75 ONLRET" | |
1469 | ||
1470 | .IP "90 CS7" | |
1471 | .IP "91 CS8" | |
1472 | .IP "92 PARENB" | |
1473 | .IP "93 PARODD" | |
1474 | ||
1475 | .IP "192 TTY_OP_ISPEED" | |
1476 | Specifies the input baud rate in bits per second. | |
1477 | .IP "193 TTY_OP_OSPEED" | |
1478 | Specifies the output baud rate in bits per second. | |
1479 | .RT | |
1480 | ||
1481 | ||
1482 | .ti 0 | |
1483 | The Authentication Agent Protocol | |
1484 | ||
1485 | The authentication agent is a program that can be used to hold RSA | |
1486 | authentication keys for the user (in future, it might hold data for | |
1487 | other authentication types as well). An authorized program can send | |
1488 | requests to the agent to generate a proper response to an RSA | |
1489 | challenge. How the connection is made to the agent (or its | |
1490 | representative) inside a host and how access control is done inside a | |
1491 | host is implementation-dependent; however, how it is forwarded and how | |
1492 | one interacts with it is specified in this protocol. The connection | |
1493 | to the agent is normally automatically forwarded over the secure | |
1494 | channel. | |
1495 | ||
1496 | A program that wishes to use the agent first opens a connection to its | |
1497 | local representative (typically, the agent itself or an SSH server). | |
1498 | It then writes a request to the connection, and waits for response. | |
1499 | It is recommended that at least five minutes of timeout are provided | |
1500 | waiting for the agent to respond to an authentication challenge (this | |
1501 | gives sufficient time for the user to cut-and-paste the challenge to a | |
1502 | separate machine, perform the computation there, and cut-and-paste the | |
1503 | result back if so desired). | |
1504 | ||
1505 | Messages sent to and by the agent are in the following format: | |
1506 | .TS | |
1507 | ; | |
1508 | l l. | |
1509 | 4 bytes Length, msb first. Does not include length itself. | |
1510 | 1 byte Packet type. The value 255 is reserved for future extensions. | |
1511 | data Any data, depending on packet type. Encoding as in the ssh packet | |
1512 | protocol. | |
1513 | .TE | |
1514 | ||
1515 | The following message types are currently defined: | |
1516 | .IP "1 SSH_AGENTC_REQUEST_RSA_IDENTITIES" | |
1517 | ||
1518 | (no arguments) | |
1519 | ||
1520 | Requests the agent to send a list of all RSA keys for which it can | |
1521 | answer a challenge. | |
1522 | .IP "2 SSH_AGENT_RSA_IDENTITIES_ANSWER" | |
1523 | .TS | |
1524 | ; | |
1525 | l l. | |
1526 | 32-bit int howmany | |
1527 | howmany times: | |
1528 | 32-bit int bits | |
1529 | mp-int public exponent | |
1530 | mp-int public modulus | |
1531 | string comment | |
1532 | .TE | |
1533 | The agent sends this message in response to the to | |
1534 | SSH_AGENTC_REQUEST_RSA_IDENTITIES. The answer lists all RSA keys for | |
1535 | which the agent can answer a challenge. The comment field is intended | |
1536 | to help identify each key; it may be printed by an application to | |
1537 | indicate which key is being used. If the agent is not holding any | |
1538 | keys, howmany will be zero. | |
1539 | .IP "3 SSH_AGENTC_RSA_CHALLENGE | |
1540 | .TS | |
1541 | ; | |
1542 | l l. | |
1543 | 32-bit int bits | |
1544 | mp-int public exponent | |
1545 | mp-int public modulus | |
1546 | mp-int challenge | |
1547 | 16 bytes session_id | |
1548 | 32-bit int response_type | |
1549 | .TE | |
1550 | Requests RSA decryption of random challenge to authenticate the other | |
1551 | side. The challenge will be decrypted with the RSA private key | |
1552 | corresponding to the given public key. | |
1553 | ||
1554 | The decrypted challenge must contain a zero in the highest (partial) | |
1555 | byte, 2 in the next byte, followed by non-zero random bytes, a zero | |
1556 | byte, and then the real challenge value in the lowermost bytes. The | |
1557 | real challenge must be 32 8-bit bytes (256 bits). | |
1558 | ||
1559 | Response_type indicates the format of the response to be returned. | |
1560 | Currently the only supported value is 1, which means to compute MD5 of | |
1561 | the real challenge plus session id, and return the resulting 16 bytes | |
1562 | in a SSH_AGENT_RSA_RESPONSE message. | |
1563 | .IP "4 SSH_AGENT_RSA_RESPONSE" | |
1564 | .TS | |
1565 | ; | |
1566 | l l. | |
1567 | 16 bytes MD5 of decrypted challenge | |
1568 | .TE | |
1569 | Answers an RSA authentication challenge. The response is 16 bytes: | |
1570 | the MD5 checksum of the 32-byte challenge. | |
1571 | .IP "5 SSH_AGENT_FAILURE" | |
1572 | ||
1573 | (no arguments) | |
1574 | ||
1575 | This message is sent whenever the agent fails to answer a request | |
1576 | properly. For example, if the agent cannot answer a challenge (e.g., | |
1577 | no longer has the proper key), it can respond with this. The agent | |
1578 | also responds with this message if it receives a message it does not | |
1579 | recognize. | |
1580 | .IP "6 SSH_AGENT_SUCCESS" | |
1581 | ||
1582 | (no arguments) | |
1583 | ||
1584 | This message is sent by the agent as a response to certain requests | |
1585 | that do not otherwise cause a message be sent. Currently, this is | |
1586 | only sent in response to SSH_AGENTC_ADD_RSA_IDENTITY and | |
1587 | SSH_AGENTC_REMOVE_RSA_IDENTITY. | |
1588 | .IP "7 SSH_AGENTC_ADD_RSA_IDENTITY" | |
1589 | .TS | |
1590 | ; | |
1591 | l l. | |
1592 | 32-bit int bits | |
1593 | mp-int public modulus | |
1594 | mp-int public exponent | |
1595 | mp-int private exponent | |
1596 | mp-int multiplicative inverse of p mod q | |
1597 | mp-int p | |
1598 | mp-int q | |
1599 | string comment | |
1600 | .TE | |
1601 | Registers an RSA key with the agent. After this request, the agent can | |
1602 | use this RSA key to answer requests. The agent responds with | |
1603 | SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE. | |
1604 | .IP "8 SSH_AGENT_REMOVE_RSA_IDENTITY" | |
1605 | .TS | |
1606 | ; | |
1607 | l l. | |
1608 | 32-bit int bits | |
1609 | mp-int public exponent | |
1610 | mp-int public modulus | |
1611 | .TE | |
1612 | Removes an RSA key from the agent. The agent will no longer accept | |
1613 | challenges for this key and will not list it as a supported identity. | |
1614 | The agent responds with SSH_AGENT_SUCCESS or SSH_AGENT_FAILURE. | |
1615 | .RT | |
1616 | ||
1617 | If the agent receives a message that it does not understand, it | |
1618 | responds with SSH_AGENT_FAILURE. This permits compatible future | |
1619 | extensions. | |
1620 | ||
1621 | It is possible that several clients have a connection open to the | |
1622 | authentication agent simultaneously. Each client will use a separate | |
1623 | connection (thus, any SSH connection can have multiple agent | |
1624 | connections active simultaneously). | |
1625 | ||
1626 | ||
1627 | .ti 0 | |
1628 | References | |
1629 | ||
1630 | .IP "[DES] " | |
1631 | FIPS PUB 46-1: Data Encryption Standard. National Bureau of | |
1632 | Standards, January 1988. FIPS PUB 81: DES Modes of Operation. | |
1633 | National Bureau of Standards, December 1980. Bruce Schneier: Applied | |
1634 | Cryptography. John Wiley & Sons, 1994. J. Seberry and J. Pieprzyk: | |
1635 | Cryptography: An Introduction to Computer Security. Prentice-Hall, | |
1636 | 1989. | |
1637 | .IP "[GZIP] " | |
1638 | The GNU GZIP program; available for anonymous ftp at prep.ai.mit.edu. | |
1639 | Please let me know if you know a paper describing the algorithm. | |
1640 | .IP "[IDEA] " | |
1641 | Xuejia Lai: On the Design and Security of Block Ciphers, ETH Series in | |
1642 | Information Processing, vol. 1, Hartung-Gorre Verlag, Konstanz, | |
1643 | Switzerland, 1992. Bruce Schneier: Applied Cryptography, John Wiley & | |
1644 | Sons, 1994. See also the following patents: PCT/CH91/00117, EP 0 482 | |
1645 | 154 B1, US Pat. 5,214,703. | |
1646 | .IP [PKCS#1] | |
1647 | PKCS #1: RSA Encryption Standard. Version 1.5, RSA Laboratories, | |
1648 | November 1993. Available for anonymous ftp at ftp.rsa.com. | |
1649 | .IP [POSIX] | |
1650 | Portable Operating System Interface (POSIX) - Part 1: Application | |
1651 | Program Interface (API) [C language], ISO/IEC 9945-1, IEEE Std 1003.1, | |
1652 | 1990. | |
1653 | .IP [RFC0791] | |
1654 | J. Postel: Internet Protocol, RFC 791, USC/ISI, September 1981. | |
1655 | .IP [RFC0793] | |
1656 | J. Postel: Transmission Control Protocol, RFC 793, USC/ISI, September | |
1657 | 1981. | |
1658 | .IP [RFC1034] | |
1659 | P. Mockapetris: Domain Names - Concepts and Facilities, RFC 1034, | |
1660 | USC/ISI, November 1987. | |
1661 | .IP [RFC1282] | |
1662 | B. Kantor: BSD Rlogin, RFC 1258, UCSD, December 1991. | |
1663 | .IP "[RSA] " | |
1664 | Bruce Schneier: Applied Cryptography. John Wiley & Sons, 1994. See | |
1665 | also R. Rivest, A. Shamir, and L. M. Adleman: Cryptographic | |
1666 | Communications System and Method. US Patent 4,405,829, 1983. | |
1667 | .IP "[X11] " | |
1668 | R. Scheifler: X Window System Protocol, X Consortium Standard, Version | |
1669 | 11, Release 6. Massachusetts Institute of Technology, Laboratory of | |
1670 | Computer Science, 1994. | |
1671 | .RT | |
1672 | ||
1673 | ||
1674 | .ti 0 | |
1675 | Security Considerations | |
1676 | ||
1677 | This protocol deals with the very issue of user authentication and | |
1678 | security. | |
1679 | ||
1680 | First of all, as an implementation issue, the server program will have | |
1681 | to run as root (or equivalent) on the server machine. This is because | |
1682 | the server program will need be able to change to an arbitrary user | |
1683 | id. The server must also be able to create a privileged TCP/IP port. | |
1684 | ||
1685 | The client program will need to run as root if any variant of .rhosts | |
1686 | authentication is to be used. This is because the client program will | |
1687 | need to create a privileged port. The client host key is also usually | |
1688 | stored in a file which is readable by root only. The client needs the | |
1689 | host key in .rhosts authentication only. Root privileges can be | |
1690 | dropped as soon as the privileged port has been created and the host | |
1691 | key has been read. | |
1692 | ||
1693 | The SSH protocol offers major security advantages over existing telnet | |
1694 | and rlogin protocols. | |
1695 | .IP o | |
1696 | IP spoofing is restricted to closing a connection (by encryption, host | |
1697 | keys, and the special random cookie). If encryption is not used, IP | |
1698 | spoofing is possible for those who can hear packets going out from the | |
1699 | server. | |
1700 | .IP o | |
1701 | DNS spoofing is made ineffective (by host keys). | |
1702 | .IP o | |
1703 | Routing spoofing is made ineffective (by host keys). | |
1704 | .IP o | |
1705 | All data is encrypted with strong algorithms to make eavesdropping as | |
1706 | difficult as possible. This includes encrypting any authentication | |
1707 | information such as passwords. The information for decrypting session | |
1708 | keys is destroyed every hour. | |
1709 | .IP o | |
1710 | Strong authentication methods: .rhosts combined with RSA host | |
1711 | authentication, and pure RSA authentication. | |
1712 | .IP o | |
1713 | X11 connections and arbitrary TCP/IP ports can be forwarded securely. | |
1714 | .IP o | |
1715 | Man-in-the-middle attacks are deterred by using the server host key to | |
1716 | encrypt the session key. | |
1717 | .IP o | |
1718 | Trojan horses to catch a password by routing manipulation are deterred | |
1719 | by checking that the host key of the server machine matches that | |
1720 | stored on the client host. | |
1721 | .RT | |
1722 | ||
1723 | The security of SSH against man-in-the-middle attacks and the security | |
1724 | of the new form of .rhosts authentication, as well as server host | |
1725 | validation, depends on the integrity of the host key and the files | |
1726 | containing known host keys. | |
1727 | ||
1728 | The host key is normally stored in a root-readable file. If the host | |
1729 | key is compromised, it permits attackers to use IP, DNS and routing | |
1730 | spoofing as with current rlogin and rsh. It should never be any worse | |
1731 | than the current situation. | |
1732 | ||
1733 | The files containing known host keys are not sensitive. However, if an | |
1734 | attacker gets to modify the known host key files, it has the same | |
1735 | consequences as a compromised host key, because the attacker can then | |
1736 | change the recorded host key. | |
1737 | ||
1738 | The security improvements obtained by this protocol for X11 are of | |
1739 | particular significance. Previously, there has been no way to protect | |
1740 | data communicated between an X server and a client running on a remote | |
1741 | machine. By creating a fake display on the server, and forwarding all | |
1742 | X11 requests over the secure channel, SSH can be used to run any X11 | |
1743 | applications securely without any cooperation with the vendors of the | |
1744 | X server or the application. | |
1745 | ||
1746 | Finally, the security of this program relies on the strength of the | |
1747 | underlying cryptographic algorithms. The RSA algorithm is used for | |
1748 | authentication key exchange. It is widely believed to be secure. Of | |
1749 | the algorithms used to encrypt the session, DES has a rather small key | |
1750 | these days, probably permitting governments and organized criminals to | |
1751 | break it in very short time with specialized hardware. 3DES is | |
1752 | probably safe (but slower). IDEA is widely believed to be secure. | |
1753 | People have varying degrees of confidence in the other algorithms. | |
1754 | This program is not secure if used with no encryption at all. | |
1755 | ||
1756 | ||
1757 | .ti 0 | |
1758 | Additional Information | |
1759 | ||
1760 | Additional information (especially on the implementation and mailing | |
1761 | lists) is available via WWW at http://www.cs.hut.fi/ssh. | |
1762 | ||
1763 | Comments should be sent to Tatu Ylonen <ylo@cs.hut.fi> or the SSH | |
1764 | Mailing List <ssh@clinet.fi>. | |
1765 | ||
1766 | .ti 0 | |
1767 | Author's Address | |
1768 | ||
1769 | .TS | |
1770 | ; | |
1771 | l. | |
1772 | Tatu Ylonen | |
1773 | Helsinki University of Technology | |
1774 | Otakaari 1 | |
1775 | FIN-02150 Espoo, Finland | |
1776 | ||
1777 | Phone: +358-0-451-3374 | |
1778 | Fax: +358-0-451-3293 | |
1779 | EMail: ylo@cs.hut.fi | |
1780 | .TE |