Howto enable SSL

Be advised that due to changes in the current development this post is deprecated. It will be updated soon to reflect the needed changes.

Enabling SSL in betterFORM XRX / eXist:

Be advised that for the latest stable eXist (Version 1.4.1 Eindhoven) you will have to update the betterFORM extension prior to running these steps. See http://betterform.wordpress.com/deploying-a-dev-version-to-exist to do so.

1. Depending on your installation change into your betterFORM XRX or the eXist installation directory respectively.

2. Run the Java keytool to create a keystore usable with the sample jetty configuration and specify “localhost” as CN-Property!

keytool -genkey -alias jetty -keyalg RSA -keystore tools/jetty/etc/demokeystore -storepass secret

3. Enable SSL in tools/jetty/etc/jetty.xml

Open the file in an editor and search for the string ‘Add a HTTPS SSL listener on port 8443′ and uncomment <Call name=”addListener”> ….

4. Extract the SSL-certificate from the demokeystore with keytool with the following command

keytool -export -keystore tools/jetty/etc/demokeystore -file betterFORM-XRX.cert -alias jetty

5. Import the SSL certificate into a separate keystore:

keytool -import -alias betterFORM-XRX -file betterFORM-XRX.cert -keystore webapp/WEB-INF/httpcomponents.keystore

6. Edit webapp/WEB-INF/betterform-config.xml to use the keystore:

uncomment the line:

<property name="httpclient.ssl.context"
          value="de.betterform.connector.http.ssl.KeyStoreSSLContext"
          description="Full classpath of SSLProtocolSocketFactory which should be used by httpclient."/>

and change the line :

<property name="httpclient.ssl.keystore.path"
          value="PATH-TO-KEYSTORE"
          description="Location of the keystore to be used by httpclient."/>

to

<property name="httpclient.ssl.keystore.path"
          value="[YOUR betterFORM-XRX Installation]/webapp/WEB-INF/httpcomponents.keystore"
          description="Location of the keystore to be used by httpclient."/>

Replace [YOUR betterFORM-XRX Installation] with the absolute path to your betterFORM-XRX installation.

Afterwards replace KEYSTORE-PASSWD  in the property below httpclient.ssl.keystore.passwd with the password you have choosen in step 5  :

<property name="httpclient.ssl.keystore.passwd"
          value="KEYSTORE-PASSWD"
          description="Password to unlock  keystore."/>

7. Start betterFORM-XRX and you are ready to use a Custom-SSL-certificate.

Enabling SSL for betterFORM WAR with Tomcat

1. Change into your Tomcat installation.

1. Run keytool to create a keystore and be sure to specify “localhost” as CN-Property!

keytool -genkey -alias tomcat -keyalg RSA -keystore  conf/tomcat.keystore -storepass changeit

Attention: ‘changeit’ is the default password used by Tomcat. If you like to change this you have to adapt the Tomcat configuration (see next point)

2. Edit conf/server.xml to provide a SSL-Connector and use the just created keystore

<Connector
           port="8443" maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="[YOUR Tomcat Installation]/conf/tomcat.keystore" keystorePass="changeit"
           clientAuth="false" sslProtocol="TLS"/>

3. Edit betterform-config.xml to use keystore:

uncomment the line:

<property name="httpclient.ssl.context"
          value="de.betterform.connector.http.ssl.KeyStoreSSLContext"
          description="Full classpath of SSLProtocolSocketFactory which should be used by httpclient."/>

Change the line :

<property name="httpclient.ssl.keystore.path"
          value="PATH-TO-KEYSTORE"
          description="Location of the keystore to be used by httpclient."/>

to

<property name="httpclient.ssl.keystore.path"
          value="[YOUR Tomcat Installation]/conf/tomcat.keystore"
          description="Location of the keystore to be used by httpclient."/>

Afterwards replace [YOUR Tomcat Installation] with the absolute path to your  Tomcat Installation.

and replace KEYSTORE-PASSWD  in the property below httpclient.ssl.keystore.passwd with the password you choosed in step 1

<property name="httpclient.ssl.keystore.passwd"
          value="KEYSTORE-PASSWD"
          description="Password to unlock  keystore."/>

to

<property name="httpclient.ssl.keystore.passwd"
          value="changeit"
          description="Password to unlock  keystore."/>

4. Start Tomcat and you are ready to use a Custom-SSL-certificate.

Known Problems

KeyStoreSSLContext right now uses only the keystore configured in betterform-config.xml. The JAVA provided certificates are not used right now. As a workaround you can extract and add needed certificates to the configured keystore.

Hints

1. Get a certificate from a local or remote  Server with openssl on *nix.

A script for this task could look like this:

#!/bin/sh
#
# usage: retrieve-cert.sh remote.host.name [port]
#
REMHOST=$1
REMPORT=${2:-443}
echo |\
 openssl s_client -connect ${REMHOST}:${REMPORT} 2>&1 |\
 sed -ne '/-BEGIN CERTIFICATE-/,/-END CERTIFICATE-/p'