slush         SSL remote shell

0. Check prerequisites:

   You will need OpenSSL v0.9.3 or above installed.
   You can get OpenSSL from http://www.openssl.org/

1. Compile the software:

        ./configure
        make
        make install

2. Modify /etc/inetd.conf startup files.

Add a variant of the following line to your /etc/inetd.conf

1966	stream	tcp	nowait	root /path/to/slushd slushd

and restart inetd. "killall -HUP inetd". 1966 is the official port
assigned to slush.

3. Set /etc/hosts.allow and /etc/hosts.deny

You can limit access to slush based on IP address using the tcp wrappers.
For example:

echo "slushd: 10.10.5.0/255.255.255.0, localhost" > /etc/hosts.allow
echo "slushd: ALL" > /etc/hosts.deny

Will limit access to slush to hosts on the 10.10.5.0/255.255.255.0
network.

4. Create a certification authority

You can use the script 'wannabe-ca.sh' to setup a basic CA. You may
want to edit the script to set the path to the ca youself.

Do not forget the pass phrase you assigned to the CA. You will need it
in a minute.

You will need to copy the ca.crt file to wherever you openssl
installation looks for certificates and keys. This might be 
/usr/local/openssl/certs or /var/ssl/certs

5. Create and install a server key

Use the "make-server-cert.sh" script to generate a key. When you
are generating the certificate, you should specify the hostname
of the server on which you want to use the certificate in response
to the "Common Name (eg, YOUR name)" question.

Copy the resultant file "server.pem" to the same place you copied
"ca.crt" a moment ago and rename it to "slushd.pem".

6. Rehash the certificate directory

Since the slushd server looks for CA certificates by the hash, it is
necessary to symlink the certificates to a numerical representation of
their contents. You can do this by running the script "hash-certs.sh".
You will probably need to edit this script to reflect the location of the
certificate files.

7. Create one or more client keys

You can create client keys using the "make-cert.sh" script. You might
have to edit it to tell it where you want your CA directory.

When the script is run, it will create several files. The ones that 
you are interested in are:

new.pem     - move this to "<home directory>/.slush/key.pem"
new.subject - A short form representation of the certificate holder
new.issuer  - A short form representation of the certificate issuer (CA)

8. Set up client authentication

Client authentication is a multistep process which occurs whenever
a connection is recieved. It uses X509 certificates only, so if they
are not set correctly the user will not authenticate.

Certificate subjects and issuers are identified by their short form
(oneline) representation. You should have examples of this in the 
"new.subject" and "new.issuer" files above.

    a) slushd searches for the certificate issuer in the file
      /etc/slushd/denied-issuers. If found, then access is denied.

    b) slushd searches for the certificate subject in the file
      /etc/slushd/denied-subjects. If found, then access is denied.

    c) slushd searches for the certificate issuer in the file
      .slush/trusted-issuers in the home directory of the target
      user. If the issuer is not found then access is denied.

    d) slushd searches for the certificate issuer in the file
      .slush/allowed-issuers in the home directory of the target
      user. If the issuer is found then access is granted.

    e) slushd searches for the certificate subject in the file
      .slush/allowed-subjects in the home directory of the target
      user. If the subject is found then access is granted, 
      otherwise access is denied.

A quick setup would look like this:
cat CA/new.issuer  >> /home/user/.slush/trusted-issuers
cat CA/new.subject  >> /home/user/.slush/allowed-subjects

9. Try the client:

   slush my.hostname

Replace "my.hostname" with the hostname that you want to connect to.

If this fails, check your syslog for errors. Common errors are

 - Inetd not restarted

 - hosts.allow file not setup correctly

 - Server certificate file missing or wrong name

 - CA certificate file missing or wrong name

 - Certificates not hashed

 - Client auth not set up properly



Damien Miller <damien@ibs.com.au>

