C.5. SSL Key Generation

During the install process, SavaPage generates a self-signed key and SHA-2 certificate issued for the host's machine name. This key is used by default when the system is accessed via HTTPS on port 8632.

The default SSL certificate provides good security, however there are two downsides to using a self-signed certificate, since users accessing the HTTPS site will encounter warnings from the browser.

  1. When users access the HTTPS site using a fully-qualified domain name, the browser will issue a Domain mismatch warning. To avoid this warning, re-create the self-signed certificate with the machine's fully qualified domain name, see Section C.5.1, “Re-Create the Self-Signed Certificate”.

  2. The browser will also warn the user that the certificate is not signed by a trusted authority. To overcome this you must obtain a certificate signed by a trusted authority, see Section C.5.2, “Importing an Existing SSL Certificate”.

C.5.1. Re-Create the Self-Signed Certificate

The tool create-ssl-keystore can be used to re-create the key/certificate (stored in a keystore file) for a different hostname eliminating the browser domain mismatch warning. An example of the command's use:

cd /opt/savapage/server/bin
./create-ssl-keystore -f --default --system-name "savapage.mycompany.com"

More information is available via the --help command line option.

usage: [OPTION]...
    --create <FILE>        Creates a specific keystore file.
 -d,--default              Creates the default keystore file
                           /opt/savapage/server/data/default-ssl-keystore.
 -f,--force                Force. Overwrite any existing keystore file.
 -h,--help                 Displays this help text.
    --system-name <NAME>   The name of the computer/server used for the
                           SSL Certificate. If not set the current
                           computer name is used.

C.5.2. Importing an Existing SSL Certificate

If you have an existing SSL certificate you can import it into a Java keystore to be used by SavaPage. Reasons for having an existing signed key include:

  • You have obtained a dedicated SSL certificate for use with your SavaPage Application Server.

  • Your organization's intranet as served by Internet Information Server (Windows), Apache (GNU/Linux) or another web server uses a certificate that can be re-used for SavaPage.

    Note

    Unless your intranet server and SavaPage run on the same server (i.e. on different ports), the server name of your intranet server will be different from your SavaPage Application Server. E.g. the intranet address might be internal.mycompany.com while the SavaPage Application Server can be reached at savapage.mycompany.com. In this case the certificate can only be re-used if it is a so-called wild-card certificate that allows arbitrary subdomains under the mycompany.com domain name that it was issued for.

If the SSL certificate is held in a Windows environment you will have a certificate with an attached private key in a so-called PCKS #12 file with *.p12 or .pfx extension[37]. Please convert this PCKS #12 file to a separate PEM private key and PEM certificate.

Note

If the certificate with key exist in the certificates store of Windows or IIS Server, you need to export it as a .PFX file first.

On GNU/Linux you will typically already have separate PEM encoded[38] key and certificate files. In this example, they are called your_private_key.pem and your_certificate.pem respectively.

However, we are not quite done yet, since we should add the intermediate certificate(s) of the Certificate Authority to the keystore as well. These certificates should be supplied by your CA or are available for download on the CA's web site as a file ending with .pem or .crt. A single PEM file has to be made, containing your certificate and all the intermediate certificates of your CA.

Use these commands to combine your certificate and the intermediates into one PEM file:

cat your_certificate.pem > savapage.pem
cat intermediate_cert_1.pem >> savapage.pem
cat intermediate_cert_2.pem >> savapage.pem
[...]

Use this command to combine the private key and the certificates into a single .p12 file:

openssl pkcs12 -export -inkey your_private_key.pem -in savapage.pem -out savapage.p12

Enter pass phrase for your_private_key.pem: (Enter your private key password, if present)
Enter Export Password:                      (Make up a password)
Verifying - Enter Export Password:          (Repeat the password you made up)

The keytool command used in this section is part of the OpenJDK package as installed on the host. Now, use this command to create a new Java keystore and import the .p12 or .pfx file at hand:

keytool -importkeystore -destkeystore my-ssl-keystore.jks -srckeystore savapage.p12 \
-srcstoretype PKCS12

Enter destination keystore password:        (Make up another password)
Enter source keystore password:             (Enter password you made up with OpenSSL before)

At this point your keystore file is ready to use, so follow the instructions in Section C.5.3, “Installing the Keystore” to install it and start serving up your new SSL certificate.

C.5.3. Installing the Keystore

The previous section described how to create a keystore file from an existing SSL certificate. This section describes how to install your keystore so that SavaPage can start serving up your new certificate.

To configure the SavaPage Application Server to use the new key/certificate:

  1. Copy your signed keystore onto the server running the SavaPage Application Server. The suggested location is /opt/savapage/server/custom/my-ssl-keystore.jks

  2. Open the file /opt/savapage/server/server.properties with a text editor.

  3. Locate the section titled SSL/HTTP Configuration.

  4. Remove the # (hash) comment marker from all lines starting with "server.ssl".

  5. Define the location of your keystore, keystore password and key password as chosen previously. The file should look something like this:

    server.ssl.keystore=custom/my-ssl-keystore.jks
    server.ssl.keystore-password=password
    server.ssl.key-password=password
  6. Restart the SavaPage Application Server and verify all is working. If the server fails to start, error messages will be recorded in logs located in the server's logs directory.



[37] PKCS #12 is one of the family of standards called Public-Key Cryptography Standards (PKCS), published by RSA Laboratories. It defines a (binary) file format commonly used to store X.509 private keys with accompanying public key certificates, protected with a password-based symmetric key, and is the successor to PFX from Microsoft.

[38] PEM or Privacy Enhanced Mail is a Base64 encoded DER certificate. PEM certificates are frequently used for web servers as they can easily be translated into readable data using a simple text editor. Generally when a PEM encoded file is opened in a text editor, it contains very distinct headers and footers.