DinkySSL - a lightweight SSL solution for Wonka

Contents

• Introduction
  • Limitations
• Installation
  • Editing the "system.properties" file
  • Setting up the "extensions" directory
  • Installing the trusted certificates
  • Testing the installion
• Rebuilding from source
• Licensing

Introduction

DinkySSL is a lightweight SSL provider for Wonka^(TM), based on Adam Megacz' TinySSL. TinySSL was developed for the XWT project (www.xwt.org), and is in turn based on work performed by the League of the Bouncy Castle (www.bouncycastle.org). The credit belongs to these guys, I'm just the integrator here.

Differences between TinySSL and DinkySSL:

• In order to be able to run on any Java-like environment from 1.1 up, TinySSL uses its own random number generator. DinkySSL uses Wonka's SecureRandom class.
• The list of root certificates is hard-coded into the TinySSL sources, in DinkySSL it's read in from a file.
• DinkySSL includes bindings which allow it to be invoked automatically by the java.net.URL stuff when a URL beginning with https:// is encountered.

Limitations

DinkySSL inherits the limitations of TinySSL, which reflect the latter's design goal:

The main design goal for this class was the smallest possible body of code capable of connecting to 99% of all active HTTPS servers. Although this class is useful in many other situations (IMAPS, Secure SMTP, etc), the authors will refuse all feature requests and submitted patches which go beyond this scope.

It follows that DinkySSL is only useful for clients, not for servers; that no means are provided for client certificates to be presented, nor for server certificates to be issued or revoked; and that any deviation from the most stereotypical web client <-> web server protocol exchange will end in tears. If you want any of this then you need to look elsewhere.

Installation

Editing up the "system.properties" file

To use DinkySSL, you will need to have a working "extensions" directory. Open Wonka's system.properties file in an editor and see if you have a line looking something like this:

java.ext.dirs.path=/system/ext

If not, then you need to have one. The right-hand side of the equation should be /system/ext if your Wonka installation works relative to fsroot, or /usr/local/lib/wonka/ext if your Wonka installation uses absolute paths.

The directory also needs to exist, so use mkdir or whatever to create it.

Also in system.properties, you need to enable DinkySSL as a provider of the https protocol. The entry to do so looks like this:

java.protocol.handler.pkgs=be.kiffer.dinkyssl|com.acunia.wonka.net

That's a "pipe" symbol (vertical bar) between be.kiffer.dinkyssl and com.acunia.wonka.net. This means: look for a protocol handler in be.kiffer.dinkyssl first (e.g. to find be.kiffer.dinkyssl.https.Handler for https://), and then in com.acunia.wonka.net (for the rest).

Setting up the "extensions" directory

Copy two files into the "extensions" directory:

• The Bouncy Castle provider jar file (e.g. bcprov-jdk13-124.jar), OR JCE file (e.g. jce-jdk13-124.jar). Note that the JCE file is a superset of the provider file, there's no need to have both. It doesn't seem to matter whether you use the jdk12 or jdk13 version.
• The dinkyssl.jar file from the bin directory of this distribution.

Installing the trusted certificates

Copy the file resource/trusted.certs from this distribution into the same directory where system.properties resides.

Notes:(1) trusted.certs is the default location. You can change it using the system property be.kiffer.dinkyssl.trusted.certs, but it will always be loaded as a system resource (so it has to be on the bootclasspath).
(2) the format of the trusted.certs file is non-standard, but it is documented in the file itself. If you want to make your own file, for example because you want to include some self-signed certificates, just use openssl to dump the certificate in DER format and a utility such as b64encode(1) to convert this to base64 format. Note that it's perfectly legal for the "hint" line before the base64-encoded DER string to be blank, if you want that public key to be tried on all certificates which are presented.

Testing the installation

To check that everything is installed, correctly, run DinkySSLTest:

./wonka DinkySSLTest https://www.paypal.com

If everything is installed correctly, you should get back a bunch of HTML.

Rebuilding from source

No build scripts are included in this release, but the principles are pretty straightforward: compile all the Java files in the src directory, and then pack all the resulting class files (be/kiffer/dinkyssl/*.class, be/kiffer/dinkyssl/https/*.class) and the manifest (META-INF/MANIFEST.MF) into dinkyssl.jar.

  Length     Date   Time    Name
 --------    ----   ----    ----
       46  07-15-04 01:01   META-INF/MANIFEST.INF
      327  07-15-04 01:49   be/kiffer/dinkyssl/DinkySSL$SSLException.class
    10892  07-15-04 01:49   be/kiffer/dinkyssl/DinkySSL$SSLInputStream.class
     6726  07-15-04 01:49   be/kiffer/dinkyssl/DinkySSL$SSLOutputStream.class
    10138  07-15-04 01:49   be/kiffer/dinkyssl/DinkySSL.class
      639  07-15-04 01:49   be/kiffer/dinkyssl/DinkySSLTest$MyAuthenticator.class
     2737  07-15-04 01:49   be/kiffer/dinkyssl/DinkySSLTest.class
     1858  07-15-04 01:49   be/kiffer/dinkyssl/https/ChunkedInputStream.class
     2361  07-15-04 01:49   be/kiffer/dinkyssl/https/DinkyHttpsOutputStream.class
    10318  07-15-04 01:49   be/kiffer/dinkyssl/https/DinkyHttpsURLConnection.class
      610  07-15-04 01:49   be/kiffer/dinkyssl/https/Handler.class
 --------                   -------
    46652                   11 files