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 PDFreactor's Jetty server by following these steps:

1. Create a Self-Signed PKCS12 Certificate

You can skip this section if you already have an SSL certificate for your Jetty server in PKCS12 format. 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 key tool):


openssl genrsa -des3 -out jetty.key
openssl req -new -x509 -key jetty.key -out jetty.crt
keytool -keystore /path/to/PDFreactor/jetty/etc/keystore -import -alias jetty -file jetty.crt -trustcacerts
openssl req -new -key jetty.key -out jetty.csr
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 "start.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


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 "start.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 start.ini file (found in /PDFreactor/jetty) 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 a 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 start.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".