source: trunk/third/ssh/README @ 12646

SSH (Secure Shell) is a program to log into another computer over a
network, to execute commands in a remote machine, and to move files
from one machine to another.  It provides strong authentication and
secure communications over insecure channels.  It is intended as a
replacement for rlogin, rsh, rcp, and rdist.

See the file INSTALL for installation instructions.  See COPYING for
license terms and other legal issues.  See RFC for a description of
the protocol.  There is a WWW page for ssh; see http://www.cs.hut.fi/ssh.

This file has been updated to match ssh-1.2.26 / f-secure ssh 1.3.6.


FEATURES

 o  Strong authentication.  Closes several security holes (e.g., IP,
    routing, and DNS spoofing).  New authentication methods: .rhosts
    together with RSA based host authentication, and pure RSA
    authentication.

 o  Improved privacy.  All communications are automatically and
    transparently encrypted.  RSA is used for key exchange, and a
    conventional cipher (normally IDEA, Blowfish, or triple-DES) for
    encrypting the session.  Encryption is started before
    authentication, and no passwords or other information is
    transmitted in the clear.  Encryption is also used to protect
    against spoofed packets.

 o  Secure X11 sessions.  The program automatically sets DISPLAY on
    the server machine, and forwards any X11 connections over the
    secure channel.  Fake Xauthority information is automatically
    generated and forwarded to the remote machine; the local client
    automatically examines incoming X11 connections and replaces the
    fake authorization data with the real data (never telling the 
    remote machine the real information).

 o  Arbitrary TCP/IP ports can be redirected through the encrypted channel
    in both directions (e.g., for e-cash transactions).

 o  No retraining needed for normal users; everything happens
    automatically, and old .rhosts files will work with strong
    authentication if administration installs host key files.

 o  Never trusts the network.  Minimal trust on the remote side of
    the connection.  Minimal trust on domain name servers.  Pure RSA
    authentication never trusts anything but the private key.

 o  Client RSA-authenticates the server machine in the beginning of
    every connection to prevent trojan horses (by routing or DNS
    spoofing) and man-in-the-middle attacks, and the server
    RSA-authenticates the client machine before accepting .rhosts or
    /etc/hosts.equiv authentication (to prevent DNS, routing, or
    IP-spoofing).

 o  Host authentication key distribution can be centrally by the
    administration, automatically when the first connection is made
    to a machine (the key obtained on the first connection will be
    recorded and used for authentication in the future), or manually
    by each user for his/her own use.  The central and per-user host
    key repositories are both used and complement each other.  Host
    keys can be generated centrally or automatically when the software
    is installed.  Host authentication keys are typically 1024 bits.

 o  Any user can create any number of user authentication RSA keys for
    his/her own use.  Each user has a file which lists the RSA public
    keys for which proof of possession of the corresponding private
    key is accepted as authentication.  User authentication keys are
    typically 1024 bits.

 o  The server program has its own server RSA key which is
    automatically regenerated every hour.  This key is never saved in
    any file.  Exchanged session keys are encrypted using both the
    server key and the server host key.  The purpose of the separate
    server key is to make it impossible to decipher a captured session by
    breaking into the server machine at a later time; one hour from
    the connection even the server machine cannot decipher the session
    key.  The key regeneration interval is configurable.  The server
    key is normally 768 bits.

 o  An authentication agent, running in the user's laptop or local
    workstation, can be used to hold the user's RSA authentication
    keys.  Ssh automatically forwards the connection to the
    authentication agent over any connections, and there is no need to
    store the RSA authentication keys on any machine in the network
    (except the user's own local machine).  The authentication
    protocols never reveal the keys; they can only be used to verify
    that the user's agent has a certain key.  Eventually the agent
    could rely on a smart card to perform all authentication
    computations.

 o  The software can be installed and used (with restricted
    functionality) even without root privileges.

 o  The client is customizable in system-wide and per-user
    configuration files.  Most aspects of the client's operation can
    be configured.  Different options can be specified on a per-host basis.

 o  Automatically executes conventional rsh (after displaying a
    warning) if the server machine is not running sshd.

 o  Optional compression of all data with gzip (including forwarded X11
    and TCP/IP port data), which may result in significant speedups on
    slow connections.

 o  Complete replacement for rlogin, rsh, and rcp.


WHY TO USE SECURE SHELL

Currently, almost all communications in computer networks are done
without encryption.  As a consequence, anyone who has access to any
machine connected to the network can listen in on any communication.
This is being done by hackers, curious administrators, employers,
criminals, industrial spies, and governments.  Some networks leak off
enough electromagnetic radiation that data may be captured even from a
distance.

When you log in, your password goes in the network in plain
text.  Thus, any listener can then use your account to do any evil he
likes.  Many incidents have been encountered worldwide where crackers
have started programs on workstations without the owners knowledge
just to listen to the network and collect passwords.  Programs for
doing this are available on the Internet, or can be built by a
competent programmer in a few hours.

Furthermore, it is possible to hijack connections going though the
network.  This means that an intruder can enter in the middle of an
existing connection, and start modifying data in both directions.
This can, e.g., be used to insert new commands in sessions
authenticated by one-time passwords.  A consequence is that no
security method based on purely authenticating the user is safe.
Furthermore, routing spoofing can be used to bring almost any
connection in the Internet to a location where it can be attacked.

Encryption and cryptographic authentication and integrity protection
are required to secure networks and computer systems.  SSH uses strong
cryptographic algorithms to achieve these goals.

Ease of use is critical to the acceptance of a piece of software.  SSH
attempts to be *easier* to use than its insecure counterparts.

SSH has gained very wide acceptance.  It is currently (late 1996)
being used in approximately 50 countries at probably tens of thousands
of organizations.  Its users include top universities, research
laboratories, banks, major corporations, and numerous smaller
companies and individuals.

SSH is available for almost all Unix platforms, and commercial
versions are available for Windows (3.1, 95, NT) and Macintosh.  For
more information, see http://www.datafellows.com/f-secure.


OVERVIEW OF SECURE SHELL

The software consists of a number of programs.

   sshd         Server program run on the server machine.  This
                listens for connections from client machines, and
                whenever it receives a connection, it performs
                authentication and starts serving the client.

   ssh          This is the client program used to log into another
                machine or to execute commands on the other machine.
                "slogin" is another name for this program.

   scp          Securely copies files from one machine to another.

   ssh-keygen   Used to create RSA keys (host keys and user
                authentication keys).

   ssh-agent    Authentication agent.  This can be used to hold RSA
                keys for authentication.

   ssh-add      Used to register new keys with the agent.

   make-ssh-known-hosts
                Used to create the /etc/ssh_known_hosts file.


Ssh is the program users normally use.  It is started as

  ssh host

or

  ssh host command

The first form opens a new shell on the remote machine (after
authentication).  The latter form executes the command on the remote
machine.

When started, the ssh connects sshd on the server machine, verifies
that the server machine really is the machine it wanted to connect,
exchanges encryption keys (in a manner which prevents an outside
listener from getting the keys), performs authentication using .rhosts
and /etc/hosts.equiv, RSA authentication, or conventional password
based authentication.  The server then (normally) allocates a
pseudo-terminal and starts an interactive shell or user program.

The TERM environment variable (describing the type of the user's
terminal) is passed from the client side to the remote side.  Also,
terminal modes will be copied from the client side to the remote side
to preserve user preferences (e.g., the erase character).

If the DISPLAY variable is set on the client side, the server will
create a dummy X server and set DISPLAY accordingly.  Any connections
to the dummy X server will be forwarded through the secure channel,
and will be made to the real X server from the client side.  An
arbitrary number of X programs can be started during the session, and
starting them does not require anything special from the user.  (Note
that the user must not manually set DISPLAY, because then it would
connect directly to the real display instead of going through the
encrypted channel).  This behavior can be disabled in the
configuration file or by giving the -x option to the client.

Arbitrary IP ports can be forwarded over the secure channel.  The
program then creates a port on one side, and whenever a connection is
opened to this port, it will be passed over the secure channel, and a
connection will be made from the other side to a specified host:port
pair.  Arbitrary IP forwarding must always be explicitly requested,
and cannot be used to forward privileged ports (unless the user is
root).  It is possible to specify automatic forwards in a per-user
configuration file, for example to make electronic cash systems work
securely.

If there is an authentication agent on the client side, connection to
it will be automatically forwarded to the server side.

For more information, see the manual pages ssh(1), sshd(8), scp(1),
ssh-keygen(1), ssh-agent(1), ssh-add(1), and make-ssh-known-hosts(1)
included in this distribution.


X11 CONNECTION FORWARDING

X11 forwarding serves two purposes: it is a convenience to the user
because there is no need to set the DISPLAY variable, and it provides
encrypted X11 connections.  I cannot think of any other easy way to
make X11 connections encrypted; modifying the X server, clients or
libraries would require special work for each machine, vendor and
application.  Widely used IP-level encryption does not seem likely for
several years.  Thus what we have left is faking an X server on the
same machine where the clients are run, and forwarding the connections
to a real X server over the secure channel.

X11 forwarding works as follows.  The client extracts Xauthority
information for the server.  It then creates random authorization
data, and sends the random data to the server.  The server allocates
an X11 display number, and stores the (fake) Xauthority data for this
display.  Whenever an X11 connection is opened, the server forwards
the connection over the secure channel to the client, and the client
parses the first packet of the X11 protocol, substitutes real
authentication data for the fake data (if the fake data matched), and
forwards the connection to the real X server.

If the display does not have Xauthority data, the server will create a
unix domain socket in /tmp/.X11-unix, and use the unix domain socket
as the display.  No authentication information is forwarded in this
case.  X11 connections are again forwarded over the secure channel.
To the X server the connections appear to come from the client
machine, and the server must have connections allowed from the local
machine.  Using authentication data is always recommended because not
using it makes the display insecure.  If XDM is used, it automatically
generates the authentication data.

One should be careful not to use "xin" or "xstart" or other similar
scripts that explicitly set DISPLAY to start X sessions in a remote
machine, because the connection will then not go over the secure
channel.  The recommended way to start a shell in a remote machine is

  xterm -e ssh host &

and the recommended way to execute an X11 application in a remote
machine is

  ssh -n host emacs &

If you need to type a password/passphrase for the remote machine,

  ssh -f host emacs

may be useful.



RSA AUTHENTICATION

RSA authentication is based on public key cryptography.  The idea is
that there are two encryption keys, one for encryption and another for
decryption.  It is not possible (on human time scale) to derive the
decryption key from the encryption key.  The encryption key is called
the public key, because it can be given to anyone and it is not
secret.  The decryption key, on the other hand, is secret, and is
called the private key.

RSA authentication is based on the impossibility of deriving the
private key from the public key.  The public key is stored on the
server machine in the user's $HOME/.ssh/authorized_keys file.  The
private key is only kept on the user's local machine, laptop, or other
secure storage.  Then the user tries to log in, the client tells the
server the public key that the user wishes to use for authentication.
The server then checks if this public key is admissible.  If so, it
generates a 256 bit random number, encrypts it with the public key,
and sends the value to the client.  The client then decrypts the
number with its private key, computes a 128 bit MD5 checksum from the
resulting data, and sends the checksum back to the server.  (Only a
checksum is sent to prevent chosen-plaintext attacks against RSA.)
The server checks computes a checksum from the correct data,
and compares the checksums.  Authentication is accepted if the
checksums match.  (Theoretically this indicates that the client
only probably knows the correct key, but for all practical purposes
there is no doubt.)

The RSA private key can be protected with a passphrase.  The
passphrase can be any string; it is hashed with MD5 to produce an
encryption key for 3DES, which is used to encrypt the private part of
the key file.  With passphrase, authorization requires access to the key
file and the passphrase.  Without passphrase, authorization only
depends on possession of the key file.

RSA authentication is the most secure form of authentication supported
by this software.  It does not rely on the network, routers, domain
name servers, or the client machine.  The only thing that matters is
access to the private key.  

All this, of course, depends on the security of the RSA algorithm
itself.  RSA has been widely known since about 1978, and no effective
methods for breaking it are known if it is used properly.  Care has
been taken to avoid the well-known pitfalls.  Breaking RSA is widely
believed to be equivalent to factoring, which is a very hard
mathematical problem that has received considerable public research.
So far, no effective methods are known for numbers bigger than about
512 bits.  However, as computer speeds and factoring methods are
increasing, 512 bits can no longer be considered secure.  The
factoring work is exponential, and 768 or 1024 bits are widely
considered to be secure in the near future.


RHOSTS AUTHENTICATION

Conventional .rhosts and hosts.equiv based authentication mechanisms
are fundamentally insecure due to IP, DNS (domain name server) and
routing spoofing attacks.  Additionally this authentication method
relies on the integrity of the client machine.  These weaknesses is
tolerable, and been known and exploited for a long time.

Ssh provides an improved version of these types of authentication,
because they are very convenient for the user (and allow easy
transition from rsh and rlogin).  It permits these types of
authentication, but additionally requires that the client host be
authenticated using RSA.  

The server has a list of host keys stored in /etc/ssh_known_host, and
additionally each user has host keys in $HOME/.ssh/known_hosts.  Ssh
uses the name servers to obtain the canonical name of the client host,
looks for its public key in its known host files, and requires the
client to prove that it knows the private host key.  This prevents IP
and routing spoofing attacks (as long as the client machine private
host key has not been compromised), but is still vulnerable to DNS
attacks (to a limited extent), and relies on the integrity of the
client machine as to who is requesting to log in.  This prevents
outsiders from attacking, but does not protect against very powerful
attackers.  If maximal security is desired, only RSA authentication
should be used.

It is possible to enable conventional .rhosts and /etc/hosts.equiv
authentication (without host authentication) at compile time by giving
the option --with-rhosts to configure.  However, this is not
recommended, and is not done by default.

These weaknesses are present in rsh and rlogin.  No improvement in
security will be obtained unless rlogin and rsh are completely
disabled (commented out in /etc/inetd.conf).  This is highly
recommended.


LEGAL ISSUES

See the file COPYING for distribution conditions.  To summarize, you
can use this software freely for non-commercial purposes.  However,
this software cannot be sold or used for directly revenue-generating
purposes without licensing.  THERE IS NO WARRANTY FOR THIS PROGRAM.

In some countries, particularly Russia, Iraq, Pakistan, and France, it
may be illegal to use any encryption at all without a special permit.

This software may be freely imported into the United States; however,
the United States Government may consider re-exporting it a criminal
offense.  Thus, if you are outside the US, please retrieve this
software from outside the US.

Note that any information and cryptographic algorithms used in this
software are publicly available on the Internet and at any major
bookstore, scientific library, or patent office worldwide.


MAILING LISTS AND OTHER INFORMATION

There is a mailing list for ssh.  It is ssh@clinet.fi.  If you would
like to join, send a message to majordomo@clinet.fi with "subscribe
ssh" in body.

The WWW home page for ssh is http://www.cs.hut.fi/ssh.  It contains an
archive of the mailing list, and detailed information about new
releases, mailing lists, and other relevant issues.

For information about Windows, Macintosh, and commercial licensing,
see http://www.datafellows.com/f-secure, or mail to
f-secure-ssh-sales@datafellows.com.

Bug reports should be sent to ssh-bugs@cs.hut.fi.


ABOUT THE AUTHOR

This software was originally written by Tatu Ylonen <ylo@cs.hut.fi> in
Finland.  It is now being maintained by SSH Communications Security
(http://www.ssh.fi) and Data Fellows (http://www.datafellows.com).


ACKNOWLEDGEMENTS

Many people have contributed to the development of this software.

Martin Abadi, Jason Ackley, Satoshi Adachi, Tim Adam, Kazunori Ando,
Andre April, Walker Aumann, E. Jay Barkenbilt, Steve Bellovin, Steve
Birnbaum, Steve Bonds, Paul Borman, Stephane Bortzmeyer, Jim Bourne,
Jurgen Botz, Hans-Werner Braun, Bill Broadley, Piete Brooks, Loren
Buchanan, Donald Buczek, Joao Castro, Andrey Chernov, Adrian Colley,
Michael Cooper, Brian Cully, Felix von Delius, David Dombek, Ian
Donaldson, Sean Doran, Danek Duvall, Garance Drosehn, Niklas
Edmundsson, Doug Engert, Jerome Etienne, Bill Fithen, Mike Friedman,
Florian Fuchs, Mark Fullmer, Jean-Loup Gailly, Bert Gijsbers, Eivind
Gjelseth, Bob Goellner, Ian Goldberg, Chuck Goodhart, Aaron Gowatch,
Torbjorn Granlund, Teddy Grenman, Klaus Guntermann, Andreas
Gustafsson, Kojima Hajime, Charles M. Hannum, Michael Henits, Ville
Herva, Nick Hibma, Mark Horn, Ton Hospel, Antti Huima, Cedomir Igaly,
Bradford W. Johnson, Steve Johnson, LaMont Jones, Arne Juul, Petri
Kaukasoina, Charles Karney, Richard Kaszeta, Brendan Kehoe, Tero
Kivinen, Philip Kizer, Mika Kojo, Georg-W. Koltermann, David Kågedal,
Thomas König, Joseph Lappa, Felix Leitner, Ofer Licht, Gunnar
Lindberg, Markus Linnala, Harald Lundberg, Glenn Machin, Andrew
Macpherson, Marc Martinec, Paul Mauvais, David Mazieres, Harry
McGavran Jr., Donald McKillican, Pedro Melo, Luke Mewburn, Leon
Mlakar, Robert Muchsel, Kaj Mustikkamäki, Hannu Napari, Pekka
Nikander, Bill O'Neill, Bryan O'Sullivan, John P.Speno, Andy Polyakov,
Matt Power, Theo de Raadt, Andrew Raphael, Matt Richards, Michael
Richardson, Timo Rinne, Ollivier Robert, Maciej W. Rozycki, Dima
Ruban, Tomi Salo, Paul J. Sanchez, Corey Satten, Jakob Schlyter, Wayne
Schroeder, Jay Schuster, Harry Shamansky, Janne Snabb, Harlan Stenn,
Kevin Steves, Mikael Suokas, Heikki Suonsivu, Tomasz Surmacz, Holger
Trapp, Mark Treacy, Andrew Tridgell, Rick Troxel, Dragan Vecerina,
Wietse Venema, Witse Venema, Alvar Vinacua, Russell Vincent, Petri
Virkkula, Michael Warfield, Brian Weaver, Peter Wemm, Raymund Will,
Mike Williams, Christophe Wolfhugel and Craig Yap.

My apologies to people whom I have forgotten to list.

Thanks also go to Philip Zimmermann, whose PGP software and the
associated legal battle provided inspiration, motivation, and many
useful techniques, and to Bruce Schneier whose book Applied
Cryptography has done a great service in widely distributing knowledge
about cryptographic methods.


Copyright (c) 1996,1997,1998 SSH Communications Security, Espoo, Finland.