By default, the PDFreactor Web Service does not provide SSL and is accessible only via HTTP. If a secure HTTPS connection is required, you can enable SSL in the Jetty server shipped with PDFreactor by following these steps.

What Do You Need?

  • openssl to generate a self-signed certificate. This should be available on most OS.
  • keytool to import certificates into a keystore. The executable can usually be found in the "bin" directory of any Java installation.
  • The jetty-util JAR to generate password hashes. The JAR is located in the "PDFreactor/jetty/lib" directory.

1. Create a Self-Signed PKCS12 Certificate

You can skip this section if you already have an SSL certificate in PKCS12 format for your Jetty server. If your certificate is in another format, you have to convert it into PKCS12 first.

To create a self-signed certificate, execute the following commands on the command line (note: you will require openssl and keytool):


1.1. Create a private key. You will have to enter a password for this private key:

openssl genrsa -des3 -out jetty.key


1.2. Create a certificate using the private key. You will have to enter the key's password from (1.1).

openssl req -new -x509 -key jetty.key -out jetty.crt


1.3. Convert the certificate into PKCS12 format. You will have to enter a new password for the certificate (which is later used for the [certificatePasswordHash]) and you will have to enter the key's password from (1.1):

openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12


For simplicity you can use the same password for all commands. If you are using different passwords, make sure to use the appropriate password when configuring the "ssl.ini" (see below).

IMPORTANT: if you are using a self-signed certificate, some clients (especially browsers) need to accept the certificate before they can make calls over SSL to your server. These calls will fail due to security restrictions if the certificate was not accepted by the client first.

2. Import the PKCS12 Certificate in Jetty

keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore /path/to/PDFreactor/jetty/etc/keystore


The destination keyStore password is a new password (which is later used for the [keystorePasswordHash]), the source keyStore password is the certificate's password from (1.3) or the password from your existing certificate.


If the Jetty keystore already exists, remove or rename it before creating the new keystore.

3. Enable SSL in Jetty

You can now use the keystore you created to configure SSL in Jetty. Since you will have to enter the password for your keystore and certificate in the "ssl.ini" file, we recommend creating a hash from your keystore and certificate passwords first. You can do this as follows:

java -cp /path/to/PDFreactor/jetty/lib/jetty-util-9.x.x.xxxxxxxxx.jar org.eclipse.jetty.util.security.Password yourPassword


Now open the ssl.ini file (found in /PDFreactor/jetty/start.d) and edit/uncomment the following section (if you used the same password for your keystore as well as the certificate, [keystorePasswordHash] and [certificatePasswordHash] will be identical):


#========================
# SSL Configuration
#========================

--module=https
--module=ssl

jetty.ssl.port=8443
jetty.ssl.idleTimeout=30000
jetty.ssl.acceptors=2
jetty.ssl.acceptorQueueSize=100

jetty.sslContext.keyStorePath=etc/keystore
jetty.sslContext.trustStorePath=etc/keystore
jetty.sslContext.keyStorePassword=OBF:[keystorePasswordHash]
jetty.sslContext.keyManagerPassword=OBF:[certificatePasswordHash]
jetty.sslContext.trustStorePassword=OBF:[keystorePasswordHash]


The [keystorePasswordHash] and [certificatePasswordHash] (including the brackets) have to be replaced by the hashes you created using the org.eclipse.jetty.util.security.Password as described above. If you are using an MD5 hash of your password or your password in plain text instead, change the "OBF" prefix to "MD5" or remove it.

After you changed the ssl.ini, restart the PDFreactor Web Service like this:

Windows:

  • Go to 'Services'
  • Find the 'PDFreactor WebService'
  • Restart the service

OS X:

sudo launchctl stop com.realobjects.PDFreactorWebService
sudo launchctl start com.realobjects.PDFreactorWebService


Linux/Unix:

sudo /PDFreactor/bin/pdfreactorwebservice restart


After restarting, you can now access the REST API of the PDFreactor Web Service securely at "https://localhost:8443/service/rest".