SSL Certificate Management

As a reminder, Payara Server uses the following PKCS12 keystore files to manage SSL/TLS certificates required for secure communications:

keystore.p12

Java Keystore formatted file containing the Cryptographic keys, like the private keys associated with the certificates.

cacerts.p12

Java Keystore formatted file used as Trust Store file holding the X.509 certificates.

These keystores are protected with the Master Password of your domain.

Adding a new SSL Certificate

To add your SSL Certificate to the Payara Server configuration files, you need:

  • The private key associated with your certificate.

  • The Certificate you received from the Certificate Authority based on your Certificate Signing Request (CSR).

You can generate a self-signed certificate using the generate-self-signed-certificate command:

asadmin generate-self-signed-certificate --dn "CN=test.payara.fish,IP=127.0.0.1" mydomain_certificate
Alternatively

You can find the detailed steps of adding a self-signed certificate into Payara Server for testing purposes using keytool and openssl here.

The private key can be stored in various formats. We assume that the key is in a format which can be read by the Java key tool program, such as PKCS12.

First, you’ll have to combine the Private key and the Certificate you generated into a single file. This file can then be used to merge our data into the files used by the server.

Then specify an alias name for your key/certificate. This alias name is important as it will be used to refer to the SSL Certificate as a complete unit.

The command to perform this combination is the following with OpenSSL:

openssl pkcs12 -export -in mycert.crt -inkey mycert.key -out mycert.p12 -name mydomain_certificate

The resulting P12 bundle file can then be added to the keystore and truststore in Payara Server as described in the following sections.

Import into the Keystore

The information needs to be imported into the keystore.p12 file of your Payara Server domain which will use it.

Using Asadmin CLI

You can use the add-to-keystore command:

asadmin add-to-keystore --file mycert.p12 mydomain_certificate

Using the Admin Console

From the Admin Console, open the instance details page (e.g. on the navigation bar select Instances → $instanceName) and navigate to the Certificate Management tab.

From here, Click on the Add button of the keystore table (highlighted):

Certificate Management Add Button

You can then enter the alias name and the path to the certificate bundle:

Add Keystore Entry

Using the keytool command

You can also use the keytool command of the JDK:

keytool -importkeystore -destkeystore keystore.p12 -srckeystore mycert.p12 -srcstoretype PKCS12 -alias mydomain_certificate

Import into the Truststore

A similar command is used to import the information into the Trust Store file so that our certificate is trusted by the JVM.

Using Asadmin CLI

You can use the add-to-truststore command:

asadmin add-to-truststore --file mycert.crt mydomain_certificate

Using the Admin Console

You can also follow the same steps as done for adding the bundle to the keystore via the admin console, though selecting the Add button of the truststore table

Certificate Management Add Button

And then specifying the mycert.crt file.

Add Truststore Entry

Using the keytool command

You can also use the keytool command of the JDK:

keytool -importcert -trustcacerts -destkeystore cacerts.p12 -file mycert.crt -alias mydomain_certificate

Update HTTP Listeners

The last step you have to perform is to configure which certificate needs to be used when the server receives an SSL/TLS request. This can be done by specifying the alias name we have used when we integrated the required information into the key store files of the domain.

Using Asadmin CLI

This information can be set via the CLI:

asadmin set configs.config.server-config.network-config.protocols.protocol.http-listener-2.ssl.cert-nickname=mydomain_certificate
In a default installation, the http-listener-2 listener is responsible for handling the secure connections on port 8181. The above command sets the alias name so that the system knows which certificate needs to be used.

Using the Admin Console

The information can also be entered in the Web Administration console, by navigating to the page Configurations → server-config → HTTP Service → HTTP Listeners → http-listener-2.

Loading Certificates From Multiple Keystores

All additional keystores must have the same password as your domain master password.

To add additional keystores to Payara Server you will need to have your keystore and truststore files in a local directory. You can then configure this using the admin console or asadmin commands. If you want to load more than one additional keystore, you will need to use a delimiter between the paths to the additional keystores. This is different depending on your OS, Windows uses ';' and Linux uses ':'.

When specifying the key or trust store for a specific listener, this is deemed as an absolute and any additional key or trust stores are not considered.

The new JVM properties used to add additional keystores are:

-Dfish.payara.ssl.additionalKeyStores
-Dfish.payara.ssl.additionalTrustStores

Using the Admin Console

To configure the additional keystore locations in the admin console, head to the Configurations → <instance configuration> → JVM Settings and on the JVM Options tab click Add JVM Option.

You can add the new JVM property and the relative paths to your keystores or truststores here.

Configure Additional keystores and truststores in Admin Console

Using Asadmin CLI

JVM options can be configured using the create-jvm-options asadmin command, you can configure your additional keystore and truststore files using this command. If you are loading in multiple additional keystores via asadmin commands, you will need to prefix the appropriate delimiter for your OS with \ to avoid creating multiple JVM options.

Additional Keystores

asadmin create-jvm-options "-Dfish.payara.ssl.additionalKeyStores=/path/to/keystore.p12\:/path2/to/keystore2.p12"

Additional Truststores

asadmin create-jvm-options "-Dfish.payara.ssl.additionalTrustStores=/path/to/truststore.p12\:/path2/to/truststore2.p12"
If you load multiple keystores with the same alias, the server will use the first keystore with that alias, starting with the default and then the additional keystores in the order they are listed in the JVM option.

Certificate expiration

All X.509 certificates have a validity period when they can be used. Once this validity period is passed, the users will see a warning or error message depending on the browser that the certificate is no longer valid.

Within the server log file, the expired certificates are listed when the system encounters one. Besides your custom certificates which are added as described in a previous chapter, the Trust Store also contains certificates from recognized Certificate Authorities, which can also expire in due time and thus can be listed as entries in the log file too.

The log level of the expired certificates is of type WARNING.

Removing expired certificates

Using Asadmin CLI

If you wish to remove all expired certificates, you can use the following Asadmin CLI subcommands:

asadmin remove-expired-certificates
asadmin remove-from-keystore mydomain_certificate
asadmin remove-from-truststore mydomain_certificate

Using the Admin Console

You can also remove individual or groups of certificates using the admin console Certificate Management tab (Instances → $instanceName → Certificate Management).

Select the desired certificates from the keystore or truststore entries table (not both), and click on the Delete button:

Certificate Management Delete Button