TLS Configuration

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

note

TLS is the successor to SSL and is no longer supported.

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

caution

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

Certificate store

A certificate store (keystore) is required for the TLS configuration. This keystore 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 certificate store (keystore) must be provided in a keystore file and is supported 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.

caution

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:

• Keystore Explorer (https://keystore-explorer.org/)
• XCA (https://hohnstaedt.de/xca/)

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.

On Windows systems

On Windows systems, the certificate store for user and (local) computer certificates is also supported. Before use, the certificate must be imported into the certificate store together with the private key. Both must be stored in the certificate store under Personal -> Certificates.

caution

If the certificates are stored in the Windows certificate store, it is important to ensure that the entire certificate chain (from the root CA to the certificate) is imported. This can be checked in the properties of the certificate in the Windows certificate manager.

In the selection when the server is running under Windows, the two certificate stores appear as

• Windows User Certificate Store (Personal) and
• Windows Computer Certificate Store (Personal)

If one of these certificate stores is selected, the server searches for the requested certificate in the Personal -> Certificates area.

info

If the Windows Computer Certificate Store is used, the server must be run with an account that has the corresponding authorizations. This is the case, for example, if the server is run as a service and is run with a Windows Service Account.

Admin Portal configuration

In order to use an 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 sidebar entry Connections (1) and then select the entry *:8443 (HTTP/1.1) (2) under the connections on the right-hand side.

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

Then click on Edit certificate (6) to upload the new certificate to the server or to select a certificate store (Windows only).

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, first select the keystore type (1). The dialog changes depending on your selection. If you have selected a file-based type, you must select the certificate file (2).

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 only one certificate is available, this entry can be left blank. If the selected keystore type only ever has one certificate, the field is not available.

If the keystore (or the private key) 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.

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 TLS connection, you need an X509 certificate and the corresponding private key (see “keystore”). Both must be stored in a keystore. This can be a file-based keystore (JKS, PKCS#12 or PEM) or the certificate store under Windows.

info

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

After server installation, the keystore/ folder already contains a (default) 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.

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 your own keystore, store it in the JKS, PKCS#12 or PEM 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"/>

tip

The file entry can also contain an absolute path if you want to refer to an existing keystore file.

If you want to use a secure connection only, you can 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 TLS connection, set the connector that has an ssl element to enabled with a value of true:

note

SSL is no longer supported, but for historical reasons the entries in the configuration still have the name <ssl>, but always refer to the TLS configuration.

<?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 TLS connection:

<connector port="8443">
    ...
</connector>

Enter the name for the keystore file. If the file is not preceded by a path, it must be located in the keystore/ directory of the installation. 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 the server.

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.