blob: ed360844185490b923a30b67b13c1a722d00402d [file] [log] [blame]
Damien Miller5ffa6441999-10-30 11:30:35 +10001Ssh (Secure Shell) is a program to log into another computer over a
2network, to execute commands in a remote machine, and to move files
3from one machine to another. It provides strong authentication and
4secure communications over insecure channels. It is inteded as a
5replacement for rlogin, rsh, rcp, and rdist.
6
7See the file INSTALL for installation instructions. See COPYING for
8license terms and other legal issues. See RFC for a description of
9the protocol. There is a WWW page for ssh; see http://www.cs.hut.fi/ssh.
10
11This file has been updated to match ssh-1.2.12.
12
13
14FEATURES
15
16 o Strong authentication. Closes several security holes (e.g., IP,
17 routing, and DNS spoofing). New authentication methods: .rhosts
18 together with RSA based host authentication, and pure RSA
19 authentication.
20
21 o Improved privacy. All communications are automatically and
22 transparently encrypted. RSA is used for key exchange, and a
23 conventional cipher (normally IDEA, DES, or triple-DES) for
24 encrypting the session. Encryption is started before
25 authentication, and no passwords or other information is
26 transmitted in the clear. Encryption is also used to protect
27 against spoofed packets.
28
29 o Secure X11 sessions. The program automatically sets DISPLAY on
30 the server machine, and forwards any X11 connections over the
31 secure channel. Fake Xauthority information is automatically
32 generated and forwarded to the remote machine; the local client
33 automatically examines incoming X11 connections and replaces the
34 fake authorization data with the real data (never telling the
35 remote machine the real information).
36
37 o Arbitrary TCP/IP ports can be redirected through the encrypted channel
38 in both directions (e.g., for e-cash transactions).
39
40 o No retraining needed for normal users; everything happens
41 automatically, and old .rhosts files will work with strong
42 authentication if administration installs host key files.
43
44 o Never trusts the network. Minimal trust on the remote side of
45 the connection. Minimal trust on domain name servers. Pure RSA
46 authentication never trusts anything but the private key.
47
48 o Client RSA-authenticates the server machine in the beginning of
49 every connection to prevent trojan horses (by routing or DNS
50 spoofing) and man-in-the-middle attacks, and the server
51 RSA-authenticates the client machine before accepting .rhosts or
52 /etc/hosts.equiv authentication (to prevent DNS, routing, or
53 IP-spoofing).
54
55 o Host authentication key distribution can be centrally by the
56 administration, automatically when the first connection is made
57 to a machine (the key obtained on the first connection will be
58 recorded and used for authentication in the future), or manually
59 by each user for his/her own use. The central and per-user host
60 key repositories are both used and complement each other. Host
61 keys can be generated centrally or automatically when the software
62 is installed. Host authentication keys are typically 1024 bits.
63
64 o Any user can create any number of user authentication RSA keys for
65 his/her own use. Each user has a file which lists the RSA public
66 keys for which proof of possession of the corresponding private
67 key is accepted as authentication. User authentication keys are
68 typically 1024 bits.
69
70 o The server program has its own server RSA key which is
71 automatically regenerated every hour. This key is never saved in
72 any file. Exchanged session keys are encrypted using both the
73 server key and the server host key. The purpose of the separate
74 server key is to make it impossible to decipher a captured session by
75 breaking into the server machine at a later time; one hour from
76 the connection even the server machine cannot decipher the session
77 key. The key regeneration interval is configurable. The server
78 key is normally 768 bits.
79
80 o An authentication agent, running in the user's laptop or local
81 workstation, can be used to hold the user's RSA authentication
82 keys. Ssh automatically forwards the connection to the
83 authentication agent over any connections, and there is no need to
84 store the RSA authentication keys on any machine in the network
85 (except the user's own local machine). The authentication
86 protocols never reveal the keys; they can only be used to verify
87 that the user's agent has a certain key. Eventually the agent
88 could rely on a smart card to perform all authentication
89 computations.
90
91 o The software can be installed and used (with restricted
92 functionality) even without root privileges.
93
94 o The client is customizable in system-wide and per-user
95 configuration files. Most aspects of the client's operation can
96 be configured. Different options can be specified on a per-host basis.
97
98 o Automatically executes conventional rsh (after displaying a
99 warning) if the server machine is not running sshd.
100
101 o Optional compression of all data with gzip (including forwarded X11
102 and TCP/IP port data), which may result in significant speedups on
103 slow connections.
104
105 o Complete replacement for rlogin, rsh, and rcp.
106
107
108WHY TO USE SECURE SHELL
109
110Currently, almost all communications in computer networks are done
111without encryption. As a consequence, anyone who has access to any
112machine connected to the network can listen in on any communication.
113This is being done by hackers, curious administrators, employers,
114criminals, industrial spies, and governments. Some networks leak off
115enough electromagnetic radiation that data may be captured even from a
116distance.
117
118When you log in, your password goes in the network in plain
119text. Thus, any listener can then use your account to do any evil he
120likes. Many incidents have been encountered worldwide where crackers
121have started programs on workstations without the owners knowledge
122just to listen to the network and collect passwords. Programs for
123doing this are available on the Internet, or can be built by a
124competent programmer in a few hours.
125
126Any information that you type or is printed on your screen can be
127monitored, recorded, and analyzed. For example, an intruder who has
128penetrated a host connected to a major network can start a program
129that listens to all data flowing in the network, and whenever it
130encounters a 16-digit string, it checks if it is a valid credit card
131number (using the check digit), and saves the number plus any
132surrounding text (to catch expiration date and holder) in a file.
133When the intruder has collected a few thousand credit card numbers, he
134makes smallish mail-order purchases from a few thousand stores around
135the world, and disappears when the goods arrive but before anyone
136suspects anything.
137
138Businesses have trade secrets, patent applications in preparation,
139pricing information, subcontractor information, client data, personnel
140data, financial information, etc. Currently, anyone with access to
141the network (any machine on the network) can listen to anything that
142goes in the network, without any regard to normal access restrictions.
143
144Many companies are not aware that information can so easily be
145recovered from the network. They trust that their data is safe
146since nobody is supposed to know that there is sensitive information
147in the network, or because so much other data is transferred in the
148network. This is not a safe policy.
149
150Individual persons also have confidential information, such as
151diaries, love letters, health care documents, information about their
152personal interests and habits, professional data, job applications,
153tax reports, political documents, unpublished manuscripts, etc.
154
155One should also be aware that economical intelligence and industrial
156espionage has recently become a major priority of the intelligence
157agencies of major governments. President Clinton recently assigned
158economical espionage as the primary task of the CIA, and the French
159have repeatedly been publicly boasting about their achievements on
160this field.
161
162
163There is also another frightening aspect about the poor security of
164communications. Computer storage and analysis capability has
165increased so much that it is feasible for governments, major
166companies, and criminal organizations to automatically analyze,
167identify, classify, and file information about millions of people over
168the years. Because most of the work can be automated, the cost of
169collecting this information is getting very low.
170
171Government agencies may be able to monitor major communication
172systems, telephones, fax, computer networks, etc., and passively
173collect huge amounts of information about all people with any
174significant position in the society. Most of this information is not
175sensitive, and many people would say there is no harm in someone
176getting that information. However, the information starts to get
177sensitive when someone has enough of it. You may not mind someone
178knowing what you bought from the shop one random day, but you might
179not like someone knowing every small thing you have bought in the last
180ten years.
181
182If the government some day starts to move into a more totalitarian
183direction (one should remember that Nazi Germany was created by
184democratic elections), there is considerable danger of an ultimate
185totalitarian state. With enough information (the automatically
186collected records of an individual can be manually analyzed when the
187person becomes interesting), one can form a very detailed picture of
188the individual's interests, opinions, beliefs, habits, friends,
189lovers, weaknesses, etc. This information can be used to 1) locate
190any persons who might oppose the new system 2) use deception to
191disturb any organizations which might rise against the government 3)
192eliminate difficult individuals without anyone understanding what
193happened. Additionally, if the government can monitor communications
194too effectively, it becomes too easy to locate and eliminate any
195persons distributing information contrary to the official truth.
196
197Fighting crime and terrorism are often used as grounds for domestic
198surveillance and restricting encryption. These are good goals, but
199there is considerable danger that the surveillance data starts to get
200used for questionable purposes. I find that it is better to tolerate
201a small amount of crime in the society than to let the society become
202fully controlled. I am in favor of a fairly strong state, but the
203state must never get so strong that people become unable to spread
204contra-offical information and unable to overturn the government if it
205is bad. The danger is that when you notice that the government is
206too powerful, it is too late. Also, the real power may not be where
207the official government is.
208
209For these reasons (privacy, protecting trade secrets, and making it
210more difficult to create a totalitarian state), I think that strong
211cryptography should be integrated to the tools we use every day.
212Using it causes no harm (except for those who wish to monitor
213everything), but not using it can cause huge problems. If the society
214changes in undesirable ways, then it will be to late to start
215encrypting.
216
217Encryption has had a "military" or "classified" flavor to it. There
218are no longer any grounds for this. The military can and will use its
219own encryption; that is no excuse to prevent the civilians from
220protecting their privacy and secrets. Information on strong
221encryption is available in every major bookstore, scientific library,
222and patent office around the world, and strong encryption software is
223available in every country on the Internet.
224
225Some people would like to make it illegal to use encryption, or to
226force people to use encryption that governments can break. This
227approach offers no protection if the government turns bad. Also, the
228"bad guys" will be using true strong encryption anyway. Good
229encryption techniques are too widely known to make them disappear.
230Thus, any "key escrow encryption" or other restrictions will only help
231monitor ordinary people and petty criminals. It does not help against
232powerful criminals, terrorists, or espionage, because they will know
233how to use strong encryption anyway. (One source for internationally
234available encryption software is http://www.cs.hut.fi/crypto.)
235
236
237OVERVIEW OF SECURE SHELL
238
239The software consists of a number of programs.
240
241 sshd Server program run on the server machine. This
242 listens for connections from client machines, and
243 whenever it receives a connection, it performs
244 authentication and starts serving the client.
245
246 ssh This is the client program used to log into another
247 machine or to execute commands on the other machine.
248 "slogin" is another name for this program.
249
250 scp Securely copies files from one machine to another.
251
252 ssh-keygen Used to create RSA keys (host keys and user
253 authentication keys).
254
255 ssh-agent Authentication agent. This can be used to hold RSA
256 keys for authentication.
257
258 ssh-add Used to register new keys with the agent.
259
260 make-ssh-known-hosts
261 Used to create the /etc/ssh_known_hosts file.
262
263
264Ssh is the program users normally use. It is started as
265
266 ssh host
267
268or
269
270 ssh host command
271
272The first form opens a new shell on the remote machine (after
273authentication). The latter form executes the command on the remote
274machine.
275
276When started, the ssh connects sshd on the server machine, verifies
277that the server machine really is the machine it wanted to connect,
278exchanges encryption keys (in a manner which prevents an outside
279listener from getting the keys), performs authentication using .rhosts
280and /etc/hosts.equiv, RSA authentication, or conventional password
281based authentication. The server then (normally) allocates a
282pseudo-terminal and starts an interactive shell or user program.
283
284The TERM environment variable (describing the type of the user's
285terminal) is passed from the client side to the remote side. Also,
286terminal modes will be copied from the client side to the remote side
287to preserve user preferences (e.g., the erase character).
288
289If the DISPLAY variable is set on the client side, the server will
290create a dummy X server and set DISPLAY accordingly. Any connections
291to the dummy X server will be forwarded through the secure channel,
292and will be made to the real X server from the client side. An
293arbitrary number of X programs can be started during the session, and
294starting them does not require anything special from the user. (Note
295that the user must not manually set DISPLAY, because then it would
296connect directly to the real display instead of going through the
297encrypted channel). This behavior can be disabled in the
298configuration file or by giving the -x option to the client.
299
300Arbitrary IP ports can be forwarded over the secure channel. The
301program then creates a port on one side, and whenever a connection is
302opened to this port, it will be passed over the secure channel, and a
303connection will be made from the other side to a specified host:port
304pair. Arbitrary IP forwarding must always be explicitly requested,
305and cannot be used to forward privileged ports (unless the user is
306root). It is possible to specify automatic forwards in a per-user
307configuration file, for example to make electronic cash systems work
308securely.
309
310If there is an authentication agent on the client side, connection to
311it will be automatically forwarded to the server side.
312
313For more infomation, see the manual pages ssh(1), sshd(8), scp(1),
314ssh-keygen(1), ssh-agent(1), ssh-add(1), and make-ssh-known-hosts(1)
315included in this distribution.
316
317
318X11 CONNECTION FORWARDING
319
320X11 forwarding serves two purposes: it is a convenience to the user
321because there is no need to set the DISPLAY variable, and it provides
322encrypted X11 connections. I cannot think of any other easy way to
323make X11 connections encrypted; modifying the X server, clients or
324libraries would require special work for each machine, vendor and
325application. Widely used IP-level encryption does not seem likely for
326several years. Thus what we have left is faking an X server on the
327same machine where the clients are run, and forwarding the connections
328to a real X server over the secure channel.
329
330X11 forwarding works as follows. The client extracts Xauthority
331information for the server. It then creates random authorization
332data, and sends the random data to the server. The server allocates
333an X11 display number, and stores the (fake) Xauthority data for this
334display. Whenever an X11 connection is opened, the server forwards
335the connection over the secure channel to the client, and the client
336parses the first packet of the X11 protocol, substitutes real
337authentication data for the fake data (if the fake data matched), and
338forwards the connection to the real X server.
339
340If the display does not have Xauthority data, the server will create a
341unix domain socket in /tmp/.X11-unix, and use the unix domain socket
342as the display. No authentication information is forwarded in this
343case. X11 connections are again forwarded over the secure channel.
344To the X server the connections appear to come from the client
345machine, and the server must have connections allowed from the local
346machine. Using authentication data is always recommended because not
347using it makes the display insecure. If XDM is used, it automatically
348generates the authentication data.
349
350One should be careful not to use "xin" or "xstart" or other similar
351scripts that explicitly set DISPLAY to start X sessions in a remote
352machine, because the connection will then not go over the secure
353channel. The recommended way to start a shell in a remote machine is
354
355 xterm -e ssh host &
356
357and the recommended way to execute an X11 application in a remote
358machine is
359
360 ssh -n host emacs &
361
362If you need to type a password/passphrase for the remote machine,
363
364 ssh -f host emacs
365
366may be useful.
367
368
369
370RSA AUTHENTICATION
371
372RSA authentication is based on public key cryptograpy. The idea is
373that there are two encryption keys, one for encryption and another for
374decryption. It is not possible (on human timescale) to derive the
375decryption key from the encryption key. The encryption key is called
376the public key, because it can be given to anyone and it is not
377secret. The decryption key, on the other hand, is secret, and is
378called the private key.
379
380RSA authentication is based on the impossibility of deriving the
381private key from the public key. The public key is stored on the
382server machine in the user's $HOME/.ssh/authorized_keys file. The
383private key is only kept on the user's local machine, laptop, or other
384secure storage. Then the user tries to log in, the client tells the
385server the public key that the user wishes to use for authentication.
386The server then checks if this public key is admissible. If so, it
387generates a 256 bit random number, encrypts it with the public key,
388and sends the value to the client. The client then decrypts the
389number with its private key, computes a 128 bit MD5 checksum from the
390resulting data, and sends the checksum back to the server. (Only a
391checksum is sent to prevent chosen-plaintext attacks against RSA.)
392The server checks computes a checksum from the correct data,
393and compares the checksums. Authentication is accepted if the
394checksums match. (Theoretically this indicates that the client
395only probably knows the correct key, but for all practical purposes
396there is no doubt.)
397
398The RSA private key can be protected with a passphrase. The
399passphrase can be any string; it is hashed with MD5 to produce an
400encryption key for IDEA, which is used to encrypt the private part of
401the key file. With passphrase, authorization requires access to the key
402file and the passphrase. Without passphrase, authorization only
403depends on possession of the key file.
404
405RSA authentication is the most secure form of authentication supported
406by this software. It does not rely on the network, routers, domain
407name servers, or the client machine. The only thing that matters is
408access to the private key.
409
410All this, of course, depends on the security of the RSA algorithm
411itself. RSA has been widely known since about 1978, and no effective
412methods for breaking it are known if it is used properly. Care has
413been taken to avoid the well-known pitfalls. Breaking RSA is widely
414believed to be equivalent to factoring, which is a very hard
415mathematical problem that has received considerable public research.
416So far, no effective methods are known for numbers bigger than about
417512 bits. However, as computer speeds and factoring methods are
418increasing, 512 bits can no longer be considered secure. The
419factoring work is exponential, and 768 or 1024 bits are widely
420considered to be secure in the near future.
421
422
423RHOSTS AUTHENTICATION
424
425Conventional .rhosts and hosts.equiv based authentication mechanisms
426are fundamentally insecure due to IP, DNS (domain name server) and
427routing spoofing attacks. Additionally this authentication method
428relies on the integrity of the client machine. These weaknesses is
429tolerable, and been known and exploited for a long time.
430
431Ssh provides an improved version of these types of authentication,
432because they are very convenient for the user (and allow easy
433transition from rsh and rlogin). It permits these types of
434authentication, but additionally requires that the client host be
435authenticated using RSA.
436
437The server has a list of host keys stored in /etc/ssh_known_host, and
438additionally each user has host keys in $HOME/.ssh/known_hosts. Ssh
439uses the name servers to obtain the canonical name of the client host,
440looks for its public key in its known host files, and requires the
441client to prove that it knows the private host key. This prevents IP
442and routing spoofing attacks (as long as the client machine private
443host key has not been compromized), but is still vulnerable to DNS
444attacks (to a limited extent), and relies on the integrity of the
445client machine as to who is requesting to log in. This prevents
446outsiders from attacking, but does not protect against very powerful
447attackers. If maximal security is desired, only RSA authentication
448should be used.
449
450It is possible to enable conventional .rhosts and /etc/hosts.equiv
451authentication (without host authentication) at compile time by giving
452the option --with-rhosts to configure. However, this is not
453recommended, and is not done by default.
454
455These weaknesses are present in rsh and rlogin. No improvement in
456security will be obtained unless rlogin and rsh are completely
457disabled (commented out in /etc/inetd.conf). This is highly
458recommended.
459
460
461WEAKEST LINKS IN SECURITY
462
463One should understand that while this software may provide
464cryptographically secure communications, it may be easy to
465monitor the communications at their endpoints.
466
467Basically, anyone with root access on the local machine on which you
468are running the software may be able to do anything. Anyone with root
469access on the server machine may be able to monitor your
470communications, and a very talented root user might even be able to
471send his/her own requests to your authentication agent.
472
473One should also be aware that computers send out electromagnetic
474radition that can sometimes be picked up hundreds of meters away.
475Your keyboard is particularly easy to listen to. The image on your
476monitor might also be seen on another monitor in a van parked behind
477your house.
478
479Beware that unwanted visitors might come to your home or office and
480use your machine while you are away. They might also make
481modifications or install bugs in your hardware or software.
482
483Beware that the most effective way for someone to decrypt your data
484may be with a rubber hose.
485
486
487LEGAL ISSUES
488
489As far as I am concerned, anyone is permitted to use this software
490freely. However, see the file COPYING for detailed copying,
491licensing, and distribution information.
492
493In some countries, particularly France, Russia, Iraq, and Pakistan,
494it may be illegal to use any encryption at all without a special
495permit, and the rumor has it that you cannot get a permit for any
496strong encryption.
497
498This software may be freely imported into the United States; however,
499the United States Government may consider re-exporting it a criminal
500offence.
501
502Note that any information and cryptographic algorithms used in this
503software are publicly available on the Internet and at any major
504bookstore, scientific library, or patent office worldwide.
505
506THERE IS NO WARRANTY FOR THIS PROGRAM. Please consult the file
507COPYING for more information.
508
509
510MAILING LISTS AND OTHER INFORMATION
511
512There is a mailing list for ossh. It is ossh@sics.se. If you would
513like to join, send a message to majordomo@sics.se with "subscribe
514ssh" in body.
515
516The WWW home page for ssh is http://www.cs.hut.fi/ssh. It contains an
517archive of the mailing list, and detailed information about new
518releases, mailing lists, and other relevant issues.
519
520Bug reports should be sent to ossh-bugs@sics.se.
521
522
523ABOUT THE AUTHOR
524
525This software was written by Tatu Ylonen <ylo@cs.hut.fi>. I work as a
526researcher at Helsinki University of Technology, Finland. For more
527information, see http://www.cs.hut.fi/~ylo/. My PGP public key is
528available via finger from ylo@cs.hut.fi and from the key servers. I
529prefer PGP encrypted mail.
530
531The author can be contacted via ordinary mail at
532 Tatu Ylonen
533 Helsinki University of Technology
534 Otakaari 1
535 FIN-02150 ESPOO
536 Finland
537
538 Fax. +358-0-4513293
539
540
541ACKNOWLEDGEMENTS
542
543I thank Tero Kivinen, Timo Rinne, Janne Snabb, and Heikki Suonsivu for
544their help and comments in the design, implementation and porting of
545this software. I also thank numerous contributors, including but not
546limited to Walker Aumann, Jurgen Botz, Hans-Werner Braun, Stephane
547Bortzmeyer, Adrian Colley, Michael Cooper, David Dombek, Jerome
548Etienne, Bill Fithen, Mark Fullmer, Bert Gijsbers, Andreas Gustafsson,
549Michael Henits, Steve Johnson, Thomas Koenig, Felix Leitner, Gunnar
550Lindberg, Andrew Macpherson, Marc Martinec, Paul Mauvais, Donald
551McKillican, Leon Mlakar, Robert Muchsel, Mark Treacy, Bryan
552O'Sullivan, Mikael Suokas, Ollivier Robert, Jakob Schlyter, Tomasz
553Surmacz, Alvar Vinacua, Petri Virkkula, Michael Warfield, and
554Cristophe Wolfhugel.
555
556Thanks also go to Philip Zimmermann, whose PGP software and the
557associated legal battle provided inspiration, motivation, and many
558useful techniques, and to Bruce Schneier whose book Applied
559Cryptography has done a great service in widely distributing knowledge
560about cryptographic methods.
561
562
563Copyright (c) 1995 Tatu Ylonen, Espoo, Finland.