source: trunk/third/openssh/RFC.nroff @ 16801

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