SSHProxy v0.20 (18 Nov 2004)
============================

SSHProxy is a client for the SSH v1.5 protocol, which allows secure
connections between computers over networks that may be eavesdropped by
others or subject to security attacks by third parties.  The SSH v1.5
protocol provides a number of secure services, notably:

Terminal session 
 - similar to rsh (remote shell) or telnet - but _NOT_ encrypted telnet
File transfer (scp)
 - similar to rcp (remote copy), not much like FTP
Port forwarding
 - data sent to a local port is encrypted and sent to a specified port
   on a remote machine - eg forwarding a connection to your mailserver on
   port 25 (SMTP) allows you to send email securely to your mailserver,
   as long as the mailserver is running an ssh server
X11 forwarding
 - allows X11 sessions to be passed to your machine over a secure link
Optional transparent compression of the above streams

SSHProxy is an implementation of the terminal session part of the protocol,
without compression.  A sister command line application, pscp, provides
secure file transfer.  SSHProxy works as a proxy, allowing you to use your
favourite telnet client to control a terminal session, yet sending all data
encrypted securely over the network.

Why is SSH useful?
------------------

Many people do not realise that when they use a standard protocol, such as
telnet, FTP, POP3 etc, their passwords and all their data is sent 'in the
clear'.  This means that anyone with a computer that is hooked up to the
network along which it travels can run a simple program on their computer and
see what you are typing - capture your passwords, read your email and so on.
The danger is most present close to the machines at each end of the
connection - for example, anyone one on the same run of ethernet cable as
either end of the connection can read all the data.  Other vulnerabilities
include 'IP spoofing', in which someone else can pretend to be the remote
machine, so when you login to send your email, you send your password and all
your data to some hacker, rather than the reputable mail server you thought
you were talking to.  SSH prevents these problems by encrypting the data so
no-one can eavesdrop, and by each end having a private key, which allows you
to be sure that you are talking to who you think you are talking to.

SSH 1 or SSH 2?
---------------

There are two versions of the SSH protocol out there.  SSH 2 is a brand new
protocol from SSH 1, and is completely incompatible with SSH 1, while
corrects some rare security issues in SSH 1. Also, the offical SSH 2 server
is only available under a restrictive licence, which makes it free for only a
limited set of organisations and individuals.  OpenSSH, a GPLd SSH 2 server
has recently been released, but due to the previous restrictions, uptake of
SSH 2 servers has been slow.  To add to this, some SSH 2 servers can be built
with an SSH 1 backwards compatibility mode, but not the other way around. 
Therefore pscp and SSHProxy implement SSH 1, to allow the widest possible
use.

Running SSHProxy
----------------

First you need to have installed:
  An Internet stack
    (if telnet other than Termite already works on your machine then
     you've already got one of those)
  SysLog 0.17 by Doggysoft
    ( http://www.acornsearch.com/archives/freenet.barnet.ac.uk/pub/Acorn/freenet/j.ribbens/syslog-0.17.spk )
  A telnet client
  
Run the !SSHProxy application.  Nothing will appear to happen, except an
SSHProxy line will appear in the TaskManager.  To open a session, telnet to
localhost on port 2200 (if your telnet client doesn't have a port option, try
'localhost:2200' or 'localhost 2200').  You should get a prompt similar to:

  Welcome to SSHProxy! 0.11 (12 Nov 2000)
  Build 730, Nov 19 2000, 22:22:03
  By Theo Markettos (theo@markettos.org.uk)
  
  Connect to: 

At the connect prompt, enter the name of the host you want to connect to, and
it should try to connect - eg:

  Connect to: somehost.example.com
  Connecting - resolving...
  Resolving...
  
  *** Don't recognise this remote host - adding to local list of known hosts
  *** Make sure they are who they claim to be...
  login as:

If you want to connect to a port on the server other than the default (22),
use the form hostname:port instead.

Now enter your username and, when prompted, your password.  A session should
now open and you are connected to the remote machine.  You can use this like
a normal shell, except you don't have to worry about it being intercepted.

To open more sessions, you can repeatedly telnet to localhost port 2200, up
to a limit of 16 sessions open at the same time.  For security reasons, the
default configuration is for SSHProxy to only accept connections from
localhost (127.0.0.1) - attempting to connect from any other machine will
result in the connection being closed.  If you quit SSHProxy and rerun it
less than a minute or so after a connection was closed, you may find you need
to wait a few seconds or so for the Internet stack to tidy up its connections
before it can successfully run on the same port as it was before.  This is a
design feature of the stack (so that the new server on port 2200 doesn't get
sent anything meant for the one that's just been killed), and can't be
avoided.

The warning given above is due to SSH's use of 'host keys'.  When tyou
connect to a remote machine 'fred', these make it possible to check whether
the machine called 'fred' you connected to last time is actually the same
machine (keys agree) or someone else pretending to be them (keys differ). 
The keys are stored on your machine in Choices:Crypto.SSH.KnownHosts-
this is the same format as the Unix version of SSH, so if your network
supplies a known-hosts file, you can put it here (for example, a list of
Cambridge University machines can be found at
http://www-uxsup.csx.cam.ac.uk/CD/ ).  If the machine was known before and
the keys match, SSHProxy will confirm this, while if the keys do not match,
SSHProxy will give you a warning.  If you are at all suspicious, do not
continue to login - however, if the system has poor system administration the
key change might be to loss of it at the server, such as a disc crash or a
system upgrade, in which case it is safe.  If you are in doubt, check by some
other means.  SSHProxy will give you a warning as above if you've not logged
into this host before - you should be cautious, but not unduly worried in
this case.  It will store the host key for future use, so you should only get
this once per machine.

SSHProxy will try its best to relay the terminal type sent by your telnet
client to the SSH server.  However, there's a particular race condition that
causes problems in this respect.  The telnet server can be slow at sending
the terminal type when it starts up - if it's slow enough such that a shell's
already been started at the SSH end, there's nothing SSHProxy can do as the
SSH server needs to know the terminal type when it starts a shell.  This may
happen particularly if you have a script to enter a host/username/password
combination for you.  In that case, the best strategy is to try to insert
pauses between the lines to give the client long enough to send the terminal
string.  An alternative strategy is to explicitly set the TERM variable (on a
Unix box) in the login script - eg 'export TERM=vt102' for bash shells.

Configuring SSHProxy
--------------------

No configuration is really necessary, as the default values should be
adequate for most.  The port on which SSHProxy connects can be changed by
suppling it as an argument to SSHProxy, either as:

Filer_Run <SSHProxy$Dir> 2201

or by adding it in the last line of the !Run file:

Run <SSHProxy$Dir>.sshproxy 2201 %*0

It is not currently recommended to run more than one copy of SSHProxy
on different ports.

Logging is produced in SysLog.  The default level of 125 should be
acceptable, the logging levels being:

  0  Errors (some which aren't reported elsewhere)
 30  Warnings (similarly)
 60  Initialisation data
100  Connections (opening/closing)
130  Low level connections (debugging messages from remote host)
160  High level debugging
200  Low level debugging
230  Very low level debugging
250  Code flow tracing

Increasing the logging level will provide more detail on what's happening,
but be prepared for a _lot_ of output (including all your passwords).  The
level can be changed in the !Run file, or while SSHProxy is running with
*Syslog SSHProxy <level>

SSHProxy will attempt to store its settings using a Choices: path.  If you
don't have one set up, it will store them inside the !SSHProxy application. 
This can be changed by setting the <SSHProxy$Choices> variable to point to
where they are to be stored.

If you wish to allow machines other than localhost to connect, you need to
set up some HostsAllow and HostsDeny text files.  This should be placed in
the Choices:Internet directory, and have the same format as /etc/hosts.allow
and hosts.deny on Unix.  The format of them is described in the Unix man
page, supplied as 'hosts_acc' - SSHProxy will take notice of a line beginning
'sshproxy:'.  Shell commands, rfc931 and NIS/YP are not currently supported. 
Some example files can be found in the HostsExmpl directory.  Typically you
might have ALL: ALL in HostsDeny (don't allow anyone unless specifically
given permission), then a line such as:

sshproxy:	loopback .intranet.example.com

to allow the local machine and other machines on your intranet.  Note that a)
if you want localhost to connect, you need to include localhost in this list
and b) to prevent DNS spoofing, if specifying by name you must specify
machines by the name their IP address looks up to (and not aliases), which
can be found using *host:

*host 127.0.0.1
Name: loopback
Address: 127.0.0.1
Aliases: localhost loghost

[so on my machine I specify loopback in the line above]

*host www.foo.com
www.foo.com is a nickname for foo.com
foo.com has address 209.54.94.99
foo.com mail is handled by mail.pyxos.com
*host 209.54.94.99
Name: www.digimedia.com
Address: 209.54.94.99
Aliases:

[so to allow www.foo.com to connect, I either have to specify its IP or
www.digimedia.com as that's the name the DNS return when it gets reverse
looked up]


Building SSHProxy
-----------------

The source for SSHProxy is available at
http://www.markettos.org.uk/

To build it you will need:

  A C compiler, I've used Castle's C v5.5 - GCC or Acorn C should work but
  are untested

  Libraries:
    Standard C library headers and stubs
    OSLib ( from http://ro-oslib.sf.net/ )
    Acorn's TCPIPLibs (supplied with Acorn/Castle C - Unixlib might work)
    Desk v3.10 or higher (a newer version of the library formerly known as
      DeskLib)

Later versions of libraries should be OK, although I haven't tested them.  If
you have any problems finding any of these or with compiling, let me know.

Contacting
----------

The latest version of SSHProxy should be available from
http://www.markettos.org.uk/riscos/crypto/ including binaries and sources. 
pscp and CryptRandom are also available from the same address.

The RISC OS version is written by Theo Markettos, who is contactable as
follows:

email: theo@markettos.org.uk

post:
5 Willow Close
Liphook
Hampshire
GU30 7HX
UK

SSHProxy is based on PuTTY 0.45beta, a Windows SSH client by Simon Tatham. 
PuTTY is available at http://www.chiark.greenend.org.uk/~sgtatham/putty.html
The official SSH Data Communications Inc. servers are available at
http://www.ssh.fi

Legalities
----------

See the file Copyright for more details

