Skip to main content
Version: 9.0

SSL/TLS Configuration

For a secure communication between the webPDF server and your application, an SSL or TLS connection should be configured and enabled.

The following settings describe how to adjust the SSL configuration via the Admin Portal and manually in the server configuration. If possible, you should always perform the SSL configuration via the Admin Portal.

caution

We recommend that you use at least TLSv1.2 (TLSv1.3 is better) for SSL/TLS encryption if your client application supports it.

Keystore​

A keystore file (certificate store) is required for the SSL/TLS configuration. This keystore file must contain the server`s X509 certificate, the private key for the server certificate and all certificates in the certificate chain (root CAs, intermediates and certificates).

The keystore must be available as a file and can be in the following formats:

  • JKS (Java Keystore .jks)
  • PKCS#12 (.p12 or pfx)
  • PEM (.pem or .cabundle)

If the format supports it, the certificate store can be secured with a password.

important

When using the PEM format, make sure that the chain hierarchy of the certificates is reversed, in other words, from the server certificate to the root CA certificate. The private key is at the end of the list.

The Certificate for your server -> The intermediates in ascending order to the Root CA -> A Root CA, if any (usually none) -> Private Key

The certificate provider usually already provides the server certificate in one of the above-mentioned formats. If this is not the case, you can create such a file using the following tools, for example:

caution

Always make sure that the private key of the server certificate is also present in the keystore.

Under Windows, certificates can also be exported directly from the certificate store of the computer if they are already stored there.

Admin Portal configuration​

In order to use an SSL/TLS connection, you need a keystore with an X509 certificate and the corresponding private key (“Keystore”).

Log in to the Admin Portal.

On the admin page, go to the entry Connections (1) and then select the entry *:8443 (HTTP/1.1) (2) under the connections on the right-hand side.

Connection configuration

Set Enabled to On (3) so that the SSL/TLS connection for port 8443 is enabled. If required, you can change the port number under Port (4) or select or restrict the SSL/TLS protocols under SSL protocol (5).

Then click on Edit certificate (6) to load the new certificate or certificate store onto the server.

Current certificate

In the dialog that appears, you will see the current certificate (1) that the server is currently using.

info

You can also use the dialog later to display the currently configured certificate. In a standard installation, this is a “self-signed” certificate that the server provides and is only intended for test purposes.

To replace this certificate now, click on Select a new certificate (2).

In the following dialog, select your keystore file (1).

Select certificate

If your keystore file has more than one server certificate, you can use Alias (2) to specify the name of the certificate in the keystore. If there is only one certificate, this entry can be left blank.

If the keystore is protected with a password, enter the corresponding Password in the dialog (3).

When all the entries have been made, click on Save (4) and the keystore will be checked. If the keystore is correct, everything is saved, the dialog is closed and the keystore is configured.

caution

If something is wrong with the keystore or the certificates, an error message appears in the dialog when you click on Save. The causes may be, for example, that the password is incorrect, the certificate has expired, the private key does not exist or an invalid alias name has been entered.

In order for the settings to be applied, you must save the settings and restart the server.

Server neu starten

Manual configuration​

The necessary settings are located in the conf/ folder of your webPDF installation. The relevant connection settings are configured in the server.xml file.

caution

If you want to make changes to conf/server.xml file, we recommend to make them exclusively in the portal’s administration page. Wrong manual changes can render the entire server inoperable.

To be able to use an SSL/TLS connection, you need a keystore with an X509 certificate and the corresponding private key (see "Keystore").

caution

Currently, no PEM file format is supported for the keystore during manual configuration.

info

You should use a certificate issued by a registered certification authority in your live environment.

After installation, the keystore/ folder already contains a keystore with the name ssl.jks. The necessary settings for using the ssl.jks keystore are already found in conf/server.xml and are configured for the existing keystore.

If you want to use your own keystore, store it in the JKS or PKCS#12 format in the keystore/ folder. Then adjust the following settings to your keystore file and the keystore format.

Example: <keystore type="PKCS12" password="mypassword" file="my-ssl.p12"/>

caution

Please note that the keystore ssl.jks only contains a "self-sign-certificate" which you should only use for testing purposes.

If you want to use a secure connection only, you can simply disable the unsecured standard connection. To do this, set the connector that does not have an SSL element to enabled with a value of false.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
<server xmlns="http://schema.webpdf.de/1.0/configuration/server">  
...  
    <connectors>  
        <connector enabled="false" address="" port="8080"/>  
    </connector>  
...  
</server>

To enable the SSL connection, set the "connector" that has an SSL element to "enabled" with a value of true:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>  
<server xmlns="http://schema.webpdf.de/1.0/configuration/server">  
...  
    <connectors>  
        <connector enabled="false" address="" port="8080"/>  
        <connector enabled="true" address="" port="8443">  
            <ssl maxThreads="150" scheme="https" clientAuth="false">  
                <keystore type="JKS" password="webpdf" file="ssl.jks"/>  
                <protocols>  
                    <protocol>TLSv1</protocol>  
                    <protocol>TLSv1.1</protocol>  
                    <protocol>TLSv1.2</protocol>  
                </protocols>  
            </ssl>  
        </connector>  
    </connectors>  
...  
</server>

Specify the port that should be used to establish the SSL connection:

port="8443"

Enter the name for the keystore file. The file must be located in the webPDF installations keystore/ directory. The keystore file that is already present, ssl.jks, uses the password webpdf:

<keystore type="JKS" password="webpdf" file="ssl.jks"/>

Leave the remaining settings with their default values:

<ssl maxThreads="150" scheme="https" clientAuth="false">

In order for the settings to be applied, you must save the file and restart webPDF.

After this, you can access the portal using the secured connection:

For example: https://localhost/webPDF/index.html (if you are using port 443 on the local machine)

caution

If you use the "self-signed certificate" from ssl.jks, the browser may display a message. You must then accept the certificate as "valid" so that the browser shows the portal page.