Last updated at 2005/06/06 18:45:51 PDT by Temporal

If you intend to use the Evlan command client to connect to a server over the internet, you must set up SSL support for proper security. Without SSL, an attacker with the ability to sniff network packets could use a replay attack to gain access to your Evlan VM.

Evlan does not have SSL support built-in. This is because the only well-tested open source library available for doing this, OpenSSL, has the absolute worst programming interface ever known to man. Instead, Evlan relies on Stunnel, a convenient program which accepts SSL connections, decrypts them, and forwards them unencrypted to other local services. Using Stunnel, SSL support can be added to Evlan totally transparently. Not a single line of code is needed in the Evlan VM to handle it.

First, download and install Stunnel on the machine on which you will be running the Evlan VM. You will also need to generate a private key and a certificate. The details of this are beyond the scope of this document.

Edit your stunnel.conf to look something like this:

cert = my-certificate.crt
key = my-private-key.key
options = SINGLE_DH_USE
session = 300

accept = 51310
connect =

Edit the Evlan VM's config file (in modules/evlan.org/internal/Config.evlan) to accept connections on "". Now run both. Congratulations, you now have SSL support.

There is still another hurdle to clear, unfortunately. evlan-client uses the SSL library that comes with Java. By default, this library will refuse to connect to servers if it cannot verify their key with a trusted root. This means that if you are using a self-signed key, or if your SSL certificate is signed by someone not on Java's very limited list of trusted roots, you will be unable to connect.

The solution is to add your certificate to Java's trusted list. Unfortunately, as with everything else in Java, the methods for doing this are a complete mess, poorly documented, and unintuitive. On Windows, the Java control panel applet has a GUI for managing certificates, but adding your certificate to it will not help. After an epic battle, I managed to get Java to recognize my certificate using obscure command-line utilities. Type the following all on one line:

keytool -import -alias MyCertificate -file my-certificate.crt
        -keystore c:\path\to\JRE\lib\security\cacerts
        -storetype jks

You will be asked for a password. The password is "changeit". Clever, that.

If this doesn't help, try searching your Java directories for other files called "cacerts", and just add your certificate to every one you find. Hopefully you'll hit the right one eventually.

Note that when Java refuses to make an SSL connection because of this problem, it does not print a happy error message. Instead, it throws an obscure internal exception.

Hopefully some Java guru will read this and help me update the command client's code so that it doesn't require a signed certificate. Until then, this is all I can tell you.

SSL for Your Web Server

You can use Stunnel to add SSL support to your Evlan-based web server, too. Just add something like this to stunnel.conf:

accept = 443
connect =
TIMEOUTclose = 0

(The "TIMEOUTclose" option is to work around a bug present in IE and Firefox, which don't properly respond to requests to close the SSL stream.)

Now, when you get to the step in the web server setup guide where you create the authenticator, use "https://" rather than "http://" in the URL. Users will now use SSL to log in, then drop to unencrypted mode for normal operation. (You could also encourage users to always use SSL if you prefer.)

Unfortunately, there is a down side of using such a tunnel. Users will now be able to mask their IP address by connecting to your site via SSL, since the web server will see all the connections as coming from the local Stunnel daemon. evlan.org implements a hack to fix this, but the hack is too much of a hack to be worth releasing publicly. Consider investigating the module evlan.org/io/TunnelListener if you like.

evlan.org © Copyright 2003-2005 Kenton Varda
Powered by Io Community Manager, Evlan, and FreeBSD