During the install process, SavaPage generates a Self-Signed Key and SHA-2 Certificate issued for the host's machine name where the Certificate Issuer is the Certificate Authority (CA). 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:
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 Section C.6.1, “Re-Create the Self-Signed Certificate”.
The browser will also warn that the certificate is not signed by a trusted authority. To overcome this you have two options:
Set trust for the Self-Signed Certificate. For Chrome based browsers:
Select the certificate from the browser's URL
entry field, and 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".
Obtain a certificate signed by a trusted authority. See Section C.6.2, “Importing an Existing SSL 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/linux-x64 ./create-ssl-keystore -f --default --common-name "savapage.mycompany.com"
More information is available via the --help command line
option.
usage: [OPTION]...
--common-name <NAME> Subject and Issuer CN of the SSL Certificate (optional).
If not set the computer hostname 'system-hostname' is used.
--create <FILE> Creates a specific keystore file.
-d,--default Creates the default keystore file
/opt/savapage/server/data/default-ssl-keystore.
--dns-name <LIST> A list of comma separated DNS names to use as SSL
Certificate Subject Alternative Name (optional). If not
set the value of --common-name is used.
-f,--force Force. Overwrites any existing keystore file.
-h,--help Displays this help text.
--ip-addr <LIST> A list of comma separated IP addresses to use as SSL
Certificate Subject Alternative Name (optional).
--no-ca SSL Certificate Issuer is not a Certificate Authority
(CA).
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.
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[46]. Please convert this PCKS #12 file to a separate PEM
private key and PEM certificate.
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[47] 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 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: (Make up another password) Re-enter new password: (Repeat this password) Enter source keystore password: (Enter Export Password from the previous openssl command)
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 Section C.6.3, “Installing the Keystore” to install it and start serving up your new SSL certificate.
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:
Copy your signed keystore onto the server running the
SavaPage Application Server. The suggested location is
/opt/savapage/server/custom/my-ssl-keystore.jks
Open the file
/opt/savapage/server/server.properties
with a text editor.
Locate the section titled SSL/HTTP Configuration.
Remove the # (hash) comment marker from all lines
starting with "server.ssl".
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
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.
[46] 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.
[47] 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.