3.7. SSL Key Generation

3.7.1. Introduction

Each time SavaPage server starts it checks if the default Self-Signed Key and SHA-2 certificate and password file are present. If not, they are generated (a missing password file will generate both) with defaults described in Re-Create the Self-Signed Certificate. This certificate is used by default when the system is accessed via HTTPS on port 8632.

This 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 accessing the HTTPS site with a fully-qualified domain name that does not match the Certificate Subject Alternative 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 as common name with optional lists of Certificate Subject Alternative DNS Names and IP addresses. See Re-Create the Self-Signed Certificate.
   
   

2. The browser will also warn that the certificate is not signed by a trusted authority. To overcome this you have two options:

   1. Set trust for the Self-Signed Certificate. For Chrome based browsers:

      • Select the certificate from the browser’s URL entry field, and Export as “Base64-encode ASCII, single certificate” savapage.pem file.

      • Import savapage.pem as Certificate Authority and “Trust this certificate for identifying websites”.

      For Firefox you need to create a permanent server exception for each SavaPage https://fqdn:port via Certificate Manager > Servers > “Add Exception”.

   2. Obtain a certificate signed by a trusted authority. See Importing an Existing SSL Certificate.

3.7.2. 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:

example

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

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

create-ssl-keystore

usage: [OPTION]...
    --common-name <NAME>   Subject and Issuer CN of the SSL Certificate (optional).
                           Default: server hostname [hostname].
    --create <FILE>        Creates a specific keystore file.
 -d,--default              Creates keystore file in default location
                           /opt/savapage/server/data/default-ssl-keystore.
    --dns-name <LIST>      Comma-separated list of DNS names to use as SSL
                           Certificate Subject Alternative Name (optional). Default:
                           value of --common-name if specified, if not
                           [hostname,hostname.local,hostname.local.,localhost].
 -f,--force                Force. Overwrites any existing keystore file.
 -h,--help                 Displays this help text.
    --ip-addr <LIST>       Comma-separated list of IP addresses to use as SSL
                           Certificate Subject Alternative Name (optional). Default:
                           server IPv4/IPv6 addresses [ip-addr,127.0.0.1,::1]
    --localhost            Creates a keystore for [localhost,127.0.0.1,::1] only.
                           (this option is incompatible with --common-name,
                           --dns-name and --ip-addr)
    --no-ca                SSL Certificate Issuer is not Certificate Authority (CA).

Important

localhost is always present as Subject Alternative Name, whatever the options are. This host is needed because local clients use it to send messages to the SavaPage server.

Note

DNS name hostname.local. belongs to top-level domain .local. and is the Multicast DNS (mDNS) host name according to RFC 6762.

Note

The Issuer in the self-signed certificate is also the Certificate Authority (CA). In this way the certificate can be exported/imported as trusted CA in a browser. Use the --no-ca switch if you do not want the issuer to be CA.

Tip

If the Self-Signed Certificate (or its password file) is not found at server startup it is re-created ad hoc with default values described above. So, if you encounter an “HTTP ERROR 400 Invalid SNI” error when accessing a SavaPage webapp, re-create the certificate file with tailored values or remove the file, restart the server and try again. Also see SSL Certificate and Password.

3.7.3. 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 [1]. 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 [2] 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 Export Password: ②
Verifying - Enter Export Password: ③

1:

Enter your private key password, if present.

2:

Make up a password.

3:

Repeat this password.

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: ①
Re-enter new password: ②
Enter source keystore password: ③

1:

Make up another password.

2:

Repeat this password.

3:

Enter Export Password from the previous openssl command.

Note

keytool “Warning: The JKS keystore uses a proprietary format” can be ignored.

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

[1]

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.

[2]

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.

3.7.4. 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/data/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 if all is working correctly. If the server fails to start, error messages will be recorded in logs located in the server’s logs directory.

Note

Alternative TCP/IP Interface and Ports explains how IP ports are assigned to internal self-signed and external SSL certificates.