We recently released version 3.3.0 of the Universal Wiki Converter (full release notes), a content migration platform that helps users get their content into Confluence.

Along with the miscellaneous bug fixes and minor improvements, there are two new features that I’m excited we can support now. First, we now have a Trac Converter module, compliments of Stefan Gybas. I had another Trac user who was willing to figure out how to build the UWC himself so he could get access to it early 2 weeks ago, so I’m pleased it’s finally public. Secondly, the long-awaited SSL Support feature is finally available.

Basically, up until this version if you wanted to connect the UWC to an SSL encrypted Confluence (hidden behind the https protocol), then on some level you were out of luck. There were work-arounds, like installing a local Confluence for the UWC to work with and then exporting to the real Confluence, but this required more effort, and response to this work-around tended towards exasperation.

The thing about SSL is that on some level it’s always going to be extra work. Secure communication has a lot of parts to it. It’s not just the encryption. There’s also proving your identity, and proving that the remote machine you’re talking to is who you think it is. That’s where certificates come in. Whenever SSL is involved, somewhere in the background the machines are examining and approving (or requesting approval for) certificates which handle all this identity business. You may have noticed your browser popup a request for you to double check a certificate every so often. Or maybe not. Browsers tend to hide alot of these details.

So why aren’t we hiding alot of these details? Well, it’s to prepare you. To prepare you for the bad news – the bad news which is in order to use SSL with the UWC, you will have to tell the UWC where your Confluence’s certificate is. Well, you do if you want to be sure that you know where your data is going.

Basically, there’s the “right” way to do this: importing your SSL’d Confluence’s certificate into a keystore and telling the UWC about it. This involves a lot of steps. But if you do them, then the SSL can do its job properly and protect you from hijacking, tampering, or otherwise disclosure of your secure data in the event that some Nefarious Bad Guy was attempting to snoop.

In the other direction, there’s the “quick and easy path”. It’s very easy to configure. Really just one property: trustall. It means trust all certificates. In other words, don’t verify the identity of the machine you’re transmitting to. This means that if there’s a Nefarious Bad Guy loitering about your network, then said NBG could intercept your data, do something with it, and then send it on its way to your Confluence. SSL can’t protect you if you tell it to trust everybody. In the same way that your front door can’t protect you from people walking in if you leave it unlocked.

So, why offer the trustall option if it’s so insecure?
Well, sometimes it’s handy to be able to leave your front door unlocked. Maybe your house doesn’t have anything all that valuable to anyone else in it, or there’s an outer door (firewall) that’s already locked, and you’ve decided that’s sufficient. You’re the one who knows how valuable your data is, how secure your network, what your organization’s policies are, and how much time you want to spend on this.

Connecting securely wasn’t actually all that difficult in terms of changes to the codebase. Well, except for the part where publicly available documentation is minimal. Not that I’m bitter. Luckily for me, PKI experts are thicker on the ground in my neighborhood than you might imagine, so I was able to enlist help when I got stuck. The critical important must have chunk of code necessary for connecting securely was the following 4 lines:

System.setProperty("javax.net.ssl.trustStore", truststore);
Security.addProvider(new com.sun.net.ssl.internal.ssl.Provider());

where truststore is the location of your imported certificate, and trustpass is the associated password. I just had to add these lines somewhere before the XMLRPC connection request. Without them, one will get any of a boatload of different sorts of errors depending on which stage in the process got munged, the most likely being an SSLHandshakeException. You’ll get one of those if SSL decides it can’t trust the machine you’re attempting to connect to (usually because your truststore is inadequate).

There are step by step instructions for the whole certificate importing process in the documentation. You can read more about that here: UWC SSL Support

If you want to take a look at the code, which I could imagine some java-security buffs might want, there’s a publicly accessible crucible project with all the related bits diffed and highlighted: CR-381.

For the latest download and documentation, please visit the website here: Universal Wiki Converter
Need Help? Check out the UWC Forum
Want to submit to the project? Great! Check out this FAQ entry for the most recent details on the code submission process: UWC Code Submission Process

Universal Wiki Converter – Now with SSL Support