freebsd-src/crypto/openssh/README

[ Please note that this file has not been updated for OpenSSH and 
  covers the ssh-1.2.12 release from Dec 1995 only. ]

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.12.


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, DES, 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.

Any information that you type or is printed on your screen can be
monitored, recorded, and analyzed.  For example, an intruder who has
penetrated a host connected to a major network can start a program
that listens to all data flowing in the network, and whenever it
encounters a 16-digit string, it checks if it is a valid credit card
number (using the check digit), and saves the number plus any
surrounding text (to catch expiration date and holder) in a file.
When the intruder has collected a few thousand credit card numbers, he
makes smallish mail-order purchases from a few thousand stores around
the world, and disappears when the goods arrive but before anyone
suspects anything.

Businesses have trade secrets, patent applications in preparation,
pricing information, subcontractor information, client data, personnel
data, financial information, etc.  Currently, anyone with access to
the network (any machine on the network) can listen to anything that
goes in the network, without any regard to normal access restrictions.

Many companies are not aware that information can so easily be
recovered from the network.  They trust that their data is safe
since nobody is supposed to know that there is sensitive information
in the network, or because so much other data is transferred in the
network.  This is not a safe policy.

Individual persons also have confidential information, such as
diaries, love letters, health care documents, information about their
personal interests and habits, professional data, job applications,
tax reports, political documents, unpublished manuscripts, etc.

One should also be aware that economical intelligence and industrial
espionage has recently become a major priority of the intelligence
agencies of major governments.  President Clinton recently assigned
economical espionage as the primary task of the CIA, and the French
have repeatedly been publicly boasting about their achievements on
this field.


There is also another frightening aspect about the poor security of
communications.  Computer storage and analysis capability has
increased so much that it is feasible for governments, major
companies, and criminal organizations to automatically analyze,
identify, classify, and file information about millions of people over
the years.  Because most of the work can be automated, the cost of
collecting this information is getting very low.  

Government agencies may be able to monitor major communication
systems, telephones, fax, computer networks, etc., and passively
collect huge amounts of information about all people with any
significant position in the society.  Most of this information is not
sensitive, and many people would say there is no harm in someone
getting that information.  However, the information starts to get
sensitive when someone has enough of it.  You may not mind someone
knowing what you bought from the shop one random day, but you might
not like someone knowing every small thing you have bought in the last
ten years.

If the government some day starts to move into a more totalitarian
direction (one should remember that Nazi Germany was created by
democratic elections), there is considerable danger of an ultimate
totalitarian state.  With enough information (the automatically
collected records of an individual can be manually analyzed when the
person becomes interesting), one can form a very detailed picture of
the individual's interests, opinions, beliefs, habits, friends,
lovers, weaknesses, etc.  This information can be used to 1) locate
any persons who might oppose the new system 2) use deception to
disturb any organizations which might rise against the government 3)
eliminate difficult individuals without anyone understanding what
happened.  Additionally, if the government can monitor communications
too effectively, it becomes too easy to locate and eliminate any
persons distributing information contrary to the official truth.

Fighting crime and terrorism are often used as grounds for domestic
surveillance and restricting encryption.  These are good goals, but
there is considerable danger that the surveillance data starts to get
used for questionable purposes.  I find that it is better to tolerate
a small amount of crime in the society than to let the society become
fully controlled.  I am in favor of a fairly strong state, but the
state must never get so strong that people become unable to spread
contra-offical information and unable to overturn the government if it
is bad.  The danger is that when you notice that the government is
too powerful, it is too late.  Also, the real power may not be where
the official government is.

For these reasons (privacy, protecting trade secrets, and making it
more difficult to create a totalitarian state), I think that strong
cryptography should be integrated to the tools we use every day.
Using it causes no harm (except for those who wish to monitor
everything), but not using it can cause huge problems.  If the society
changes in undesirable ways, then it will be to late to start
encrypting.

Encryption has had a "military" or "classified" flavor to it.  There
are no longer any grounds for this.  The military can and will use its
own encryption; that is no excuse to prevent the civilians from
protecting their privacy and secrets.  Information on strong
encryption is available in every major bookstore, scientific library,
and patent office around the world, and strong encryption software is
available in every country on the Internet.

Some people would like to make it illegal to use encryption, or to
force people to use encryption that governments can break.  This
approach offers no protection if the government turns bad.  Also, the
"bad guys" will be using true strong encryption anyway.  Good
encryption techniques are too widely known to make them disappear.
Thus, any "key escrow encryption" or other restrictions will only help
monitor ordinary people and petty criminals.  It does not help against
powerful criminals, terrorists, or espionage, because they will know
how to use strong encryption anyway.  (One source for internationally
available encryption software is http://www.cs.hut.fi/crypto.)


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 infomation, 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 cryptograpy.  The idea is
that there are two encryption keys, one for encryption and another for
decryption.  It is not possible (on human timescale) 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 IDEA, 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 compromized), 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.


WEAKEST LINKS IN SECURITY

One should understand that while this software may provide
cryptographically secure communications, it may be easy to
monitor the communications at their endpoints.

Basically, anyone with root access on the local machine on which you
are running the software may be able to do anything.  Anyone with root
access on the server machine may be able to monitor your
communications, and a very talented root user might even be able to
send his/her own requests to your authentication agent.

One should also be aware that computers send out electromagnetic
radition that can sometimes be picked up hundreds of meters away.
Your keyboard is particularly easy to listen to.  The image on your
monitor might also be seen on another monitor in a van parked behind
your house.

Beware that unwanted visitors might come to your home or office and
use your machine while you are away.  They might also make
modifications or install bugs in your hardware or software.

Beware that the most effective way for someone to decrypt your data
may be with a rubber hose.


LEGAL ISSUES

As far as I am concerned, anyone is permitted to use this software
freely.  However, see the file COPYING for detailed copying,
licensing, and distribution information.

In some countries, particularly France, Russia, Iraq, and Pakistan,
it may be illegal to use any encryption at all without a special
permit, and the rumor has it that you cannot get a permit for any
strong encryption.

This software may be freely imported into the United States; however,
the United States Government may consider re-exporting it a criminal
offence.

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.

THERE IS NO WARRANTY FOR THIS PROGRAM.  Please consult the file
COPYING for more information.


MAILING LISTS AND OTHER INFORMATION

There is a mailing list for ossh.  It is ossh@sics.se.  If you would
like to join, send a message to majordomo@sics.se 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.

Bug reports should be sent to ossh-bugs@sics.se.


ABOUT THE AUTHOR

This software was written by Tatu Ylonen <ylo@cs.hut.fi>.  I work as a
researcher at Helsinki University of Technology, Finland.  For more
information, see http://www.cs.hut.fi/~ylo/.  My PGP public key is
available via finger from ylo@cs.hut.fi and from the key servers.  I
prefer PGP encrypted mail.

The author can be contacted via ordinary mail at
  Tatu Ylonen
  Helsinki University of Technology
  Otakaari 1
  FIN-02150 ESPOO
  Finland

  Fax. +358-0-4513293


ACKNOWLEDGEMENTS

I thank Tero Kivinen, Timo Rinne, Janne Snabb, and Heikki Suonsivu for
their help and comments in the design, implementation and porting of
this software.  I also thank numerous contributors, including but not
limited to Walker Aumann, Jurgen Botz, Hans-Werner Braun, Stephane
Bortzmeyer, Adrian Colley, Michael Cooper, David Dombek, Jerome
Etienne, Bill Fithen, Mark Fullmer, Bert Gijsbers, Andreas Gustafsson,
Michael Henits, Steve Johnson, Thomas Koenig, Felix Leitner, Gunnar
Lindberg, Andrew Macpherson, Marc Martinec, Paul Mauvais, Donald
McKillican, Leon Mlakar, Robert Muchsel, Mark Treacy, Bryan
O'Sullivan, Mikael Suokas, Ollivier Robert, Jakob Schlyter, Tomasz
Surmacz, Alvar Vinacua, Petri Virkkula, Michael Warfield, and
Cristophe Wolfhugel.

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) 1995 Tatu Ylonen, Espoo, Finland.