WebConnector: Enable SSL

This tutorial shows you how to use the WebConnector with SSL encryption to allow HTTPS connections. It's similar on how to enable HTTPS support with the HTTPConnector.

All steps were tested under Ubuntu 14.04 with OpenSSL 1.0.1f and Oracle Java 1.8.0_66 but should be similar on other systems.

First thing you need a valid certificate for your domain. This can either be a self signed certificate or signed by a certificate authority (CA).

Using self signed certificate

Hint: With this method all clients get at least a warning when using your WebConnector, because your certificate is not in the list of trusted certificate authorities. For a more professional way see the method below.

If you don't have a certificate yet, use the following commands to create a self signed one.

First you have to generate a private key without password:

openssl genrsa -des3 -out webconnector.key 1024

Next step you have to generate a certificate signing request:

openssl req -new -key webconnector.key -out webconnector.csr

Then you sign your own request with your private key:

openssl x509 -req -days 365 -in webconnector.csr -signkey webconnector.key -out webconnector.pem

Using a CA signed certificate

If you want your certificate to be accepted smoothly by almost every client, you have to hand the certificate signing request to a trusted certificate authority.

First you have to generate a private key without password:

openssl genrsa -des3 -out webconnector.key 1024

Next step you have to generate a certificate signing request:

openssl req -new -key webconnector.key -out webconnector.csr

Here comes the difference! You don't sign the certificate request yourself, but hand it to the certificate authority. They sign the request and hand you the signed certificate. This one is now accepted by every client which trusts this certificate authority.

Please Note: You have to add the complete certificate chain to the received certificate! This means manually adding the corresponding chain to your certificate before you generate the keystore. Otherwise you will run into trouble when other Web services have to use your service. You can check if the chain was added correctly here: https://www.sslshopper.com/ssl-checker.html

The webconnector.csr request file is no longer needed and can be deleted.

Creating the Java key store

You should now have a webconnector.key file containing the private key and a webconnector.pem file containing the certificate. In order to use the certificate with Java you have to generate a Java key store (jks).

First you have to pack the private key and certificate into a pkcs12 key store, because the Java key store can't import private key and certificate directly. The Java keytool can convert a pkcs12 key store into a Java key store.

You have to use the same passwords in both steps!

Generate a pkcs12 key store with following commands:

openssl pkcs12 -export -in webconnector.pem -inkey webconnector.key -out webconnector.p12 -name connector

keytool -importkeystore -destkeystore webconnector.jks -srckeystore webconnector.p12 -srcstoretype PKCS12 -alias connector

The pkcs12 key store file webconnector.p12 is no longer needed an can be deleted.

Integrate the Java key store

You should now have a Java key store called webconnector.jks. Now you copy this file to the etc folder of your node instance. NOT the operating system /etc/ folder!

Then you just have to add or edit the WebConnector properties file etc/i5.las2peer.webConnector.WebConnector.properties and add or edit the following line:

sslKeystore = etc/webconnector.jks

sslKeyPassword = secretpassword

And don't forget to enable HTTPS by setting the following parameters, too:

httpsPort = 9090

startHttps = TRUE