.. /* * This file is part of the SavaPage project . * Copyright (c) 2026 Datraverse B.V. * Author: Rijk Ravestein. * * SPDX-FileCopyrightText: (c) 2020 Datraverse B.V. * SPDX-License-Identifier: CC-BY-SA-4.0 * * For more information, please contact Datraverse B.V. at this * address: info@datraverse.com */ .. _app-tools-ssl-key: SSL Key Generation ------------------ .. contents:: |RST_TABLE_OF_CONTENTS| :depth: 2 :local: .. _app-tools-ssl-key-intro: 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 :ref:`Re-Create the Self-Signed Certificate `. This certificate is used by default when the system is accessed via HTTPS on port |PROD_IP_PORT_SSL|. 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 :ref:`Re-Create the Self-Signed Certificate `. |br| |br| 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 :ref:`Importing an Existing SSL Certificate `. .. _app-tools-ssl-key-recreate: 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: .. code-block:: bash :caption: 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. .. code-block:: text :caption: create-ssl-keystore usage: [OPTION]... --common-name Subject and Issuer CN of the SSL Certificate (optional). Default: server hostname [hostname]. --create Creates a specific keystore file. -d,--default Creates keystore file in default location /opt/savapage/server/data/default-ssl-keystore. --dns-name 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 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 :ref:`SSL Certificate and Password `. .. _app-tools-ssl-key-import: Importing an Existing SSL Certificate ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you have an existing SSL certificate you can import it into a Java keystore to be used by |PRODUCT_NAME|. 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 |PRODUCT_NAME|. .. 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: .. code-block:: bash 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: .. code-block:: bash openssl pkcs12 -export -inkey your_private_key.pem -in savapage.pem -out savapage.p12 .. callout:: .. code-block:: text Enter pass phrase for your_private_key.pem: # <1> Enter Export Password: # <2> Verifying - Enter Export Password: # <3> .. annotations:: :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: .. code-block:: bash keytool -importkeystore -destkeystore my-ssl-keystore.jks -srckeystore savapage.p12 \ -srcstoretype PKCS12 .. callout:: .. code-block:: text Enter destination keystore password: # <1> Re-enter new password: # <2> Enter source keystore password: # <3> .. annotations:: :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 :ref:`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. .. _app-tools-ssl-key-install-keystore: 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 |PRODUCT_NAME| Application Server. The suggested location is ``/opt/savapage/server/custom/my-ssl-keystore.jks`` |br| |br| 2. Open the file :ref:`/opt/savapage/server/data/server.properties ` with a text editor. |br| |br| 3. Locate the section titled ``SSL/HTTP Configuration``. |br| |br| 4. Remove the ``#`` (hash) comment marker from all lines starting with ``server.ssl``. |br| |br| 5. Define the location of your keystore, keystore password and key password as chosen previously. The file should look something like this: .. code-block:: ini 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:: :ref:`Alternative TCP/IP Interface and Ports ` explains how IP ports are assigned to internal self-signed and external SSL certificates.