Securing pubserver with a custom SSL certificate
Use case
The IT personell of a customer provides you with a valid SSL server certificate and you must install it in publishing server.
Background
General information of how to handle HTTPS in publishing server is given here:
How-To Configuration of priint:suite for HTTPS
This task is a general Payara process not specific to publishing server in any way.
See https://docs.payara.fish/docs/5.201/documentation/payara-server/server-configuration/ssl-certificates.html (this is for version 5.201 the latest at time of writing)
Recommended Procedure
This procedure differs from the old way described in Payara documentation since it relies on the SNI feature (Server Name Indication) available to Payara since version 5.182. The “old way” is of course still possible.
SNI will map the domain name in a request to a certificate in the keystore given the name of a keystore entry – the alias – matches. It will fall back to a default certificate if no match is found.
Two steps must be done a) add certificate to the Payara keystore using all required DNS names, b) allow Payara to use SNI (Server Name Indication) to detect the correct certificate.
Add certificate
Download JKS Explorer tool from internet (keystore-explorer.org). This is a simple GUI that makes working with Java Keystores much easier.
Open the certificate file you got in JKS Explorer. For our example here we use the file “printsrv.example.com.p12”. But JKS explorer allows other file formats as well, like PEM or CRT etc. JKS explorer will normally ask for a password. The password Is typically sent together with the certificate file. Or ask the customer IT that created the certificate.
Inspect the certificate’s extension values. Especially the value for “Subject Alternative Name”. It should contain one or more DNS entries along with optional other entries. The DNS entries are the fully qualified domain names supported by the certificate.
Copy the supported DNS entries into a text editor. Check if it contains only lowercase characters. If not make it all lowercase. Background: DNS servers are supposed to handle names case-insensitive but Java keystore tools are in several aspects case sensitive, which may lead to problems. Best strategy: Always use domain names in lowercase letters.
Open file keystore.jks from <domain>/config folder in JKS Explorer. It will ask for a password. The default is “changeit”. If the default does not work, ask the people who originally installed pubserver, which password they had chosen.
Now, copy the new certificate – e.g. “printsrv.example.com“ - and paste it into the keystore.jks - via context menu copy and paste.
Then change the password of the new entry – via context menu. Password must be identical to the password of the keystore itself (e.g. the default “changeit”).
Rename the entry to the full qualified domain name, that is set as subject alternative name – and be sure that the name is in lowercase letters only. This name is also called “nickname” or “alias” in the context of JKS.
If there are more DNS entries in the subject alternative name field, just add more copies of the imported certificate using the respective DNS names as alias (again in lowercase).
The save the modified JKS file to make the changes permanent.
Here are some screenshots to show how our example looks after the changes:
Enable SNI
To add SNI support is simple.
Either use asadmin command line tool:
asadmin> set configs.config.server-config.network-config.protocols.protocol.http-listener-2.ssl.sni-enabled=true
Or use webadmin and click the SNI checkbox in the SSL settings for http-listener-2.
You probably need to restart the server to get this activated.
Given your SSL port was set to the default 443 please check the URL with your browser:
- a) https://printsrv.example.com:443 and https://printsrv:443
- b) https://localhost:443 and https://127.0.0.1:443
The first two URLs should work, and the certificate should be new newly imported certificate.
The third and fourth URLs (localhost) should complain about a self-signed certificate since it should use the “s1as” certificate generating during pubserver installation.
Debugging
Hopefully, this is not necessary for you. In rare cases and with sufficient knowledge on Java security you may add SSL debugging. Please: NEVER do this on a production system!
<java-config> section:
<jvm-options>-Djavax.net.debug=SSL</jvm-options>